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

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

Query Metadata 是什麼？

Query Metadata（查詢元資料）是一組限縮知識檢索範圍的條件：指定某個聯絡人／某段對話／某則訊息在檢索時，只能參考哪些「知識庫、文件、FAQ、符合標籤條件的內容」。聯絡人／對話／訊息是容器，Query Metadata 是掛在容器上、實際決定可視範圍的條件；角色不是容器。

概念、應用情境與後台操作見使用者手冊知識管理權限：查詢元資料。本頁是工程師入口：各層級對應的 API 欄位、解析順序與條件模型，JSON 寫法見開始建構—使用 JSON 格式。

延伸閱讀：聯絡人 (Contact) 介紹及串接、角色 (Role) 和聯絡人 (Contact) 的差異

可以設定在哪些層級

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

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

解析順序

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

Message > Conversation > Contact > Agent 的預設標籤過濾 > 皆未設定（不限制，可查 Agent 掛載的全部知識庫）

• 某一層未設定（null）→ 往下一層查找

• 第一個有設定的層級整份生效，不與下層合併——上層設定會完全蓋過下層

• 「空物件 {}」也算有設定（意為不限制），會終止往下查找——「空集合 vs 未設定」的精確語意見 JSON 格式指南

• Agent 的預設標籤過濾（Agent 設定的 defaultLabelRelations）只在 Message、Conversation、Contact 三層都是 null 時套用：以它的標籤條件過濾 Agent 掛載的全部知識庫。三層中任一層有設定（含 {}），就不會套用。後台設定方式見使用者手冊知識庫標籤過濾

內部成員呢？ 成員在平台內看得到哪些資源由角色權限控制（另一套機制）；成員使用內部問答時逐訊息選擇知識範圍，即上表的訊息層級，操作見使用者手冊開始建構—使用「查詢構建器」。

條件如何縮小範圍

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

1. knowledge_bases：開放哪些知識庫，以及各知識庫內開放哪些文件／FAQ（全選、全選排除少數、只選少數）

2. label_relations：在已開放的文件中，再依標籤條件（AND／OR，可巢狀）過濾

Query Metadata 只約束知識庫檢索：它不進入 LLM prompt、AI 讀不到條件本身。要讓 AI「知道」某個值（如商品 ID），請用 contextData。

它也不套用到 Text to SQL 與工具：Agent 查資料庫時不看 Query Metadata，請求層級沒有限制資料表的欄位，資料庫範圍只能靠啟用、關聯 Agent、指定資料表 與帳號權限控制，見 Text to SQL：常見問題。

兩種建構方式

方式	適合	指南
查詢構建器（圖形化）	後台手動設定聯絡人權限、內部問答逐訊息選擇	使用者手冊開始建構—使用「查詢構建器」
JSON 格式	API 串接、Web Chat 嵌入、複雜巢狀條件	開始建構—使用 JSON 格式

實際應用情境

同一個 Agent 服務多種身分時，只需要依身分換一份 Query Metadata、不需要複製 Agent。訪客、會員、客服人員、內部員工、管理員各帶什麼條件的對照表，見使用者手冊實際應用情境。