什么是 检索器（Retriever）？
检索器（Retriever）是查询到证据的组件，根据明确的搜索契约返回可排序、可归因的候选，或向下游 RAG 与 Agent 阶段报告显式失败。
快速了解
| 规范文档 | 官方规范 |
|---|
工作原理
先定义请求与结果契约
输入应显式包含查询文本、用户作用域、租户、语言、过滤器、topK、截止时间和目标索引版本。输出应有序，并携带不可变候选 ID、来源 URI、分块定位、内容、分数类型、原始分数、分支和版本。例如 Eino v0.9.21 定义 Retrieve(context.Context, query, options...)，返回带元数据的有序文档，并明确分数阈值负责过滤而不是排序；后端私有选项不能悄悄改写通用语义。
有意设计失败语义
取消和截止时间必须传递到每个后端。只有查询成功完成且没有符合条件的证据时才能返回空结果，不能把超时或权限服务故障折叠为空列表。可选的相关性分支可按已记录策略降级，但租户与授权检查通常应失败即关闭。重试需要受限退避、剩余时间预算和幂等读取；响应还应指出哪些分支成功、失败或被跳过。
对边界做版本化、观测与评测
把 Analyzer、查询编码器、文档编码器、索引、过滤和融合配置视为同一个检索版本。记录 Trace ID、经过脱敏的请求属性、分支延迟、候选数量、过滤选择率、去重和最终来源，但不要记录受保护正文。评测候选 Recall@K、MRR 或 nDCG、空结果率、越权、过期证据、超时率和 p95 延迟；答案质量属于下游信号，不能代替检索级标注。
主要特点
- 把应用的查询到证据契约与具体存储后端解耦
- 将作用域、过滤器、版本、结果预算和截止时间带入检索
- 返回具有稳定身份、来源和明确分数语义的有序候选
- 区分成功空结果、超时、鉴权和后端错误
- 可与查询改写、融合、重排和证据验证组合
- 构成质量、延迟、新鲜度和访问控制指标的可观测边界
常见用途
- 为有依据的回答管线提供可归因的企业知识证据
- 为编程 Agent 搜索源代码、Issue、日志和文档
- 在统一类型化结果契约下联邦查询多个知识库
- 在生成前执行租户、权限、版本和新鲜度约束
- 把检索封装为 Graph、工作流、API 或 MCP 工具中的复用组件
示例
Loading code...常见问题
检索器和向量数据库是一回事吗？
不是。向量数据库只是一种可能后端。检索器负责面向应用的请求、作用域、过滤、截止时间、结果身份、来源和失败契约，还可以同时编排多个非向量后端。
检索结果应该保留哪些字段？
至少保留稳定候选 ID、来源或引用定位、内容、元数据、检索分支、索引版本、名次和名称明确的分数语义。缺少来源与版本时，下游引用、去重、调试和重放都不可靠。
后端超时时，检索器应该返回空列表吗？
不应该。成功空列表表示没有符合条件的证据；超时、取消、配置错误和鉴权失败需要显式错误或类型化状态，调用方才能拒答、在预算内重试或执行明确的降级策略。
分数阈值可以在不同检索器之间共用吗？
默认不能。BM25、余弦、点积、重排 Logit 和归一化分数的含义与分布不同。阈值属于指定模型、索引、查询和校准契约，不能跨后端直接复制。
应该如何评测检索器？
使用查询级相关性与权限标注，测量 Recall@K、MRR 或 nDCG、空结果率、过期结果率、越权、p95 延迟、超时率和版本一致性。下游答案需单独评测，以免掩盖候选阶段问题。