# 開始建構—使用 JSON 格式

## Query Metadata 控制項目說明 <a href="#querymetadata-kong-zhi-xiang-mu-shuo-ming" id="querymetadata-kong-zhi-xiang-mu-shuo-ming"></a>

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

### 結構格式範例與說明

```json
"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？ <a href="#ru-he-huo-qu-ge-ceng-ji-id" id="ru-he-huo-qu-ge-ceng-ji-id"></a>

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

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-ac377b11864763f6d3b96811593f2262b28eba95%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-08%20101733.png?alt=media" alt=""><figcaption><p>取得各層級 ID 位置</p></figcaption></figure>

## 關鍵邏輯說明 <a href="#guan-jian-luo-ji-shuo-ming" id="guan-jian-luo-ji-shuo-ming"></a>

### 1. label\_relations 邏輯 <a href="#id-1labelrelations-luo-ji" id="id-1labelrelations-luo-ji"></a>

* `OR` 運算：符合任一標籤即可存取
* `AND` 運算：必須符合所有標籤才能存取
* 嵌套邏輯：支援多層、巢狀的權限組合

### 2. knowledge\_bases 設定 <a href="#id-2knowledgebases-she-ding" id="id-2knowledgebases-she-ding"></a>

* `has_user_selected_all = "True"`：可存取該知識庫的所有內容
* `has_user_selected_all = "False"`：僅能存取指定的文件跟 FAQ

## 聯絡人(Contact)設定 <a href="#lian-luo-ren-contact-she-ding" id="lian-luo-ren-contact-she-ding"></a>

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

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-948b74fac65e94e770db5ec15e7f148c07f242c2%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-07%20163545.png?alt=media" alt=""><figcaption><p>聯絡人 JSON 編輯介面</p></figcaption></figure>

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

## Web Chat 初始化設定 <a href="#webchat-chu-shi-hua-she-ding" id="webchat-chu-shi-hua-she-ding"></a>

{% hint style="info" %}
Web Chat 嵌入介紹請參考 [🔗Web Chat 初始化](https://docs.maiagent.ai/tech/api-integration/web-chat-sdk)
{% endhint %}

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

### 程式碼範例 <a href="#cheng-shi-ma-fan-li" id="cheng-shi-ma-fan-li"></a>

```javascript
<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 參數說明

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

<table><thead><tr><th width="82">參數值</th><th>行為</th><th>適用場景</th></tr></thead><tbody><tr><td><code>"True"</code></td><td>系統選擇該知識庫中的所有內容，排除 <code>chatbotFileIds</code> 和 <code>faqIds</code> 中列出的項目</td><td>100 個文件中使用 98 個文件，2 個文件在參數中列出表示不使用</td></tr><tr><td><code>"False"</code></td><td>系統選擇 <code>chatbotFileIds</code> 和 <code>faqIds</code> 中明確列出的項目</td><td>100 個文件中只使用 2 個文件</td></tr></tbody></table>

### 程式碼範例

```js
// 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 的設定