google-gemini-embeddings

Google Gemini Embeddings

Google Gemini embeddings API 的完整生产级指南

本技能全面介绍用于生成文本嵌入的 gemini-embedding-001 模型，包括 SDK 用法、REST API 模式、批处理、与 Cloudflare Vectorize 的 RAG 集成，以及语义搜索和文档聚类等高级用例。

---

目录

1. 快速入门
2. gemini-embedding-001 模型
3. 基础嵌入
4. 批量嵌入
5. 任务类型
6. 最常见的 5 个错误
7. 最佳实践
8. 何时加载参考资料

---

1. 快速入门

安装

安装 Google Generative AI SDK：

bun add @google/genai@^1.27.0

对于 TypeScript 项目：

bun add -d typescript@^5.0.0

环境设置

将 Gemini API 密钥设置为环境变量：

export GEMINI_API_KEY="your-api-key-here"

从以下地址获取 API 密钥：https://aistudio.google.com/apikey

首个嵌入示例

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
  }
});

console.log(response.embedding.values); // [0.012, -0.034, ...]
console.log(response.embedding.values.length); // 768

结果：一个 768 维嵌入向量，表示文本的语义含义。

---

2. gemini-embedding-001 模型

模型规格

当前模型：gemini-embedding-001（稳定，可用于生产环境）

• 状态：稳定
• 实验性模型：gemini-embedding-exp-03-07（已于 2025 年 10 月弃用，请勿使用）

维度

该模型使用 Matryoshka 表征学习，支持灵活设置输出维度：

维度	用例	存储	性能
768	大多数用例的推荐选项	低	快
1536	准确性与效率之间的平衡	中	中
3072	最高准确性（默认值）	高	较慢

默认值：3072 维 推荐值：对于大多数 RAG 应用，推荐使用 768 维

如果需要详细比较存储成本、准确性权衡或不同维度之间的迁移策略，请加载 references/dimension-guide.md。

如果要将 Gemini embeddings 与 OpenAI（text-embedding-3-small/large）或 Cloudflare Workers AI（BGE）进行比较，请加载 references/model-comparison.md。

速率限制

层级	RPM	TPM	RPD
免费	100	30,000	1,000
Tier 1	3,000	1,000,000	-

RPM = 每分钟请求数，TPM = 每分钟令牌数，RPD = 每日请求数

上下文窗口

• 输入限制：每段文本 2,048 个令牌
• 输入类型：仅限文本（不支持图像、音频或视频）

---

3. 基础嵌入

SDK 方式（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: 'The quick brown fox jumps over the lazy dog',
  config: {
    taskType: 'SEMANTIC_SIMILARITY',
    outputDimensionality: 768
  }
});

console.log(response.embedding.values);
// [0.00388, -0.00762, 0.01543, ...]

Fetch 方式（Cloudflare Workers）

适用于不支持 SDK 的 Workers/边缘环境：

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const apiKey = env.GEMINI_API_KEY;
    const text = "What is the meaning of life?";

    const response = await fetch(
      'https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent',
      {
        method: 'POST',
        headers: {
          'x-goog-api-key': apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          content: {
            parts: [{ text }]
          },
          taskType: 'RETRIEVAL_QUERY',
          outputDimensionality: 768
        })
      }
    );

    const data = await response.json();

    // Response format:
    // {
    //   embedding: {
    //     values: [0.012, -0.034, ...]
    //   }
    // }

    return new Response(JSON.stringify(data), {
      headers: { 'Content-Type': 'application/json' }
    });
  }
};

解析响应

interface EmbeddingResponse {
  embedding: {
    values: number[];
  };
}

const response: EmbeddingResponse = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: 'Sample text',
  config: { taskType: 'SEMANTIC_SIMILARITY', outputDimensionality: 768 }
});

const embedding: number[] = response.embedding.values;
const dimensions: number = embedding.length; // 768

---

4. 批量嵌入

在一次请求中处理多段文本（SDK）

同时为多段文本生成嵌入：

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const texts = [
  "What is the meaning of life?",
  "How does photosynthesis work?",
  "Tell me about the history of the internet."
];

const response = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  contents: texts, // Array of strings
  config: {
    taskType: 'RETRIEVAL_DOCUMENT',
    outputDimensionality: 768
  }
});

// Process each embedding
response.embeddings.forEach((embedding, index) => {
  console.log(`Text ${index}: ${texts[index]}`);
  console.log(`Embedding: ${embedding.values.slice(0, 5)}...`);
  console.log(`Dimensions: ${embedding.values.length}`);
});

按块处理以符合速率限制

处理大型数据集时，将请求分块，以符合速率限制：

async function batchEmbedWithRateLimit(
  texts: string[],
  batchSize: number = 100, // Free tier: 100 RPM
  delayMs: number = 60000 // 1 minute delay between batches
): Promise<number[][]> {
  const allEmbeddings: number[][] = [];

  for (let i = 0; i < texts.length; i += batchSize) {
    const batch = texts.slice(i, i + batchSize);

    console.log(`Processing batch ${i / batchSize + 1} (${batch.length} texts)`);

    const response = await ai.models.embedContent({
      model: 'gemini-embedding-001',
      contents: batch,
      config: {
        taskType: 'RETRIEVAL_DOCUMENT',
        outputDimensionality: 768
      }
    });

    allEmbeddings.push(...response.embeddings.map(e => e.values));

    // Wait before next batch (except last batch)
    if (i + batchSize < texts.length) {
      await new Promise(resolve => setTimeout(resolve, delayMs));
    }
  }

  return allEmbeddings;
}

// Usage
const embeddings = await batchEmbedWithRateLimit(documents, 100);

---

5. 任务类型

taskType 参数可针对特定用例优化嵌入。为获得最佳效果，请始终指定任务类型。

可用任务类型（共 8 种）

任务类型	用例	示例
RETRIEVAL_QUERY	用户搜索查询	“如何修理漏气的轮胎？”
RETRIEVAL_DOCUMENT	要编入索引或供搜索的文档	产品描述、文章
SEMANTIC_SIMILARITY	比较文本相似度	重复项检测、聚类
CLASSIFICATION	对文本进行分类	垃圾邮件检测、情感分析
CLUSTERING	对相似文本分组	主题建模、内容整理
CODE_RETRIEVAL_QUERY	代码搜索查询	“用于排序数组的函数”
QUESTION_ANSWERING	寻求答案的问题	FAQ 匹配
FACT_VERIFICATION	根据证据验证说法	事实核查系统

RAG 系统（最常见）

// When embedding user queries
const queryEmbedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: userQuery,
  config: {
    taskType: 'RETRIEVAL_QUERY', // ← Use RETRIEVAL_QUERY
    outputDimensionality: 768
  }
});

// When embedding documents for indexing
const docEmbedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: documentText,
  config: {
    taskType: 'RETRIEVAL_DOCUMENT', // ← Use RETRIEVAL_DOCUMENT
    outputDimensionality: 768
  }
});

影响：使用正确的任务类型可将搜索相关性提升 10-30%。

---

6. 五大常见错误

错误 1：维度不匹配

错误：Vector dimensions do not match. Expected 768, got 3072

原因：未指定 outputDimensionality 参数（默认值为 3072）。

修复方法：

// ❌ BAD: No outputDimensionality (defaults to 3072)
const embedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text
});

// ✅ GOOD: Match Vectorize index dimensions
const embedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text,
  config: { outputDimensionality: 768 } // ← Match your index
});

错误 2：速率限制（429 请求过多）

错误：429 Too Many Requests - Rate limit exceeded

原因：超出每分钟 100 次请求的限制（免费套餐）。

修复方法：

// ✅ GOOD: Exponential backoff
async function embedWithRetry(text: string, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await ai.models.embedContent({
        model: 'gemini-embedding-001',
        content: text,
        config: { taskType: 'SEMANTIC_SIMILARITY', outputDimensionality: 768 }
      });
    } catch (error: any) {
      if (error.status === 429 && attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

错误 3：文本截断（无提示）

错误：没有错误！文本会在 2,048 个 token 处静默截断。

原因：输入文本超过 2,048 个 token 的限制。

修复方法：嵌入前将长文本分块：

function chunkText(text: string, maxTokens = 2000): string[] {
  const words = text.split(/\s+/);
  const chunks: string[] = [];
  let currentChunk: string[] = [];

  for (const word of words) {
    currentChunk.push(word);

    // Rough estimate: 1 token ≈ 0.75 words
    if (currentChunk.length * 0.75 >= maxTokens) {
      chunks.push(currentChunk.join(' '));
      currentChunk = [];
    }
  }

  if (currentChunk.length > 0) {
    chunks.push(currentChunk.join(' '));
  }

  return chunks;
}

错误 4：任务类型不正确

错误：没有错误，但搜索质量较差（差 10-30%）。

原因：使用了错误的任务类型（例如，将 RETRIEVAL_DOCUMENT 用于查询）。

修复方法：

// ❌ BAD: Wrong task type for RAG query
const queryEmbedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: userQuery,
  config: { taskType: 'RETRIEVAL_DOCUMENT' } // ← Wrong!
});

// ✅ GOOD: Correct task types
const queryEmbedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: userQuery,
  config: { taskType: 'RETRIEVAL_QUERY', outputDimensionality: 768 }
});

错误 5：余弦相似度计算错误

错误：Similarity values out of range (-1.5 to 1.2)

原因：使用点积，而不是正确的余弦相似度公式。

修复方法：

// ✅ GOOD: Proper cosine similarity
function cosineSimilarity(a: number[], b: number[]): number {
  if (a.length !== b.length) {
    throw new Error('Vector dimensions must match');
  }

  let dotProduct = 0;
  let magnitudeA = 0;
  let magnitudeB = 0;

  for (let i = 0; i < a.length; i++) {
    dotProduct += a[i] * b[i];
    magnitudeA += a[i] * a[i];
    magnitudeB += b[i] * b[i];
  }

  if (magnitudeA === 0 || magnitudeB === 0) {
    return 0; // Handle zero vectors
  }

  return dotProduct / (Math.sqrt(magnitudeA) * Math.sqrt(magnitudeB));
}

加载 references/top-errors.md，查看全部 8 个错误及详细解决方案，包括批次大小限制、向量存储精度损失和模型版本混淆。

---

7. 最佳实践

务必做到

✅ 指定任务类型

const embedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text,
  config: { taskType: 'RETRIEVAL_QUERY' } // ← Always specify
});

✅ 使维度与 Vectorize 匹配

const embedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text,
  config: { outputDimensionality: 768 } // ← Match index
});

✅ 实施速率限制

// Use exponential backoff for 429 errors (see Error 2)

✅ 缓存嵌入向量

const cache = new Map<string, number[]>();

async function getCachedEmbedding(text: string): Promise<number[]> {
  if (cache.has(text)) {
    return cache.get(text)!;
  }

  const response = await ai.models.embedContent({
    model: 'gemini-embedding-001',
    content: text,
    config: { taskType: 'SEMANTIC_SIMILARITY', outputDimensionality: 768 }
  });

  const embedding = response.embedding.values;
  cache.set(text, embedding);
  return embedding;
}

✅ 对多个文本使用 Batch API

// Single batch request vs multiple individual requests
const embeddings = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  contents: texts, // Array of texts
  config: { taskType: 'RETRIEVAL_DOCUMENT', outputDimensionality: 768 }
});

绝不要做

❌ 不要跳过任务类型 - 质量会降低 10-30% ❌ 不要混用不同维度 - 无法比较嵌入向量 ❌ 不要在 RAG 中使用错误的任务类型 - 搜索质量会下降 ❌ 不要超过 2,048 个 token - 文本会被静默截断 ❌ 不要忽略速率限制 - 将触发 429 错误

---

8. 何时加载参考资料

在以下情况下加载 references/rag-patterns.md：

• 构建 RAG（检索增强生成）系统
• 需要包含分块策略的文档摄取流水线
• 实现使用余弦相似度的语义搜索
• 构建带历史记录的对话式 RAG
• 需要引用型 RAG 或多查询 RAG 模式
• 需要筛选型 RAG、流式 RAG 或混合搜索的完整示例
• 需要使用 K-means 实现文档聚类

在以下情况下加载 references/vectorize-integration.md：

• 为嵌入向量设置 Cloudflare Vectorize 索引
• 需要包含 Vectorize 插入／查询模式的完整 RAG 示例
• 配置 Vectorize 的维度／度量设置
• 实施元数据最佳实践
• 排查 Vectorize 的维度不匹配错误
• 需要索引管理命令（创建／删除／列出）

在以下情况下加载 references/dimension-guide.md：

• 决定使用 768、1536 还是 3072 维
• 需要存储成本分析（10 万与 100 万个向量）
• 了解准确率权衡（MTEB 基准测试）
• 在不同维度之间迁移
• 需要查询性能对比
• 选择最佳维度时需要测试方法

在以下情况下加载 references/model-comparison.md：

• 比较 Gemini 与 OpenAI（text-embedding-3-small/large）
• 比较 Gemini 与 Cloudflare Workers AI（BGE）
• 需要 MTEB 基准测试分数
• 决定使用哪个嵌入模型
• 从 OpenAI 迁移到 Gemini
• 了解不同提供商之间的成本差异

在以下情况下加载 references/top-errors.md：

• 遇到 8 个已记录错误中的任何一个
• 需要详细的根因分析
• 需要经过生产环境验证、带代码示例的解决方案
• 为生产系统构建错误处理机制
• 部署前需要验证清单

---

使用捆绑资源

模板（templates/）

• package.json - 包配置，包含已验证的版本
• basic-embeddings.ts - 使用 SDK 生成单条文本嵌入
• embeddings-fetch.ts - 基于 Fetch，适用于 Cloudflare Workers
• batch-embeddings.ts - 带速率限制的批处理
• rag-with-vectorize.ts - 使用 Vectorize 的完整 RAG 实现
• semantic-search.ts - 余弦相似度和 top-K 搜索
• clustering.ts - K-means 聚类实现

参考资料（references/）

• model-comparison.md - 比较 Gemini、OpenAI 和 Workers AI 嵌入
• vectorize-integration.md - Cloudflare Vectorize 的设置和模式
• rag-patterns.md - 完整的 RAG 实现策略
• dimension-guide.md - 选择合适的维度（768、1536 或 3072）
• top-errors.md - 8 个常见错误及详细解决方案

脚本（scripts/）

• check-versions.sh - 检查 @google/genai 软件包版本是否为最新版本

---

官方文档

• 嵌入指南：https://ai.google.dev/gemini-api/docs/embeddings
• 模型规范：https://ai.google.dev/gemini-api/docs/models/gemini#gemini-embedding-001
• 速率限制：https://ai.google.dev/gemini-api/docs/rate-limits
• SDK 参考：https://www.npmjs.com/package/@google/genai
• Context7 库 ID：/websites/ai_google_dev_gemini-api

---

相关技能

• google-gemini-api - 用于文本和图像生成的 Gemini API 主技能
• cloudflare-vectorize - 用于存储嵌入的向量数据库
• cloudflare-workers-ai - Workers AI 嵌入（BGE 模型）

---

成功指标

Token 节省：与手动实现相比约节省 60% 预防错误：记录了 8 个错误及其解决方案 经过生产环境测试：✅ 已在 RAG 应用中验证 软件包版本：@google/[email protected] 最后更新：2025-11-21

---

许可证

MIT 许可证 - 可免费用于个人和商业项目。

---

有问题或遇到故障？

• GitHub：https://github.com/secondsky/claude-skills
• 电子邮件：[email protected]