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

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

仅当您想要有其他控件（不移除列表、拒绝列表）或需要使用自己的自动补全数据时，可以考虑导入自动补全数据。对于大多数需要自动补全功能的情况，启用自动学习功能就足够了。自动学习功能会根据用户搜索事件，提供由机器学习技术提供支持的建议数据集。请参阅自动补全，了解如何开启自动学习功能。

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

准备工作

如需导入自动补全信息，您必须先完成准备工作中的说明，具体来说就是设置项目、创建服务帐号以及将服务帐号添加到本地环境。

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

自动补全导入最佳实践

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

  • 阅读以下部分和 API 文档中列出的 BigQuery 架构。

  • 请勿使用占位值。

  • 请添加尽可能多的字段。

  • 如果您打算使用自己的上传的数据集，请确保自己的自动补全数据集保持最新。

  • 不允许从其他项目导入数据。

导入自动补全数据

从 BigQuery 导入自动补全数据

适用于零售的 Vertex AI Search 支持通过 BigQuery 数据导入功能来拒绝名单、不移除名单和建议字词列表。如需了解详情，请参阅自动补全。

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

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

BigQuery 数据集位置

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

将数据填充到 BigQuery

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

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

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

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

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

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

  1. 在 Google Cloud Console 中打开 IAM 页面。

    打开 IAM 页面

  2. 选择您的 Vertex AI Search for Retail 项目。

  3. 在 IAM 和管理页面上，点击  授予访问权限。

  4. 在新的主帐号部分，输入 cloud-retail-customer-data-access@system.gserviceaccount.com 并选择 BigQuery > BigQuery Data Viewer 角色。

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

  5. 点击保存。

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

控制台

  1. 转到“控件”页面

  2. 转到自动补全控件标签。

  3. 在术语列表部分，找到要导入的列表类型（拒绝列表、“请勿移除”列表或建议的字词列表），然后点击导入或替换。

    系统随即会打开 Import 窗格。

  4. 输入数据位置的 BigQuery 路径，或选择浏览以选择位置。

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

  5. 在导入窗格中，点击导入。

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

cURL

  1. 为导入作业的输入参数创建一个数据文件。输入参数值取决于您是从 Cloud Storage 还是 BigQuery 导入。

    使用 BigQuerySource 对象指向 BigQuery 数据集。

    • dataset-id：BigQuery 数据集的 ID。
    • table-id：存放数据的 BigQuery 表的 ID。
    • data-schema：对于 dataSchema 属性，请使用值 suggestions（默认值）、allowlist、denylist。使用 Vertex AI Search for Retail 自动补全架构。
    {
  "inputConfig":{
    "bigQuerySource": {
      "datasetId":"dataset-id",
      "tableId":"table-id",
      "dataSchema":"data-schema"
    }
  }
}

  2. 向 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。如需请求此对象的状态，请将 name 字段替换为导入方法返回的值。导入完成后，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 表，并使用您的自动补全数据加载这些表。

建议的架构

此数据集用于提供您自己的自动补全建议短语和您自己的分数。

拒绝名单架构

此数据集用作拒绝名单，以阻止提供建议的短语。

许可名单的架构

此数据集用于针对此许可名单中的所有词组跳过后期处理（例如拼写更正和零结果过滤）。