> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 智能过滤检索

> 使用固定条件、Agent 动态条件和类型化元数据，让一个知识库安全地服务多个业务领域。

XpertAI 的**智能过滤检索**将结构化条件与向量语义检索组合在同一次查询中。你可以把工程、水利、物流、制度等不同领域的文档保存在同一个知识库中，再通过文件名、逻辑文件夹、文件类型和业务元数据缩小候选范围，避免在全库内容中无差别匹配。

该功能同时支持两类互不替代的条件：

* **固定过滤条件**由管理员配置，形成 Agent 不可修改的业务边界。
* **Agent 动态过滤**由 Agent 根据用户问题和对话上下文按需生成，用来进一步提高召回精度。

最终检索始终在租户、组织、知识库权限和启用状态约束内执行。Agent 只能缩小固定范围，不能覆盖或绕过固定条件。

## 适用场景

智能过滤特别适合以下场景：

* 一个知识库存放多个专业领域或项目的文档；
* 不同 Agent 共享同一批知识，但只能检索各自负责的范围；
* 报价、合规、客服等应用需要先满足结构化条件，再进行语义匹配；
* 用户问题中经常包含年份、地区、文件格式、文档状态或分类；
* 需要在调试和审计中还原“为什么检索到这些内容”。

例如，同一个“工程造价”知识库可以同时包含水利、物流和建筑工程资料。水利报价 Agent 的固定条件限定 `metadata.domain = 水利` 和 `metadata.documentStatus = effective`，用户询问“查找 2025 年 PDF 定额”时，Agent 可再自动增加年份、PDF 和文件名条件。

## 两层过滤如何协作

| 层级         | 配置者        | 作用               | Agent 能否修改   |
| ---------- | ---------- | ---------------- | ------------ |
| 固定过滤条件     | 管理员或工作流设计者 | 定义业务范围、权限边界和长期约束 | 不能           |
| Agent 动态过滤 | Agent      | 根据当前问题临时缩小候选范围   | 只能决定是否添加合法条件 |

如果 Agent 无法从问题中确定可靠条件，它会省略动态过滤，只在固定条件范围内执行检索。固定条件不会作为工具参数暴露给 Agent。

### 条件合并规则

一次查询的有效范围可理解为：

```text theme={null}
租户 / 组织 / 知识库边界
AND 文档与分块处于启用状态
AND 固定过滤条件
AND 调用方测试条件
AND Agent 动态过滤条件
```

固定条件与动态条件之间始终使用 `AND`。每一层内部可以使用 `AND` 或 `OR` 分组，因此可以表达“有效文档，并且属于华东或华南区域”等组合条件。

## 可过滤字段

### 系统字段

| 字段                       | 说明          | 示例                     |
| ------------------------ | ----------- | ---------------------- |
| `document.fileName`      | 文件名         | `水利工程预算定额（2025）.pdf`   |
| `document.folderPath`    | 知识库中的逻辑目录路径 | `工程造价/水利/华东`           |
| `document.fileExtension` | 规范化扩展名      | `pdf`                  |
| `document.mimeType`      | MIME 类型     | `application/pdf`      |
| `document.category`      | 文档内容分类      | `text`                 |
| `document.sourceType`    | 文档来源类型      | `local-file`           |
| `document.createdAt`     | 文档创建时间      | `2025-01-15T08:00:00Z` |
| `document.updatedAt`     | 文档更新时间      | `2025-06-01T12:30:00Z` |

`document.folderPath` 是知识库内的逻辑路径，不是服务器文件存储路径。使用“位于目录下（under）”时，系统会匹配当前目录及其子目录，并按完整路径段判断，不会把 `水利` 错误匹配为 `水利工程旧版`。

### 文件夹路径的取值与匹配规则

XpertAI 根据知识库目录树生成文件夹路径。界面中的面包屑 **水利 > 华东** 对应规范值 `水利/华东`。

* 规范路径使用 `/` 分隔目录名，不包含开头或结尾的 `/`。
* 直接位于知识库根目录的文档，其文件夹路径为空字符串；召回测试的目录选择器将其显示为 **/（根目录）**。
* \*\*等于（`eq`）\*\*只匹配当前目录的完整路径。`水利/华东` 不会包含 `水利/华东/归档`。
* \*\*位于目录下（`under`）\*\*匹配所选目录及其全部后代目录。系统会先规范化首尾斜杠，再按完整路径段判断。
* 召回测试面板会列出已有目录并提交规范路径，避免手工抄写面包屑造成顺序或斜杠错误。

不要使用文档的 `filePath` 值作为过滤条件。`filePath` 标识内部或外部存储对象，可能包含自动生成的目录、ID 或文件名；它不属于公开过滤字段，也不要求在逻辑目录重命名或移动时变化。

创建、重命名或移动文件夹时，系统会更新该目录及其后代的逻辑路径，并将最新属性同步至 PGVector 或 Milvus，不重新计算 embedding。系统升级时，历史逻辑路径同样根据父子目录关系重建，而不是从存储路径推断。

### 业务元数据

知识库的 metadata schema 可以声明文档级或分块级字段：

* `metadata.<字段>`：应用于整份文档及其所有分块，例如领域、年份、地区、文档状态。
* `chunk.metadata.<字段>`：只应用于对应分块，例如章节类型、专业编码、清单类别。

字段支持字符串、枚举、数值、日期时间、布尔值、字符串数组、数值数组和对象类型。管理员还可以为字段设置显示名称、说明和枚举值。Agent 只能使用 schema 中已登记且类型有效的字段。

<Tip>
  将长期稳定、会频繁参与检索的业务属性定义为 metadata 字段。例如 `domain`、`effectiveYear`、`region`、`documentStatus` 和 `specialtyCode`。
</Tip>

## 过滤操作符

系统会根据字段类型提供可用操作符，避免错误比较。

| 字段类型     | 常用操作符                           |
| -------- | ------------------------------- |
| 字符串、枚举   | 等于、不等于、属于、不属于、包含、不包含、开头为、结尾为、存在 |
| 文件夹路径    | 字符串操作符，以及位于目录下（当前目录及子目录）        |
| 数值、日期时间  | 等于、不等于、大于、大于等于、小于、小于等于、区间、属于、存在 |
| 布尔值      | 等于、不等于、存在                       |
| 字符串或数值数组 | 包含、包含任一、包含全部、为空、存在              |
| 对象       | JSON 包含、存在                      |

精确匹配用于等于和属于；文本包含、开头为和结尾为不区分大小写。日期时间统一使用 ISO-8601 UTC 格式。

## 配置固定过滤条件

固定条件配置在**数字专家或工作流节点与知识库的绑定**上，而不是设置成知识库的全局策略。这样，同一个知识库可以安全地服务多个 Agent，每个绑定拥有不同边界。

1. 在 Studio 中打开数字专家的知识库节点，或工作流中的知识检索节点。
2. 添加或选择知识库，并将检索模式设置为 **Vector**。
3. 在“固定过滤条件”区域添加字段、操作符和值。
4. 根据需要创建 `AND` 或 `OR` 分组。
5. 保存并使用测试面板验证结果。

固定值可以是常量，也可以引用 Agent 或工作流变量。例如：

```text theme={null}
metadata.domain 等于 "水利"
AND metadata.documentStatus 等于 "effective"
AND document.folderPath 位于目录 {{input.regionFolder}} 下
```

如果固定变量缺失、类型错误或已经失效，检索会在访问向量库前停止并返回配置错误。系统不会忽略固定边界后继续全库检索。

## 允许 Agent 自动过滤

在同一个知识库绑定中开启“**允许 Agent 自动过滤**”后，知识检索工具会向 Agent 提供所有可用系统字段和 metadata schema 字段，以及对应类型、枚举值和操作符。

Agent 会结合用户问题和对话上下文决定是否添加动态条件。例如用户询问：

> 查找 2025 年 PDF 水利工程定额。

Agent 可以生成以下动态条件：

```text theme={null}
document.fileExtension 属于 ["pdf"]
AND metadata.effectiveYear 等于 2025
AND document.fileName 包含 "定额"
```

这些条件只会进一步缩小管理员配置的水利领域和有效文档范围。

### 让 Agent 查询实时过滤选项

文件夹名称、文件类型和业务 metadata 值都属于知识库中的实时数据，因此不应要求 Agent 根据对话猜测。开启 Agent 自动过滤后，XpertAI 会同时为该知识库注册一个只读的“**知识过滤选项**”工具。

Agent 可以先在不指定字段的情况下调用工具，查看全部可发现字段、字段类型、允许的操作符和选项形式；再选择一个字段查询：

* 实际存在的文件名、扩展名、MIME 类型、分类、来源类型、枚举值、布尔值和字符串值；
* 数值和日期时间的不同取值，以及当前最小值和最大值；
* 字符串数组、数值数组 metadata 中可选择的成员值；
* 对主要使用 `exists` 的字段，比较合格文档/分块数与字段实际存在数；
* 使用不区分大小写的关键词搜索值，或分页读取完整列表；
* 将返回值原样复制到知识检索工具的动态条件中。

文档级 metadata 会返回对应的文档数和分块数；分块级 metadata 会按匹配分块及其来源文档计数。字段目录仍展示 schema 配置的枚举值，而实时值查询会说明哪些值当前实际存在于有效边界内。

目录路径会得到额外处理：工具列出规范逻辑路径，区分知识库根目录（`""`），返回当前目录和后代文档数，并补充可用于 `under` 的祖先路径。

例如，用户提到“华东目录”时，Agent 可以按以下顺序执行：

```text theme={null}
1. 查看过滤字段，再查询 document.folderPath 中的 "华东"
2. 得到 document.folderPath = "水利/华东"
3. 使用 document.folderPath under "水利/华东" 进行检索
```

工具只返回知识库相对逻辑路径，不会返回服务器 `filePath`。所有实时值和计数都会先经过租户、组织、知识库、启用状态以及管理员固定条件的约束；固定条件本身仍对 Agent 隐藏，固定变量缺失时选项查询也会像正式检索一样失败关闭。空目录和没有合格分块的目录不会返回；祖先目录仍可返回，因为它们可以作为 `under` 操作符的有效选项。

### 先探索 GraphRAG，再检索知识分块

绑定的知识库启用 GraphRAG 后，XpertAI 还会为 Agent 提供只读的“**知识图谱探索**”工具。当用户只知道某个概念或关系，却不知道文档中的准确术语时，Agent 不必要求一次图查询直接给出最终答案，而可以通过多次小调用逐步探索：

1. 使用 `search` 输入问题或简短概念，语义查找候选种子实体。
2. 使用 `neighbors` 和上一步返回的实体 ID，沿相关关系展开一到两跳。
3. 使用 `evidence` 查看某个候选实体在当前范围内的支持证据。
4. 关系仍不清楚时继续探索；信息充分后，将 `suggestedRetrievalQuery` 交给知识召回工具，检索最终原始分块和引用。

例如：

```text theme={null}
search("泵站供应商")
→ 实体 GOODSPRINGS

neighbors(实体 GOODSPRINGS)
→ GOODSPRINGS -- SUPPLIES --> 泵站设备

evidence(实体 GOODSPRINGS)
→ 支持文档/分块信息，以及建议检索词

Retriever("泵站供应商 GOODSPRINGS 泵站设备")
→ 用于回答的原始分块和引用
```

图谱工具有意采用简单参数：`action`、`query`、`entityId`、`depth` 和 `take`。实体 ID 由前一次调用返回，Agent 不需要构造复杂嵌套图表达式，也不需要猜测内部标识。

知识图谱探索和过滤选项查询可以配合使用：过滤选项工具发现实时目录、文件类型、年份和 metadata 等结构化值；图谱探索工具发现从文档内容抽取的实时实体、名称和关系。Agent 可以综合两类信息，再调用知识召回工具。

每次图谱结果都会经过租户、组织、知识库、启用状态和固定条件边界校验。实体只有在当前有效范围内存在合格分块证据时才会返回；关系也必须在范围内存在支持证据。固定条件生效时，系统不会返回可能由边界外文档聚合得到的全局实体描述、摘要、别名和统计数量。固定变量缺失时，会在图谱探索前失败关闭。

图谱证据只用于探索线索，不作为最终回答来源。Agent 会在探索完成后调用知识召回工具，让普通回答继续使用完整分块和可追溯引用。该辅助工具不等于开启带过滤的 **Graph** 或 **Hybrid** 检索模式；当前版本的最终过滤检索仍使用 **Vector**。

有关图谱抽取、索引、可视化治理、检索模式和运维建议，请参阅[知识图谱与 GraphRAG](/zh-Hans/ai/knowledge-base/knowledge-graph-graphrag)。

### 异常与零命中处理

* 动态条件中出现未知字段、类型错误或非法操作符时，整组动态条件会被舍弃，系统改用固定条件检索，并记录 `invalid_dynamic_filter`。
* 合法动态条件返回零条结果时，服务端不会自动放宽范围。
* 工具会告诉 Agent 本次结果为零，并标记可以在不带动态条件的情况下重试；是否重试由 Agent 根据任务判断。
* 禁用文档和禁用分块在所有调用路径中都不会被召回。

## 测试与诊断

知识库测试面板和 Agent 调试界面会显示：

* 固定条件、调用方测试条件和 Agent 动态条件；
* 最终生效条件及每个条件的来源；
* 候选文档数、候选分块数和最终命中数；
* 向量后端、过滤耗时和向量检索耗时；
* 动态条件是否因校验失败而降级，以及对应原因。

普通用户看到的 Agent 最终回答默认只包含答案和引用，不展示内部过滤决策。

检索日志会保存规范化条件、条件摘要、命中统计、后端和耗时等审计信息，但不会记录文档正文。日志访问权限沿用知识库权限。

## 支持范围

| 能力                | 当前支持情况                                |
| ----------------- | ------------------------------------- |
| Vector 模式         | 支持                                    |
| PGVector          | 正式支持                                  |
| Milvus            | 正式支持，要求 Milvus Server 2.6.2 或更高版本     |
| 图谱辅助探索            | 知识库启用 GraphRAG 后支持；最终过滤分块检索仍使用 Vector |
| Graph / Hybrid 模式 | 使用智能过滤配置时不支持，并明确报错                    |
| Chroma / Weaviate | 不支持新过滤条件，并明确报错                        |
| 外部知识库             | 取决于外部提供商接口；XpertAI 新过滤 DSL 不会静默传递或忽略  |

## 最佳实践

* 用固定条件表达安全边界、适用领域、文档生效状态和项目范围。
* 只在用户问题中经常出现且数据质量可靠的字段上启用 Agent 自动过滤。
* 枚举类属性优先使用 enum，而不是自由文本，减少拼写差异。
* 年份使用数值，生效时间使用日期时间，布尔属性保存为布尔值，不要全部保存成字符串。
* 文件夹用于内容组织，metadata 用于稳定业务语义；二者可以组合使用。
* 上线前使用代表性问题测试“带动态条件”“不带动态条件”“零命中”和“固定变量缺失”等场景。

接下来可阅读[维护文档与元数据](/zh-Hans/ai/knowledge-base/maintain-documents)、[召回测试](/zh-Hans/ai/knowledge-base/recall-test)和[知识库的使用方式](/zh-Hans/ai/knowledge-base/ways-to-use-knowledge-base)。