データストア検索の構成

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

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

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

検索条件の入力

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

検索条件は、 コンソールを使用するか、 直接 API 呼び出しを送信するかのいずれかの方法で構成できます。 この 2 つには重要な違いがあります。

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

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

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

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

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

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

主なフィールド:

• condition: （文字列）ブーストを適用するタイミングを指定する式。標準のフィルタ式構文を使用します。 Dialogflow CX 式（$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 を直接呼び出す場合は、ConditionBoostSpecs を 完全な SearchConfig オブジェクトで指定する必要があります。次の検索構成は、ブースト仕様を表しています。

"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 は Agent Search の フィルタ式構文に従う必要があります。
ブースト値 は -1.0 ～ 1.0 にする必要があります。

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

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

各フィルタ スペック は文字列式として入力する必要があります。文字列は 標準のフィルタ式構文に準拠している必要があります。 この文字列内で Dialogflow CX 式（$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 は Agent Search の フィルタ式構文に従う必要があります。

Dialogflow CX の動的式

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

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

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

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

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

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

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

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

検索条件を構成する

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

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

コンソールの構成

1. 会話エージェント コンソールを開き、 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 式（構文が正しくない、存在しないパラメータを参照しているなど）が含まれている場合、式のコンパイルは失敗します。式のコンパイルに関連するエラーは通常、DetectIntentResponse のdiagnostic_info フィールドにSystemFunctionResultsとして返されます。

ConditionBoostSpec JSON が無効です

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

ランタイム置換エラー

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

コンパイルされた SearchConfig を確認する

クエリの実行時に適用される SearchConfig は、レスポンスの search_signals で確認できます。SearchConfig を確認すると、ここに記載されていない追加の問題を把握できる場合があります。

次のステップ

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