データストア検索の構成

ブーストとフィルタの仕様を構成することで、会話エージェント（Dialogflow CX）データストア ツールから取得した検索結果に影響を与えることができます。これにより、エージェントがデータストアを使用して情報を検索する際に、よりパーソナライズされたコンテキスト認識型のやり取りが可能になります。

必要に応じて、動的式を含めて、会話のコンテキストに基づいて結果を微調整できます。たとえば、エージェントがエンドユーザーが「携帯電話」を所有していることを示す情報を取得したとします。データストア ツールを構成して、会話の後半で「留守番電話を確認するにはどうすればよいですか？」などの一般的な質問に回答する際に、携帯電話に関連するドキュメントをブーストできます。

データストアの検索結果は、コンソール、API、または Dialogflow CX Messenger 統合を使用して構成できます。

検索条件の入力

検索結果は、SearchConfig オブジェクトのブースト仕様（BoostSpec）フィールドとフィルタ仕様（FilterSpec）フィールドを使用して構成されます。これらの構成はツール内のデータストアごとに適用されるため、接続された各データストアの動作をきめ細かく制御できます。

検索条件を構成するには、コンソールを使用するか、API 呼び出しを直接送信します。両者には重要な違いがあります。

• API 呼び出し: BoostSpec と FilterSpec は、DetectIntent API 呼び出しを使用して SearchConfig で送信されます。リクエストで完全な SearchConfig オブジェクトを指定する必要があります。直接 API 呼び出しによって送信された SearchConfig は、コンソールを使用して送信された SearchConfig を常にオーバーライドします。動的式とパラメータ参照はサポートされていません。

• コンソール: BoostSpec と FilterSpec の構成を使用して、検索リクエストとともに送信される SearchConfig オブジェクトが作成されます。必要に応じて、パラメータ参照と動的式を含めて、会話から記録されたコンテキスト データに合わせて結果を調整できます。完全な SearchConfig オブジェクトではなく、ConditionBoostSpec オブジェクトとフィルタ文字列のリストを指定するだけで FilterSpecs を構築できます。

エンドユーザー情報は JSON として提供されます。想定されるスキーマはないため、オブジェクト プロパティを自由に定義できます。

ブーストの仕様（ブーストスペック）

ブースト仕様を使用すると、特定のドキュメントにブースト値を適用することで、検索結果のランキングを変更できます。1 つのデータストアに複数のブースト仕様を追加できます。

各ブースト仕様は JSON 文字列として入力されます。この JSON 文字列は、単一の ConditionBoostSpec オブジェクトを表す必要があります。

主なフィールド:

• condition:（文字列）ブーストを適用するタイミングを指定する式。これは、標準のフィルタ式の構文を使用します。Dialogflow 式（$session.params.YOUR_PARAM_NAME や $request.end-user-metadata.YOUR_KEY など）を使用して、結果を動的にすることができます。
• boost:（数値）ブーストの強さを決定する -1.0 ～ 1.0 の値。
  • 正の値は、一致するドキュメントを促進します。値 1.0 は、強力なプロモーションを示します。
  • 負の値は、一致するドキュメントを降格します。値が -1.0 の場合は、強い降格が行われます。
  • 値 0.0 はブーストを適用しないため、使用できません。
• boostControlSpec: 条件とブーストの基本的な組み合わせよりも、カスタマイズされたランキングの制御を強化します。このフィールドの構成の詳細については、リファレンス ドキュメントをご覧ください。

コンソールの入力例:

コンソールでエージェントを構成する場合は、次の形式で ConditionBoostSpecs のリストを指定する必要があります。

この例では、$session.params.doc_id セッション パラメータの値と一致する URI を持つドキュメントは、ブースト強度が 0.5 でブーストされます。この形式の JSON

{
  "condition": "uri: ANY(\"http://www.example.com/docs/$session.params.doc_id\")",
  "boost": 0.5
}

API 入力の例:

API を直接呼び出す場合は、完全な SearchConfig オブジェクトで ConditionBoostSpecs を指定する必要があります。次の検索構成は、ブースト仕様を示しています。

"searchConfig": {
  "boostSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "spec": [
        {
          "conditionBoostSpecs": {
            "condition": "CONDITION",
            "boost": "1.0"
          }
        }
      ]
    }
  ]
}

注: DATASTORE_ID はデータストアのフルネーム projects/your_project_id/locations/your_location/collections/your_collection_name/dataStores/your_datastore_name です。
CONDITION は AI Applications のフィルタ式構文に従う必要があります。
ブースト値は -1.0 ～ 1.0 にする必要があります。

フィルタ仕様（フィルタスペック）

フィルタ仕様では、定義された条件に一致するドキュメントのみが検索結果に含まれるように制限します。1 つのデータストアに複数のフィルタ仕様を追加できます。

各フィルタ仕様は、文字列式として入力する必要があります。文字列は、標準のフィルタ式の構文に準拠している必要があります。この文字列内で Dialogflow 式（$session.params.YOUR_PARAM_NAME や $request.end-user-metadata.YOUR_KEY など）を使用すると、結果を動的にできます。

コンソール フィルタの仕様文字列の例:

コンソールを使用してエージェントを構成する場合は、filter 文字列のリストを指定して FilterSpec オブジェクトを形成する必要があります。

この例では、フィルタは numeric_field が $session.params.min_value の値以上で、stock_availability が "IN_STOCK" のドキュメントのみを返します。

"numeric_field >= $session.params.min_value AND stock_availability: ANY(\"IN_STOCK\")"

API フィルタ構成の例:

API を直接呼び出す場合は、完全な SearchConfig オブジェクトで filter 文字列を指定する必要があります。

"searchConfig": {
  "filterSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "filter": "CONDITION"
    }
  ]
}

注: DATASTORE_ID はデータストアのフルネーム projects/your_project_id/locations/your_location/collections/your_collection_name/dataStores/your_datastore_name です。
CONDITION は AI アプリケーションのフィルタ式構文に従う必要があります。

Dialogflow の動的式

注: 動的式はデータストア ツールでのみ使用できます。データストア ハンドラでは使用できません。

BoostSpec 条件と FilterSpec 文字列の両方に Dialogflow 式を組み込んで、動的にすることができます。これにより、進行中の会話から取得したコンテキスト データに基づいて検索動作を調整できます。動的式は直接 API 呼び出しではサポートされていません。コンソールを使用して構成する場合にのみ使用できます。

会話コンテキスト データには、次の 2 つの方法でアクセスできます。

• セッション パラメータ: $session.params.YOUR_PARAMETER_ID を使用して会話中に収集された値。
• エンドユーザーのメタデータ: $request.end-user-metadata.YOUR_KEY を使用して DetectIntentRequest で渡されるエンドユーザーに関するメタデータ。このオプションを利用するには、end_user_metadata が DetectIntent 呼び出しの QueryParameters に含まれていることを確認します。詳細については、endUserMetadata をご覧ください。

使用可能なシステム関数と式構文の詳細については、条件とシステム関数のリファレンスをご覧ください。

実行時に適用される検索条件

データストア ツールが検索を実行すると、次のようになります。

1. ブースト仕様に指定した JSON 文字列が評価されます。有効な JSON 文字列はそれぞれ ConditionBoostSpec オブジェクトに変換されます。これらは、特定のデータストア接続の BoostSpecs オブジェクトにグループ化され、全体的な SearchConfig に追加されます。
2. フィルタ仕様に指定した文字列は、Dialogflow 式として評価されます。結果として得られた各フィルタ文字列は、データストアの FilterSpecs オブジェクトを作成するために使用され、このオブジェクトは SearchConfig にも追加されます。
3. この動的に構築された SearchConfig は、データストアに送信される検索リクエストの QueryParameters に含まれます。

検索条件を構成する

検索条件を構成する前に、次のことを確認してください。

• 既存の会話エージェント（Dialogflow CX）エージェント。
• 1 つ以上のデータストアが有効になっているエージェント用に構成されたデータストア ツール。

コンソールの構成

1. Conversational Agents コンソールを開き、 Google Cloudプロジェクトを選択します。
2. プルダウン メニューからエージェントを選択します。
3. 左側のメニューに移動して、[ツール] をクリックします。構成するデータストア ツールを選択します。
4. ツール編集ページで、[データストア] セクションに移動します。変更するデータストアの横にある [設定] アイコン（⚙️）をクリックします。
5. [データストアを構成] メニューが表示されます。ここでは、ブースト仕様とフィルタ仕様を追加して、検索結果を変更できます。
   • ブースト仕様の場合は、ConditionBoostSpec を定義する JSON オブジェクトを指定します。詳細については、ブーストの仕様をご覧ください。
   • フィルタ仕様の場合は、フィルタ条件を定義する文字列を指定します。詳しくは、フィルタの仕様をご覧ください。
6. 仕様を追加して構成したら、サイドパネルの下部にある [確認] をクリックします。
7. データストア ツールの編集ページで [保存] をクリックして、変更を保存します。

API 設定

インテント検出リクエストを送信するときに、検索構成データを会話エージェント（Dialogflow CX）に提供できます。この情報はセッションで維持されないため、すべてのインテント検出リクエストで提供する必要があります。

この情報は、Sessions.detectIntent メソッドの queryParams.searchConfig フィールドに入力します。

Session API リファレンスに移動

セッション リファレンスのプロトコルとバージョンを選択:

プロトコル	V3	V3beta1
REST	セッション リソース	セッション リソース
RPC	セッション インターフェース	セッション インターフェース
C++	SessionsClient	利用できません
C#	SessionsClient	利用できません
Go	SessionsClient	利用できません
Java	SessionsClient	SessionsClient
Node.js	SessionsClient	SessionsClient
PHP	利用不可	利用できません
Python	SessionsClient	SessionsClient
Ruby	利用不可	利用できません

終了

Dialogflow CX Messenger の構成

検索構成データを Dialogflow CX Messenger の統合に提供できます。詳しくは、setContext メソッドをご覧ください。

検索仕様または検索構成を適用するには、ウェブサイトに埋め込むときに、次のスニペットを Dialogflow CX Messenger コードに追加する必要があります。

<script>
  document.addEventListener('df-messenger-loaded', () => {
    const dfMessenger = document.querySelector('df-messenger');
    const searchConfig = { ... }
    dfMessenger.setQueryParameters(searchConfig);
  });
</script>

詳しくは、setQueryParameters メソッドをご覧ください。

トラブルシューティング

このセクションでは、構成中に発生する一般的な問題の解決策について説明します。さまざまなセッション パラメータとエンドユーザーのメタデータ値をトリガーする会話をシミュレートして、構成を常に徹底的にテストしてください。

無効な式

ブースト仕様の条件またはフィルタ仕様の文字列に無効な会話エージェント（Dialogflow CX）式（構文が正しくない、存在しないパラメータを参照しているなど）が含まれている場合、式のコンパイルは失敗します。式のコンパイルに関連するエラーは通常、diagnostic_info フィールド内の DetectIntentResponse として SystemFunctionResults で返されます。

無効な ConditionBoostSpec JSON

Conversational Agents コンソールは、ConditionBoostSpec JSON 文字列を保存するときに検証を行います。これは、有効な JSON であり、その構造を ConditionBoostSpec オブジェクトにマッピングできることを確認するためです。JSON が有効であっても、基盤となる検索サービスで無効な SearchConfig が生成される場合（パラメータ置換後の無効な条件文字列など）、検索サービスはエラーを返します。

実行時の置換エラー

ConditionBoostSpec JSON 文字列が有効で解析可能であっても、そのフィールド（条件文字列など）内の Dialogflow 式の実行時置換中にエラーが発生した場合、これらのエラーは diagnostic_info で SystemFunctionResults として報告されます。

コンパイル済みの SearchConfig を確認する

クエリの実行時に適用された SearchConfig は、レスポンスの search_signals で確認できます。SearchConfig を確認すると、ここに記載されていない問題に関する情報が得られることがあります。

次のステップ

• SearchConfig の構造とそのコンポーネントの詳細については、search_config のドキュメントをご覧ください。
• 式の構文の詳細については、Dialogflow の条件とシステム関数のリファレンスをご覧ください。
• 検索のフィルタ式構文の詳細については、結果のフィルタリングと並べ替えをご覧ください。