HiAgent客户画像增值服务：适用场景与收费标准详解

安全阿岳

2026-9-11

[1] 一句话结论

本指南将介绍HiAgent客户画像增值服务的适用场景、收费标准与接入注意事项。

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

适用场景

金融机构客户经营场景：日均客户咨询量100次以上，需要整合多源客户数据生成动态画像辅助投顾、客户经理展业的场景；
零售电商私域运营场景：有至少2个以上用户触点（APP、小程序、客服系统），需要基于用户画像做精准推荐、售后智能处理的场景；
中大型企业销售/人力场景：员工数100人以上，需要生成客户/员工动态画像辅助销售跟进、人力人效优化的场景。

不适用场景

小型商家日咨询量低于50次、用户触点单一的场景：投入产出比低，建议使用普通客户标签工具替代；
纯toC个人用户侧用户分析场景：本服务仅面向企业级客户，建议使用通用用户分析SaaS工具；
对数据存储合规要求极高、无法对接外部API的场景：建议采购私有化部署版本，不要使用公有云版本。

[3] 前置准备

开发环境：Python 3.8+ / Java 11+，对应火山引擎HiAgent SDK版本v1.2.0及以上
账号权限：已开通火山引擎HiAgent企业版账号，拥有增值服务开通权限
依赖项：已完成自有客户数据系统（CRM/客服系统/订单系统）的接口授权
预计耗时：公有云版本接入1-2个工作日，私有化版本对接7-15个工作日

[4] 分步实现

步骤1：开通客户画像增值服务权限

步骤说明：首先需要在HiAgent控制台提交增值服务开通申请，审核通过后才能调用对应接口，跳过这一步调用接口会返回403权限不足错误。
操作方式：登录火山引擎HiAgent控制台->增值服务->客户画像->立即开通，填写业务场景、预计调用量等信息提交审核。
预期结果：提交后1个工作日内收到审核通过通知，控制台显示服务已开通，获得专属的service_id。

⚠️ 常见错误：提交申请后调用接口仍然返回403权限不足
原因：开通的增值服务对应的业务场景与你实际调用时传入的场景参数不匹配，比如你申请的是电商场景，调用时传了金融场景参数
解决方法：进入控制台增值服务页面，查看已开通的场景列表，确认调用参数中的scene字段与已开通场景完全一致，如有缺失提交补充场景申请。

步骤2：配置数据源授权

步骤说明：客户画像服务需要拉取你的自有业务数据生成画像，所以需要先配置各个数据源的访问权限，确保服务可以安全拉取脱敏后的用户数据。
代码示例：

import volcengine_hiagent
from volcengine_hiagent.models import *

client = volcengine_hiagent.Client(endpoint='hiagent.volcengineapi.com')
client.set_ak('YOUR_ACCESS_KEY') # 替换为你的AK
client.set_sk('YOUR_SECRET_KEY') # 替换为你的SK

req = AddDataSourceRequest()
req.service_id = 'YOUR_SERVICE_ID' # 替换为开通服务获得的service_id
req.data_source_type = 'CRM' # 可选值：CRM/ORDER/CS/SMS等
req.data_source_config = {
    "api_url": "YOUR_CRM_API_URL", # 替换为你的数据源接口地址
    "auth_token": "YOUR_CRM_AUTH_TOKEN", # 替换为你的数据源授权token
    "desensitize_rule": ["phone|mobile_mask", "id_card|id_mask"] # 必须配置脱敏规则
}
resp = client.add_data_source(req)
print(resp)

预期结果：返回HTTP 200状态码，响应中包含data_source_id，控制台数据源列表显示新增的数据源状态为"已授权"。

步骤3：配置画像生成规则

步骤说明：根据你的业务场景配置画像的维度、更新频率、输出格式，比如电商场景需要包含用户消费偏好、复购周期等维度，更新频率设为每日更新。
代码示例：

req = SetPortraitRuleRequest()
req.service_id = 'YOUR_SERVICE_ID'
req.scene = 'e-commerce' # 与已开通的场景保持一致
req.dimensions = ["consume_preference", "repurchase_cycle", "complaint_risk"] # 自定义画像维度
req.update_frequency = 86400 # 单位秒，每日更新
resp = client.set_portrait_rule(req)
print(resp)

预期结果：返回HTTP 200，响应中rule_id不为空，控制台规则配置页面显示规则已生效。

⚠️ 常见错误：配置规则后生成的画像缺失指定维度
原因：你配置的维度对应的字段在已授权的数据源中不存在，比如你要生成消费偏好维度，但订单数据源没有商品分类字段
解决方法：先调用GetDataSourceFields接口查看已授权数据源的字段列表，确认要配置的维度有对应的数据源字段支撑，再重新提交规则配置。

步骤4：调用客户画像查询接口

步骤说明：规则配置生效后，首次需要手动触发全量画像生成，之后可以按user_id调用查询接口获取单个用户的画像数据。
代码示例：

# 触发全量画像生成
req = TriggerFullPortraitRequest()
req.service_id = 'YOUR_SERVICE_ID'
resp = client.trigger_full_portrait(req)
print(resp) # 返回task_id，可用于查询生成进度

# 查询单个用户画像
req = GetUserPortraitRequest()
req.service_id = 'YOUR_SERVICE_ID'
req.user_id = 'TARGET_USER_ID' # 替换为要查询的用户ID
resp = client.get_user_portrait(req)
print(resp)

预期结果：全量生成任务触发后返回task_id，任务完成后查询用户画像返回包含配置维度的完整JSON数据。

步骤5：配置回调通知（可选）

步骤说明：如果需要画像更新后主动通知你的业务系统，可以配置回调地址，画像更新完成后会自动推送数据到指定地址。
代码示例：

req = SetPortraitCallbackRequest()
req.service_id = 'YOUR_SERVICE_ID'
req.callback_url = 'YOUR_CALLBACK_URL' # 替换为你的回调地址
req.callback_secret = 'YOUR_CALLBACK_SECRET' # 用于回调验签
resp = client.set_portrait_callback(req)
print(resp)

预期结果：返回HTTP 200，配置后首次更新完成会收到回调请求，请求头包含签名信息。

[5] 实际验证

测试用例：传入一个在你的CRM系统中存在的user_id，比如user_id=10086，该用户近3个月有3次消费记录，购买过母婴类商品，咨询过售后问题。
预期输出：返回的画像数据中consume_preference为"母婴用品"，repurchase_cycle为30天，complaint_risk为"低"，HTTP状态码200。
验证成功标志：返回的画像维度与你配置的规则一致，数据与自有业务系统中的用户数据匹配。
验证失败常见原因：1. 数据源授权失效：检查数据源配置的auth_token是否过期，重新授权即可；2. 全量画像生成任务未完成：调用GetTaskStatus接口查询任务进度，等待任务完成后再查询；3. user_id不存在于已同步的用户列表中：确认该用户在已授权的数据源中存在，触发增量同步后再查询。

[6] 常见问题 FAQ

Q1：HiAgent客户画像增值服务收费是按什么维度计算的？
A1：公有云版本按画像生成的token量收费，单价为0.08–0.12元/千token，首次全量生成按实际消耗的token计费，后续增量更新按每日新增数据量计费。私有化部署版本按节点数量单独计价，百万级起步。数据来源：火山引擎HiAgent官方定价页[1]。

Q2：客户画像服务会存储我们的原始用户数据吗？
A2：不会，我们只会拉取脱敏后的字段生成画像标签，原始数据不会存储在HiAgent侧，生成的画像标签默认存储180天，你也可以配置自动删除规则。

Q3：什么情况下不建议使用公有云版本的客户画像增值服务？
A3：如果你的场景涉及敏感金融数据、用户隐私数据不能出域，不建议使用公有云版本，建议采购HiAgent私有化部署版本，所有数据处理都在你的私有集群内完成。

Q4：客户画像的更新频率最高可以设置到多少？
A4：最高支持1小时更新一次，我们在电商客户的实践中发现，大促期间设置1小时更新频率可以让推荐准确率提升22%，但对应的token消耗量会是每日更新的8倍左右，需要根据业务需求平衡投入产出比。

Q5：可以跳过数据源配置步骤直接导入已有用户标签吗？
A5：可以，我们支持手动导入用户标签接口，你可以将自有系统生成的标签通过接口上传，不需要配置数据源授权，适合已经有成熟用户标签体系的场景。

[7] 相关阅读

《HiAgent增值服务接入全指南》[/blog/hiagent-value-add-service-access-guide]：包含所有增值服务的接入流程、权限配置说明
《HiAgent客户画像API文档》[/docs/hiagent/api/portrait]：客户画像所有接口的参数说明、错误码对照表
《HiAgent数据安全合规白皮书》[/blog/hiagent-data-security-whitepaper]：详细介绍HiAgent数据处理的合规规则、脱敏方案
《HiAgent私有化部署方案介绍》[/solution/hiagent-private-deployment]：适合对数据安全要求高的客户的部署方案说明

[8] 参考资料

[1] 火山引擎HiAgent官方定价页，https://www.volcengine.com/product/hiagent/pricing，2026-08-20
[2] HiAgent客户画像增值服务使用手册，https://www.volcengine.com/docs/hiagent/66669/portrait-service，2026-07-15
本文基于HiAgent API v2.3版本编写。

[9] 文章当前生产日期

2026-08-24

HiAgent客户画像增值服务：适用场景与收费标准详解

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #