Retrievers：召回、重排与权限过滤

抽象边界

Retriever 接收非结构化字符串 query，返回 list[Document]。它比 vector store 更宽：可以包装已有向量库、企业搜索、网页搜索、图遍历或 reranker；Retriever 只承诺“取回”，不要求能写入文档。

/retrievers 与 /retrievers/index 当前同正文，列的是自定义 BaseRetriever 实现；所有 vector store 也可通过 as_retriever() 转成 retriever。统一的 invoke() 形状并不统一 score、过滤、ACL、引用、时效和分页。

17 个路由

路由	包/实现	能力与限制
`retrievers`、`index`	`BaseRetriever` 索引	区分 bring-your-own documents 与 external index；输入 query、输出 Documents。
`bedrock`	`langchain-aws` / `AmazonKnowledgeBasesRetriever`	Bedrock Knowledge Bases 的 vector、managed KB 和 agentic retrieval；S3/KB ingestion 由 AWS 管理，调用需明确 IAM。
`box`	`langchain-box` / `BoxRetriever`	full-text search 或 Box AI；Box AI 需 Enterprise Plus 且必须给 file IDs，无文本表示的文件会跳过。
`cohere`	`langchain-cohere` / `CohereRagRetriever`	用 connector 或调用时传 documents；两者不能同时使用，传 documents 时优先且 connector 不运行；示例含 `ainvoke`。
`cohere-reranker`	`langchain-cohere` / `CohereRerank`	在 base retriever 后用 `ContextualCompressionRetriever` 重排；页面示例依赖不再维护的 community FAISS/loader。
`egnyte`	`egnyte-langchain-connector` / `EgnyteRetriever`	keyword+semantic hybrid、search options、batch；明确支持 sync、`ainvoke` 和 `abatch`。
`elasticsearch_retriever`	`langchain-elasticsearch`	直接接 Query DSL，覆盖 vector、BM25、hybrid、fuzzy、complex filter 和自定义 document mapper；普通场景优先更专用的 store 类。
`google_drive`	`langchain-googledrive` / `GoogleDriveRetriever`	从 Drive 检索文档和 description metadata；依赖用户/服务账号身份与源权限。
`google_vertex_ai_search`	`langchain-google-community`	unstructured/structured/website/blended datastore、extractive answer/segment、multi-turn search；需 Search Service API 和迁移参数核对。
`graph_rag`	`langchain-graph-retriever` / `GraphRetriever`	从 vector candidates 按 metadata edge 做 graph traversal；召回提高的同时增加 fan-out 和查询成本。
`ibm_watsonx_ranker`	`langchain-ibm` / `WatsonxRerank`	watsonx rerank + contextual compression；凭证可 API key/token/username-password，示例含 classic/community 组件。
`nvidia`	`langchain-nvidia-ai-endpoints` / `NVIDIARAGRetriever`	调 NVIDIA RAG Blueprint `/v1/search`，支持 rerank、query rewrite、metadata filter，明确支持 sync/async。
`parallel`	`langchain-parallel` / `ParallelSearchRetriever`	Search API 返回带 URL、title、publish date、search ID、excerpt、query 的 Documents；有 `ainvoke`。
`perplexity_search`	`langchain-perplexity` / `PerplexitySearchRetriever`	带来源的 web search，可按 search 参数过滤；query 会发往外部服务。
`pinecone_rerank`	`langchain-pinecone` / `PineconeRerank`	hosted rerank，支持 top-n、custom rank fields 和附加参数；它是重排器，不负责第一阶段召回。
`ragatouille`	`ragatouille<0.0.10` / ColBERT	本地/自建 late-interaction 检索；官方页明确只适用于低于 0.0.10 的版本，并建议新 ColBERT 场景查看 Pylate。

两阶段检索

可靠 RAG 常用 candidate retrieval → ACL/filter → rerank → context packing：

第一阶段用 dense、sparse、hybrid 或 graph 快速召回较大的 fetch_k。
权限过滤应尽量在数据源查询前完成；绝不能为了补足 top-k 放松 tenant/ACL。
reranker 对 query-document pair 重新打分，通常提升 precision，但网络或模型计算成本近似随候选数增长。
最后按 token 预算、来源多样性、重复段落和相邻 chunk 关系组装上下文。

Cohere/IBM/Pinecone rerank 与 cross-encoder 都属于第二阶段。把 rerank 的高分当成“事实正确率”是错误的：它只代表对 query 的相关性估计。

同步、异步与流式

当前文档明确提供 async 的只有 Cohere RAG、Egnyte、NVIDIA 和 Parallel；其他页面多展示同步调用。abatch 仍需要应用限制并发和 provider QPS。Retriever 的结果一般在一次调用完成后返回，不是 token 流；multi-turn search 也不等同于结果逐条 streaming。

外部搜索、agentic retrieval 和 rerank 应分别设置 connect/read/total timeout。重试只对确定幂等的读取生效，并保存原 query、filter、provider request/search ID 以便诊断，但日志需做隐私处理。

权限、安全与数据治理

Box、Drive、Egnyte 等企业源必须以当前用户或服务端授权主体执行，并把源 ACL 映射到 pre-filter；service account 全局可读不代表最终用户可读。
Web search 的页面和 excerpts 是不可信数据，可能含 prompt injection；保留 URL、时间和 provider metadata，只把内容当证据候选。
Bedrock/Vertex/NVIDIA 等托管检索会接收用户 query；查询可能含客户、健康或商业机密，需检查区域、保留和合规条款。
Elasticsearch Query DSL、Graph traversal 和 metadata filter 都要限制字段、深度、size 和超时，避免模型构造高成本查询。
返回文档在进入模型前做 DLP、内容长度和 MIME 检查；错误中不要泄漏底层 query、凭证或越权文档标题。

质量与运营指标

离线至少测 recall@k、MRR/nDCG、rerank gain、ACL precision、无答案率和 citation coverage；在线监控空结果率、重复率、过期率、P95/P99、provider 错误、重排候选数和每 query 成本。按语言、租户、source、query 长度和问题类型切片，不能只看总体平均值。

版本升级或更换 embedding/reranker 时固定评测集，shadow 比较后再切换。网页 search 结果随时间变化，评测需保存时间、query 参数和结果 provenance。

验证边界

已逐页核对 17 个官方 Markdown 路由、包、接口和页面声明的 sync/async/版本限制。未以真实 Box/Google/AWS/NVIDIA/搜索账号验证 ACL、配额、结果时效或 rerank 质量，生产结论仍需目标环境回归与评测集证据。