GuidesModels

用 Gemini Embeddings 做文本向量化

按 Gemini API Embeddings 文档：用 embedContent 生成向量，配置 task 前缀或 task_type，并用 output_dimensionality 控制维度。

基于 Google AI for Developers 整理 · 官方资料 ↗

Embedding 把文本（以及更新模型上的多模态内容）映射成向量。相近语义在空间里更近，适合检索、分类、聚类，而不是靠关键词硬匹配。

官方当前主推 gemini-embedding-2（多模态统一向量空间）；纯文本场景仍可用 gemini-embedding-001。这篇先把文本向量化跑通，再补上 task 配置与维度控制。

Embeddings 能做什么

Gemini API 的 embedding 模型把内容变成数值向量。常见用途是语义搜索、分类、聚类，以及 RAG：先检索相关片段，再交给生成模型回答。

若你只想要托管式文档检索，官方也提供 File Search；需要自己掌控 chunk、索引与相似度计算时，才直接用 Embeddings。

生成第一条文本向量

用 google-genai 的 Client，调用 models.embed_content。最新模型名是 gemini-embedding-2。

官方 embedContent 最小示例

python

from google import genai

client = genai.Client()

result = client.models.embed_content(
    model="gemini-embedding-2",
    contents="What is the meaning of life?",
)

print(result.embeddings)

成功时 result.embeddings 里是向量对象；每个向量的 values 才是你要入库或算相似度的浮点数组。

Task 类型为什么重要

同一段话用于检索查询、文档入库、分类或句子相似度时，优化目标不同。官方要求按任务组织输入，否则检索质量会掉。

对 gemini-embedding-2 的非对称检索，查询侧用 task 前缀，文档侧用 title/text 结构。例如搜索：

Embeddings 2：非对称检索的 query / document 前缀

python

def prepare_query(query: str) -> str:
    return f"task: search result | query: {query}"

def prepare_document(content: str, title: str | None = None) -> str:
    if title is None:
        title = "none"
    return f"title: {title} | text: {content}"

# 对称任务（分类 / 聚类 / 句子相似度）则 query 与 document 用同一格式：
# return f"task: classification | query: {content}"

对 gemini-embedding-001，可在 EmbedContentConfig 里设 task_type。语义相似度示例：

Embeddings 1：task_type=SEMANTIC_SIMILARITY

python

from google import genai
from google.genai import types

client = genai.Client()

texts = [
    "What is the meaning of life?",
    "What is the purpose of existence?",
    "How do I bake a cake?",
]

result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=texts,
    config=types.EmbedContentConfig(task_type="SEMANTIC_SIMILARITY"),
)

print([len(e.values) for e in result.embeddings])

检索文档用 RETRIEVAL_DOCUMENT；查询用 RETRIEVAL_QUERY（001）或 task: search result（2）
分类 / 聚类 / 句子相似度属于对称任务，查询与文档格式必须一致
不要用 sentence similarity 任务去做搜索检索

用 output_dimensionality 控制向量长度

两个模型都按 Matryoshka Representation Learning 训练：默认 3072 维，也可截到更短前缀。官方推荐 768、1536 或 3072。

截断到 768 维

python

from google import genai
from google.genai import types

client = genai.Client()

result = client.models.embed_content(
    model="gemini-embedding-2",
    contents="What is the meaning of life?",
    config=types.EmbedContentConfig(output_dimensionality=768),
)

[embedding_obj] = result.embeddings
print(f"Length of embedding: {len(embedding_obj.values)}")

更短向量可省存储、加快下游计算。gemini-embedding-2 在小于 3072 时会自动归一化；001 在非 3072 维度上需要你自行归一化后再比相似度。

容易踩的坑

查询向量与文档向量对不上，检索几乎随机

检查两边是否用了同一套 task 约定；检索场景不要混用 sentence similarity 格式。

维度改小后相似度异常

确认模型：embedding-2 自动 normalize；embedding-001 需按官方说明手动归一化。

只想做文档问答却卡在自建向量库

若接受托管检索，先看 File Search；只有需要自建索引流水线时才坚持纯 Embeddings。

官方资料

Google AI for Developers

Embeddings ↗