导入自动补全数据以供搜索

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

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

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

准备工作

在导入自动补全信息之前，您必须先按照准备工作中的说明完成操作，具体包括设置项目、创建服务帐号以及将服务帐号添加到本地环境。

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

自动补全导入的最佳实践

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

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

  • 请勿使用占位值。

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

  • 如果您计划使用自己的上传的数据集，请及时更新自己的自动补全数据集。

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

导入自动补全数据

从 BigQuery 导入自动补全数据

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

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

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

BigQuery 数据集位置

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

将数据填充到 BigQuery

使用适用于零售业的 Vertex AI Search 自动补全架构，将您的自动补全数据上传到 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. 在 Import 窗格中，点击 Import。

    导入过程随即开始。您可以在不中断导入的情况下离开页面。

cURL

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

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

    {
  "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 表，并使用您的自动补全数据加载这些表。

建议的架构

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

拒绝名单架构

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

许可名单的架构

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