--- type: study status: verified created: 2026-08-11 updated: 2026-08-11 sensitivity: standard tags: - study - langchain - python - integrations - retriever - reranking topic: LangChain Python 检索器召回重排与权限过滤 sources: - https://docs.langchain.com/oss/python/integrations/retrievers - https://docs.langchain.com/oss/python/integrations/retrievers/bedrock - https://docs.langchain.com/oss/python/integrations/retrievers/box - https://docs.langchain.com/oss/python/integrations/retrievers/cohere - https://docs.langchain.com/oss/python/integrations/retrievers/cohere-reranker - https://docs.langchain.com/oss/python/integrations/retrievers/egnyte - https://docs.langchain.com/oss/python/integrations/retrievers/elasticsearch_retriever - https://docs.langchain.com/oss/python/integrations/retrievers/google_drive - https://docs.langchain.com/oss/python/integrations/retrievers/google_vertex_ai_search - https://docs.langchain.com/oss/python/integrations/retrievers/graph_rag - https://docs.langchain.com/oss/python/integrations/retrievers/ibm_watsonx_ranker - https://docs.langchain.com/oss/python/integrations/retrievers/index - https://docs.langchain.com/oss/python/integrations/retrievers/nvidia - https://docs.langchain.com/oss/python/integrations/retrievers/parallel - https://docs.langchain.com/oss/python/integrations/retrievers/perplexity_search - https://docs.langchain.com/oss/python/integrations/retrievers/pinecone_rerank - https://docs.langchain.com/oss/python/integrations/retrievers/ragatouille last_verified: 2026-08-11 --- # 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`： 1. 第一阶段用 dense、sparse、hybrid 或 graph 快速召回较大的 `fetch_k`。 2. 权限过滤应尽量在数据源查询前完成；绝不能为了补足 top-k 放松 tenant/ACL。 3. reranker 对 query-document pair 重新打分，通常提升 precision，但网络或模型计算成本近似随候选数增长。 4. 最后按 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 质量，生产结论仍需目标环境回归与评测集证据。