> 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/org/querymetadata.md).

# 知識管理權限：查詢元資料

本篇將說明如何透過查詢元資料控管 Agent 可參考的資料、知識範圍。

## 功能說明 <a href="#feature-description" id="feature-description"></a>

AI 對話系統導入時，因使用者權限、使用需求不同通常需對 「 知識庫 / AI 助理 / 對話平台 」 的可用範圍進行細緻控管。

在 MaiAgent 中，可以利用附加在不同對話 / 身分層級的查詢元資料，決定「這個人 / 這段對話能參考哪些內容」。

### 查詢元資料是什麼？ <a href="#what-is-query-metadata" id="what-is-query-metadata"></a>

查詢元資料是一組限定查詢範圍的動態條件，能夠指定使用者在某對話平台下能查詢的 「 知識庫、FAQ、符合標籤條件的文件 」 等資料內容。

它不取代聯絡人等身分機制，而是讓身分 「 有條件地發揮作用 」 ，實現對話層級的最小權限控制。

> **訊息 / 對話 / 聯絡人 是容器，查詢元資料是掛在容器上、實際決定可視範圍的條件**

{% hint style="info" %}
**角色不是查詢元資料的容器。** 成員在後台看得到、管得到哪些 Agent 與知識庫，由 [角色權限](/org/roles/role-permission.md) 控制，是另一套機制；成員使用內部問答時，則是逐訊息選擇知識範圍（訊息層級）。兩者的差別見 [角色和聯絡人的差異](/org/roles/contact-role-comparison.md)。

透過以下文章介紹了解更多：

* [**聯絡人**](/serve/daily-operations/contact.md)
* [**角色權限管理**](/org/roles/role-permission.md)
  {% endhint %}

## 權限層級概念 <a href="#permission-level-concept" id="permission-level-concept"></a>

查詢元資料可以設定在三個層級，各自對應不同的設定方式：

| 層級      | 生效範圍      | 設定方式                                    |
| ------- | --------- | --------------------------------------- |
| **訊息**  | 僅該則訊息     | 內部問答右側的知識選擇；Web Chat 嵌入時帶入的查詢元資料；對話 API |
| **對話**  | 該段對話的所有訊息 | 建立對話的 API                               |
| **聯絡人** | 該聯絡人的所有對話 | 後台聯絡人編輯（查詢構建器或 JSON）、聯絡人 API            |

另外，Agent 本身可以設定一組預設的標籤過濾條件，作為最後的兜底，設定方式見 [知識庫標籤過濾](/build/agent/label-filter.md)。

> 可參考以下文件操作：
>
> 1. [開始建構—使用「查詢構建器」](/org/querymetadata/query-builder.md)
> 2. 技術人員手冊：[JSON 介面設定指南(聯絡人、Web chat 嵌入設定)](https://docs.maiagent.ai/tech/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces)

### 文件篩選條件判斷層級 <a href="#document-filter-condition-levels" id="document-filter-condition-levels"></a>

Agent 檢索知識時，由上而下取**第一個「有設定」的層級**，整份套用：

```
訊息 > 對話 > 聯絡人 > AI 助理的預設標籤過濾 > 皆未設定（不限制，可查 AI 助理掛載的全部知識庫）
```

* 某一層沒有設定時，往下一層查找。
* 第一個有設定的層級**整份生效**，不與下層合併：例如聯絡人設定了查詢元資料，該聯絡人的對話就不會再套用 Agent 的預設標籤過濾。
* Agent 的預設標籤過濾只在訊息、對話、聯絡人三層都沒有設定時才會套用。

透過層層傳遞，查詢元資料成為 AI 回應邏輯的實際決策依據。「空設定」與「未設定」的差別等 JSON 細節，見技術人員手冊 [開始建構—使用 JSON 格式](https://docs.maiagent.ai/tech/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces#empty-vs-unset)。

### 適用範圍與限制 <a href="#scope-and-limits" id="scope-and-limits"></a>

查詢元資料只管**知識庫檢索**（文件、FAQ、標籤）。它不會套用到：

* **資料庫（Text to SQL）**：Agent 查資料庫時不看查詢元資料，也沒有逐次請求限制資料表的欄位。資料庫的範圍由資料庫是否啟用、是否關聯到這個 Agent、<mark style="color:blue;">指定資料表</mark> 與 [角色權限](/build/database/link-chatbots-groups.md) 決定；要讓不同身分查到不同資料，請用不同的 Agent 搭配不同的資料庫連線或唯讀帳號。
* **工具與 MCP**：工具能不能被呼叫由 Agent 的工具設定與角色權限決定。
* **角色指令**：條件本身不會送進模型，Agent 不知道自己被限制了什麼；要讓模型知道使用者身分，請用 [contextData](https://docs.maiagent.ai/tech/serve/web-chat-sdk/web-chat-context-data)。

## 實際應用情境 <a href="#practical-use-cases" id="practical-use-cases"></a>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-21376b207a81274598525fe8ce20993dee869d89%2F%E7%9F%A5%E8%AD%98%E5%BA%AB.png?alt=media" alt=""><figcaption></figcaption></figure>

同一個 Agent 服務多種身分時，只要依身分帶入不同的查詢元資料：

<table><thead><tr><th width="162.5028076171875">身分</th><th>傳入條件（查詢元資料）</th><th>回應結果</th></tr></thead><tbody><tr><td>訪客</td><td>知識庫：<code>一般</code><br>檔案文件：無<br>標籤：<code>訪客</code><br>FAQ：<code>1</code>、<code>2</code></td><td>取得 <code>一般</code> 知識庫中含 <code>訪客</code> 標籤的文件及 FAQ <code>1</code>、FAQ <code>2</code></td></tr><tr><td>一般會員</td><td>知識庫：<code>一般</code><br>檔案文件：<code>A</code>、<code>B</code>、<code>C</code><br>標籤：無<br>FAQ：無</td><td>取得 <code>一般</code> 知識庫中 <code>A</code>、<code>B</code>、<code>C</code> 文件與所有 FAQ</td></tr><tr><td>客服人員</td><td>知識庫：<code>員工</code><br>檔案文件：無<br>標籤：<code>客服</code><br>FAQ：無</td><td>取得 <code>員工</code> 知識庫中標註為 <code>客服</code> 標籤的文件與所有 FAQ</td></tr><tr><td>內部員工</td><td>知識庫：<code>員工</code><br>檔案文件：<code>A</code>、<code>B</code><br>標籤：無<br>FAQ：無</td><td>取得 <code>員工</code> 知識庫中 <code>A</code>、<code>B</code> 文件與所有 FAQ</td></tr><tr><td>管理員</td><td>知識庫：<code>員工</code>、<code>一般</code><br>檔案文件：無<br>標籤：無<br>FAQ：無</td><td>取得 <code>員工</code> 與 <code>一般</code> 知識庫中所有文件內容及 FAQ</td></tr></tbody></table>

***

## 小結：企業使用查詢元資料的價值 <a href="#summary-enterprise-value" id="summary-enterprise-value"></a>

🎯 **多維身分交叉控管**（會員等級＋地區＋產品線）

🎯 **即時查詢控制**：無需複製 Agent，只要改條件即可因應場景切換

🎯 **大型知識庫靈活管理**：標籤與知識庫可隨場景拆分與授權

> **建議將查詢元資料納入產品架構核心，讓企業能以最少設定達成最多授權彈性，**\
> **確保知識安全，同時提升對話體驗與維運效率。**


---

# 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/org/querymetadata.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.