構築を始める—JSON 形式を使う

より複雑なフィルタリング条件を記述したい場合、JSON 形式で各レベル（ナレッジベース、個別ファイルなど）の ID を直接指定できます

Query Metadata 制御項目の説明

項目カテゴリ

Key 名称

説明

使用方法

ナレッジベース

knowledge_base

AI アシスタントが対話を生成する際に参照するナレッジベースです

knowledge_bases という名前の Array→[...] に格納し、ナレッジベース ID を渡して複数のナレッジベースを開放します

ナレッジベースファイル

Chatbot_file

knowledge_base で指定されたナレッジベース内で参照可能なファイルです

knowledge_base 内で渡される オブジェクト→{...} の中で定義します

FAQ データセット

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 を一括で設定できます。
1 つ目のナレッジベースは has_user_selected_all: false = 明示的にリストされたファイルと FAQ のみ開放します。2 つ目は has_user_selected_all: true = そのナレッジベースの全コンテンツを開放します。
label_relations.operator は "OR"（いずれかのラベルに一致）または "AND"（すべてのラベルに同時に一致する必要がある）で条件を組み合わせ、ネストによる複雑な条件定義もサポートしています。
上記の例はそのままコピーして使用できる有効な JSON です（JSON は // コメントをサポートしていません）。

空コレクションと未設定のセマンティクス（重要）

「空コレクション」と「未設定」は意味が異なります。誤った設定は権限の全開放または全閉鎖を引き起こします：

設定

効果

未提供または null

未設定 → 次のレベルへ検索を続行します。3 レベルすべてが未設定の場合 = 制限なし、AI アシスタントに紐付けられたすべてのナレッジベースを検索できます

{}（空オブジェクト）

制限なし（全選択）と見なされます。また「設定済み」であるため次のレベルへの検索が停止します。「権限なし」を設定するには必ず "knowledge_bases": [] を使用してください

"knowledge_bases": []（空配列）

すべてのナレッジベースが検索不可になります — 「権限なし」にはこの設定を使用してください

"label_relations": {"operator": "OR", "conditions": []}（空条件）

ラベルフィルタリングを行いません = 選択したナレッジベースのコンテンツがすべて検索可能になります。権限なしではありません

値あり

条件でフィルタリングします：ナレッジベース → ファイル／FAQ → ラベルの順にスコープを絞り込みます

label_relations は knowledge_bases と一緒に提供する必要があります。label_relations のみを単独で提供した場合（knowledge_bases なし）、ナレッジベース検索にラベルフィルタリングは適用されません（制限なしと同等になります）。

フィールド名は完全に正確でなければなりません

conditions 内の各条件は 2 つの形式のみ受け付けます：{"label_id": "..."}、またはネストされたグループ {"operator": ..., "conditions": [...]}。label、labelid などの他のキー名を使用すると、API は 400 を返し、誤ったフィールド名を示します。
knowledge_bases 内のオブジェクトは knowledge_base_id、chatbot_file_ids、knowledge_base_file_ids、faq_ids、has_user_selected_all の 5 つのフィールドのみ受け付けます。それ以外のフィールドが含まれている場合も同様に 400 を返します。
query_metadata のトップレベルには独自の識別フィールド（例：_user_id）を追加できます。これらのフィールドは無視され、検索範囲に影響しません。

フォーマットエラーはすべて API の境界で 400 としてブロックされます（fail-closed）。想定よりも広い権限が暗黙的に適用されることはありません。設定完了後は一度テストを実施し、範囲が想定通りであることを確認することを推奨します。

レベル優先順位

query_metadata は Message / Conversation / Contact の 3 つのレベルで設定でき、上から順に最初の「設定済み」レベルが使用されます：Message > Conversation > Contact。上位レベルの設定が下位レベルを上書きします。

各レベルの ID を取得するには？

左側メニューの各レベルのコンテンツに移動して ID フィールドを確認できます（ナレッジベースを例にすると、コピーアイコンをクリックしてすべての ID コンテンツを直接コピーできます）。

重要なロジックの説明

1. label_relations のロジック

OR 演算：いずれかのラベルに一致すればアクセスできます
AND 演算：すべてのラベルに一致する必要があります
ネストロジック：多階層のネストされた権限の組み合わせをサポートしています

2. knowledge_bases の設定

has_user_selected_all = true：そのナレッジベースのすべてのコンテンツにアクセスできます（リストに記載された項目は除外されます）
has_user_selected_all = false：指定されたファイルと FAQ のみアクセスできます
JSON のブーリアン値（true / false）の使用を推奨します。文字列 "True" / "False" もシステムで受け入れ可能です（既存の統合との互換性のため）

コンタクト（Contact）の設定

コンタクトの編集画面で JSON 形式の query_metadata 設定を直接入力できます：

システムが自動的にフォーマットを検証し、権限設定を適用します。

Web Chat 初期化設定

Web Chat の埋め込みについては Web Chat 埋め込みと SDK を参照してください

コンタクトが設定される前に対話コンテンツを制限したい場合（例：未登録のコンタクトアカウントを持たない顧客に Web Chat サービスを提供する場合）、埋め込み時に Query Metadata を提供できます。システムはデフォルトでメッセージ（Message）レベルのナレッジベースファイルフィルタリング機能を有効にします。

コード例

<script>
  window.maiagentChatbotConfig = {
    // Web Chat の基本パラメータを設定
    webChatId: 'Admin の埋め込みウィンドウから取得した Web Chat ID',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    primaryColor: '#3854d8',
    
    // 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 のみ選択
        }
      ]
    },
    
    // コンタクトを設定
    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" }
            ]
        }
    ]
}

3 つの設定場所の違い

設定場所

適用範囲

適用シナリオ

コンタクト（Contact）

そのコンタクトのすべての対話

身分に基づいて長期的に権限を紐付けます

Web Chat 埋め込み

その埋め込みページで生成された対話

未登録のコンタクトの訪問者に対してスコープを制限します

対話 API（message.queryMetadata）

そのリクエストのみ

バックエンドがリクエストごとに条件を構成し、同一アシスタントで複数の権限に対応します

フィールド命名：camelCase と snake_case の両方が使用可能

API は命名スタイルを自動変換するため、以下の 2 つの記述方法は等価です：

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 アシスタントはナレッジベース内にそのファイルが見つからないと回答します。

前へ構築を始める—「クエリビルダー」を使う

次へLINE LIFF とは

最終更新 21 日前

役に立ちましたか？