Embedding 与 Rerank 检索 API

小白：召回与重排各做什么

POST /v1/embeddings 把查询和文档映射到向量，用近邻索引从海量语料快速召回候选；POST /v1/rerank 同时读取查询和一组候选，返回每项的 index 与 relevance_score，用于精排。典型 RAG 链路是权限过滤 → 向量召回 → Rerank → 组装上下文，而不是先检索全部数据再做权限过滤。

路由存在不等于当前 Key 一定有可用模型。调用前先在令牌管理创建本站 API Key，再打开模型广场，确认当前 Key 或账户所属分组能够看到 Embedding 模型。模型广场当前已公开 text-embedding-3-small 等型号，但详情中的端点标签暂未正确显示 /v1/embeddings，不要把其中显示的通用聊天端点当作 Embedding 请求路径。

本页只选择 text-embedding-3-small 作为代表型号，不表示列出全部 Embedding 模型。如果当前 Key 分组看不到该型号，请选择模型广场中当前分组可见的其他 Embedding 型号，或先向本站确认渠道配置：

Copyexport BASE_URL="https://api.tu-zi.com"
export API_KEY="你的本站 API Key"
export EMBEDDING_MODEL_NAME="text-embedding-3-small"

最小 Embedding 请求

Copycurl "$BASE_URL/v1/embeddings" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<JSON
  {
    "model": "$EMBEDDING_MODEL_NAME",
    "input": ["退款政策是什么？", "订阅可在账单页取消。"],
    "encoding_format": "float"
  }
JSON

响应 data[] 的 index 对应输入顺序，embedding 是向量。建库前固定模型、dimensions、文本规范化、切块器版本和距离度量；同一索引不能混入不同维度或不同模型的向量。批量输入可提高吞吐，但必须限制单批文本数、总 token 和响应体内存。

Rerank 当前可用性

本站保留 /v1/rerank 兼容路由，但截至本文复核时，公开模型广场没有列出可验证调用的 Rerank 模型。因此本页不提供“复制即可执行”的 Rerank curl，也不要把其他平台的模型名称直接填入本站请求。

后续只有在模型广场明确列出 /v1/rerank、精确模型 ID 和当前 Key 可用分组后，才应发送 query、documents、top_n 与 return_documents。响应的 index 指向原始 documents；不要按返回位置反推文档。return_documents=false 可减少响应体，但应用必须保存稳定的候选 ID 映射。

切块、索引和权限

切块应保留文档 ID、租户、ACL、来源位置、更新时间和内容哈希。先用结构化权限过滤缩小合法语料，再做向量召回；Rerank 也只能接收当前用户有权查看的候选。远程内容进入索引前做格式解析、提示注入标记、恶意链接和敏感数据检查。删除源文档时同步删除向量、缓存和派生摘要。

评测、阈值与迁移

使用真实查询建立带相关性标注的数据集，至少观察 Recall@K、MRR、nDCG、无答案准确率、延迟和单次成本。relevance_score 不是跨模型统一概率；阈值要按模型和领域校准。更换模型、维度、切块器或距离度量时创建新索引，双写或离线重建，灰度比较后切换，并保留可回滚的旧版本。

专家：容量、缓存和故障模式

为 Embedding 批处理设置 token、项目数、并发和响应字节上限，采用流式读取源文档与有界工作队列。缓存键必须包含模型、维度、规范化版本和内容哈希。Rerank 候选过多会增加延迟与费用，先限制召回 K，再按领域动态选择 top_n。对空向量、NaN、维度不符、索引延迟、过期 ACL、候选 ID 错位和模型降级建立告警；使用日志要关联查询版本、索引版本、模型、Request-ID 和最终引用文档。