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

此页面由 Cloud Translation API 翻译。

导入用于搜索的自动补全数据

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

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

以下说明仅适用于上传您自己的自动补全数据。如果您打算使用自动补全功能，请及时更新该信息数据集。如需在查询时获取自动补全结果，请参阅 CompletionService.CompleteQuery。自动补全数据现为仅用于搜索。此数据不会用于建议。

准备工作

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

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

自动补全导入最佳实践

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

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

导入自动补全数据

从 BigQuery 导入自动补全数据

适用于零售业的 Vertex AI Search 支持拒绝 BigQuery 数据导入列表、“请勿删除列表”和“建议字词列表”。如需了解详情，请参阅自动补全。

若要以正确的格式从 BigQuery，请使用 Vertex AI Search for Retail 自动补全架构以正确的格式创建 BigQuery 表并使用自动补全数据加载表格。然后，上传您的 Vertex AI Search for Retail。

如需有关 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

控制台

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

系统随即会打开 Import 窗格。
输入数据位置的 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"
    }
  }
}
```

通过以下方式将自动补全信息导入 Vertex AI Search for Retail 向POST CompletionData:import REST 方法，提供数据文件的名称（在下面的示例中显示为 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
}

名称字段是操作对象的 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。

数据集导入完成后，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 自动补全拒绝名单架构 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"
  }
]