向量检索怎么按租户和文档类型过滤结果

向量相似度只能回答“内容像不像”，不能替代“这个租户有没有权限看”。知识库做多租户检索时，建议把租户编号和文档类型写进 Qdrant 的 payload，再在查询的过滤器里用 must 同时限制两个字段。这样，向量负责找相关内容，payload filter 负责守住数据边界。

一、先把租户和文档类型放进 payload

故障通常从一条“相似但不属于当前客户”的结果开始：embedding 找到了语义相近的段落，却不知道它属于哪个租户。写入点时把权限边界做成结构化字段，例如 tenant_id=tenant_a、doc_type=policy、doc_id=refund-2026。字段名称一旦确定，后续写入和查询都要保持同样的类型与层级。

二、用 must 组合两个精确条件

Qdrant 的 must 表示列表中的每一个条件都要满足，正好对应“同一租户并且是某种文档”。下面的 Python 片段只展示过滤结构；向量生成仍由你的 embedding 服务负责，不能用自然语言中的“只看某租户”替代结构化过滤。

from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")

# 语义向量由上游 embedding 服务生成，这里只负责限定检索范围
query_vector = [0.12, -0.08, 0.31, 0.44]

hits = client.query_points(
    collection_name="knowledge_base",
    query=query_vector,
    query_filter=models.Filter(
        must=[
            # 租户条件是权限边界，不能省略
            models.FieldCondition(
                key="tenant_id",
                match=models.MatchValue(value="tenant_a"),
            ),
            # 类型条件把政策文档与 FAQ、产品手册分开
            models.FieldCondition(
                key="doc_type",
                match=models.MatchValue(value="policy"),
            ),
        ]
    ),
    limit=5,
)

# 只打印业务需要的字段，避免把完整正文写入日志
for point in hits.points:
    print(point.id, point.payload.get("doc_id"))

如果一个字段允许多个值，例如允许检索 policy 或 manual，可以把这个字段改成 match any；但租户条件仍应保持单值精确匹配。不要把多个租户放进 OR 列表来“复用”查询，除非调用方本身已经完成了明确的租户授权。

三、为高频过滤字段建立 payload index

过滤逻辑正确，不代表大集合上的代价可以忽略。Qdrant 官方文档建议为经常过滤的 payload 字段建立索引，并尽量在写入数据前完成。租户字段和文档类型通常是高频条件，应该先列为索引候选；不要给每一个偶尔出现的字段都建索引。

from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")

# 在持续写入前创建高频过滤字段的索引
client.create_payload_index(
    collection_name="knowledge_base",
    field_name="tenant_id",
    field_schema=models.PayloadSchemaType.KEYWORD,
)
client.create_payload_index(
    collection_name="knowledge_base",
    field_name="doc_type",
    field_schema=models.PayloadSchemaType.KEYWORD,
)

如果历史 collection 已经存在，先确认字段值类型一致，再安排索引创建和灰度查询。索引优化的是过滤路径，不会自动修复错误的租户字段，也不会把缺失 payload 的旧点变成合规数据。

四、用结果字段和边界清单复查

复查时不要只看相似度分数。至少抽样确认每个结果的 tenant_id、doc_type 和 doc_id 都存在，并与请求上下文一致；过滤后没有结果时返回“当前范围没有匹配文档”，不要偷偷扩大到其他租户。

• 字段是否在所有新写入点中存在，且没有把租户编号写成混合类型。
• 查询是否同时包含租户条件和文档类型条件，是否误用了 should。
• 索引是否覆盖高频字段，新增字段是否经过小流量检索验证。
• 空结果、字段缺失和权限拒绝是否走不同的业务分支。

这套边界的核心是职责分离：embedding 解决相关性，payload filter 解决范围，业务服务解决最终授权。三者缺一不可。

常见问题

只把 tenant_id 放进查询文本可以吗？

不可以。查询文本会影响向量相似度，却不能保证结果只来自目标租户；租户必须成为结构化过滤条件。

tenant_id 和 doc_type 都要用 must 吗？

如果要求同时满足两个条件，就应放在同一个 must 列表中。只有同一字段允许多个枚举值时，才考虑 match any。

没有建立 payload index 会查不到结果吗？

通常不会直接改变匹配语义，但大集合上的过滤性能可能变差。先保持字段类型一致，再按实际过滤频率建立索引。