> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/build/agent/label-filter.md).

# 知識庫標籤過濾

在 Agent 設定一次標籤過濾條件，讓 Agent 在所有對話平台都只參考符合標籤的檔案

知識庫標籤過濾讓您以 Agent 為單位，設定一組預設的標籤條件。設定後，這個 Agent 回答問題時只會參考符合條件的檔案與 FAQ，其他內容一律不參考。不論使用者從 Web Chat、LINE、API 或後台對話發問，規則都一樣。

{% hint style="info" %}
未設定標籤過濾時，Agent 會參考所有已掛載知識庫的全部檔案，行為與過去完全相同。
{% endhint %}

過去若要限制 Agent 只查某些標籤的檔案，必須在每次 API 呼叫帶入查詢元資料，或逐一設定聯絡人；現在只要在 Agent 設定頁設定一次即可。

## 使用情境 <a href="#use-case" id="use-case"></a>

一間連鎖門市的知識庫裡同時放了對外的退換貨辦法、會員點數制度，以及只給店員看的開店收銀 SOP。知識庫管理員把對外文件加上「客服可公開」標籤、內部文件加上「內部作業」標籤。接著在客服助理的設定頁開啟「標籤過濾」，點選「客服可公開」後儲存。從此顧客不論在官網 Web Chat 或 LINE 提問，Agent 都只會引用對外文件；就算顧客問到開店流程，Agent 也找不到內部 SOP，不會把內部資訊說出去。整個過程不需要工程師改任何串接程式。

## 事前準備 <a href="#prerequisites" id="prerequisites"></a>

* Agent 已掛載至少一個知識庫（在 Agent 設定頁的「<mark style="color:blue;">知識庫設定</mark>」設定）。
* 知識庫中已建立標籤，且檔案或 FAQ 已加上標籤。標籤的建立與套用方式請參考 [文件管理：標籤及元資料](/build/knowledge-base/tags-and-metadata.md)。

可選的標籤來自這個 Agent 已掛載的知識庫。Agent 掛載多個知識庫時，同一組條件會套用到全部知識庫。

## 設定標籤過濾 <a href="#setup" id="setup"></a>

{% stepper %}
{% step %}
在左側選單點選「<mark style="color:blue;">AI 助理</mark>」，選擇要設定的 Agent，進入「<mark style="color:blue;">設定</mark>」。
{% endstep %}

{% step %}
在「知識與資料」群組中點選「<mark style="color:blue;">標籤過濾</mark>」。右上角會顯示套用範圍，也就是這個 Agent 目前掛載的知識庫。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-aec3fd4687b3caaa423417cf9d2dde10320fda55%2Flabel-filter-initial.png?alt=media" alt="Agent 設定頁的標籤過濾區塊，尚未加入任何條件"><figcaption><p>尚未設定條件時，Agent 會參考全部檔案</p></figcaption></figure>
{% endstep %}

{% step %}
在「條件組 1」點選下方的標籤，將它加入條件。可以加入多個標籤，並用「<mark style="color:blue;">包含所有標籤</mark>」或「<mark style="color:blue;">包含任一標籤</mark>」決定這一組的判斷方式。
{% endstep %}

{% step %}
往下查看「<mark style="color:blue;">受影響的檔案</mark>」面板，確認哪些檔案會被檢索、哪些會被排除。面板會依目前畫面上的條件即時計算，含尚未儲存的變更。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-5675433977f7d3074d970799450b832974aec8ec%2Flabel-filter-configured.png?alt=media" alt="加入「客服可公開」標籤後，受影響的檔案面板顯示可被檢索 3 / 4 份"><figcaption><p>加入標籤後，白話說明與受影響的檔案面板會即時更新</p></figcaption></figure>
{% endstep %}

{% step %}
點選右下角「<mark style="color:blue;">儲存</mark>」。儲存後，左側「標籤過濾」項目旁會顯示「已設定」。
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
標籤過濾與 Agent 的其他設定共用同一顆「儲存」按鈕。離開頁面前請記得儲存，否則條件不會生效。
{% endhint %}

## 條件怎麼讀 <a href="#how-conditions-work" id="how-conditions-work"></a>

建構器介面用白話描述條件，不顯示 AND／OR；本手冊在括號內標註對應的邏輯，方便對照舊版畫面或 API 文件。條件分成「組內」與「組間」兩層：

| 層級              | 選項           | 意思                |
| --------------- | ------------ | ----------------- |
| 組內（同一個條件組的標籤之間） | 包含所有標籤（AND）  | 檔案必須同時有這一組列出的每個標籤 |
| 組內              | 包含任一標籤（OR）   | 檔案只要有這一組的其中一個標籤即可 |
| 組間（多個條件組之間）     | 每一組都要符合（AND） | 檔案必須同時通過每一組條件     |
| 組間              | 符合任一組即可（OR）  | 檔案只要通過其中一組條件即可    |

需要「A 或 B」這類不同組合時，點選「<mark style="color:blue;">新增一組條件</mark>」再加一組。有兩組以上時，才會出現「多組條件時」的組間切換。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-c9ac268cbac87e553237e80781808e2b70aeac98%2Flabel-filter-groups.png?alt=media" alt="兩組條件並用「符合任一組即可」串接"><figcaption><p>兩組條件：有「客服可公開」的檔案，或者有「內部作業」的檔案</p></figcaption></figure>

建構器底部會用一句話描述目前的條件，例如「助理只會參考：有「客服可公開」的檔案，或者有「內部作業」的檔案。」不確定條件設得對不對時，以這句話和「受影響的檔案」面板為準。

{% hint style="info" %}
「受影響的檔案」面板統計的是已載入畫面的檔案。知識庫檔案很多時，面板會標示「僅統計已載入的前 N 份」，實際檢索仍會套用到全部檔案。
{% endhint %}

## 套用範圍與優先順序 <a href="#scope-and-priority" id="scope-and-priority"></a>

Agent 的標籤過濾是「預設值」，套用在所有透過這個 Agent 進行的對話：Web Chat、LINE 等對話平台、API 串接，以及後台對話。

如果某次對話已經在其他層級指定了查詢元資料，會以該層級為準，Agent 預設不參與。優先順序由高到低為：

1. 單則訊息帶入的查詢元資料（例如 API 呼叫或 Web Chat 嵌入時指定）
2. 對話層級的查詢元資料
3. 聯絡人的查詢元資料
4. Agent 的標籤過濾（本頁設定）

也就是說，既有的聯絡人或 API 設定不受影響；只有在前三層都沒有指定時，才會套用 Agent 的預設條件。各層級的設定方式請參考 [知識管理權限：查詢元資料](/org/querymetadata.md) 與 [開始建構—使用「查詢構建器」](/org/querymetadata/query-builder.md)。

{% hint style="info" %}
知識庫的「搜尋測試」是用來檢查檢索品質的工具，不會套用 Agent 的標籤過濾。
{% endhint %}

## 標籤失效時 <a href="#invalid-labels" id="invalid-labels"></a>

若條件中引用的標籤已被改名、刪除，或所屬知識庫已從 Agent 卸載，重新打開設定頁時會看到失效提示，列出受影響的標籤。此時可點選「<mark style="color:blue;">移除失效標籤</mark>」一鍵清掉，或改選其他標籤後儲存。

{% hint style="warning" %}
失效標籤在檢索時不會命中任何檔案，也不會放大為檢索全部。若 Agent 突然回答不出知識庫內容，請先檢查標籤過濾是否有失效標籤。
{% endhint %}

## 清除設定 <a href="#clear" id="clear"></a>

點選建構器右上角的「<mark style="color:blue;">清除所有條件</mark>」再儲存，Agent 就會回到參考全部檔案的狀態。

若 Agent 掛載的知識庫還沒有任何標籤，這一頁會提示「掛載的知識庫還沒有任何標籤」，請先到知識庫幫檔案加上標籤。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-643602b6c5278d200b0704ca967d0ed7f678661f%2Flabel-filter-empty.png?alt=media" alt="掛載的知識庫還沒有任何標籤時的提示"><figcaption><p>知識庫尚無標籤時的提示</p></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/build/agent/label-filter.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.