Embedding 与 Rerank 检索 API

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

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

最小 Embedding 请求

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

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

最小 Rerank 请求

Copycurl "$BASE_URL/v1/rerank" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina-reranker-v3.5",
    "query": "如何取消订阅？",
    "documents": ["可以导出使用日志。", "在账单页打开订阅并选择取消。", "API Key 可随时轮换。"],
    "top_n": 2,
    "return_documents": true
  }'

响应的 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 和最终引用文档。