⚡

谷歌Gemini嵌入API技能 google-gemini-embeddings

本技能提供了Google Gemini嵌入API的全面生产就绪指南，用于生成文本嵌入向量，支持检索增强生成（RAG）、语义搜索、文档聚类等应用。包含SDK使用、REST API模式、批量处理、与Cloudflare Vectorize集成等高级用例。关键词：Gemini嵌入，RAG，语义搜索，向量搜索，文档聚类，API集成。

RAG应用 0 次安装 0 次浏览 更新于 3/7/2026

名称: google-gemini-embeddings 描述: Google Gemini嵌入API（gemini-embedding-001）用于RAG和语义搜索。适用于向量搜索、Vectorize集成，或处理维度不匹配、速率限制、文本截断。

关键词: gemini嵌入，gemini-embedding-001，google嵌入，语义搜索，RAG，向量搜索，文档聚类，相似性搜索，检索增强生成，vectorize集成，cloudflare vectorize嵌入，768维度，嵌入内容gemini，批量嵌入，嵌入api，余弦相似度，向量归一化，检索查询，检索文档，任务类型，维度不匹配，嵌入速率限制，文本截断，@google/genai 许可证: MIT 元数据: 版本: 1.0.0 最后更新: 2025-11-21 测试包版本: “@google/genai@1.27.0” 目标受众: “构建RAG、语义搜索或基于向量的应用的开发者” 复杂度: 中级 预计阅读时间: “8分钟” 节省令牌: “~60%” 预防错误: 8 生产测试: true

Google Gemini 嵌入

Google Gemini嵌入API的完整生产就绪指南

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

目录

  1. 快速开始
  2. gemini-embedding-001 模型
  3. 基本嵌入
  4. 批量嵌入
  5. 任务类型
  6. 前5大错误
  7. 最佳实践
  8. 何时加载参考资料

1. 快速开始

安装

安装Google生成式AI SDK：

bun add @google/genai@^1.27.0

对于TypeScript项目：

bun add -d typescript@^5.0.0

环境设置

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

export GEMINI_API_KEY="您的API密钥"

从以下网址获取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: '生命的意义是什么？',
  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维度 推荐：768维度用于大多数RAG应用

当您需要详细比较存储成本、准确性权衡或维度间迁移策略时，加载参考资料/维度指南.md。

当比较Gemini嵌入与OpenAI（text-embedding-3-small/large）或Cloudflare Workers AI（BGE）时，加载参考资料/模型比较.md。

速率限制

层级 RPM TPM RPD
免费 100 30,000 1,000
层级 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: '快速的棕色狐狸跳过懒狗',
  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 = "生命的意义是什么？";

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

    // 响应格式：
    // {
    //   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: '示例文本',
  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 = [
  "生命的意义是什么？",
  "光合作用如何工作？",
  "告诉我互联网的历史。"
];

const response = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  contents: texts, // 字符串数组
  config: {
    taskType: 'RETRIEVAL_DOCUMENT',
    outputDimensionality: 768
  }
});

// 处理每个嵌入
response.embeddings.forEach((embedding, index) => {
  console.log(`文本 ${index}: ${texts[index]}`);
  console.log(`嵌入: ${embedding.values.slice(0, 5)}...`);
  console.log(`维度: ${embedding.values.length}`);
});

分块处理以应对速率限制

处理大型数据集时，分块请求以保持在速率限制内：

async function batchEmbedWithRateLimit(
  texts: string[],
  batchSize: number = 100, // 免费层级：100 RPM
  delayMs: number = 60000 // 批次间延迟1分钟
): Promise<number[][]> {
  const allEmbeddings: number[][] = [];

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

    console.log(`处理批次 ${i / batchSize + 1} (${batch.length} 个文本)`);

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

    // 等待下一个批次（最后一个批次除外）
    if (i + batchSize < texts.length) {
      await new Promise(resolve => setTimeout(resolve, delayMs));
    }
  }

  return allEmbeddings;
}

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

5. 任务类型

taskType 参数针对特定用例优化嵌入。始终指定任务类型以获得最佳结果。

可用任务类型（总共8个）

任务类型 用例 示例
RETRIEVAL_QUERY 用户搜索查询 “如何修理爆胎？”
RETRIEVAL_DOCUMENT 要索引/搜索的文档 产品描述、文章
SEMANTIC_SIMILARITY 比较文本相似性 重复检测、聚类
CLASSIFICATION 分类文本 垃圾邮件检测、情感分析
CLUSTERING 分组相似文本 主题建模、内容组织
CODE_RETRIEVAL_QUERY 代码搜索查询 “排序数组的函数”
QUESTION_ANSWERING 寻求答案的问题 常见问题匹配
FACT_VERIFICATION 用证据验证声明 事实核查系统

RAG系统（最常见）

// 当嵌入用户查询时
const queryEmbedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: userQuery,
  config: {
    taskType: 'RETRIEVAL_QUERY', // ← 使用 RETRIEVAL_QUERY
    outputDimensionality: 768
  }
});

// 当嵌入文档进行索引时
const docEmbedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: documentText,
  config: {
    taskType: 'RETRIEVAL_DOCUMENT', // ← 使用 RETRIEVAL_DOCUMENT
    outputDimensionality: 768
  }
});

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

6. 前5大错误

错误1：维度不匹配

错误：向量维度不匹配。预期768，得到3072

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

修复：

// ❌ 错误：无outputDimensionality（默认为3072）
const embedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text
});

// ✅ 正确：匹配Vectorize索引维度
const embedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text,
  config: { outputDimensionality: 768 } // ← 匹配您的索引
});

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

错误：429 请求过多 - 速率限制超出

原因：超出100个每分钟请求（免费层级）。

修复：

// ✅ 正确：指数退避
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个令牌处静默截断。

原因：输入文本超过2,048令牌限制。

修复：在嵌入前分块长文本：

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

    // 粗略估计：1令牌 ≈ 0.75单词
    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）。

修复：

// ❌ 错误：RAG查询的错误任务类型
const queryEmbedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: userQuery,
  config: { taskType: 'RETRIEVAL_DOCUMENT' } // ← 错误！
});

// ✅ 正确：正确的任务类型
const queryEmbedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: userQuery,
  config: { taskType: 'RETRIEVAL_QUERY', outputDimensionality: 768 }
});

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

错误：相似度值超出范围（-1.5 到 1.2）

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

修复：

// ✅ 正确：适当的余弦相似度
function cosineSimilarity(a: number[], b: number[]): number {
  if (a.length !== b.length) {
    throw new Error('向量维度必须匹配');
  }

  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; // 处理零向量
  }

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

加载参考资料/前错误.md以获取所有8个错误的详细解决方案，包括批量大小限制、向量存储精度损失和模型版本混淆。

7. 最佳实践

始终做

✅ 指定任务类型

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

✅ 匹配Vectorize的维度

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

✅ 实施速率限制

// 对429错误使用指数退避（见错误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;
}

✅ 对多个文本使用批量API

// 单个批量请求 vs 多个单独请求
const embeddings = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  contents: texts, // 文本数组
  config: { taskType: 'RETRIEVAL_DOCUMENT', outputDimensionality: 768 }
});

永远不做

❌ 不要跳过任务类型 - 质量降低10-30% ❌ 不要混合不同维度 - 无法比较嵌入 ❌ 不要对RAG使用错误的任务类型 - 降低搜索质量 ❌ 不要超过2,048个令牌 - 文本将被静默截断 ❌ 不要忽略速率限制 - 将遇到429错误

8. 何时加载参考资料

加载参考资料/rag模式.md当：

  • 构建RAG（检索增强生成）系统
  • 需要带有分块策略的文档摄取管道
  • 实施带有余弦相似度的语义搜索
  • 构建带有历史的对话RAG
  • 需要引用RAG或多查询RAG模式
  • 想要过滤RAG、流式RAG或混合搜索的完整示例
  • 需要带有K-means实现的文档聚类

加载参考资料/vectorize集成.md当：

  • 为嵌入设置Cloudflare Vectorize索引
  • 需要带有Vectorize插入/查询模式的完整RAG示例
  • 配置Vectorize的维度/指标设置
  • 实施元数据最佳实践
  • 排除与Vectorize的维度不匹配错误
  • 需要索引管理命令（创建/删除/列表）

加载参考资料/维度指南.md当：

  • 决定使用768、1536或3072维度
  • 需要存储成本分析（100k vs 1M向量）
  • 理解准确性权衡（MTEB基准测试）
  • 在不同维度间迁移
  • 想要查询性能比较
  • 用于最佳维度选择的测试方法

加载参考资料/模型比较.md当：

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

加载参考资料/前错误.md当：

  • 遇到任何8个文档化错误
  • 需要详细的根本原因分析
  • 想要经过生产测试的解决方案和代码示例
  • 为生产系统构建错误处理
  • 需要部署前的验证清单

使用捆绑资源

模板（templates/）

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

参考资料（references/）

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

脚本（scripts/）

  • check-versions.sh - 验证@google/genai包版本为最新

官方文档

相关技能

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

成功指标

令牌节省：~60% 相比手动实现 预防错误：8个文档化错误和解决方案 生产测试：✅ 在RAG应用中验证 包版本：@google/genai@1.27.0 最后更新：2025-11-21

许可证

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

问题或问题？