“零售”已重命名为 Vertex AI Search 零售解决方案。我们正在更新内容，以反映新品牌。

此页面由 Cloud Translation API 翻译。

导入搜索的自动补全数据

自动补全功能用于预测用户正在输入字词的其余部分，从而改善用户搜索体验。它可以根据您提供的数据集或您提供的用户事件提供预输入建议。

仅当您想要使用其他控制功能（“请勿移除名单”“拒绝名单”）或需要使用自己的自动补全数据时，才应考虑导入自动补全数据。对于需要自动补全的大多数情况，只需开启自动学习功能即可。自动学习功能可根据用户搜索事件提供机器学习支持的建议数据集。如需了解如何开启自动学习功能，请参阅自动补全。

以下说明仅适用于上传您自己的自动补全数据。如果您计划始终使用自动补全数据集，请使其保持最新。如需在查询时获取自动补全结果，请参阅 CompletionService.CompleteQuery。自动补全数据仅用于搜索。这些数据不会用于推荐功能。

准备工作

在导入自动补全信息之前，您必须已完成准备工作中的说明，特别是设置项目、创建服务账号和将服务账号添加到本地环境。

您必须拥有 Retail Editor IAM 角色才能执行导入。

自动补全导入最佳实践

导入自动补全数据时，请确保实现以下最佳实践：

阅读以下部分和 API 文档中列出的 BigQuery 架构。
请勿使用占位符值。
请添加尽可能多的字段。
如果您计划使用自己上传的数据集，请使您自己的自动补全数据集保持最新。
不允许从其他项目导入数据。

导入自动补全数据

从 BigQuery 导入自动补全数据

Vertex AI Search for Retail 支持将拒绝名单、请勿移除名单和建议字词列表导入 BigQuery。如需了解详情，请参阅自动补全。

如需从 BigQuery 以正确的格式导入自动补全数据，请使用 Vertex AI Search for Retail 自动补全架构以正确格式创建 BigQuery 表，并使用您的自动补全数据加载表。然后，将您的数据上传到 Vertex AI Search 零售解决方案。

如需有关 BigQuery 表的更多帮助，请参阅表简介。如需有关 BigQuery 查询的帮助，请参阅查询 BigQuery 数据概览。

BigQuery 数据集位置

首次为自动补全 BigQuery 表创建 BigQuery 数据集时，请确保将数据集位置设置为多区域位置 "US"。如果未正确设置，日后您的导入请求可能会失败。如需详细了解 BigQuery 数据集位置，请参阅 BigQuery 文档中的数据集位置。

将数据填充到 BigQuery

使用 Vertex AI Search for Retail 自动补全架构将自动补全数据上传到 BigQuery。

BigQuery 可以使用架构来验证 JSON 格式的数据是否具有正确的字段名称和类型（例如 STRING、INTEGER 和 RECORD），但无法执行如下验证：确定：

如果字符串字段映射到可识别的枚举值。
使用正确格式的字符串字段。
如果整数或浮点字段的值在有效范围内。
若缺少字段为必填字段。

为了确保数据和最终用户搜索体验的质量，请务必参阅架构和参考文档，详细了解值和格式。

设置对 BigQuery 数据集的访问权限

如需设置访问权限，请确保您的 BigQuery 数据集与 Vertex AI Search for Retail 服务位于同一项目中，然后完成以下步骤。

在 Google Cloud Console 中打开 IAM 页面。

打开 IAM 页面
选择您的 Vertex AI Search for Retail 项目。
在 IAM 和管理页面上，点击 授予访问权限。
对于新主账号，输入 cloud-retail-customer-data-access@system.gserviceaccount.com，然后选择 BigQuery > BigQuery Data Viewer 角色。

如果您不想向整个项目提供 Data Viewer 角色，则可以将此角色直接添加到数据集。了解详情。
点击保存。

触发将数据导入 Vertex AI Search for Retail

控制台

转到“控件”页面
前往自动补全控件标签页。
在字词列表部分，找到您计划导入的列表类型（拒绝列表、不移除列表或建议的字词列表），然后点击导入或替换。

系统会打开导入窗格。
输入数据位置的 BigQuery 路径，或选择浏览以选择该位置。

BigQuery 路径必须位于同一项目中，并且其架构应正确无误。如需进行检查，请点击浏览，然后点击表名称以在 BigQuery 控制台中查看其内容。
在导入窗格中，点击导入。

导入流程随即开始。您可以离开此页面，而不会中断导入。

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"
    }
  }
}
```

通过向 CompletionData:import REST 方法发出 POST 请求，提供数据文件的名称（在以下示例中显示为 input.json），将自动补全信息导入 Vertex AI Search 零售解决方案。

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。如需请求此对象的状态，请将名称字段替换为导入方法返回的值。导入完成后，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"

操作完成后，返回的对象的 done 值为 true，并且包含一个类似于以下示例的 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 进行一次导入通常需要大约几分钟到 1 小时。

数据集导入完成后，操作对象中的 done 字段会被标记为 true。之后，可能还需要 1 到 2 天的时间来编制索引，然后才能在正式版中使用。

使自动补全数据集保持最新

如果您打算使用自己的上传数据集，则最佳做法是定期更新上传的数据集。

批量更新

您可以使用导入方法来批量更新自动补全功能。具体操作方式与初始导入相同；按照导入自动补全数据中的步骤操作。这将替换整个导入的数据集。

监控导入运行状况

使用最新的数据集，对于在使用数据集时获得高质量的建议结果非常重要。您应监控导入错误率，并在需要时采取措施。

Vertex AI Search 零售解决方案自动补全架构

从 BigQuery 导入自动补全数据集时，请使用下面的 Vertex AI Search for Retail 架构创建具有正确格式的 BigQuery 表，并加载包含自动补全数据的表。

建议的架构

此数据集用于提供您自己的自动补全建议短语，并附带您自己的得分。

Vertex AI Search for Retail 自动补全建议架构 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 for Retail 自动补全功能拒绝名单架构 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 for Retail 自动补全功能许可名单架构 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"
  }
]