这是与 Recommendations AI、Retail Search 和新的 Retail 控制台相关的文档。如需在受限 GA 阶段使用 Retail Search,请与 Cloud 销售人员联系

如果您仅使用 Recommendations AI,请保留在 Recommendations 控制台上并参阅 Recommendations AI 文档

导入自动补全数据

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

本页面介绍如何将自动补全的数据集导入 Retail。以下说明仅适用于上传您自己的自动补全数据。如果您计划始终使用自动完成数据集,请使其保持最新。如需获取自动补全,请参阅 CompletionService.CompleteQuery。自动补全数据仅用于 Retail Search。此数据不会用于 Recommendations AI。

准备工作

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

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

自动补全导入最佳做法

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

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

    请勿使用虚拟值或占位值。

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

  • 如果您计划使用自己上传的数据集,请使您自己的自动补全数据集保持最新。

导入自动补全数据

从 BigQuery 导入自动补全数据

要从 BigQuery 以正确格式导入自动补全数据,请使用Retail 自动补全架构创建 BigQuery 表格,使用正确的格式,并使用您的自动补全数据加载表。然后,将您的数据上传到 Retail。

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

将数据补全到 BigQuery

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

BigQuery 可以使用架构来验证 JSON 格式的数据是否具有正确的字段名称和类型(例如 STRINGINTEGERRECORD),但无法执行如下验证:确定:

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

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

将自动补全数据导入 Retail

curl

  1. 如果您的 BigQuery 数据集位于其他项目中,请配置所需的权限,以便 Retail 可以访问 BigQuery 数据集。了解详情

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

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

    • dataset-id:BigQuery 数据集的 ID。
    • table-id:存放数据的 BigQuery 表的 ID。
    • data-schema:对于 dataSchema 属性,请使用值 suggestions(默认值)、allowlistdenylist。您将使用 Retail 自动架构
    {
      "inputConfig":{
        "bigQuerySource": {
          "datasetId":"dataset-id",
          "tableId":"table-id",
          "dataSchema":"data-schema"
        }
      }
    }
    
  3. 通过向 CompletionData:import REST 方法发出 POST 请求,提供数据文件的名称(此处显示为),将自动补全信息导入 Retail 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",
      }
    }
    

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

如果 BigQuery 数据集与 Retail 服务属于不同的项目,要设置访问权限,请完成以下步骤。

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

    打开 IAM 页面

  2. 选择您的 Retail 项目。

  3. 找到名为 Retail Service Account 的服务帐号。

    如果您之前未曾使用过 Retail 启动导入操作,则此服务帐号可能未列出。如果您没有看到此服务帐号,请返回导入任务并启动导入。当由于权限错误而失败时,请返回此处完成此任务。

  4. 复制服务帐号的标识符,类似于电子邮件地址(例如 cloud-retail-customer-data-access@system.gserviceaccount.com)。

  5. IAM 和管理上,点击添加

  6. 输入 Retail 服务帐号的标识符,然后选择 BigQuery > BigQuery Data Viewer 角色。

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

  7. 点击保存

自动补全数据格式

JSON 文件应类似于以下示例。换行符便于阅读;您应该在一行中提供完整的建议。每条建议应各为一行。

建议最少的必填字段:

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

或:

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

自动填充数据导入时长

从 BigQuery 进行一次导入通常需要大约 10 小时。长时间运行的操作推送数据集推进行生产服务。数据集准备就绪后,操作对象中的 done 字段将被标记为 true。在操作为 done 之前,无法保证从导入数据集中获取最新建议。

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

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

批量更新

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

监控导入运行状况

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

Retail 自动补全架构

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

建议的架构

此数据集用于建议带有 typeahead 的短语。

拒绝名单架构

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

许可名单的架构

此数据集用于跳过此许可名单中的所有短语,例如进行拼写更正。