知识库接入：向量与重排序
了解 Embeddings 和 Rerank 的区别，按已开通模型选择协议；本页示例不代表所有接口当前可用。
给知识库找资料，通常分两步：先把文字转换成一串数字，找出意思接近的段落；再让重排序模型把候选段落排得更准确。前者叫 Embeddings（向量嵌入），后者叫 Rerank（重排序）。它们不会直接生成聊天回答。
先选对用途和协议#
| 你要做什么 | 协议与路径参考 | 使用前必须确认 |
|---|---|---|
| 文字转向量：OpenAI 兼容格式 | POST /v1/embeddings | 已开放对应向量模型；不能填普通聊天模型 |
| Gemini 向量：OpenAI 兼容方式 | 若渠道提供兼容映射，可用 /v1/embeddings | 是否提供兼容映射及映射后的准确模型 ID |
| Gemini 向量：原生方式 | 常见 Google 原生动作是 /v1beta/models/{model}:embedContent | 归壹是否开放此动作、对应版本及鉴权方式；本页不承诺原生透传可用 |
| 对候选段落重新排序 | POST /v1/rerank | 已开放专用重排序模型及兼容请求格式 |
- 1
准备模型和密钥
向平台确认向量模型或重排序模型的完整 ID、可用分组和接口格式，再创建自己的归壹 API 密钥。
- 2
从两段短文字开始
先确认价格与费用单位，使用无敏感信息的短文本。不要第一次就导入整本书或完整客户资料。
- 3
分别验收向量和重排序
两种任务通常使用不同模型；某一种成功，不表示另一种也已开通。
OpenAI 兼容：把文字转换为向量#
确认渠道开放后，完整请求地址为 https://univto.com/v1/embeddings，使用 POST，常见鉴权头为 Authorization: Bearer 加你自己的归壹 API 密钥，Content-Type 为 application/json。下面只是请求体：先替换模型占位值，再由你自己的服务端程序发送。
{
"model": "REPLACE_WITH_ENABLED_EMBEDDING_MODEL",
"input": [
"归壹支持哪些接入工具？",
"如何查看自己的使用日志？"
],
"encoding_format": "float"
}| 字段 | 含义 | 怎么使用 |
|---|---|---|
| model | 专用向量模型的完整 ID | 使用明确支持 /v1/embeddings 的型号 |
| input | 待转换的一段文字或文字数组 | 先用短文本，注意该模型的单段长度与批量限制 |
| encoding_format | 向量返回形式 | 示例为 float；是否支持 base64 由模型与渠道决定 |
| dimensions（可选） | 希望输出的向量维度 | 仅在模型明确支持时填写；不能任意压成任何长度 |
常见成功结构中，data[].embedding 是数字数组，data[].index 对应输入顺序，usage 可能记录用量。本页没有提供伪造的成功响应；以你实际获得的结构与归壹日志为准。保存向量时，同时保存原文、段落 ID、模型 ID 和维度。
Gemini 模型名称，不等于 Gemini 原生协议#
同一个 Gemini 向量模型可能通过不同协议开放。若平台明确提供 OpenAI 兼容映射，就按上一节的 model/input 结构请求；若明确提供 Google 原生 embedContent，则按该动作的 content/parts 结构请求。不要只修改模型名，就混用两套请求体。
{
"content": {
"parts": [
{
"text": "如何查看自己的使用日志？"
}
]
}
}| 原生 Gemini 内容 | 作用 | 注意 |
|---|---|---|
| 路径中的 {model} | 选择向量模型 | 用平台确认开放的精确 ID 替换，不保留花括号 |
| content.parts[].text | 要转换的文字 | 此结构不使用 OpenAI 的 input 字段 |
| taskType（可选） | 区分检索问题、检索文档等用途 | 仅按该模型支持的任务类型设置；不确定时先省略 |
| outputDimensionality（可选） | 指定输出维度 | 字段名不同于 OpenAI 的 dimensions；仍需模型支持 |
Rerank：给候选资料重新排队#
先通过检索拿到一批候选段落，再把“用户问题”和“候选段落”一起交给重排序模型。确认接口开放后，常见完整地址为 POST https://univto.com/v1/rerank，使用归壹 API 密钥鉴权；具体兼容格式以该渠道说明为准。
{
"model": "REPLACE_WITH_ENABLED_RERANK_MODEL",
"query": "如何查看使用日志？",
"documents": [
"在归壹控制台打开使用日志，按时间和模型筛选。",
"在钱包页面查看充值记录。"
],
"top_n": 1,
"return_documents": false
}| 字段 | 含义 | 怎么使用 |
|---|---|---|
| query | 这次要查的问题 | 保持原始检索意图 |
| documents | 候选段落列表 | 示例使用文字数组；对象形式须确认渠道支持 |
| top_n（可选） | 想保留前几条 | 不超过候选数量；更多候选会增加处理量 |
| return_documents（可选） | 是否连原文一起返回 | 不同服务支持情况可能不同，可从省略可选字段开始 |
| results[].index | 对应原 documents 数组的位置 | 用它找回原文，不把返回顺序当作原始位置 |
| results[].relevance_score | 当前模型给出的相关性分数 | 适合本次结果排序，不直接当成百分比或跨模型统一阈值 |
接入知识库前，再检查这几项#
- 1
统一向量规格
建库与查询使用相容的模型、维度和处理方式。换向量模型或维度后，通常需要重新生成旧资料向量；不能直接混进原来的索引。
- 2
检查结果是否完整
向量条数应匹配输入条数，维度一致且数值可解析；重排序结果的 index 应落在候选范围内。
- 3
核对日志和计费
记录时间、模型、用量与实际扣额。不要默认按段落数、字数或 Chat 模型价格收费。
- 4
再逐步扩大资料量
先验证中文问题能找到正确段落，再验证批量限制、失败重试与断点续传；避免失败后无限重跑整库。