Gemini API Embeddings 文本向量怎么用:gemini-embedding 调用、任务类型(task_type)与维度裁剪

用 Gemini API 搭 RAG 知识库或做语义搜索时,gemini-embedding-001 怎么调?本文按官方文档整理单条与批量向量化代码、8 种 task_type 选型表、维度裁剪(768/1536)及 L2 归一化必做步骤。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 其他 账号

结论先说

  1. 主力文本向量模型是 gemini-embedding-001:通过 client.models.embed_content 调用,contents 既能传单条字符串,也能传字符串列表一次生成多条向量。
  2. 做 RAG 检索时,入库和查询必须分设不同的 task_type:文档切片入库时设 RETRIEVAL_DOCUMENT,用户搜问题时设 RETRIEVAL_QUERY,专门对齐非对称检索空间。
  3. 支持用 output_dimensionality 按需裁剪维度:默认输出 3072 维,官方推荐的轻量化档位是 1536 或 768,能大幅减少向量库存储和检索内存占用。
  4. 裁剪维度后必须手动补一步 L2 归一化:官方明确提醒,默认 3072 维返回时已是单位向量,但缩减到低维后的子向量不再保持模长为 1,算点积或余弦相似度前要先归一化。
  5. 谷歌账号准备与多工具订阅入口:使用 Gemini、Google AI Studio 与 Antigravity 需具备符合地区与年龄要求的个人谷歌账号,缺号可查看本站 谷歌账号购买说明(含带 2FA 的 谷歌邮箱成品号),跨平台付费订阅总览见 AI 会员充值中心。

Gemini Embeddings 任务类型与维度配置

图:本站根据 Gemini API 官方文档:Embeddings 整理的示意图

本文根据 Google AI for Developers 官方文档《Embeddings》《Gemini Developer API pricing》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Google 官方网站。

适用于谁

  • 准备用 Gemini API 给本地 Markdown、PDF、客服问答库做向量化入库(RAG)的开发者;
  • 搜「gemini embedding api」,想知道 task_type 该填哪一个、文档入库和用户提问为什么要填不同值的人;
  • 向量数据库(如 pgvector、Milvus、Qdrant)嫌 3072 维太占内存或受索引上限限制,想安全缩减到 768 或 1536 维的人。

一、基础调用:单条与多条文本一次转向量

先确认本地已装好 google-genai 并配好环境变量 GEMINI_API_KEY(未配置见 Gemini API Key 申请与配置教程)。调用 embed_content 把多段文本转成浮点数向量只需几行代码:

python
from google import genai
from google.genai import types

client = genai.Client()

result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=[
        "支持七天无理由退货,拆封后需保留完整原包装。",
        "工作日 16:00 前下单当天发出,默认发顺丰快递。",
    ],
    config=types.EmbedContentConfig(
        task_type="RETRIEVAL_DOCUMENT",
        output_dimensionality=768,
    ),
)

for idx, emb in enumerate(result.embeddings):
    print(f"第 {idx + 1} 条向量维度:{len(emb.values)},前 4 维:{emb.values[:4]}")

如果有几十万条历史文档要离线建库,还可以走官方批量向量异步接口(client.batches.create_embeddings)享标准价五折优惠,速率限制与计费口径见 Gemini API 免费额度与限速说明 与 Gemini API 价格说明。

二、task_type 八种任务类型怎么选(别全用默认)

在 RAG 知识库场景里,用户问的是短短一句「怎么退货」,库里存的是几百字的售后规则——两者长度和语体不对等。指定任务类型能让模型把向量投影到最适合该下游任务的子空间:

task_type 参数值适用场景配套用法说明
RETRIEVAL_DOCUMENT知识库文档入库给待检索的文章段落生成向量,可配合 title 传标题
RETRIEVAL_QUERY用户搜索词向量化在线检索时把用户的提问转成向量,匹配 RETRIEVAL_DOCUMENT
CODE_RETRIEVAL_QUERY自然语言搜代码输入功能描述,去代码片段库里检索对应函数
QUESTION_ANSWERING标准问答对匹配问题侧用此类型,答案段落侧搭配 RETRIEVAL_DOCUMENT
FACT_VERIFICATION事实核查找证据待核实的陈述句用此类型,去语料库里找支撑原文
SEMANTIC_SIMILARITY两段话语义判重对称比较两句话意思是否相近,两边填同一个类型
CLASSIFICATION文本分类特征把向量喂给下游分类器识别工单类别或情绪标签
CLUSTERING无监督话题聚类把大批用户反馈自动聚成若干热点主题簇

一句话记忆:对称比相似用 SEMANTIC_SIMILARITY;短问题搜长文档,存用 RETRIEVAL_DOCUMENT,查用 RETRIEVAL_QUERY。横向对比 OpenAI 同类模型见 OpenAI Embeddings 向量使用教程。

三、维度裁剪(MRL)与必做的 L2 归一化代码

维度裁剪与 L2 归一化检索四步

图:本站根据 Gemini API 官方文档:Embeddings 整理的示意图

gemini-embedding-001 采用套娃表示学习(MRL)训练,最重要特征集中在最前面的维度。通过 output_dimensionality 把默认的 3072 维截断成 1536 或 768 维时,无需重训模型即可把存储压降一半到四分之三,也兼容部分向量索引的 2000 维上限。

注意一个关键数学细节:官方说明 3072 维完整向量出厂已是单位向量,直接点积等于余弦相似度;但裁剪成 768 或 1536 维后模长不再等于 1。入库和检索前请务必补做 L2 归一化:

python
import numpy as np
from google import genai
from google.genai import types

client = genai.Client()

def l2_normalize(vec: list[float]) -> np.ndarray:
    arr = np.array(vec, dtype=np.float32)
    norm = np.linalg.norm(arr)
    return arr / norm if norm > 0 else arr

docs = ["退款会在审核通过后 1 至 3 个工作日原路退回。", "修改收货地址请在发货前联系在线客服。"]
doc_res = client.models.embed_content(
    model="gemini-embedding-001",
    contents=docs,
    config=types.EmbedContentConfig(task_type="RETRIEVAL_DOCUMENT", output_dimensionality=768),
)
doc_matrix = np.vstack([l2_normalize(e.values) for e in doc_res.embeddings])

query_res = client.models.embed_content(
    model="gemini-embedding-001",
    contents="申请退钱之后多久能到账?",
    config=types.EmbedContentConfig(task_type="RETRIEVAL_QUERY", output_dimensionality=768),
)
scores = doc_matrix @ l2_normalize(query_res.embeddings[0].values)
best_idx = int(np.argmax(scores))
print(f"最匹配文档:{docs[best_idx]}(相似度:{scores[best_idx]:.4f})")

若准备海外开发环境时需要独立 Google 账号开通 AI Studio 和 API 项目,可查看本站 谷歌账号购买说明 或浏览 充值服务总览。

常见问题

问:能不能入库时存 768 维,查询时忘记传维度用默认 3072 维去搜?

答:不能。维度不一致在任何向量数据库里都会直接报错,建库与在线检索必须锁定同一个模型名称和同一个维度数字。

问:升级向量模型后需要重跑全库索引吗?

答:必须全量重新生成向量(Re-index)。不同模型的向量空间互不相通,即便把维度裁成一样的数字,算出的余弦距离也没有意义。

问:单条文本最长能塞多少字进去转向量?

答:向量模型的单条输入上限(数千 token 级)远小于对话模型的百万窗口,以官方 Models 页标注为准。长文档建议按 300 至 800 字做语义分块(Chunking)效果更稳。

问:没有可用的个人谷歌账号,或者同时想开其他主流 AI 会员怎么办?

答:本站提供即买即发的 谷歌邮箱成品号(登录方法见 谷歌账号购买页),同时支持支付宝、微信支付与 AlipayHK 自助充值 ChatGPT Plus、Claude Code 等主流服务,实时价格与质保细则以各商品页说明为准。

相关教程

参考资料

  • Gemini API 官方文档:Embeddings — https://ai.google.dev/gemini-api/docs/embeddings
  • Gemini Developer API pricing — https://ai.google.dev/gemini-api/docs/pricing

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同模型

  1. 01

    用 Google Takeout 单独备份导出 NotebookLM 笔记本与 Gemini 记录:只勾选指定服务不下载整个云端硬盘的步骤

    想把 NotebookLM 里的几十个研究笔记本、来源副本与音频概览,连同 Gemini 聊天记录一起备份到本地,又怕 Google Takeout 把整个云端硬盘和相册全打包?本文讲清先取消全选、精准勾选两项服务、解压目录查看与跨号迁移的做法。

    Gemini0
  2. 02

    Google Workspace 企业/教育版管理员怎么在后台给成员开启 Gemini 应用、NotebookLM 与设置年龄访问权限

    团队成员或学校师生登录 Google Workspace 账号时提示无权使用 Gemini 或打不开 NotebookLM?本文按 Google 管理控制台官方文档整理服务开关路径、组织部门(OU)与群组放行、18 岁年龄访问权限设置及对话保留合规配置。

    Gemini0
  3. 03

    安卓手机默认助手换成 Gemini 后设闹钟、发短信或控制智能家居失灵怎么办:Workspace 与实用程序扩展开启步骤

    安卓手机把默认语音助手从 Google Assistant 换成 Gemini 后,喊它定闹钟、开手电筒、发短信或开关智能灯全都没反应?本文按官方帮助中心整理实用程序(Utilities)、Google Home 与 Workspace 关联应用开启步骤及锁屏放行设置。

    Gemini0
  4. 04

    Gemini 写长代码或长文档到一半突然停住、格式截断怎么无缝续写:锚点接续指令与 Canvas 分块修改技巧

    让 Gemini 写几百行代码或万字长文时经常写到一半突然停住、Markdown 代码块没闭合,直接回「继续」又重头抄一遍?本文整理字面锚点续写指令、代码块防乱码补齐法与 Canvas 局部圈选修改工作流。

    Gemini0
  5. 05

    NotebookLM 中文音频播客(Audio Overview)高阶玩法:用自定义引导词控制对谈深度、受众水平与重点章节(附模板)

    NotebookLM 生成的中文音频播客总是泛泛而谈、漏掉核心章节或夹杂生僻英文缩写?本文按官方帮助中心整理来源勾选过滤、四种播客格式搭配与三维自定义引导词写法,附 4 套可直接复制的中文控场模板。

    Gemini0
  6. 06

    NotebookLM 添加 YouTube 视频、网页或扫描版 PDF 提示「无法导入来源」怎么办:无字幕、反爬与纯图 PDF 逐项解决

    往 NotebookLM(Gemini Notebook)塞 YouTube 链接、外文网页或扫描教材时总是亮红叹号提示无法导入来源?本文按官方帮助中心逐项排查无字幕视频、反爬动态页与加密纯图 PDF 的替代导入步骤。

    Gemini0

同产品的其他教程

  1. 01

    iPhone 操作按钮(Action Button)或锁屏小组件一键开启 ChatGPT / Gemini 实时语音对话配置教程

    每次在 iPhone 上练口语或语音提问都要解锁、找图标、再点耳机按钮太繁琐?本文整理利用 iPhone 操作按钮(Action Button)、iOS 18 锁屏底部控制项、控制中心与背面轻点一键直达 ChatGPT 实时语音或 Gemini Live 的完整步骤。

    ChatGPTGemini0
  2. 02

    Firebase Studio(原 Project IDX)是什么、怎么用:浏览器云端全栈开发环境搭配 Gemini 智能体实战

    以前收藏的 Project IDX 网址为什么跳到了 Firebase Studio?本文按 Google 官方文档讲清它的全栈云端定位、App Prototyping 原型智能体、Code 视图切换、.idx/dev.nix 环境定制与免费工作区上限。

    Gemini其他 AI 工具0
  3. 03

    Google Colab 内置 Gemini 编程助手怎么用:免费云端 GPU 笔记本自动生成数据分析代码、修报错与限额说明

    不用配本地 Python 环境,怎么在 Google Colab 云端笔记本里免费用 Gemini 自动写数据分析代码、一键修复红字报错并跑 Data Science Agent?本文整理四大入口用法、Secrets 密钥管理与免费版限额。

    Gemini其他 AI 工具0
  4. 04

    Gemini API Token 计数(count_tokens)与多模态计费规则:图片分辨率、音频秒数与视频帧率怎么折算 Token

    传一张高清截图或一段 10 分钟视频给 Gemini API 到底扣多少 Token?本文按官方文档拆解 258 图片切片、每秒 32 音频与每秒 263 视频折算公式,附 count_tokens 免费预估与降本代码。

    Gemini0
  5. 05

    Gemini API 回答被安全策略拦截(SAFETY / PROHIBITED_CONTENT)怎么办:阈值调节边界与合规提示词排查

    调用 Gemini API 翻译文档或分析安全日志时返回空白、报 finish_reason: SAFETY 或 PROHIBITED_CONTENT 怎么办?本文详解四类可调安全阈值代码写法、不可关闭的硬性红线区别与误报排查步骤。

    Gemini0
  6. 06

    Gemini API 图像生成与多轮改图怎么调:用 google-genai SDK 出图、局部修改与宽高比控制参数

    怎么用 Python 代码调用 Gemini API 生成高清配图并像聊天一样连续局部改图?本文详解 google-genai SDK 原生生图代码、多轮对话改图、参考图融合与 aspect_ratio 宽高比配置。

    Gemini0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~