# 集合标签体系与范围过滤

> 掌握知识库集合标签创建、多维属性挂载，以及在应用中通过标签限定检索范围。

Source: https://doc.fastgpt.cn/zh-CN/guide/dataset/collection_tags

在包含大量不同部门、产品线或密级资料的综合知识库中，使用集合标签能够实现检索范围的前置精准过滤，避免无关业务数据相互干扰。

## 标签体系规划原则

建议根据组织管理维度建立正交的标签集合：

* **组织架构维度**：`Finance`（财务部）、`HR`（人力资源部）、`Legal`（法务部）、`Tech`（技术研发部）。
* **业务产品维度**：`Product-A`、`Product-B`、`Global-SaaS`。
* **安全密级维度**：`Public`（公开）、`Internal`（内部）、`Confidential`（机密）。

![两份已处理资料分别设置部门标签](/imgs/optimized/current/tags-collections.png.webp)

## 步骤一：创建与管理标签定义

1. 进入目标知识库，点击右上角的“标签管理”（需具备该知识库的写权限）。
2. 点击“+ 添加标签”，输入标签名称（最长 20 个字符）并选择标签属性（标签创建后属性类型固定，标签名称可随时重命名；删除标签会同步移除该知识库下所有文件已绑定的该标签数据）：

| 标签属性   | 适用场景              | 赋值方式与限制                                | 示例                             |
| :----- | :---------------- | :------------------------------------- | :----------------------------- |
| **选项** | 适合固定分类或一对多归属场景    | 单个文件可勾选多个选项（单文件最多 64 个选项，单选项最长 256 字符） | `部门`（`Finance`、`Support`、`HR`） |
| **数字** | 适合按大小或数值区间比较的量化指标 | 单个文件填写 1 个整数值                          | `保密等级`（`1`、`2`、`3`）            |
| **日期** | 适合具有明确时效性的文档时间节点  | 单个文件选择 1 个日期时间（精确到 `YYYY-MM-DD HH:mm`） | `生效日期`（`2026-01-01 09:00`）     |

3. **选项管理**：点击选项属性标签右侧的设置图标（`⚙`）进入选项管理，支持预先录入标准分类词、重命名选项（自动同步更新所有已绑定该选项的文件）以及删除选项（自动从已绑定文件中移除该选项值）。在为集合打标时，也可直接在输入框中输入新选项名称并按回车快速创建。
4. **跨知识库过滤时的标签展示**：当应用或工作流同时关联多个知识库时，过滤条件中的自定义标签下拉列表仅展示在所有已选知识库中**名称和属性类型均完全一致**的共有标签（选项标签的可选值为各知识库选项的并集）。
5. **历史标签升级**：从旧版本升级时，系统会自动将旧版本的纯字符串标签迁移为名为 `default_tag` 的选项属性标签，原打标关系完整保留；可在标签管理中将其重命名为业务名称。
6. **重命名影响**：过滤条件依据标签名称与选项值文本进行匹配。重命名标签或选项后，需同步更新已保存的过滤配置。

## 步骤二：为集合挂载标签

1. 进入知识库集合列表，选择目标文件或目录集合。
2. 点击集合行 `···` 菜单中的“标签设置”，打开“设置标签”弹窗。
3. 勾选适用于该集合的标签条目，例如将 `travel-policy.txt` 打上 `部门: Finance` 标签。
4. 点击“确认”，检索通过集合元数据筛选可用的数据块。

![为差旅资料设置部门 Finance 标签](/imgs/optimized/current/tags-finance.png.webp)

5. **批量修改标签**：在集合列表中勾选多个文件，点击底部浮窗操作栏的“批量修改标签”：
   * **批量添加标签**：选项属性标签支持选择**追加**（默认，保留各文件原有选项并合并本次新增选项）或**覆盖**（替换为本次选择的选项）；数字与日期属性标签因单文件仅存单值，批量添加时直接覆盖原值。
   * **批量移除标签**：弹窗自动汇总所选文件已绑定的全部标签。选项属性标签支持点击右侧删除图标移除整个标签，或展开后仅勾选移除特定选项值并保留其余选项。
6. **在集合列表中按标签筛选**：点击集合列表表头上方的“标签 | 全部”筛选按钮，左列选择标签名称（角标显示已勾选值数量），右列搜索并勾选具体标签值。组合筛选规则：
   * **同一标签内勾选多个值**：为 **或（OR）** 关系，包含其中任意一个选项的文件均会展示。
   * **不同标签之间**：为 **且（AND）** 关系，仅展示同时满足各标签条件的文件。
7. **通过 API 导入与更新**：通过 OpenAPI 创建或更新集合时，请求体支持传入结构化 `tags` 数组（如 `[{"tag": "部门", "value": ["Finance"]}, {"tag": "保密等级", "value": 1}, {"tag": "生效日期", "value": 1767229200000}]`），同时兼容旧版字符串数组。若传入的标签名称在当前知识库中尚不存在，系统会根据 `value` 的数据形态自动创建对应标签定义（字符串数组创建为选项属性，数值创建为数字属性）。

## 步骤三：在应用中配置标签检索过滤

通过为应用限定检索标签，实现跨业务线的精准数据隔离：

### 1. 在对话 Agent 中配置标签过滤

在应用编辑页的「知识库」区域点击 **参数**，打开「知识库搜索配置」弹窗并切换到 **标签过滤** 标签页。添加条件行，选择标签、操作符、值来源与比较值，例如“部门 → 包含 → Finance”。多个条件可按 AND 或 OR 关系组合；引用变量时，传入值应符合标签类型。

![调试对话中仅引用差旅制度资料](/imgs/optimized/current/tags-finance-result.png.webp)

### 2. 在工作流中实现动态标签路由

在工作流画布中找到 **知识库搜索** 节点，开启 **标签过滤** 区域展开条件配置器。将问题分类节点输出的业务类别传入知识库搜索节点，用于按主题选择检索范围。需要按成员隔离敏感资料时，应配合**使用者鉴权**与集合权限实施，标签用于描述检索范围。

![Support 条件下只引用支持资料](/imgs/optimized/current/tags-support-result.png.webp)

### 3. 过滤条件组合逻辑（自定义标签 + 系统标签）

标签过滤面板分为**自定义标签**与**系统标签**两个区域，两个区域之间固定为 **`AND`（同时满足）** 关系：

1. **自定义标签**：点击“+ 添加过滤条件”选择标签、比较操作符与目标值（支持手动输入或变量引用）。存在多条自定义标签条件时，可通过左上角的 `AND / OR` 按钮切换逻辑关系（`AND` 要求全部满足，`OR` 满足任一即可）。
2. **系统标签**：基于文件自身的系统属性过滤，多条系统标签条件之间固定为 `AND` 关系：
   * **创建时间**：按文件在知识库中的创建时间过滤，支持 `大于等于`（`>=`）和 `小于等于`（`<=`）。
   * **集合 ID**：操作符固定为 `属于`，通过变量引用传入指定的集合 ID 或文件夹 ID（传入文件夹 ID 时自动递归包含其下所有子文件）。

### 4. 各属性标签支持的操作符与匹配规则

| 标签属性   | 支持的操作符                                     | 匹配规则说明                                                                                                                                |
| :----- | :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| **选项** | `等于`、`不等于``包含`、`不包含``属于`、`不属于``为空`、`不为空`   | - **等于 / 不等于**：文件的选项集合与目标选项集合完全相同 / 不完全相同（忽略顺序）- **包含 / 不包含**：文件的选项中包含全部目标选项 / 不包含全部目标选项- **属于 / 不属于**：文件的选项与目标选项存在交集（命中任一即满足）/ 无任何交集 |
| **数字** | `等于`、`不等于``大于`、`小于``大于等于`、`小于等于``为空`、`不为空` | 按数值大小进行比较。变量引用支持传入数值或可转为数值的字符串                                                                                                        |
| **日期** | `等于`、`不等于``晚于`、`早于``为空`、`不为空`              | 按时间先后进行比较。变量引用支持传入毫秒时间戳或标准日期字符串                                                                                                       |

### 5. 未打标集合（空值）匹配规则

当知识库中有部分文件尚未绑定某个标签时：

* **正向匹配**（`等于`、`包含`、`属于`、`大于`、`小于`、`大于等于`、`小于等于`、`晚于`、`早于`、`不为空`）：未绑定该标签的文件判定为不满足条件，不会被检索召回。
* **反向与空值匹配**（`为空`、`不等于`、`不包含`、`不属于`）：未绑定该标签的文件判定为满足条件，正常参与检索。

### 6. 通过变量引用传入 JSON 过滤表达式

在工作流「知识库搜索」节点中，可将输入方式从手动输入切换为 **变量引用**，直接传入 JSON 过滤表达式或字符串：

```json
{
  "tags": {
    "$and": [
      { "部门": { "$in": ["Finance", "Support"] } },
      { "保密等级": { "$lte": 2 } },
      { "生效日期": { "$gt": "2026-01-01 00:00" } }
    ]
  },
  "createTime": {
    "$gte": "2026-01-01 00:00",
    "$lte": "2026-12-31 23:59"
  },
  "collectionIds": ["6593e137231a2be9c5603ba9"]
}
```

顶层字段之间固定为 `AND` 关系：

* `tags`：自定义标签过滤条件，内部支持包含 `$and`（全部满足）或 `$or`（满足任一）条件数组。
* `createTime`：文件创建时间范围，支持 `$gte`（大于等于）和 `$lte`（小于等于）。
* `collectionIds`：限定检索的集合 ID 列表（传入文件夹 ID 时递归包含其子文件）。

| 标签属性        | JSON 操作符标识                   | 对应含义           | 示例                                        |
| :---------- | :--------------------------- | :------------- | :---------------------------------------- |
| **选项**      | `$is` / `$isNot`             | 等于 / 不等于       | `{"部门": {"$is": ["Finance", "Support"]}}` |
| **选项**      | `$contains` / `$notContains` | 包含 / 不包含       | `{"部门": {"$contains": ["Finance"]}}`      |
| **选项**      | `$in` / `$notIn`             | 属于 / 不属于       | `{"部门": {"$in": ["Finance", "Support"]}}` |
| **选项**      | `$empty` / `$notEmpty`       | 为空 / 不为空       | `{"部门": {"$empty": true}}`                |
| **数字 / 日期** | `$eq` / `$ne`                | 等于 / 不等于       | `{"保密等级": {"$eq": 1}}`                    |
| **数字 / 日期** | `$gt` / `$lt`                | 大于（晚于）/ 小于（早于） | `{"生效日期": {"$gt": "2026-01-01 00:00"}}`   |
| **数字**      | `$gte` / `$lte`              | 大于等于 / 小于等于    | `{"保密等级": {"$lte": 2}}`                   |
| **数字 / 日期** | `$empty` / `$notEmpty`       | 为空 / 不为空       | `{"保密等级": {"$notEmpty": true}}`           |

## 下一步

* 团队权限控制：学习 [集合权限控制与协作](/zh-CN/guide/dataset/collection_permission)。
* 挂载应用实操：查阅 [将知识库接入应用](/zh-CN/guide/dataset/connect-application)。
* 日常维护：学习 [数据维护与增量更新](/zh-CN/guide/dataset/update-data)。
* 标签常见排障：查阅 [知识库常见排障手册](/zh-CN/guide/dataset/faq)。
