Vertex AI Search for retail 已更名為 Vertex AI Search for commerce。我們會更新內容，反映新的品牌形象。

本頁面由 Cloud Translation API 翻譯而成。

匯入搜尋的自動完成資料

自動完成功能可預測使用者正在輸入的字詞其餘部分，進而改善使用者的搜尋體驗。這項服務可根據您提供的資料集或使用者事件，提供輸入建議。

只有在您想要使用額外控制項 (「請勿移除」清單、「拒絕清單」) 或需要使用自己的自動完成資料時，才考慮匯入自動完成資料。在需要自動完成功能的大多數情況下，只要開啟自動學習功能即可。自動學習功能會根據使用者的搜尋事件，提供機器學習技術輔助的建議資料集。如要瞭解如何開啟自動學習功能，請參閱「自動完成」一文。

以下操作說明僅適用於上傳您自己的自動完成資料。如果您打算持續使用自動完成資料集，請務必保持資料集更新。如要在查詢時取得自動完成結果，請參閱 CompletionService.CompleteQuery。自動完成資料只會用於搜尋。這項資料不會用於提供推薦內容。

事前準備

您必須先完成「開始前準備」一節中的操作說明，才能匯入自動完成資訊，具體來說，就是設定專案、建立服務帳戶，以及將服務帳戶新增至本機環境。

你必須具備Retail 編輯者身分與存取權管理角色，才能執行匯入作業。

自動完成匯入最佳做法

匯入自動完成資料時，請務必實施下列最佳做法：

請參閱下列章節和 API 說明文件中列出的 BigQuery 結構定義。
請勿使用預留位置值。
請盡可能多加入欄位。
如果您打算使用自己上傳的資料集，請確保自訂的自動完成資料集保持最新狀態。
不允許從其他專案匯入資料。

匯入自動完成資料

從 BigQuery 匯入自動完成資料

Vertex AI Search for Commerce 支援拒絕清單、請勿移除清單和建議字詞清單的 BigQuery 資料匯入功能。詳情請參閱「自動完成」。

如要以正確格式從 BigQuery 匯入自動完成資料，請使用 Vertex AI Search for commerce 自動完成資料結構定義，以正確格式建立 BigQuery 資料表，並載入資料表，其中包含您的自動完成資料。接著，將資料上傳至商家適用的 Vertex AI Search。

如需 BigQuery 資料表的其他說明，請參閱「資料表簡介」。如需 BigQuery 查詢的說明，請參閱「查詢 BigQuery 資料總覽」。

BigQuery 資料集位置

首次為自動完成 BigQuery 資料表建立 BigQuery 資料集時，請確認資料集位置已設為多區域位置 "US"。如果未正確設定，日後匯入要求就會失敗。如要進一步瞭解 BigQuery 資料集位置，請參閱 BigQuery 說明文件中的「資料集位置」。

將資料填入 BigQuery

使用 Vertex AI Search for commerce 自動完成結構定義，將自動完成資料上傳至 BigQuery。

BigQuery 可以使用結構定義驗證 JSON 格式資料是否有正確的欄位名稱和類型 (例如 STRING、INTEGER 和 RECORD)，但無法執行驗證作業，例如判斷：

如果字串欄位對應至可辨識的列舉值。
字串欄位是否使用正確的格式。
如果整數或浮點欄位的值位於有效範圍內。
未填寫的欄位是必填欄位。

為確保資料品質和使用者搜尋體驗，請務必參閱結構定義和參考文件，瞭解值和格式的詳細資訊。

設定 BigQuery 資料集的存取權

如要設定存取權，請確認您的 BigQuery 資料集與 Vertex AI Search for commerce 服務位於相同專案，然後完成下列步驟。

在 Google Cloud 控制台中開啟「IAM」頁面。

開啟 IAM 頁面
選取 Vertex AI Search for Commerce 專案。
在「IAM 與管理」頁面中，按一下「授予存取權」。
針對「New principals」(新管理者)，請輸入 cloud-retail-customer-data-access@system.gserviceaccount.com，然後選取「BigQuery > BigQuery Data Viewer」(BigQuery 資料檢視者) 角色。

如果您不想將「資料檢視者」角色提供給整個專案，可以直接將這個角色新增至資料集。瞭解詳情。
按一下 [儲存]。

觸發資料匯入至商家適用的 Vertex AI Search

主控台

前往「Controls」(控制項) 頁面
前往「Autocomplete」(自動完成) 分頁。
在「關鍵字清單」部分，找出要匯入的清單類型 (拒絕清單、不要移除清單或建議關鍵字清單)，然後按一下「匯入」或「取代」。

「Import」窗格隨即開啟。
輸入資料位置的 BigQuery 路徑，或選取「瀏覽」來選取位置。

BigQuery 路徑必須位於相同專案中，且其結構定義應正確無誤。如要確認這項資訊，請按一下「Browse」，然後點選資料表名稱，即可在 BigQuery 控制台中查看其內容。
在「Import」窗格中，按一下「Import」。

匯入作業開始。您可以離開頁面，匯入作業不會因此中斷。

cURL

建立匯入作業的輸入參數資料檔案。輸入參數值取決於您是從 Cloud Storage 或 BigQuery 匯入資料。

使用 BigQuerySource 物件指向 BigQuery 資料集。
- 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"
    }
  }
}
```

將自動完成資訊匯入商家適用的 Vertex AI Search，方法是向 CompletionData:import REST 方法提出 POST 要求，並提供資料檔案名稱 (在下方範例中顯示為 input.json)。

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
}

name 欄位是 operation 物件的 ID。如要要求這個物件的狀態，請將名稱欄位替換為匯入方法傳回的值。匯入完成後，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 檔案應如以下範例所示。換行符號可讓內容更易於閱讀；建議您在單一行中提供完整的建議內容。每個建議都應單獨一行。

建議的最低必填欄位：

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

或：

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

自動完成資料匯入時間長度

從 BigQuery 匯入資料通常需要幾分鐘到一個小時。

資料集匯入完成後，作業物件中的 done 欄位會標示為 true。之後，資料可能還需要 1 到 2 天的時間才能建立索引，並用於正式版服務。

保持自動完成資料集的最新狀態

如果您打算使用自己上傳的資料集，建議您定期更新上傳的資料集。

批次更新

您可以使用匯入方法批次更新自動完成功能。這項操作的做法與初始匯入相同，請按照「匯入自動完成資料」一文中的步驟操作。這會取代整個匯入的資料集。

監控匯入作業的健康狀態

如要取得優質的建議結果，請務必隨時更新自己的資料集。您應監控匯入錯誤率，並視需要採取行動。

商家適用的 Vertex AI Search 自動完成結構定義

從 BigQuery 匯入自動完成資料集時，請使用下方的 Vertex AI Search for commerce 結構定義，以正確格式建立 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 Search 自動完成拒絕清單 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"
  }
]

匯入搜尋的自動完成資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

自動完成匯入最佳做法

匯入自動完成資料

從 BigQuery 匯入自動完成資料

BigQuery 資料集位置

將資料填入 BigQuery

設定 BigQuery 資料集的存取權

觸發資料匯入至商家適用的 Vertex AI Search

主控台

cURL

自動完成資料格式

自動完成資料匯入時間長度

保持自動完成資料集的最新狀態

批次更新

監控匯入作業的健康狀態

商家適用的 Vertex AI Search 自動完成結構定義

建議的結構定義

商家適用的 Vertex AI Search 自動完成建議 JSON 結構定義

JSON

拒絕清單的結構定義

商家適用的 Vertex AI Search 自動完成拒絕清單 JSON 結構定義

JSON

許可清單的結構定義

商家適用的 Vertex AI Search 自動完成功能許可清單結構定義 JSON

JSON

匯入搜尋的自動完成資料