通过 CRM 个性化功能增强 Vertex AI Search for Commerce

这份 Vertex AI Search for commerce API 实现指南概述了如何使用客户关系管理 (CRM) 数据在 Vertex AI Search for commerce 中打造个性化的搜索体验。通过集成 CRM 中的用户属性，您可以提供更相关的搜索结果，最终提高客户互动度和转化率。本文档详细介绍了集成这些用户属性的过程，包括数据注意事项和技术规范。

选择用于个性化功能的数据

个性化效果取决于您提供的 CRM 数据的质量、覆盖面和相关性。考虑一下哪些客户信息会真正影响知识渊博的销售人员可能提供的搜索结果。

完成小规模测试后，您将获得更可靠的建议，了解哪些数据具有影响力（哪些数据没有影响力）。

建议的用于评估影响的数据类别

这些数据类别构成了最能说明您商业网站用户行为的信息。

地理位置信息：客户位置，例如州/省/自治区或国家/地区。邮政编码信息过于精细。如需了解详情，请参阅有关粒度过细的部分。
受众特征数据：核心客户特征，例如年龄和性别。
- 了解客户的年龄段（例如 18-24 岁与 55-64 岁）可能会影响服装或电子产品等商品的展示策略。这是极具影响力的数据。
买家角色：例如，注重预算或节俭的买家，而不是挥金如土的买家。

不太可能产生影响的数据类别

这些数据类别对您的商业数据捕获影响不大。

从购买历史记录中派生的属性：
- 我们的系统已将过往购买行为纳入个性化考量。
- 发送 user bought a green dress yesterday 等属性是多余的，因为系统会原生捕获并利用这些信息。
- 专注于从 CRM 中获取新颖的数据洞见。
具体的营销响应数据，例如 Clicked email #7：
- 虽然此数据与营销广告系列分析相关，但它不会告知 AI 要显示哪些搜索结果。

数据完整性

除了相关性之外，用户群中数据的完整性也会显著影响数据在个性化方面的实用性。当某个属性适用于大部分用户时，其价值最高，因为这样一来，系统就能识别更广泛的模式，并更广泛地应用个性化设置。

非常有用：
- 您的大部分用户都具有的属性，例如 shipping_state:MA（如果 70% 的用户群都具有此属性）。
- 这有助于实现强大的模式识别功能，并广泛应用个性化功能。
不太有用：
- 仅适用于一小部分用户的属性，例如 hair_color:blonde（如果仅适用于 0.1% 的用户群）。

虽然这类稀疏数据很有趣，但由于示例不足，系统很难从中得出有意义的个性化信号。相反，您应优先考虑可覆盖更广泛客户群体的属性。

数据粒度指南

适当的数据粒度对于实现有效的个性化至关重要。数据过于宽泛或过于具体可能会削弱系统识别有意义模式的能力。选择可将客户群细分为可采取行动的群组的属性。

适当的粒度

适当粒度的示例包括以下字段：

性别
州
城市
年龄段（例如 30-39 周岁）

此粒度级别可实现个性化区分，而不会创建过多的类别，从而导致难以管理。

粒度不够精细

如果您的客户群绝大多数位于美国，则 country:US 是一个粒度不足的示例。这是因为，在整个客户群中差异较小的属性对个性化几乎没有价值。

粒度过细

粒度过细的示例包括：

确切的邮政编码 (zipcode:12345)：由于邮政编码可能有数万个，因此大多数邮政编码关联的客户都很少。这种细分会稀释信号。如果使用邮政编码，请将其截断为前两位数字，以实现更合适的精细度。邮政编码的前两位数字大致对应于州大小的区域。
确切年龄 (age:37)：这会创建过多的年龄段。如需减少此数量，请将年龄等数值数据分组到大约 10 个预定义的箱或分桶中（例如 age:30-39）。

其他数据指南

本部分将介绍分类数据和其他数据格式。

分类数据格式

此系统针对类别数据进行了优化：不同的命名值，例如：

state:MA
gender:male

数值数据

因此，在传输数据之前，应将年龄、收入或频次等任何数值属性分组到有意义的区间中。

以下分别是错误和正确的示例：

age:37
age:30-39

其他数据限制

属性数量上限：每个查询最多支持 100 个键值对。未来版本中可能会添加对更多配对的支持。
重复的键：不允许在单个查询中使用重复的键。不过，每个键支持多个值。
禁止发送的 PII：在任何情况下，您都不应发送特定的个人身份信息 (PII)，例如客户电子邮件地址、社会保障号、全名或财务数据（例如信用卡号），无论以何种形式发送。

API 集成和数据传输

客户数据应在搜索请求的 query 字段中传输，而不是在事件中传输。

协议缓冲区结构（面向开发者）

用户属性在 SearchRequest 消息中定义为从字符串到 StringList 消息的映射。

查看 protobuf 示例

// A list of string values.
message StringList {
// String values.
repeated string values;
}

// Request message for [SearchService.Search][] method.
message SearchRequest {
...
// The user attributes that could be used for personalization of search.
maptring, StringList> user_attributes;
}

JSON 请求示例

此示例说明了如何在 JSON 搜索请求中构建 user_attributes。

查看 JSON 示例

{
...

user_attributes: [
       { key: "pets" # note keys can be hashed or unhashed
         value {
           values: "dog" # Note: these values MUST be hashed
           values: "cat"
         }
       },
       { key: "state"
         value {
           values: "CA"
         }
       }
      ]
}

API 响应

使用此功能时，SearchResponse API 不会发生任何变化。系统会根据提供的用户属性在内部进行个性化处理。

数据哈希处理要求

为确保数据隐私和安全，属性值必须经过哈希处理。密钥可以经过哈希处理，也可以未经过哈希处理。

哈希处理键

属性键（例如 pet_owner 和 state）可以采用原始字符串形式发送，也可以进行哈希处理。这两种方法都可以接受。

例如：

可接受 - pet_owner
可接受 - hash(pet_owner)

哈希值

属性值（例如 dog 和 CA）必须进行哈希处理。不允许发送纯文本值。

例如：

可接受 - hash(dog)
不接受 - "Dog"

组合键值哈希处理

如果键和值都要进行哈希处理，则必须分别进行哈希处理。请勿对组合的键值字符串进行哈希处理。

例如：

可接受 - pet_owner:hash("dog")
可接受 - hash(pet_owner):hash("dog")
不接受 - hash("Pet_owner:dog")

数据传输的最佳实践

本部分概述了数据传输方面的几项最佳实践，包括如何处理重复值、数据一致性、属性键命名灵活性以及处理各种用户个人资料。

如何处理重复值

如果用户针对单个属性有多个值（例如同时养狗和养猫），请在 StringList 内的单个 key 下提供所有值。

以下代码示例分别展示了错误和正确的用法示例：

查看示例

// This is incorrect because it sends the same key multiple times for different
// values, causing only one of the two values for pets to be used, choosing one
// value or the other in an inconsistent manner.
{
  key: "pets",
  value {
    values: "dog"
  }
},
{
  key: "pets",
  value {
    values: "cat"
  }
}

查看示例

{
  key: "pets",
  value {
    values: "dog",
    values: "cat"
  }
}

数据一致性

确保所有键和值的拼写、空格和大小写都严格保持一致。即使是细微的差异，系统也会将其解读为不同的类别。

例如，State:MA、state:MA、state:ma、STATE:MA 和 residence_state:MA 都将被视为单独且不相关的属性。

属性键命名灵活性

虽然一致，但属性键（例如 pet_owner、pets、codeabc）的具体命名惯例本身并不会影响系统使用数据的能力。关键在于您传输的数据是否一致。

如何处理不同的用户个人资料

不同用户可以有不同的属性集。

示例：用户 A 可能有 age:30-39 和 pet:dog，而用户 B 有 gender:male，但没有宠物或年龄数据。系统可以妥善处理部分个人资料。

动态数据更新

用户属性可能会随时间的推移而发生变化。您可以随时使用新信息更新用户的个人资料。

示例：如果用户最初的标识符为 age:30-39 和 pet:dog，那么在获取其位置信息后，可以添加 state:MA。

跨平台一致性

力求在所有接触点（例如移动应用或网站）上，针对特定用户实现一致的属性传输。这可确保提供统一的个性化体验。

最佳：用户 A 在移动应用和网站上始终为 age:30-39。
次优：用户 A 在移动应用中为 age:30-39，但在网站中仅为 pet:dog。

如何处理缺失的数据

如果无法获取用户的特定信息，请勿发送占位值或空值。只需从请求中省略该键值对即可。

示例：避免使用 pet:unknown 或 pet:

SDK 和库访问权限

您可以在以下版本及更高版本中访问这些库：