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

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

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

注: 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:importREST メソッドに 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"
  }
]