用途
本技能提供 Google Gemini embeddings API 的生产级使用指南，核心模型为 gemini-embedding-001，用于生成文本嵌入向量，支撑 RAG（检索增强生成）系统、语义搜索、文档聚类等场景。
主要能力
- 模型：gemini-embedding-001（稳定、生产可用）。实验模型 gemini-embedding-exp-03-07 已于 2025 年 10 月弃用，不应使用。
- 维度：基于 Matryoshka 表示学习支持灵活输出维度。768 维推荐用于多数场景（存储低、速度快）；1536 维为精度与效率的平衡；3072 维为最大精度（默认值）；128–3071 之间可自定义。
- 上下文窗口：每条文本输入上限 2048 tokens，仅支持文本，不支持图像、音频或视频。
- 速率限制：Free 层 100 RPM / 30,000 TPM / 1,000 RPD（无需计费账户）；Tier 1 为 3,000 RPM / 1,000,000 TPM（需绑定计费账户）；Tier 2 为 5,000 RPM / 5,000,000 TPM（需消费 250 美元以上并等待 30 天）；Tier 3 为 10,000 RPM / 10,000,000 TPM（需消费 1,000 美元以上并等待 30 天）。
- 输出格式：{ embedding: { values: number[] } }。
使用方式
安装 SDK：npm install @google/genai@^1.37.0；TypeScript 项目可安装 typescript@^5.0.0。设置环境变量 GEMINI_API_KEY，API key 可从 https://aistudio.google.com/apikey 获取。
基础调用示例（Node.js）：
import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }); const response = await ai.models.embedContent({ model: 'gemini-embedding-001', content: 'What is the meaning of life?', config: { taskType: 'RETRIEVAL_QUERY', outputDimensionality: 768 } });
在 Cloudflare Workers 等无 SDK 的边缘环境，可直接调用 REST 端点 https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent，请求头使用 x-goog-api-key。批量请求使用 batchEmbedContents 端点。
关键要求：当使用非 3072 维时，必须在计算相似度前对向量做归一化，只有 3072 维向量由 API 预归一化。指南提供了 normalize 辅助函数。
任务类型
共 8 种 taskType：RETRIEVAL_QUERY（用户搜索查询）、RETRIEVAL_DOCUMENT（待索引文档）、SEMANTIC_SIMILARITY（文本相似度比较）、CLASSIFICATION（文本分类）、CLUSTERING（文本聚类）、CODE_RETRIEVAL_QUERY（代码搜索查询）、QUESTION_ANSWERING（问答匹配）、FACT_VERIFICATION（事实核查）。RAG 中查询用 RETRIEVAL_QUERY，文档索引用 RETRIEVAL_DOCUMENT。正确指定任务类型可提升检索相关性 10–30%。
RAG 与 Cloudflare Vectorize 集成
文档摄取流程：对分块文本用 RETRIEVAL_DOCUMENT 生成嵌入，存入 Vectorize。查询流程：用 RETRIEVAL_QUERY 嵌入用户查询，检索 topK 相似文档，拼接上下文后交给生成模型（如 gemini-2.5-flash）生成回答。
创建索引：npx wrangler vectorize create gemini-embeddings --dimensions 768 --metric cosine。在 wrangler.jsonc 中绑定 VECTORIZE。
批量处理与已知问题
批量 API 存在若干已知问题：2025 年 12 月的排序 bug，大批量（>500 条）可能不保持顺序，建议每批少于 100 条或添加唯一 ID 校验；内存限制，超过 1 万条嵌入可能触发 ERR_STRING_TOO_LONG，建议每批少于 5,000 条；2026 年 1 月的限流异常，未超配额也可能返回 429 RESOURCE_EXHAUSTED，建议实现指数退避重试。指南提供分批限流函数示例（默认每批 50 条、批间延迟 60 秒）。
错误处理与最佳实践
常见错误包括 API key 缺失或无效、维度不匹配（嵌入维度与索引维度不一致）、限流（429）。建议：批量嵌入时使用批量 API；选择较低维度（768）以加快处理并减少存储；对限流错误实现指数退避；缓存嵌入避免重复调用。
适用场景与限制
适用于构建 RAG 系统、语义搜索、文档聚类、分类、代码检索、问答匹配与事实核查等。限制：仅支持文本输入，单条上限 2048 tokens；非 3072 维需手动归一化；批量 API 存在排序、内存与限流方面的已知问题，需按建议规避。