開始建構—使用 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" // FAQ
        ],
        "has_user_selected_all": "False" // 選擇所有知識庫
      },
  //  可傳入多個物件，一次設定多個資料庫下的可參考文件、FAQ 等
  //    {
  //      "knowledge_base_id": "Id2",
  //      "chatbot_file_ids": [
  //        "file_id1" // 檔案文件
  //      ],
  //      "faq_ids": [
  //        "faq_id1",
  //        "faq_id2" // FAQ
  //      ],
  //    },
    ],
 
  "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" }
          ]
        }
      ]
    },
}

如何獲取各層級 ID？

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

取得各層級 ID 位置

關鍵邏輯說明

1. label_relations 邏輯

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

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

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

2. knowledge_bases 設定

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

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

聯絡人(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' // 選擇所有知識庫
        }
      ]
    },
    
    // 設定 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 的設定