Google 官方 Embeddings 文档说明，Gemini API 可以将文本内容转换为 embedding，也就是由数字组成的向量表示。这类向量用于表达文本的语义信息，常见用途包括相似内容查找、检索增强生成相关流程、分类和聚类等。
在检索场景中，文档和用户查询虽然都可以被转换为向量，但它们在任务中的角色不同。文档表示通常用于表示被检索的资料、段落或知识片段；查询表示则用于表示用户输入的问题、搜索词或信息需求。官方文档通过不同的任务类型来区分这些用途，例如用于文档侧的 RETRIEVAL_DOCUMENT，以及用于查询侧的 RETRIEVAL_QUERY。
这种区分的重点不是承诺某个固定检索分数或效果，而是让 embedding 生成过程与具体任务角色保持一致：文档 embedding 面向可被检索的内容，查询 embedding 面向检索请求。随后，应用可以根据自身系统设计，将查询向量与文档向量进行相似度比较，以寻找语义上相关的内容。
在实现时，应以官方文档中的模型、参数和任务类型说明为准，并避免把 embedding 结果解读为确定性的答案或质量保证。Embedding 是文本的向量表示，适合支持检索、匹配和组织文本，但实际检索流程仍取决于数据切分、索引方式、相似度计算和应用逻辑。
把目标拆成输入、动作和输出，再逐步加入检查点。
保留示例、失败条件和复核标准，教程才真正可复用。
提示：先用小样例验证，再扩大到真实任务。