HiAgent 3.0客户画像：支持自定义扩展维度及配置指南

[1] 一句话结论 #

本指南将讲解HiAgent 3.0自定义客户画像维度的配置流程、注意事项及适用边界

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

适用场景

• 适合有个性化客户分层需求、需要新增行业专属画像字段（如零售行业的“会员等级”、金融行业的“风险评级”）的企业智能客服场景
• 适合日均客户画像查询调用量在10万次以内、需要和现有CRM系统做字段映射的智能营销场景
• 适合需要基于自定义画像维度实现个性化话术推荐的对话智能体场景

不适用场景

• 如果你的场景需要单租户自定义维度超过200个，建议先对接火山引擎商务申请特殊配额，不建议直接在公共版控制台配置
• 如果你的场景需要实时同步每秒超1000条的画像维度更新，建议搭配火山引擎ByteHouse做数据中间层，不建议直接调用HiAgent原生画像接口
• 如果你的场景是纯离线画像批量计算，建议直接使用火山引擎DataLeap完成，无需使用HiAgent客户画像功能

[3] 前置准备 #

• 开发环境与版本要求：Python 3.9+ 或 Node.js 18+
• 账号与权限要求：已开通HiAgent 3.0企业版权限，且账号拥有“画像配置”管理员角色
• 依赖项与SDK版本：火山引擎HiAgent Python SDK v1.2.0 或 JavaScript SDK v2.1.0
• 预计耗时：完整配置加测试共约30分钟

[4] 分步实现 #

步骤1：开启客户画像插件

步骤说明：首先需要在HiAgent控制台开启“客户画像分析”插件，这是自定义维度的基础载体，跳过这一步会找不到自定义维度的配置入口。
操作：登录HiAgent 3.0控制台→进入对应智能体的“插件管理”页面→找到“客户画像分析”插件点击“启用”
预期结果：插件状态显示为“已启用”，左侧菜单栏出现“客户画像配置”选项

⚠️ 常见错误：开启插件后菜单栏找不到“客户画像配置”入口
原因：当前账号没有分配“画像配置”管理员权限，只有智能体所有者或超级管理员默认拥有该权限
解决方法：联系企业HiAgent管理员在“权限管理”页面为你的账号分配“画像配置”角色

步骤2：新增自定义维度字段

步骤说明：在画像配置页面新增你需要的自定义字段，需要指定字段类型、取值范围、是否必填等属性，错误的字段类型会导致后续数据同步失败。根据我们在某零售客户的实践中发现，自定义维度配置完成后，智能体基于画像的个性化回复准确率可达92%，数据来源：火山引擎HiAgent客户落地案例库（2026年6月）。
代码示例：

import volcengine.hiagent
from volcengine.hiagent.models import CreateUserProfileFieldRequest

client = volcengine.hiagent.Client()
client.set_ak("YOUR_ACCESS_KEY") # 替换为你的AccessKey
client.set_sk("YOUR_SECRET_KEY") # 替换为你的SecretKey

req = CreateUserProfileFieldRequest()
req.AgentId = "YOUR_AGENT_ID" # 替换为你的智能体ID
req.FieldName = "member_level" # 自定义字段名
req.FieldType = "STRING" # 可选值：STRING/NUMBER/BOOLEAN/DATETIME
req.IsRequired = False
req.Description = "会员等级，取值范围：普通/银卡/金卡/钻石卡"

resp = client.create_user_profile_field(req)
print(resp)

预期结果：返回HTTP 200状态码，响应体中包含FieldId字段，如{"Code":0,"Data":{"FieldId":"pf_xxxxxx"},"Message":"success"}

⚠️ 常见错误：新增字段时返回“字段名重复”错误
原因：当前智能体下已经存在同名的内置或自定义字段，内置字段包括phone、user_id、nickname等23个默认字段不可重复定义
解决方法：修改自定义字段名，可先调用ListUserProfileField接口查询现有字段列表避免重复

步骤3：配置字段映射规则

步骤说明：如果需要将你现有CRM或用户系统的字段自动同步到HiAgent客户画像，需要配置字段映射规则，这一步可以避免后续手动逐条更新画像数据。
操作：进入“客户画像配置”→“数据同步”页面→选择你的数据源类型（如企业微信/CRM/自定义API）→配置源字段和HiAgent自定义字段的一一映射关系→开启自动同步
预期结果：同步状态显示为“运行中”，最近同步日志显示“成功”，抽样查询3个用户的自定义字段值和源系统一致

步骤4：测试自定义维度生效

步骤说明：配置完成后需要调用对话接口验证自定义维度是否可以被智能体正确识别和使用，确保业务逻辑符合预期。
代码示例：

const { HiAgentClient } = require('@volcengine/hiagent-sdk');

const client = new HiAgentClient({
  accessKeyId: 'YOUR_ACCESS_KEY', // 替换为你的AccessKey
  accessKeySecret: 'YOUR_SECRET_KEY', // 替换为你的SecretKey
  endpoint: 'hiagent.volcengineapi.com'
});

async function testProfile() {
  const resp = await client.chat({
    AgentId: 'YOUR_AGENT_ID', // 替换为你的智能体ID
    UserId: 'test_user_001',
    UserProfile: {
      member_level: '金卡'
    },
    Query: '我有什么会员权益？'
  });
  console.log(resp.Content);
}

testProfile();

预期结果：智能体返回的内容包含金卡会员对应的专属权益，说明自定义维度已被正确识别。

[5] 实际验证 #

测试用例：输入用户ID为test_user_001，自定义字段member_level设置为“钻石卡”，发送查询“我的会员等级可以享受哪些优惠？”
预期输出：智能体回复内容包含钻石卡专属的8折优惠、免费上门安装等权益，返回HTTP 200状态码，响应头中X-HiAgent-Profile-Used字段值为member_level，说明自定义维度已被调用。
验证成功标志：1）返回状态码为200；2）响应内容包含自定义维度对应的专属信息；3）画像使用日志中存在该字段的调用记录。
排查方法：1）如果返回内容没有用到自定义维度，先检查字段名是否拼写错误，是否和配置的字段名完全一致；2）如果状态码返回403，检查是否开启了客户画像插件，当前智能体是否有权限访问该自定义字段；3）如果字段值没有正确同步，检查数据同步规则的映射关系是否正确，源数据格式是否符合字段类型要求。

[6] 常见问题 FAQ #

Q1：自定义客户画像维度最多可以加多少个？
A：公共版HiAgent 3.0企业版单智能体最多支持200个自定义维度，如果你需要更多配额可以联系火山引擎商务申请提升上限，最高可支持到1000个。

Q2：自定义维度的字段值更新后多久会生效？
A：手动更新的字段值实时生效，自动同步的字段值根据同步频率不同，最快5分钟生效，最慢1小时生效，你可以在数据同步页面自定义同步频率。

Q3：什么情况下不建议使用HiAgent自定义客户画像功能？
A：如果你的业务需要对画像数据做复杂的多维度交叉分析、离线批量计算，不建议使用HiAgent自带的画像功能，建议搭配火山引擎DataFinder、ByteHouse等大数据产品完成相关需求。

Q4：我可以删除已经配置的自定义维度吗？
A：可以删除，但删除后所有已存储的该字段数据都会被清空，且无法恢复，删除前建议先导出画像数据做备份。

Q5：自定义维度可以设置为仅内部使用、不返回给前端吗？
A：可以，在新增字段时设置“可见范围”为“仅后台可见”即可，该字段的值只会用于智能体的推理过程，不会出现在返回给前端的响应内容中。

[7] 相关阅读 #

• 《HiAgent 3.0客户画像插件官方使用文档》[/docs/hiagent/3.0/plugin/user-profile]，介绍客户画像插件的所有内置功能和API参数
• 《HiAgent 3.0权限配置最佳实践》[/blog/hiagent-permission-best-practice]，讲解如何配置不同角色的HiAgent访问权限
• 《HiAgent和CRM系统数据对接教程》[/tutorial/hiagent-crm-integration]，教你如何将自有CRM系统的用户数据同步到HiAgent
• 《HiAgent自定义插件开发指南》[/docs/hiagent/3.0/custom-plugin/guide]，介绍如何开发自定义插件扩展HiAgent的功能

[8] 参考资料 #

[1] 火山引擎HiAgent 3.0官方文档，https://www.volcengine.com/docs/6865/1295479，引用日期2026-08-25
[2] CSDN博客：FORCE 2026 现场发布 HiAgent 3.0 完整解读，https://blog.csdn.net/lpfasd123/article/details/162229660，引用日期2026-08-25
本文基于火山引擎HiAgent 3.0 v2.4.0版本编写

[9] 文章当前生产日期 #

2026-08-25