自动补全功能用于预测用户正在输入字词的其余部分,从而改善用户搜索体验。它可以根据您提供的数据集或您提供的用户事件提供预输入建议。
本页面介绍如何将自动补全的数据集导入 Retail。以下说明仅适用于上传您自己的自动补全数据。如果您计划始终使用自动完成数据集,请使其保持最新。如需获取自动补全,请参阅 CompletionService.CompleteQuery。自动补全数据仅用于 Retail Search。此数据不会用于 Recommendations AI。
准备工作
在导入自动补全信息之前,您必须已完成准备工作中的说明,特别是设置项目、创建服务帐号和将服务帐号添加到本地环境。
您必须拥有 Retail Editor IAM 角色才能够执行导入操作。
自动补全导入最佳做法
导入自动补全数据时,请确保实现以下最佳做法:
阅读以下部分和 API 文档中列出的架构文件。
请勿使用虚拟值或占位值。
请添加尽可能多的字段。
如果您计划使用自己上传的数据集,请使您自己的自动补全数据集保持最新。
导入自动补全数据
从 BigQuery 导入自动补全数据
要从 BigQuery 以正确格式导入自动补全数据,请使用Retail 自动补全架构来创建 BigQuery 表格,使用正确的格式,并使用您的自动补全数据加载表。然后,将您的数据上传到 Retail。
如需有关 BigQuery 表的更多帮助,请参阅表简介。如需有关 BigQuery 查询的帮助,请参阅查询 BigQuery 数据概览。
将数据补全到 BigQuery
使用 Retail 自动补全架构将自动补全数据上传到 BigQuery。
BigQuery 可以使用架构来验证 JSON 格式的数据是否具有正确的字段名称和类型(例如 STRING
、INTEGER
和 RECORD
),但无法执行如下验证:确定:
- 如果字符串字段映射到可识别的枚举值。
- 使用正确格式的字符串字段。
- 如果整数或浮点字段的值在有效范围内。
- 若缺少字段为必填字段。
为了确保数据和最终用户搜索体验的质量,请务必参阅架构和参考文档,详细了解值和格式。
将自动补全数据导入 Retail
curl
如果您的 BigQuery 数据集位于其他项目中,请配置所需的权限,以便 Retail 可以访问 BigQuery 数据集。了解详情。
为导入作业的输入参数创建一个数据文件。输入参数值取决于您是从 Cloud Storage 还是 BigQuery 导入。
使用 BigQuerySource 对象指向 BigQuery 数据集。
- dataset-id:BigQuery 数据集的 ID。
- table-id:存放数据的 BigQuery 表的 ID。
- data-schema:对于
dataSchema
属性,请使用值suggestions
(默认值)、allowlist
、denylist
。您将使用 Retail 自动架构。
{ "inputConfig":{ "bigQuerySource": { "datasetId":"dataset-id", "tableId":"table-id", "dataSchema":"data-schema" } } }
通过向
CompletionData:import
REST 方法发出POST
请求,提供数据文件的名称(此处显示为),将自动补全信息导入 Retailinput.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 服务属于不同的项目,要设置访问权限,请完成以下步骤。
在 Cloud Console 中打开 IAM 页面。
选择您的 Retail 项目。
找到名为 Retail Service Account 的服务帐号。
如果您之前未曾使用过 Retail 启动导入操作,则此服务帐号可能未列出。如果您没有看到此服务帐号,请返回导入任务并启动导入。当由于权限错误而失败时,请返回此处完成此任务。
复制服务帐号的标识符,类似于电子邮件地址(例如
cloud-retail-customer-data-access@system.gserviceaccount.com
)。在 IAM 和管理上,点击添加。
输入 Retail 服务帐号的标识符,然后选择 BigQuery > BigQuery Data Viewer 角色。
如果您不想向整个项目提供 Data Viewer 角色,则可以将此角色直接添加到数据集。了解详情。
点击保存。
自动补全数据格式
JSON 文件应类似于以下示例。换行符便于阅读;您应该在一行中提供完整的建议。每条建议应各为一行。
建议最少的必填字段:
{
"suggestion": "ABC",
"globalScore": "0.5"
}
或:
{
"suggestion": "ABC",
"frequency": "100"
}
自动填充数据导入时长
从 BigQuery 进行一次导入通常需要大约 10 小时。长时间运行的操作推送数据集推进行生产服务。数据集准备就绪后,操作对象中的 done
字段将被标记为 true。在操作为 done
之前,无法保证从导入数据集中获取最新建议。
使自动补全数据集保持最新
如果您打算使用自己的上传数据集,则最佳做法是定期更新上传的数据集。
批量更新
您可以使用导入方法来批量更新自动补全功能。具体操作方式与初始导入相同;按照导入自动补全数据中的步骤操作。这将替换整个导入的数据集。
监控导入运行状况
使用最新的数据集,对于在使用数据集时获得高质量的建议结果非常重要。您应监控导入错误率,并在需要时采取措施。
Retail 自动补全架构
从 BigQuery 导入自动补全数据集时,请使用下面的 Retail 架构创建具有正确格式的 BigQuery 表,并加载包含自动补全数据的表。
建议的架构
此数据集用于建议带有 typeahead 的短语。
拒绝名单架构
此数据集用作拒绝名单,以阻止提供建议的短语。
许可名单的架构
此数据集用于跳过此许可名单中的所有短语,例如进行拼写更正。