開始建構—使用 JSON 格式

若您想要撰寫更複雜的篩選條件，可使用 JSON 格式直接以各層級 (如知識庫、單一文件等) ID 指定

Query Metadata 控制項目說明

項目類別	Key名稱	說明	使用方法
知識庫	knowledge_base	AI 助理產生對話時參考使用的知識庫	包裹在 knowledge_bases 命名的 Array→[...] 中，傳入知識庫 id 開放多個知識庫
知識庫檔案文件	Chatbot_file	knowledge_base 指定之知識庫中可參考的檔案文件	在 knowledge_base 中傳入的 物件→{...} 中定義
問答資料集	FAQ	knowledge_base 指定之知識庫中可參考的常見問答集	同上
知識庫檔案文件標籤	label	檔案文件中的標籤，若無指定 Chatbot_file 仍可指定 label，限制只能參考符合該標籤的文件，用於支援更細緻的文件權限劃分	使用 label_relations 命名的物件傳入，以 "OR"/"AND" 定義可適用的文件標籤條件，傳入conditions 命名的 Array→[...] 中定義

結構格式範例與說明

{
  "query_metadata": {
    "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"],
        "has_user_selected_all": false
      },
      {
        "knowledge_base_id": "223e4567-e89b-12d3-a456-426614174001",
        "has_user_selected_all": true
      }
    ],
    "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 可傳入多個物件，一次設定多個知識庫下的可參考文件、FAQ。

• 第一個知識庫 has_user_selected_all: false＝僅開放明確列出的文件與 FAQ；第二個 has_user_selected_all: true＝開放該知識庫全部內容。

• label_relations.operator 以 "OR"（符合任一標籤）或 "AND"（須同時符合全部標籤）組合條件，並支援巢狀定義複雜條件。

• 上述範例為可直接複製使用的合法 JSON（JSON 不支援 // 註解）。

空集合與未設定的語意（重要）

「空集合」與「未設定」意義不同，設定錯誤會造成權限全開或全關：

設定	效果
未提供或 null	未設定 → 繼續往下一層查找；三層皆未設定＝不限制，可查詢 AI 助理掛載的全部知識庫
{}（空物件）	視同不限制（全選），且因「已有設定」會終止往下層查找——要設「無權限」請務必用 "knowledge_bases": []
"knowledge_bases": []（空陣列）	全部知識庫皆不可查——「無權限」請使用此設定
"label_relations": {"operator": "OR", "conditions": []}（空條件）	不做標籤過濾＝所選知識庫內容全部可查，並非無權限
有值	依條件過濾：知識庫 → 檔案／FAQ → 標籤逐層縮小範圍

label_relations 必須與 knowledge_bases 一併提供：單獨提供 label_relations（未帶 knowledge_bases）時，知識庫檢索不會套用標籤過濾（等同不限制）。

欄位名稱必須完全正確

條件的鍵名拼錯不會報錯，但該條件不會生效——結果是實際可查範圍比您預期更寬。設定完務必實測確認。

• conditions 內的每個條件只接受兩種形態：{"label_id": "..."}，或巢狀群組 {"operator": ..., "conditions": [...]}。寫成 label、labelid 等拼法會被視為無效條件。

• knowledge_bases 內的物件只接受 knowledge_base_id、chatbot_file_ids、knowledge_base_file_ids、faq_ids、has_user_selected_all 五個欄位；出現其他欄位時 API 會回傳 400 並指出錯誤欄位名稱。

• query_metadata 頂層可附加您自己的識別欄位（例如 _user_id），這些欄位會被忽略、不影響查詢範圍。

層級優先序

query_metadata 可設定於 Message / Conversation / Contact 三個層級，由上而下取第一個「有設定」的層級：Message > Conversation > Contact，上層設定會蓋過下層。

如何獲取各層級 ID？

您可以進入左側選單的各層級內容中查看 ID 欄位 (以知識庫為例，可點選複製圖示直接複製所有 ID 內容)

取得各層級 ID 位置

關鍵邏輯說明

1. label_relations 邏輯

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

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

• 嵌套邏輯：支援多層、巢狀的權限組合

2. knowledge_bases 設定

• has_user_selected_all = true：可存取該知識庫的所有內容（排除清單中列出的項目）

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

• 建議使用 JSON boolean（true / false）；字串 "True" / "False" 亦可被系統接受（相容既有整合）

聯絡人(Contact)設定

您可以在編輯聯絡人的地方直接寫入 JSON 格式的 query_metadata 設定：

聯絡人 JSON 編輯介面

系統會自動驗證格式並套用權限設定。

Web Chat 初始化設定

Web Chat 嵌入介紹請參考 🔗Web Chat 初始化

若想要在聯絡人前限制對話內容(如：提供 Web Chat 服務給未註冊聯絡人帳號的客戶時)，可以在嵌入時提供 Query Metadata，系統將預設啟動訊息(Message)層級的知識庫文件過濾機制

程式碼範例

<script>
  window.maiagentChatbotConfig = {
    // 設定 Web Chat 基礎參數
    webChatId: '從 Admin 嵌入視窗中獲得的 Web Chat ID',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    primaryColor: '#3854d8',
    allowDrag: true,
    
    // 設定 Web Chat 知識庫文件搜索範圍
    queryMetadata: {
      labelRelations: { // 標籤
        operator: 'OR',
        conditions: [
          { labelId: '186a3012-44ac-4cd2-a132-a76bfda5bcae' },
          {
            operator: 'AND',
            conditions: [
              { labelId: '0267c405-cc26-4497-b17f-180aedf8b0eb' }, 
              { labelId: '60f81de6-a4b6-4d86-9781-5430783ef0b6' }
            ]
          }
        ]
      },
      knowledgeBases: [
        {
          knowledgeBaseId: '123e4567-e89b-12d3-a456-426614174000',
          chatbotFileIds: [
            '9f7a9f7b-2b2b-4c4c-9d9d-8e8e8e8e8e8e' // 檔案文件
          ],
          faqIds: [
            'a1b2c3d4-e5f6-7890-abcd-1234567890ab' // FAQ
          ],
          hasUserSelectedAll: false // 僅選取上列明確指定的檔案與 FAQ
        }
      ]
    },
    
    // 設定 Contact
    contactId: '60f81de6-a4b6-4d86-9781-5430783ef0b6'
  };
</script>
<script
  src="https://chat.maiagent.ai/js/embed.min.js"
  defer>
</script>

hasUserSelectedAll 參數說明

此參數為單一知識庫下的排除 / 使用少數項目之設定，在您開放的文件基礎下才會再套用標籤的過濾條件。

參數值	行為	適用場景
true	系統選擇該知識庫中的所有內容，排除 chatbotFileIds 和 faqIds 中列出的項目	100 個文件中使用 98 個文件，2 個文件在參數中列出表示不使用
false	系統選擇 chatbotFileIds 和 faqIds 中明確列出的項目	100 個文件中只使用 2 個文件

程式碼範例

// hasUserSelectedAll: true，列出想排除的文件 ID
{
  "knowledgeBaseId": "123e4567-e89b-12d3-a456-426614174000",
  "chatbotFileIds": ["不想使用的文件ID1", "不想使用的文件ID2"],
  "faqIds": ["不想使用的FAQ_ID1"],
  "hasUserSelectedAll": true
}

// hasUserSelectedAll: false，列出想使用的文件 ID
{
  "knowledgeBaseId": "123e4567-e89b-12d3-a456-426614174000",
  "chatbotFileIds": ["想使用的文件ID1", "想使用的文件ID2"],
  "faqIds": ["想使用的FAQ_ID1"],
  "hasUserSelectedAll": false
}

queryMetadata 與 contactId 的優先順序

• 當不設定 queryMetadata 和 contactId 時：系統會搜索全部知識庫範圍，不做任何排除

• 可以單獨設定 queryMetadata 或 contactId

• 當兩者都設定時：系統只會使用聯絡人(以 contactId 辨識)中 Query Metadata 的設定

對話 API（completions）逐次帶入

除了聯絡人與 Web Chat 嵌入設定，您也可以在每次呼叫對話 API 時逐次帶入 Query Metadata，讓同一個 AI 助理針對不同請求套用不同的知識範圍。適合由後端依當下使用者身分即時組裝條件的整合情境，例如：

• 金融／證券業：依會員等級決定可參考的方案文件，一般會員與 VIP 客戶問同一個問題會得到不同範圍的回覆

• 科技／電子製造業：依客戶所屬產品線，限定只參考該產品線的規格書與技術文件

• 教育機構：依在校生、校友、一般訪客身分，開放不同層級的招生與校務資訊

• 醫療／健康產業：依科別限定衛教資料範圍，避免跨科別內容互相干擾

端點：POST https://api.maiagent.ai/api/v1/chatbots/{chatbotId}/completions/

queryMetadata 要放在 message 物件內，不是請求本體的最外層。放錯位置不會報錯，但條件不會生效，結果會等同於未設定任何篩選。

完整範例

completions + queryMetadata

curl --location 'https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Api-Key 您的 API 金鑰' \
--data '{
    "conversation": null,
    "message": {
        "content": "我的會員等級可以享有哪些優惠方案？",
        "queryMetadata": {
            "knowledgeBases": [
                {
                    "knowledgeBaseId": "123e4567-e89b-12d3-a456-426614174000"
                }
            ],
            "labelRelations": {
                "operator": "AND",
                "conditions": [
                    { "labelId": "186a3012-44ac-4cd2-a132-a76bfda5bcae" }
                ]
            }
        }
    },
    "isStreaming": false
}'

上例的語意是：只在 123e4567… 這個知識庫中，參考同時符合 186a3012… 標籤（例如「一般會員」）的文件與 FAQ。換成 VIP 客戶時，後端只需改傳對應的標籤 ID，不必另外複製一個 AI 助理。

巢狀條件的寫法與 Web Chat 相同，可直接沿用上一節的 labelRelations 結構：

"labelRelations": {
    "operator": "OR",
    "conditions": [
        { "labelId": "186a3012-44ac-4cd2-a132-a76bfda5bcae" },
        {
            "operator": "AND",
            "conditions": [
                { "labelId": "0267c405-cc26-4497-b17f-180aedf8b0eb" },
                { "labelId": "60f81de6-a4b6-4d86-9781-5430783ef0b6" }
            ]
        }
    ]
}

三種設定位置的差異

設定位置	生效範圍	適用情境
聯絡人（Contact）	該聯絡人的所有對話	依身分長期綁定權限
Web Chat 嵌入	該嵌入頁面產生的對話	對未註冊聯絡人的訪客限制範圍
對話 API（message.queryMetadata）	僅該次請求	後端逐次組裝條件、同一助理服務多種權限

欄位命名：camelCase 與 snake_case 皆可

API 會自動轉換命名風格，因此下列兩種寫法等價：

• camelCase：queryMetadata、knowledgeBases、knowledgeBaseId、labelRelations、labelId、hasUserSelectedAll

• snake_case：query_metadata、knowledge_bases、knowledge_base_id、label_relations、label_id、has_user_selected_all

建議整份請求統一使用同一種風格，避免維護時混淆。

hasUserSelectedAll 省略時的預設值

hasUserSelectedAll 未傳入時，預設為 true，也就是該知識庫的全部內容，再套用標籤條件過濾。

因此當您只想「用標籤限制整個知識庫」時，knowledgeBases 只需要給 knowledgeBaseId：

"knowledgeBases": [
    { "knowledgeBaseId": "123e4567-e89b-12d3-a456-426614174000" }
]

標籤過濾的作用範圍

• 標籤條件同時套用於知識庫的檔案文件與 FAQ。

• 使用者在該次對話中直接上傳的附件不受標籤條件限制，仍可被參考；標籤只約束知識庫內的內容。

• 標籤為各知識庫獨立建立，label_id 必須使用該知識庫自己的標籤 ID，不可沿用其他知識庫的標籤。

• 標籤需實際掛在檔案／FAQ 上才會生效：僅在「標籤管理」建立標籤選項、未掛到內容上，過濾不會有任何效果。

• 在問句中直接指定檔名索取特定檔案時，同樣受標籤條件約束：若該檔案不符合條件，AI 助理會回覆在知識庫中找不到該檔案。