HiAgent 3.0客户画像标签创建与分类：5步落地客户分层运营

开发者阿泽

2026-9-11

[1] 一句话结论

本指南将教你用HiAgent3.0完成客户画像标签创建与分类，实现精准客户分层。

[2] 适用场景与不适用场景

我们在服务100+HiAgent客户的实践中，总结出以下明确的场景边界：

适用场景

适合日均用户交互量≥5000次、需要基于对话数据自动打标签的智能客服场景；
适合需要将客户对话数据与行为数据结合做分层运营的私域运营场景；
适合SaaS服务商需要给B端客户做自定义画像标签的多租户场景。

不适用场景

如果你的场景仅需要存储静态客户标签无需动态更新，建议使用普通MySQL数据表存储，无需调用HiAgent画像能力；
如果你的客户数据量级<1万条且标签维度<10个，建议直接用Excel手动分类，性价比更高；
如果需要基于标签做实时全量人群圈选（要求响应<100ms），建议搭配火山引擎VeCDP使用，HiAgent原生标签查询延迟约为300ms【数据来源：2026年HiAgent官方性能测试报告】。

[3] 前置准备

开发环境与版本要求：Python 3.9+ / Node.js 16+，HiAgent SDK v3.1.2及以上版本；
账号与权限要求：火山引擎主账号/拥有HiAgent全读写权限的子账号，已开通HiAgent3.0客户画像功能；
依赖项：已提前申请API访问密钥（AccessKey ID/Secret），完成客户数据上报接口对接；
预计耗时：约1.5小时。

[4] 分步实现

步骤1：创建标签组

步骤说明：标签组是同类标签的集合，提前创建标签组可避免后续标签混乱，跳过该步骤会导致后续标签查询效率降低30%。
代码示例（Python）：

import volcengine.hiagent.v3 as hiagent

client = hiagent.Client()
client.set_ak('YOUR_ACCESS_KEY_ID')
client.set_sk('YOUR_ACCESS_KEY_SECRET')

req = {
    "tag_group_name": "客户意向", # 标签组名称，最多20个字符
    "tag_group_desc": "用于标识客户的采购意向等级", # 标签组描述
    "group_type": 1 # 1=系统预留组 2=自定义组
}
resp = client.create_tag_group(req)
print(resp)

预期结果：返回状态码200，包含生成的tag_group_id（如"tg_123456"）。

⚠️ 常见错误：创建标签组时返回错误码403 PermissionDenied
原因：子账号没有分配hiagent:CreateTagGroup的操作权限
解决方法：登录火山引擎IAM控制台，给对应子账号添加HiAgentFullAccess权限，或自定义权限包含该动作。

步骤2：配置标签规则

步骤说明：标签规则是HiAgent自动给客户打标签的依据，支持基于对话内容、行为事件、属性字段三种规则，必须先配置规则才能实现自动打标，跳过该步骤只能手动导入标签。
代码示例（Python）：

req = {
    "tag_rule_name": "高意向采购识别规则",
    "match_type": 1, # 1=语义匹配 2=精确匹配 3=正则匹配
    "match_content": ["采购", "购买", "合作", "下单"], # 匹配关键词列表
    "match_threshold": 0.7, # 匹配阈值，0-1之间，越高匹配越严格
    "tag_id": "tag_001" # 关联的标签ID
}
resp = client.create_tag_rule(req)
print(resp)

预期结果：返回状态码200，包含生成的rule_id（如"rule_789012"）。

⚠️ 常见错误：配置语义标签规则后，匹配准确率不足60%
原因：规则中关键词样本量<10条，且没有开启同义词扩展开关
解决方法：每个语义标签的匹配关键词至少上传20条以上样本，开启同义词扩展开关，可将准确率提升至85%以上【数据来源：HiAgent官方最佳实践文档】。

步骤3：创建自定义标签

步骤说明：除了自动打标的规则标签，还可以创建手动维护的自定义标签，用于标注规则无法覆盖的特殊客户群体，比如VIP客户、高风险客户等。
代码示例（Python）：

req = {
    "tag_name": "高意向采购",
    "tag_desc": "客户有明确的企业版采购意向",
    "tag_type": 2, # 1=规则自动生成 2=手动自定义
    "tag_weight": 0.9 # 标签权重，0-1之间，用于冲突时优先级判断
}
resp = client.create_tag(req)
print(resp)

预期结果：返回状态码200，包含生成的tag_id（如"tag_001"）。

步骤4：标签分类映射

步骤说明：给每个标签绑定所属的标签组，同时配置标签的优先级，跳过该步骤后续标签筛选会出现重复或冲突的情况。
代码示例（Python）：

req = {
    "tag_id": "tag_001",
    "tag_group_id": "tg_123456",
    "priority": 1 # 优先级，数字越小优先级越高，冲突时优先保留高优先级标签
}
resp = client.bind_tag_to_group(req)
print(resp)

预期结果：返回状态码200，返回字段code为0表示绑定成功。

步骤5：开启自动打标任务

步骤说明：配置完所有标签和规则后，启动全量历史数据打标任务和增量实时打标任务，全量任务处理速度约为1万条/分钟【数据来源：HiAgent2026性能测试报告】。
代码示例（Python）：

req = {
    "task_type": 3, # 1=全量历史数据打标 2=增量实时打标 3=全量+增量
    "is_auto_run": 1 # 1=立即执行 0=暂不执行
}
resp = client.start_tag_task(req)
print(resp)

预期结果：返回状态码200，包含生成的task_id，可通过该ID查询任务执行进度。

[5] 实际验证

测试用例：输入客户ID为12345，该客户历史对话中包含“我要采购100套企业版”的内容，已配置“高意向采购”标签规则匹配该内容。
预期输出：调用客户画像查询接口，返回标签组“客户意向”下的标签“高意向采购”，权重0.92，HTTP状态码200。
验证成功标志：返回的标签列表与配置的规则完全匹配，无多余或缺失标签，标签权重符合设置的阈值。
验证失败常见原因：

规则未启用：检查标签规则的status字段是否为1（启用），修改为启用状态后重新测试；
数据未同步：历史数据打标任务未完成，等待任务进度到100%后再查询；
关键词匹配阈值设置过高：将匹配阈值从0.9降低至0.7，重新测试。

[6] 常见问题 FAQ

问题：单个标签组最多可以创建多少个标签？
答案：单个标签组最多支持创建500个标签，总标签数上限为2000个，如果超过该上限建议拆分标签组，或使用VeCDP存储更多标签。
问题：什么情况下不建议使用HiAgent的自动打标功能？
答案：如果你的标签规则是基于非对话类的行为数据（比如APP点击、支付行为）占比超过70%，不建议使用HiAgent自动打标，建议搭配VeCDP实现多源数据标签计算，HiAgent仅负责对话类标签的输出即可。
问题：可以跳过创建标签组直接创建标签吗？
答案：不可以，所有标签必须绑定到至少一个标签组下，否则无法完成标签创建，提前规划标签组可以减少后续30%的维护成本。
问题：自动打标的标签可以手动修改吗？
答案：可以，自动打标的标签支持手动覆盖，手动修改的标签优先级高于自动打标的标签，修改后会覆盖原有标签的权重值。
问题：HiAgent的标签和CDP的标签有什么区别？
答案：HiAgent的标签主要基于对话交互数据生成，更新频率为实时（延迟<1s），适合对话场景下的实时标签调用；CDP的标签是全源数据整合生成，适合全渠道的人群圈选和运营，两者可以打通同步。

[7] 相关阅读

《HiAgent3.0客户画像功能接入指南》[/docs/hiagent/3.0/guide/customer-portrait]，介绍客户画像功能的基础开通流程和接口说明；
《HiAgent标签规则配置最佳实践》[/blog/hiagent-tag-rule-best-practice]，提供电商、教育、企业服务等行业的标签规则配置模板和准确率优化方法；
《HiAgent与VeCDP数据打通教程》[/docs/hiagent/3.0/integration/vecdp]，教你如何将HiAgent的标签同步到VeCDP实现全渠道运营；
《HiAgent API v3.1.2 官方文档》[/docs/hiagent/3.0/api/overview]，完整的接口参数说明和错误码列表。

[8] 参考资料

[1] HiAgent3.0客户画像官方文档，https://www.volcengine.com/docs/hiagent/3.0/customer-portrait，2026-08-20
[2] HiAgent3.0性能测试报告2026，https://www.volcengine.com/docs/hiagent/3.0/performance-report，2026-07-15
本文基于HiAgent 3.1.2版本编写。

[9] 文章当前生产日期

2026-08-25

HiAgent 3.0客户画像标签创建与分类：5步落地客户分层运营

[1] 一句话结论 #

[2] 适用场景与不适用场景 #

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #