構築を開始—JSON 形式の利用

より複雑なフィルター条件を記述する場合は、JSON 形式を使用して、各レベル（ナレッジベース、個別ドキュメントなど）の ID を直接指定できます

Query Metadata の制御項目の説明

項目カテゴリ

キー名

説明

使用方法

ナレッジベース

knowledge_base

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

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

ナレッジベースのファイルドキュメント

Chatbot_file

knowledge_base で指定したナレッジベース内で参照できるファイルドキュメント

knowledge_base に渡す オブジェクト→{...} 内で定義します

Q&Aデータセット

FAQ

knowledge_base で指定したナレッジベース内で参照できるFAQセット

上記と同じです

ナレッジベースのファイルドキュメントのラベル

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 内の各条件は、{"label_id": "..."}、またはネストしたグループ {"operator": ..., "conditions": [...]} の2つの形式のみを受け付けます。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 boolean（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 のみを選択します
        }
      ]
    },
    
    // 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 アシスタントにリクエストごとに異なるナレッジ範囲を適用することもできます。バックエンドで現在のユーザーIDに応じて条件をリアルタイムに組み立てる連携シナリオに適しています。たとえば、次のようなシナリオがあります。

金融／証券業界：会員ランクに応じて参照できるプランのドキュメントを決定します。一般会員と 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）

その連絡先のすべての会話

ユーザーIDに基づいて権限を長期的に紐付けます

Web Chat の埋め込み

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

未登録の連絡先である訪問者の範囲を制限します

会話 API（message.queryMetadata）

そのリクエストのみ

バックエンドがリクエストごとに条件を組み立て、1つのアシスタントで複数の権限に対応します

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

前へ構築を開始—「クエリビルダー」の利用

次へ概要

最終更新 22 日前

役に立ちましたか？