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

## 功能說明

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

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

### Query Metadata / 「查詢元資料」是什麼？

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

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

> **角色 / 聯絡人 / 對話 是容器，Query Metadata 是實際控制可視範圍的條件限制設定**

{% hint style="info" %}
透過以下文章介紹了解更多：

* [**聯絡人 ( Contact ) 串接步驟**](/tech/authorization-integration/contacts.md)
* [**角色 ( Role ) 和 聯絡人 ( Contact ) 的差異**](/tech/authorization-integration/role-vs-contact.md)
  {% endhint %}

## 權限層級概念

服務建構前，Agent 會透過不同層級的 Query Metadata 確認此時可以參考的所有知識庫，權限層級參考順序如下：

```
AI 助理 > 對話平台 > 使用者 ( Ｍessage / Contact / Role ) > query_metadata > 查詢權限
```

您可以在每個層級使用圖形化介面或 JSON 格式指定權限

> 可參考以下文件操作：
>
> 1. [圖形化介面操作指南(聯絡人、內部問答設定)](/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/graphical-interface.md)
> 2. [JSON 介面設定指南(聯絡人、Web chat 嵌入設定)](/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces.md)

```mermaid
flowchart TB
  subgraph 身分層
    Message --> Identity[身份資訊]
    Contact --> Identity
    Role --> Identity
  end

  subgraph 查詢條件層
    Identity --> QM[query_metadata 條件]
    QM --> KB[知識庫]
    QM --> Chatbot_file[檔案文件]
    QM --> FAQ[問答集]
    QM --> Label[標籤]

    KB --> Filter1[篩選可用知識庫]
    Chatbot_file --> Filter2[篩選可用檔案文件]
    FAQ --> Filter3[篩選可用 FAQ]
    Label --> Filter4[篩選標籤條件]
  end

  subgraph 回答層
    Filter1 --> Chatbot[AI 助理回答內容]
    Filter2 --> Chatbot
    Filter3 --> Chatbot
    Filter4 --> Chatbot
  end
```

* Contact / Role 是身份容器
* Message 所對應的是進行內部對話時，可透過篩選來控制對話所使用到的知識庫
* `query_metadata` 是對話時真正執行的 「 篩選條件集合 」

### 文件篩選條件判斷層級

<figure><img src="/files/5l3gy8Z8ouAqj1V5gGmy" alt=""><figcaption><p>文件篩選條件層級示意圖</p></figcaption></figure>

開放的篩選邏輯為：

```mermaid
flowchart TB
    %% 知識庫層級
    KB["知識庫"]
    
    %% 文件層級
    Docs["知識庫下的文件"]
    
    %% 標籤篩選層級
    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
```

透過層層傳遞，Query Metadata 成為 AI 回應邏輯的實際決策依據

## 實際應用情境

<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>

***

## 小結：企業使用 query\_metadata 的價值

🎯 **多維身分交叉控管**（角色+地區+產品線）

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

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

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


---

# Agent Instructions: 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:

```
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>
```

The question should be specific, self-contained, and written in natural language.
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.