文章摘要企业RAG为了实现租户、部门、权限、版本和有效期控制，通常会在向量检索中加入Metadata过滤。很多项目却在加过滤后出现结果从几十条变成零条，关闭过滤又恢复正常。根因可能是字段未写入、类型不一致、布尔表达式错误、日期格式不同、过滤索引缺失、权限集合为空或过滤发生在错误阶段。本文提供一套可复用的排查顺序和数据验证方法。一、典型故障不带过滤：问题：公司差旅住宿标准是多少？ Top K：10条带过滤：tenant_id = T001 AND department_id IN [D01, D02] AND status = EFFECTIVE结果：0条很多人会立刻怀疑Embedding或向量数据库，但只要关闭过滤就能召回，说明问题通常在：Payload数据 过滤表达式 权限上下文 索引二、第一步：确认字段是否真的写进数据库代码中定义了Metadata，不代表数据已经写入。入库前打印：{"chunk_id":"C001","content":"一线城市住宿标准为500元","metadata":{"tenant_id":"T001","department_id":"D01","status":"EFFECTIVE"}}再直接查询数据库中的Point或Row，确认实际Payload：{"tenantId":"T001","departmentId":"D01","documentStatus":"EFFECTIVE"}这里已经发现命名不一致：写入字段：tenantId 过滤字段：tenant_id向量数据库不会自动做驼峰与下划线映射。建议定义常量：publicfinalclassKnowledgeMetadata{publicstaticfinalString/