検索用のオートコンプリート データをインポートする

プレビュー

この機能には、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 pre-GA の機能は「現状有姿」で利用できますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

オートコンプリートは、ユーザーが入力した語句の残りを予測する機能であり、ユーザーの検索エクスペリエンスが向上します。提供されたデータセットまたは提供されたユーザー イベントに基づいて、先行入力候補を提供できます。

その他の制御（削除対象外リスト、拒否リスト）が必要な場合や、独自のオートコンプリート データを使用する必要がある場合にのみ、オートコンプリート データをインポートすることを検討してください。オートコンプリートが必要となるほとんどのケースでは、自動学習を有効にするだけで十分です。自動学習では、ユーザー検索イベントに基づいて、機械学習を活用した候補データセットが提供されます。自動学習を有効にする方法については、オートコンプリートをご覧ください。

注: 2022 年 9 月から、[Cloud コンソール] > [コントロール] > [オートコンプリート コントロール] UI を使用して、データのインポートをトリガーできます。

以下の手順は、独自のオートコンプリート データのみをアップロードするためのものです。オートコンプリート データセットを常に使用する予定の場合は、最新の状態を保つようにしてください。クエリの実行時にオートコンプリート結果を取得する方法については、CompletionService.CompleteQuery をご覧ください。オートコンプリート データは検索にのみ使用されます。このデータはレコメンデーションでは使用されません。

始める前に

オートコンプリート情報を読み込むには、事前に始める前にの手順、特にプロジェクトの設定、サービス アカウントの作成、ローカル環境へのサービス アカウントの追加を完了しておく必要があります。

インポートを実行するには、Retail 編集者の IAM ロールが必要です。

オートコンプリートのインポートに関するベスト プラクティス

オートコンプリート データをインポートするときは、次のベスト プラクティスを実施するようにしてください。

• 次のセクションにリストされている BigQuery スキーマと API ドキュメントを確認する。

• プレースホルダの値は使用しないでください。

• できるだけ多くのフィールドを指定します。

• 独自のアップロード済みデータセットを使用する場合は、独自のオートコンプリート データセットを最新の状態に保ちます。

• 別のプロジェクトからのデータ インポートは禁止されています。

オートコンプリート データをインポートする

オートコンプリート データを BigQuery からインポートする

小売業向け Vertex AI Search は、拒否リスト、削除対象外リスト、候補の語句リストに関する BigQuery データのインポートをサポートしています。詳しくは、オートコンプリートをご覧ください。

オートコンプリート データを BigQuery から正しい形式でインポートするには、小売業向け Vertex AI Searchl のオートコンプリート スキーマを使用して、正しい形式で BigQuery テーブルを作成し、オートコンプリート データでテーブルを読み込みます。次に、データを小売業向け Vertex AI Search にアップロードします。

BigQuery テーブルの詳細については、テーブルの概要をご覧ください。BigQuery クエリについては、BigQuery データのクエリの概要をご覧ください。

BigQuery データセットの場所

オートコンプリートを使用した BigQuery テーブル用に初めて BigQuery データセットを作成するときは、データセットのロケーションがマルチリージョン ロケーション "US" に設定されていることを確認してください。正しく設定しないと、後でインポート リクエストが失敗します。BigQuery データセットのロケーションの詳細については、BigQuery のドキュメントのデータセットのロケーションをご覧ください。

BigQuery にデータを入力する

小売業向け Vertex AI Search のオートコンプリート スキーマを使用して、オートコンプリート データを BigQuery にアップロードします。

BigQuery は、このスキーマを使用して、JSON 形式のデータに正しいフィールド名と型（STRING、INTEGER、RECORD など）があるかどうかを確認できます。ただし、次のような判定の確認を行うことはできません。

• 文字列フィールドが認識可能な列挙値にマッピングされているかどうか
• 文字列フィールドが正しい形式を使用しているかどうか
• 整数フィールドまたは浮動小数点フィールドに有効な範囲内の値があるかどうか
• 欠落しているフィールドが必須フィールドであるかどうか

データの品質とエンドユーザーの検索エクスペリエンスを確保するために、値と形式に関する詳細について、スキーマとリファレンスのドキュメントを参照してください。

BigQuery データセットへのアクセス権を設定する

アクセス権を設定するには、BigQuery データセットが小売業向け Vertex AI Search サービスと同じプロジェクトにあることを確認して、次の手順を実施します。

1. Google Cloud コンソールで [IAM] ページを開きます。

   [IAM] ページを開く

2. 小売業向け Vertex AI Search プロジェクトを選択します。

3. [IAM と管理] ページで、 [アクセス権を付与] をクリックします。

4. [新しいプリンシパル] に「[e-mail]」と入力し、[BigQuery] > [BigQuery Data Viewer] のロールを選択します。

   プロジェクト全体でデータ閲覧者のロールを指定したくない場合は、このロールをデータセットに直接追加できます。詳細

5. [保存] をクリックします。

小売業向け Vertex AI Search へのデータのインポートをトリガーする

コンソール

1. [Controls] ページに移動

2. [オートコンプリート コントロール] タブに移動します。

3. [語句リスト] セクションで、インポートするリストの種類（[拒否リスト]、[削除対象外リスト]、[候補用語のリスト）を見つけ、[インポート] または [置換] をクリックします。

   [インポート] ペインが開きます。

4. データ ロケーションの BigQuery のパスを入力するか、[参照] を選択してロケーションを選択します。

   BigQuery のパスが同じプロジェクト内にあり、そのスキーマが正しいことが必要です。これを確認するには、[参照] をクリックしてテーブル名をクリックし、BigQuery コンソールでコンテンツを表示します。

5. [インポート] ペインで [インポート] をクリックします。

   インポートが開始されます。インポートを中断せずにページを離れることができます。

cURL

1. インポートの入力パラメータのデータファイルを作成します。入力パラメータ値は、Cloud Storage または BigQuery のどちらからインポートするかによって異なります。

   BigQuery データセットを指定するには、BigQuerySource オブジェクトを使用します。

   • dataset-id: BigQuery データセットの ID。
   • table-id: データを保持する BigQuery テーブルの ID。
   • data-schema: dataSchema プロパティには、suggestions（デフォルト）、allowlist、denylist の値を使用します。小売業向け Vertex AI Search のオートコンプリート スキーマを使用します。

   {
     "inputConfig":{
       "bigQuerySource": {
         "datasetId":"dataset-id",
         "tableId":"table-id",
         "dataSchema":"data-schema"
       }
     }
   }
   

2. CompletionData:import REST メソッドに POST リクエストを行い、データファイルの名前（下の例では input.json）を指定して、オートコンプリート情報を小売業向け Vertex AI Search for Retail にインポートします。

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" -d @./input.json
   "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/completionData:import"
   

   API を使用して、プログラムでステータスを確認できます。次のようなレスポンス オブジェクトが返されます。

   {
     "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456",
     "done": false
   }
   

   名前の項目は、オペレーション オブジェクトの ID です。このオブジェクトのステータスをリクエストするには、名前フィールドを import メソッドから返される値に置き換えます。インポートが完了すると、done フィールドは true を返します。

   curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456"
   

   オペレーションが完了すると、返されたオブジェクトは true の done 値を持ち、次の例のような Status オブジェクトが含まれます。

   {
     "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportMetadata",
       "createTime": "2020-01-01T03:33:33.000001Z",
       "updateTime": "2020-01-01T03:34:33.000001Z",
       "successCount": "2",
       "failureCount": "1"
     },
     "done": true
     "response": {
       "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportCompletionDataResponse",
     }
   }
   

オートコンプリート データの形式

JSON ファイルは次の例のようになります。改行は読みやすくするためのものです。候補全体を 1 行で入力する必要があります。 各候補は 1 行にまとめる必要があります。

候補の最低限の必須項目は、次のとおりです。

{
  "suggestion": "ABC",
  "globalScore": "0.5"
}

または

{
  "suggestion": "ABC",
  "frequency": "100"
}

オートコンプリート データのインポート時間

BigQuery から 1 つのインポートが完了するまでに数分から 1 時間ほどかかります。

データセットのインポートが終了すると、オペレーション オブジェクトの done フィールドが true とマークされます。その後、データがインデックスに登録され、本番環境サービスで使用されるまでに 1 ～ 2 日かかることがあります。

オートコンプリート データセットを最新の状態に保つ

独自のアップロード済みデータセットを使用する場合は、アップロード済みデータセットを、定期的に最新の状態に保つことをおすすめします。

バッチ アップデート

import メソッドを使用して、オートコンプリートをバッチ アップデートできます。これは初期インポートと同じです。オートコンプリート データをインポートするの手順に従ってください。これにより、インポートされたデータセット全体が置き換えられます。

インポート状態をモニタリングする

独自のデータセットを最新の状態に保つことは、使用時に高品質の候補の結果を得るうえで重要です。インポートのエラー率をモニタリングし、必要に応じて対処する必要があります。

小売業向け Vertex AI Search のオートコンプリート スキーマ

オートコンプリート データセットを BigQuery からインポートする場合は、以下の小売業向け Vertex AI Search スキーマを使用して、正しい形式の BigQuery テーブルを作成し、オートコンプリート データでテーブルを読み込みます。

提案のスキーマ

このデータセットは、独自のオートコンプリートの候補のフレーズに独自のスコアを提供するために使用されます。

小売業向け Vertex AI Search オートコンプリートの候補スキーマの JSON

JSON

[
  {
    "description": "The suggestion text",
    "mode": "NULLABLE",
    "name": "suggestion",
    "type": "STRING"
  },
  {
    "description": "Global score of this suggestion. Control how this suggestion would be scored / ranked. Only one of this and frequency should be set.",
    "mode": "NULLABLE",
    "name": "globalScore",
    "type": "FLOAT"
  },
  {
    "description": "Frequency of this suggestion. Will be used to rank suggestions when score is not available.",
    "mode": "NULLABLE",
    "name": "frequency",
    "type": "INTEGER"
  },
  {
    "description": "BCP-47 language code of this suggestion.",
    "mode": "NULLABLE",
    "name": "languageCode",
    "type": "STRING"
  },
  {
    "description": "If two suggestions have the same groupID, they will not be returned together. Instead the one ranked higher will be returned. This can be used to deduplicate semantically identical suggestions.",
    "mode": "NULLABLE",
    "name": "groupID",
    "type": "STRING"
  },
  {
    "description": "The score of this suggestion within its group",
    "mode": "NULLABLE",
    "name": "groupScore",
    "type": "FLOAT"
  },
  {
    "description": "Device type for this suggestion.",
    "mode": "NULLABLE",
    "name": "deviceType",
    "type": "STRING"
  },
  {
    "description": "Alternative matching phrases for this suggestion.",
    "mode": "REPEATED",
    "name": "alternativePhrases",
    "type": "STRING"
  },
  {
    "fields": [
      {
        "description": "The name of the custom attribute.",
        "mode": "NULLABLE",
        "name": "key",
        "type": "STRING"
      },
      {
        "fields": [
          {
            "description": "The textual values of this custom attribute.",
            "mode": "REPEATED",
            "name": "text",
            "type": "STRING"
          },
          {
            "description": "The numerical values of this custom attribute.",
            "mode": "REPEATED",
            "name": "numbers",
            "type": "FLOAT"
          }
        ],
        "mode": "NULLABLE",
        "name": "value",
        "type": "RECORD"
      }
    ],
    "description": "A custom attribute that is not explicitly modeled, which can be retrieved together with the suggestion at serving time.",
    "mode": "REPEATED",
    "name": "customAttributes",
    "type": "RECORD"
  }
]

拒否リストのスキーマ

このデータセットは、フレーズを提案しないように拒否リストとして使用します。

小売業向け Vertex AI Searchl オートコンプリートの拒否リスト スキーマの JSON

JSON

[
  {
    "description": "The phrase to block from autocomplete suggestions.",
    "mode": "REQUIRED",
    "name": "phrase",
    "type": "STRING"
  },
  {
    "description": "The operator to apply for this phrase. Choose whether to block the exact phrase, or block any suggestions containing this phrase. Supported value \"EXACT_MATCH\", \"CONTAINS\"",
    "mode": "REQUIRED",
    "name": "operator",
    "type": "STRING"
  }
]

許可リストのスキーマ

このデータセットは、この許可リストに含まれているフレーズの後処理（スペル修正やゼロ結果のフィルタリングなど）をスキップするために使用されます。

小売業向け Vertex AI Search オートコンプリートの許可リスト スキーマの JSON

JSON

[
  {
    "description": "The phrase to be exempted from autocomplete post processing, e.g. spell correction, filtering",
    "mode": "REQUIRED",
    "name": "phrase",
    "type": "STRING"
  },
  {
    "description": "The operator to apply for this phrase. Whether to match the exact phrase, or any suggestions contain this phrase. Supported values are \"EXACT_MATCH\", \"CONTAINS\".",
    "mode": "REQUIRED",
    "name": "operator",
    "type": "STRING"
  }
]