Query Metadata 管理權限

功能說明

企業在導入 AI 對話系統時，通常需對 「 知識庫 / AI 助理 / 對話平台 」 的可用範圍進行細緻控管。

MaiAgent 目前主要提供兩種身分管理模式：

• Role：針對內部人員，透過角色與職能權限控管知識範圍

• Contact：針對訪客或外部會員，免註冊即可識別與控管對話內容

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

• 聯絡人 ( Contact ) 串接步驟

• 角色 ( Role ) 和 聯絡人 ( Contact ) 的差異

實際上，決定 「 這個人能查哪些內容 」 的核心機制，是附加在身分上的 query_metadata。

Query Metadata 是什麼？

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

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

角色 / 聯絡人 是容器，Query Metadata 是實際控制範圍的條件組

---

權限層級概念

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

• Contact / Role 是身份容器

• Message 所對應的是進行內部對話時，可透過篩選來控制對話所使用到的知識庫

• query_metadata 是對話時真正執行的 「 篩選條件集合 」

文件篩選條件判斷層級

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

---

query_metadata 控制項目說明

項目類別	名稱	說明
知識庫	knowledge_base	AI 助理 對應使用的知識庫
知識庫檔案文件	Chatbot_file	知識庫中的檔案文件
知識庫檔案文件標籤	label	檔案文件中的標籤，用於支援更細緻的文件權限劃分
問答資料集	FAQ	知識庫內的常見問答集

結構格式範例與說明

API 串接請參考此處說明

"query_metadata": {
    "label_relations": { // 標籤
      "operator": "OR",
      "conditions": [
        { "label_id": "11111111-2222-3333-4444-555555555555" },
        {
          "operator": "AND",
          "conditions": [
            { "label_id": "66666666-7777-8888-9999-000000000000" }, 
            { "label_id": "aaaaaaa1-bbbb-cccc-dddd-eeeeeeeeeeee" }
          ]
        }
      ]
    },
    "knowledge_bases": [
      {
        "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
        "chatbot_file_ids": [
          "9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e" // 檔案文件
        ],
        "faq_ids": [
          "a1b2c3d4-e5f6-7890-abcd-1234567890ab" // FAQ
        ],
        "has_user_selected_all": "False" // 選擇所有知識庫
      }
    ]
  }
}

關鍵邏輯說明

1. label_relations 邏輯

• OR 運算：符合任一標籤即可存取

• AND 運算：必須符合所有標籤才能存取

• 嵌套邏輯：支援複雜的權限組合

2. knowledge_bases 設定

• has_user_selected_all = "True"：可存取該知識庫的所有內容

• has_user_selected_all = "False"：僅能存取指定的文件跟 FAQ

---

實際應用情境

身份	傳入條件（query_metadata）	回應結果
訪客	知識庫：一般 檔案文件：無 標籤：訪客 FAQ：1、2	取得 一般 知識庫中含 訪客 標籤的文件及FAQ 1、FAQ 2
一般成員	知識庫：一般 檔案文件：A、B、C 標籤：無 FAQ：無	取得 一般 知識庫中A、B、C 文件與所有 FAQ
客服人員	知識庫：員工 檔案文件：無 標籤：客服 FAQ：無	取得 員工 知識庫中標註為 客服 標籤的文件與所有 FAQ
內部員工	知識庫：員工 檔案文件：A、B 標籤：無 FAQ：無	取得 員工 知識庫中 A、B 文件與所有 FAQ
管理員	知識庫：員工、一般 檔案文件：無 標籤：無 FAQ：無	取得 員工 與 一般 知識庫中所有文件內容及 FAQ

---

小結：企業使用 query_metadata 的價值

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

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

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

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