Gemini API embeddings 怎样区分对称与非对称检索

Gemini API embeddings 的“对称”和“非对称”，关键不在于向量计算公式，而在于查询端与被检索内容是否属于同一种输入分布。搜索、问答、事实核查和代码检索通常是非对称任务：短查询去找较长文档；聚类、分类和句子相似度才更接近对称任务。先把任务分清，再决定输入格式。

官方地址：https://ai.google.dev/gemini-api/docs/embeddings

先看任务：搜索检索通常是非对称

如果一侧是“用户想找什么”，另一侧是“知识库里有什么”，两侧的长度、语气和信息密度都不同，这就是非对称检索。查询应表达搜索意图，文档则保留标题和正文上下文；不能把查询和文档都套成“句子相似度”再期待它稳定完成搜索。

对称任务的两侧使用同一任务格式。例如，判断两句话是否表达相近含义时，查询与候选文本都可以使用 task: sentence similarity | query: ...。这类格式适合语义相似度，不适合把用户问题映射到文档集合。

gemini-embedding-2：把任务写进文本格式

当前文档对文本检索推荐在输入中写任务指令。搜索场景可以让查询使用 task: search result | query: ...，文档使用 title: ... | text: ...；没有标题时明确写成 title: none。问答、事实核查和代码检索只需要替换查询侧的任务名，文档侧仍保持标题与正文结构。

package main

import "strings"

// prepareSearchQuery 只给查询侧加搜索任务前缀。
func prepareSearchQuery(query string) string {
	// TrimSpace 避免用户输入的换行破坏固定格式。
	return "task: search result | query: " + strings.TrimSpace(query)
}

// prepareDocument 保留标题和正文，让文档侧与查询侧形成非对称角色。
func prepareDocument(title, text string) string {
	// 空标题用 none 表示，不要让分隔符后的内容变成歧义字段。
	if strings.TrimSpace(title) == "" {
		title = "none"
	}
	return "title: " + strings.TrimSpace(title) + " | text: " + strings.TrimSpace(text)
}

这两个函数只是准备文本，真正调用 EmbedContent 时仍要对查询和文档分别生成向量，并把相同的模型和输出维度用于索引与查询。不要把文档也包装成 task: search result | query:，那会丢掉文档角色。

gemini-embedding-001：用 TaskType 表达角色

如果项目仍使用 gemini-embedding-001，角色通过请求配置表达：查询使用 RETRIEVAL_QUERY，被检索内容使用 RETRIEVAL_DOCUMENT。代码中最容易出错的地方，是把两次请求都写成同一个 TaskType，或者把 SEMANTIC_SIMILARITY 当成搜索配置。

package main

import (
	"context"
	"fmt"
	"log"

	"google.golang.org/genai"
)

func embed(ctx context.Context, client *genai.Client, text string, task genai.TaskType) ([]float32, error) {
	// 查询和文档必须传入各自的任务类型，不能为了复用函数而固定成一种角色。
	result, err := client.Models.EmbedContent(ctx, "gemini-embedding-001",
		[]*genai.Content{genai.NewContentFromText(text, genai.RoleUser)},
		&genai.EmbedContentRequest{TaskType: task},
	)
	if err != nil {
		return nil, err
	}
	if len(result.Embeddings) == 0 {
		return nil, fmt.Errorf("embedding result is empty")
	}
	// 返回值交给索引或相似度层；这里不假设维度，避免迁移时写死旧值。
	return result.Embeddings[0].Values, nil
}

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close() // 释放客户端持有的连接资源。

	queryVector, err := embed(ctx, client, "怎样配置向量检索", genai.TaskTypeRetrievalQuery)
	if err != nil {
		log.Fatal(err)
	}
	documentVector, err := embed(ctx, client, "向量检索配置指南", genai.TaskTypeRetrievalDocument)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(len(queryVector), len(documentVector))
}

示例只展示角色配置，不把向量当作运行结果。实际项目还要确保入库时的文档 TaskType 与在线查询的 Query TaskType 成对固定；如果换模型或输出维度，应按索引策略重新生成对应向量。

迁移表：改模型时要一起改什么

迁移前可以按这份清单回归：一是确认业务目标是“找文档”还是“比文本”；二是确认模型对应的任务表达方式；三是确认文档入库与查询在线路径使用同一套模型、维度和距离计算；四是给空标题、空文本和空向量结果保留明确错误处理。

常见问题

对称任务能不能直接用于搜索？

不建议。对称任务适合比较输入之间的语义接近程度；搜索检索应明确区分查询和文档角色，优先使用非对称检索格式。

换成 gemini-embedding-2 后还要传 RETRIEVAL_QUERY 吗？

不按旧模型的字段传。文档当前说明，gemini-embedding-2 用文本任务指令表达角色；gemini-embedding-001 才通过 task_type 配置检索任务。