11 · 元数据过滤 FilterExpression 学完能做什么用字符串表达式和 FilterExpressionBuilder 两种方式按 metadata 精确圈定检索范围实现多租户、分类、时间过滤。⏱️ 预计耗时40 分钟含动手 依赖前置第 09、10 章 pgvector 文档14带过滤的向量检索 难度一句话向量检索负责「找最像的」元数据过滤负责「限定在哪些里面找」两者结合才能做出多租户、分权限、按分类的生产级检索。1. 为什么需要过滤只靠相似度会检索到「全库最像的」但业务上你往往只想在特定范围内找只查 租户 1001 的资料 只查 分类售后 的资料 只查 2025 年之后更新的资料这些「范围」信息就存在灌库时写的metadata第 09 章里过滤就是对 metadata 下条件。2. 方式一字符串表达式直观ListDocumenthitsvectorStore.similaritySearch(SearchRequest.builder().query(退货政策).topK(3).filterExpression(category 售后 tenantId 1001).build());支持的运算符运算符含义示例!等于 / 不等于category 售后比较year 2025innin在/不在集合category in [售后,物流]||与 / 或a 1 b 2NOT取反NOT (status draft)3. 方式二FilterExpressionBuilder类型安全代码里动态拼条件时更安全、不易写错FilterExpressionBuilderbnewFilterExpressionBuilder();Filter.Expressionexprb.and(b.eq(tenantId,1001),b.in(category,售后,物流)).build();ListDocumenthitsvectorStore.similaritySearch(SearchRequest.builder().query(退货).topK(3).filterExpression(expr).build());常用构建方法eq / ne / gt / gte / lt / lte / in / nin / and / or / not与字符串运算符一一对应。4. 典型场景多租户隔离SaaS 必备// 每个请求都强制带上当前租户避免串数据StringtenantIdcurrentTenant();b.eq(tenantId,tenantId).build(); 安全要点多租户过滤应在服务端强制注入绝不能让前端传、也不能漏——否则会跨租户泄露数据。按分类 时间b.and(b.eq(category,公告),b.gte(year,2025)).build();动态拼接有就加没有不加FilterExpressionBuilderbnewFilterExpressionBuilder();ListFilter.ExpressionpartsnewArrayList();parts.add(b.eq(tenantId,tenantId).build());if(category!null)parts.add(b.eq(category,category).build());// 用 and 逐个合并 parts ...5. 过滤 相似度的执行关系similaritySearch: 1) 先按 filterExpression 圈定候选metadata 命中的行 2) 在候选里按向量相似度排序取 topK / 过阈值⚠️ 性能提醒过滤条件很「窄」命中极少时纯向量索引可能出现召回不足。这在 pgvector 文档21、22带过滤检索的召回塌陷、迭代扫描有系统讲解生产必读。6. 让过滤生效的前提metadata 要灌对过滤能不能用取决于灌库时有没有写对应字段回顾第 09 章// 灌库时写入可过滤字段vectorStore.add(List.of(newDocument(content,Map.of(tenantId,1001,category,售后,year,2026)))); 「先想清楚要按什么筛再决定 metadata 放什么」——过滤能力是灌库阶段就注定的。7. 常见坑现象原因过滤后结果为空metadata 里根本没这个字段/值或类型不符数字写成字符串过滤没生效字段名拼错或值大小写/类型不匹配窄过滤召回很差命中太少 ANN 索引特性见 pgvector 21/22跨租户看到别人数据服务端没强制注入租户过滤8. 一句话总结元数据过滤用filterExpression字符串或 Builder在相似检索前圈定范围是多租户、分类、时间等生产场景的基础能不能过滤取决于灌库时 metadata 写得对不对。第二阶段完成你现在掌握了生成向量、配置 pgvector、写入含幂等、相似检索、元数据过滤——RAG 的数据层已经打通。➡️ 下一阶段第 12–15 章进入文档处理 ETL把真实的 PDF/Markdown 读进来、分块、富化 metadata、批量灌库让知识库有真正的内容。