> 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/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md).

# 知識管理權限(Query Metadata / 查詢元資料) 總覽

透過 Query Metadata（查詢元資料）控管 AI 助理可檢索的知識範圍，詳細設定方式見「開始建構」子頁

## Query Metadata 是什麼？ <a href="#what-is-query-metadata" id="what-is-query-metadata"></a>

導入 AI 對話時，不同使用者往往該看到不同範圍的知識：訪客只能查公開資訊、VIP 會員多一份方案文件、內部員工才能查員工手冊。

Query Metadata 是一組**限縮知識檢索範圍的條件**：指定某個身份／某段對話／某則訊息在檢索時，只能參考哪些「知識庫、文件、FAQ、符合標籤條件的內容」。它不替代身份機制，而是讓身份**有條件地發揮作用**：

> **聯絡人／對話／訊息是容器，Query Metadata 是掛在容器上、實際決定可視範圍的條件。**

{% hint style="info" %}
延伸閱讀：[聯絡人 (Contact) 介紹及串接](/tech/authorization-integration/contacts.md)、[角色 (Role) 和聯絡人 (Contact) 的差異](/tech/authorization-integration/role-vs-contact.md)
{% endhint %}

## 可以設定在哪些層級 <a href="#levels" id="levels"></a>

Query Metadata 可設定在三個層級，各自對應不同的整合方式：

| 層級                   | 生效範圍      | 設定方式                                                                                 |
| -------------------- | --------- | ------------------------------------------------------------------------------------ |
| **訊息（Message）**      | 僅該則訊息     | 對話 API 的 `message.queryMetadata`；內部問答介面右側的知識選擇；Web Chat 嵌入的 `queryMetadata`（以訊息層級送出） |
| **對話（Conversation）** | 該段對話的所有訊息 | 建立對話的 API 帶入                                                                         |
| **聯絡人（Contact）**     | 該使用者的所有對話 | 後台聯絡人編輯（查詢構建器或 JSON）、聯絡人 API                                                         |

### 解析順序 <a href="#resolution-order" id="resolution-order"></a>

檢索時由上而下取**第一個「有設定」的層級**：

```
Message > Conversation > Contact > 皆未設定（不限制，可查 AI 助理掛載的全部知識庫）
```

* 某一層未設定（`null`）→ 往下一層查找
* 第一個有設定的層級**整份生效**，不與下層合併——上層設定會完全蓋過下層
* 「空物件 `{}`」也算有設定（意為不限制），會終止往下查找——「空集合 vs 未設定」的精確語意見 [JSON 格式指南](/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md#empty-vs-unset)

{% hint style="info" %}
**內部成員呢？** 成員在平台內看得到哪些資源由[角色權限](https://docs.maiagent.ai/org/role-permission)控制（另一套機制）；成員使用內部問答時逐訊息選擇知識範圍，即上表的訊息層級（見[圖形化介面指南](/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/graphical-interface.md)）。
{% endhint %}

## 條件如何縮小範圍 <a href="#filter-model" id="filter-model"></a>

一份 Query Metadata 由兩部分組成，逐層縮小可檢索範圍：

1. `knowledge_bases`：開放哪些**知識庫**，以及各知識庫內開放哪些**文件／FAQ**（全選、全選排除少數、只選少數）
2. `label_relations`：在已開放的文件中，再依**標籤**條件（AND／OR，可巢狀）過濾

```mermaid
flowchart TB
    KB["知識庫"]
    Docs["知識庫下的文件 / FAQ"]
    Tags["依標籤條件從已開放的內容再過濾"]
    Result["最終可檢索的內容"]

    KB --> Docs
    Docs --> Tags
    Tags --> Result

    classDef kbBox fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000000
    classDef docBox fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000000
    classDef tagBox fill:#e8f5e8,stroke:#388e3c,stroke-width:2px,color:#000000
    classDef resultBox fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000000

    class KB kbBox
    class Docs docBox
    class Tags tagBox
    class Result resultBox
```

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-d5f64342fe0f0f23717cda6c0696e03866230265%2Fimage%20(33).png?alt=media" alt=""><figcaption><p>文件篩選條件層級示意圖</p></figcaption></figure>

{% hint style="warning" %}
Query Metadata 只約束**知識庫檢索**：它不進入 LLM prompt、AI 讀不到條件本身。要讓 AI「知道」某個值（如商品 ID），請用 [contextData](/tech/api-integration/web-chat-sdk/web-chat-context-data.md)。
{% endhint %}

## 兩種建構方式 <a href="#build-methods" id="build-methods"></a>

| 方式             | 適合                        | 指南                                                                                                                                              |
| -------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **查詢構建器**（圖形化） | 後台手動設定聯絡人權限、內部問答逐訊息選擇     | [開始建構—使用「查詢構建器」](/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/graphical-interface.md) |
| **JSON 格式**    | API 串接、Web Chat 嵌入、複雜巢狀條件 | [開始建構—使用 JSON 格式](/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md)    |

## 實際應用情境 <a href="#scenarios" id="scenarios"></a>

<table><thead><tr><th width="162.5028076171875">身份</th><th>傳入條件（query_metadata）</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>

同一個 AI 助理服務多種身份時，只需要換條件、不需要複製助理——這是 Query Metadata 的核心價值：**多維身份交叉控管**（等級 × 部門 × 產品線）、**逐次查詢控制**（後端依當下身份即時組裝條件）、**大型知識庫的彈性授權**（標籤與知識庫隨場景拆分）。


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.