给 Agent 接入 Qdrant 前，先写清楚检索合同

给 Agent 接入 Qdrant 前，先写清楚检索合同

很多人把向量数据库接到 Agent 里时，第一反应是“把 embedding 存进去，再让模型查”。这条路能跑起来，但也很容易把问题藏起来：Agent 查到的东西到底来自哪个 collection？过滤条件有没有生效？分数阈值是经验值还是业务边界？召回失败时，是 embedding 问题、索引问题、payload 问题，还是查询计划本身不对？

核心判断：Qdrant 不是给 Agent 增加一个“语义搜索按钮”，而是给 Agent 增加一个需要边界、验收和失败解释的检索层。Doramagic 的 Qdrant 能力资源包也不是提示词库，它更像一份独立整理的能力资产合同：Human Manual 给阅读路线，Prompt Preview 给宿主试运行前的约束，pitfall log 和 boundary card 把不能越过的边界写出来，source map / repo evidence 提醒每个结论要回到来源验证，eval 或 smoke check 则负责把“看起来能用”变成可检查的步骤。

所以这篇不是在复述 Qdrant 的 README，也不是把同一篇内容批量发布到各处。它只讨论一个很具体的实践问题：给 AI 宿主接入 Qdrant 前，如何先写一份检索合同。

不要只验证“能插入向量”

Qdrant 的能力面不只是 collection + search。Doramagic 的项目说明书把阅读路线拆到了几个关键层：HNSW、稀疏向量、多向量检索、量化、payload indexing/filtering、分片复制、WAL 和 storage engine。这个拆法提醒了一件事：对 Agent 来说，真正的风险不在“有没有 API 能查”，而在“查询语义是否被完整约束”。

一个最小可用的 Qdrant 集成，我会先要求 Agent 输出这些内容：

• 查询目标：这次是找事实、找相似案例、找代码片段，还是做候选召回？
• collection 范围：是否允许跨 collection？如果允许，排序和去重怎么做？
• payload filter：租户、时间、文档类型、权限、版本字段是否必须参与过滤？
• score 使用方式：阈值、top-k、rerank 规则分别是谁负责？
• 空结果解释：空结果代表“没有资料”，还是“索引/过滤/embedding 可能失败”？

如果这五个问题没有回答清楚，Agent 很容易把一次“看起来合理”的向量召回包装成可靠结论。

payload filter 是权限边界，不只是查询条件

很多 RAG demo 会把 filter 当成性能优化：过滤掉不相关文档，减少召回噪音。但在真实工作流里，payload filter 经常是权限边界。

例如，一个面向客服、销售或内部知识库的 Agent 查 Qdrant 时，如果 payload 里有 tenant_id、source_type、acl_group、document_version，这些字段不应该只是“可选过滤项”。它们应该是工具调用合同的一部分。Agent 不应该自己决定“这次为了召回更多结果，先不加过滤”。

我会把它写成硬规则：

任何面向用户问题的检索调用，必须显式带上租户/权限/版本过滤。
如果缺少这些字段，工具返回 should_refuse，而不是宽松查询。

这条规则不优雅，但很实用。它能避免 Agent 在上下文不足时做“善意越权”。

向量分数不是业务置信度

另一个常见误区是把 Qdrant 返回的相似度分数直接当成答案可信度。相似度只能说明查询向量和候选向量在某个表示空间里接近，不等于答案正确，也不等于文档仍然有效。

所以我更愿意让 Agent 把检索结果分成两层：

第一层是召回证据：命中的点、payload、source id、score、collection、filter。

第二层才是回答证据：哪些命中被引用，哪些被丢弃，丢弃原因是什么，是否需要再查一次。

这样做会让输出慢一点，但能减少一种很隐蔽的问题：Agent 用一个高分但过期的片段回答，然后在文字里表现得非常确定。

量化和多向量不是“免费升级”

Doramagic 资产里提到 Qdrant 的量化、稀疏和多向量检索路线。对使用者来说，这些不是“打开就更好”的功能，而是需要测试集来决定的取舍。

量化可能节省内存和提升吞吐，但要看召回损失是否可接受。稀疏检索和 dense 检索混用时，要看关键词精确匹配和语义近似的权重如何被解释。多向量适合更细粒度的文档表示，但也会让调试变复杂：到底是哪一个子向量把结果拉上来的？

我的建议是，不要让 Agent 一开始就“自动优化索引策略”。先让它拿一组固定问题做检索验收：

• 5 个应该命中的问题；
• 3 个容易误召回的问题；
• 2 个权限或版本边界问题；
• 1 个空结果问题。

先把这 11 个问题跑稳定，再讨论量化、hybrid search、rerank 或 collection 拆分。

给 Agent 的最小检索合同

我会把 Qdrant 工具暴露给 Agent 前，先给它一段这样的合同：

你可以调用 Qdrant 做候选召回，但每次调用必须说明：
1. 查询意图：事实查找 / 相似案例 / 代码片段 / 候选召回；
2. collection 和 payload filter；
3. top-k、score 阈值和 rerank 是否启用；
4. 返回结果中哪些字段可以用于最终回答；
5. 空结果、低分结果、权限字段缺失时如何处理。

你不能把向量相似度当成事实可信度。
你不能在缺少权限/租户/版本过滤时扩大查询范围。
你不能声称 Qdrant 已在本机安装或验证，除非有单独运行记录。

这段话看起来像流程约束，但它的作用很实际：把“检索”从一个黑盒工具调用，变成一个可以复查的中间步骤。

我会怎么开始

如果今天要把 Qdrant 接进一个 AI 宿主，我不会从大规模导入开始。我会先准备一个小 collection，放 20 到 50 条来源清楚、payload 完整的样本。然后只开放一个 read-only search 工具，让 Agent 输出检索计划、执行结果和引用依据。

等这个闭环稳定后，再加写入、更新、批量导入、量化或多向量。

这不是保守，而是把调试成本放在前面。向量库一旦进入生产工作流，错误通常不是“系统完全不可用”，而是“系统给出看似合理但边界错了的结果”。这种错误更难发现。

Qdrant 本身提供的是强大的向量检索基础设施；AI 宿主需要补上的，是检索合同、权限边界和失败解释。

资料角色

• 上游项目：Qdrant repository，负责真实代码、接口和 release 事实，https://github.com/qdrant/qdrant
• 能力资产：Doramagic Qdrant 项目页，负责把项目整理成可带走、可装载、可验证的能力资源包，https://doramagic.ai/zh/projects/qdrant/
• 说明页：Doramagic Qdrant manual，适合在接入前阅读边界、pitfall、Human Manual 和 Prompt Preview，https://doramagic.ai/zh/projects/qdrant/manual/