deprecated-generative-ai-js

Google AI JavaScript SDK：Gemini API 的官方 TypeScript 封装

背景故事：一个 SDK 的"退役通知"

2024年初，如果你是一名使用 Google Gemini API 的 JavaScript/TypeScript 开发者，你大概率在用 @google/generative-ai 这个 npm 包——这是 Google 官方发布的 JavaScript 版 Gemini SDK，封装了从文本生成、对话聊天到多模态（图片/视频/音频）输入的完整能力。

然而 2024 年底，随着 Gemini 2.0 的发布，Google 做了一个对开发者生态影响深远的决定：将原本分散的多产品 SDK（Gemini、Veo、Imagen 等）合并为统一的 js-genai SDK。原来的 @google/generative-ai（即本项目 google/generative-ai-js）正式宣告退役，官方 README 第一行就写着大字标题 "[Deprecated]"——这是一个不常见的做法，说明 Google 对 SDK 合并的决心非常坚定。

这一决定的背后逻辑不难理解：开发者不需要记住三四个不同的 Google AI SDK，只需要一个统一的入口。这种"大一统"策略在 AI 平台领域越来越常见，但对依赖旧 SDK 的项目来说，迁移成本是真实存在的。

项目定位：面向开发者的 API 封装层

本项目是一个纯客户端 TypeScript/npm SDK，不运行任何 AI 模型，核心职责是将 Gemini REST API 的调用过程封装为类型安全的 TypeScript 类和函数。开发者不需要直接构造 HTTP 请求，只需要几行代码：

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const result = await model.generateContent("Hello, Gemini!");
console.log(result.response.text());

这套模式对任何用过 OpenAI SDK 的开发者来说都很熟悉——风格上几乎是 1:1 对齐 OpenAI JavaScript SDK 的设计。

核心架构：三层模块化设计

源码结构清晰，分为三大层次：

第一层：入口与模型工厂（src/gen-ai.ts）

GoogleGenerativeAI 是整个 SDK 的入口类，构造函数只接收一个 apiKey，然后通过 getGenerativeModel() 方法返回 GenerativeModel 实例。这里体现了工厂模式的设计：一次初始化，多次使用模型。

第二层：GenerativeModel 模型类（src/models/generative-model.ts）

这是核心类，约 8KB，聚合了所有生成能力的调用入口：

• generateContent() — 同步单次生成（最常用）
• generateContentStream() — 流式生成，实时输出 token
• startChat() — 创建带历史记忆的对话会话
• countTokens() — 计算输入的 token 数量（计费估算用）
• embedContent() / batchEmbedContents() — 向量嵌入

每个方法内部都通过 formatGenerateContentInput() 对输入参数做标准化处理，支持字符串、Array<string|Part> 或 GenerateContentRequest 三种输入形式，降低使用门槛。

第三层：请求/响应层（src/requests/）

• request.ts — 底层 HTTP 调用，通过 makeModelRequest() 构造真实的 Gemini API 请求
• stream-reader.ts — 流式响应解析（processStream()），处理 Server-Sent Events（SSE）格式的流数据
• response-helpers.ts — 为 API 响应附加辅助方法（如 text()、functionCall() 等）

服务端专用模块（src/server/）

cache-manager.ts 和 file-manager.ts 提供了服务端环境下的专属能力：

• 上下文缓存（CachedContent）— 将长文档缓存在 API 侧，减少 token 计费
• 文件管理（FileManager) — 上传和管理大文件（最大 2GB），支持视频、PDF 等媒体文件

这两个模块只在 Node.js 服务端可用，在浏览器中会被自动排除，体现了环境感知的设计。

代码质量评估

项目代码质量较高：

• 全面使用 TypeScript，类型定义完整（types/ 目录），导出类型包括 Part、Content、SafetySetting、GenerationConfig 等，覆盖 Gemini API 的所有参数
• 完整的单元测试：*.test.ts 文件遍布各模块，使用 Mocha + Chai 测试框架
• 集成测试：Node.js 集成测试（test-integration/node/）+ Web 集成测试（web-test-runner）
• 构建系统：Rollup 打包 + api-extractor 生成 API 报告 + api-documenter 生成 Markdown 文档
• 代码格式：Prettier + ESLint + 自定义 format 脚本，贡献规范明确

文档质量极高：每个公开类/方法都有 JSDoc 注释，README 包含 20+ 个 samples 示例（samples/ 目录），涵盖 chat、files、function_calling、code_execution、safety_settings 等所有主要功能。

使用场景与局限性

适用场景：

• Node.js 服务端：调用 Gemini API 生成内容、构建 AI 聊天后端
• 浏览器前端：网页中嵌入 Gemini 对话能力（samples/web/ 提供 Web Demo）
• 任何 JavaScript/TypeScript 环境：Electron 桌面应用、Next.js SSR 等

局限性：

1. 无 Web-UI：项目不包含独立可运行的 Web 界面，只有示例代码，需要开发者自行集成
2. 无容器化部署：纯 npm 包，发布在 npm registry，不提供 Dockerfile
3. 官方已废弃：Google 官方强烈建议迁移到 googleapis/js-genai（新统一 SDK），本项目仅接收关键 bug 修复，2025年11月30日后完全停止维护
4. 需要 API Key：必须从 Google AI Studio 或 Google Cloud 获取 API Key，有调用成本

为什么这个项目仍然值得研究

尽管已被官方废弃，@google/generative-ai 的代码是理解AI API SDK 设计模式的绝佳范本：

1. 工厂模式：getGenerativeModel() 工厂方法
2. 流式响应处理：SSE 流解析是所有 LLM 流式 API SDK 的核心技术
3. 环境隔离：服务端/浏览器端的模块自动分离
4. 参数标准化：多种输入格式统一转换为 API 请求格式
5. 测试策略：单元测试 + 集成测试 + Web 测试的全覆盖

对于正在构建自有 AI API SDK 的开发者，这套代码提供了 Google 级别的工程标准参考。迁移到新 SDK 是必然选择，但学习这套设计的价值不会随之消失。

图1：Google AI 官方组织头像（本项目所属组织）