- 固定过滤条件由管理员配置，形成 Agent 不可修改的业务边界。
- Agent 动态过滤由 Agent 根据用户问题和对话上下文按需生成，用来进一步提高召回精度。
适用场景
智能过滤特别适合以下场景：- 一个知识库存放多个专业领域或项目的文档；
- 不同 Agent 共享同一批知识，但只能检索各自负责的范围；
- 报价、合规、客服等应用需要先满足结构化条件，再进行语义匹配；
- 用户问题中经常包含年份、地区、文件格式、文档状态或分类；
- 需要在调试和审计中还原“为什么检索到这些内容”。
metadata.domain = 水利 和 metadata.documentStatus = effective，用户询问“查找 2025 年 PDF 定额”时，Agent 可再自动增加年份、PDF 和文件名条件。
两层过滤如何协作
如果 Agent 无法从问题中确定可靠条件，它会省略动态过滤，只在固定条件范围内执行检索。固定条件不会作为工具参数暴露给 Agent。
条件合并规则
一次查询的有效范围可理解为：AND。每一层内部可以使用 AND 或 OR 分组，因此可以表达“有效文档，并且属于华东或华南区域”等组合条件。
可过滤字段
系统字段
document.folderPath 是知识库内的逻辑路径，不是服务器文件存储路径。使用“位于目录下（under）”时，系统会匹配当前目录及其子目录，并按完整路径段判断，不会把 水利 错误匹配为 水利工程旧版。
文件夹路径的取值与匹配规则
XpertAI 根据知识库目录树生成文件夹路径。界面中的面包屑 水利 > 华东 对应规范值水利/华东。
- 规范路径使用
/分隔目录名，不包含开头或结尾的/。 - 直接位于知识库根目录的文档，其文件夹路径为空字符串；召回测试的目录选择器将其显示为 /（根目录）。
- **等于（
eq）**只匹配当前目录的完整路径。水利/华东不会包含水利/华东/归档。 - **位于目录下（
under）**匹配所选目录及其全部后代目录。系统会先规范化首尾斜杠，再按完整路径段判断。 - 召回测试面板会列出已有目录并提交规范路径，避免手工抄写面包屑造成顺序或斜杠错误。
filePath 值作为过滤条件。filePath 标识内部或外部存储对象，可能包含自动生成的目录、ID 或文件名；它不属于公开过滤字段，也不要求在逻辑目录重命名或移动时变化。
创建、重命名或移动文件夹时，系统会更新该目录及其后代的逻辑路径，并将最新属性同步至 PGVector 或 Milvus，不重新计算 embedding。系统升级时，历史逻辑路径同样根据父子目录关系重建，而不是从存储路径推断。
业务元数据
知识库的 metadata schema 可以声明文档级或分块级字段：metadata.<字段>：应用于整份文档及其所有分块，例如领域、年份、地区、文档状态。chunk.metadata.<字段>：只应用于对应分块，例如章节类型、专业编码、清单类别。
过滤操作符
系统会根据字段类型提供可用操作符，避免错误比较。
精确匹配用于等于和属于；文本包含、开头为和结尾为不区分大小写。日期时间统一使用 ISO-8601 UTC 格式。
配置固定过滤条件
固定条件配置在数字专家或工作流节点与知识库的绑定上，而不是设置成知识库的全局策略。这样，同一个知识库可以安全地服务多个 Agent，每个绑定拥有不同边界。- 在 Studio 中打开数字专家的知识库节点，或工作流中的知识检索节点。
- 添加或选择知识库，并将检索模式设置为 Vector。
- 在“固定过滤条件”区域添加字段、操作符和值。
- 根据需要创建
AND或OR分组。 - 保存并使用测试面板验证结果。
允许 Agent 自动过滤
在同一个知识库绑定中开启“允许 Agent 自动过滤”后，知识检索工具会向 Agent 提供所有可用系统字段和 metadata schema 字段，以及对应类型、枚举值和操作符。 Agent 会结合用户问题和对话上下文决定是否添加动态条件。例如用户询问：查找 2025 年 PDF 水利工程定额。Agent 可以生成以下动态条件：
让 Agent 查询实时过滤选项
文件夹名称、文件类型和业务 metadata 值都属于知识库中的实时数据，因此不应要求 Agent 根据对话猜测。开启 Agent 自动过滤后，XpertAI 会同时为该知识库注册一个只读的“知识过滤选项”工具。 Agent 可以先在不指定字段的情况下调用工具，查看全部可发现字段、字段类型、允许的操作符和选项形式；再选择一个字段查询：- 实际存在的文件名、扩展名、MIME 类型、分类、来源类型、枚举值、布尔值和字符串值；
- 数值和日期时间的不同取值，以及当前最小值和最大值；
- 字符串数组、数值数组 metadata 中可选择的成员值；
- 对主要使用
exists的字段，比较合格文档/分块数与字段实际存在数； - 使用不区分大小写的关键词搜索值，或分页读取完整列表；
- 将返回值原样复制到知识检索工具的动态条件中。
""），返回当前目录和后代文档数，并补充可用于 under 的祖先路径。
例如，用户提到“华东目录”时，Agent 可以按以下顺序执行：
filePath。所有实时值和计数都会先经过租户、组织、知识库、启用状态以及管理员固定条件的约束；固定条件本身仍对 Agent 隐藏，固定变量缺失时选项查询也会像正式检索一样失败关闭。空目录和没有合格分块的目录不会返回；祖先目录仍可返回，因为它们可以作为 under 操作符的有效选项。
先探索 GraphRAG，再检索知识分块
绑定的知识库启用 GraphRAG 后，XpertAI 还会为 Agent 提供只读的“知识图谱探索”工具。当用户只知道某个概念或关系，却不知道文档中的准确术语时，Agent 不必要求一次图查询直接给出最终答案，而可以通过多次小调用逐步探索：- 使用
search输入问题或简短概念，语义查找候选种子实体。 - 使用
neighbors和上一步返回的实体 ID，沿相关关系展开一到两跳。 - 使用
evidence查看某个候选实体在当前范围内的支持证据。 - 关系仍不清楚时继续探索；信息充分后，将
suggestedRetrievalQuery交给知识召回工具，检索最终原始分块和引用。
action、query、entityId、depth 和 take。实体 ID 由前一次调用返回，Agent 不需要构造复杂嵌套图表达式，也不需要猜测内部标识。
知识图谱探索和过滤选项查询可以配合使用：过滤选项工具发现实时目录、文件类型、年份和 metadata 等结构化值；图谱探索工具发现从文档内容抽取的实时实体、名称和关系。Agent 可以综合两类信息，再调用知识召回工具。
每次图谱结果都会经过租户、组织、知识库、启用状态和固定条件边界校验。实体只有在当前有效范围内存在合格分块证据时才会返回；关系也必须在范围内存在支持证据。固定条件生效时，系统不会返回可能由边界外文档聚合得到的全局实体描述、摘要、别名和统计数量。固定变量缺失时，会在图谱探索前失败关闭。
图谱证据只用于探索线索，不作为最终回答来源。Agent 会在探索完成后调用知识召回工具，让普通回答继续使用完整分块和可追溯引用。该辅助工具不等于开启带过滤的 Graph 或 Hybrid 检索模式；当前版本的最终过滤检索仍使用 Vector。
有关图谱抽取、索引、可视化治理、检索模式和运维建议，请参阅知识图谱与 GraphRAG。
异常与零命中处理
- 动态条件中出现未知字段、类型错误或非法操作符时，整组动态条件会被舍弃，系统改用固定条件检索，并记录
invalid_dynamic_filter。 - 合法动态条件返回零条结果时，服务端不会自动放宽范围。
- 工具会告诉 Agent 本次结果为零，并标记可以在不带动态条件的情况下重试；是否重试由 Agent 根据任务判断。
- 禁用文档和禁用分块在所有调用路径中都不会被召回。
测试与诊断
知识库测试面板和 Agent 调试界面会显示：- 固定条件、调用方测试条件和 Agent 动态条件；
- 最终生效条件及每个条件的来源；
- 候选文档数、候选分块数和最终命中数；
- 向量后端、过滤耗时和向量检索耗时；
- 动态条件是否因校验失败而降级，以及对应原因。
支持范围
最佳实践
- 用固定条件表达安全边界、适用领域、文档生效状态和项目范围。
- 只在用户问题中经常出现且数据质量可靠的字段上启用 Agent 自动过滤。
- 枚举类属性优先使用 enum，而不是自由文本，减少拼写差异。
- 年份使用数值，生效时间使用日期时间，布尔属性保存为布尔值，不要全部保存成字符串。
- 文件夹用于内容组织，metadata 用于稳定业务语义；二者可以组合使用。
- 上线前使用代表性问题测试“带动态条件”“不带动态条件”“零命中”和“固定变量缺失”等场景。