HiAgent 3.0酒店预订：3步配置常用入住偏好

[1] 一句话结论 #

本指南将教你快速完成HiAgent 3.0酒店预订模块的常用偏好配置。

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

适用场景

1. 企业内部差旅智能助手，员工每月差旅预订频次≥5次，需要减少重复填写入住信息的场景；
2. 面向C端的旅游类智能客服，平台月活≥10万，酒店订单占比≥30%的场景；
3. 连锁酒店自有智能预订咨询入口，会员数≥5万，复购率≥20%的场景。

不适用场景

1. 单次偶发的个人酒店预订需求，建议直接使用OTA平台手动填写信息即可；
2. 没有用户实名认证体系的匿名咨询场景，建议优先配置通用预订规则替代个性化偏好；
3. 日均调用量低于100次的小型预订系统，建议直接走后端参数透传无需配置偏好模块，可降低开发成本。

[3] 前置准备 #

• 开发环境：Node.js 16+ / Python 3.8+
• 账号权限：火山引擎HiAgent 3.0企业版账号，拥有模块配置编辑权限
• 依赖项：火山引擎HiAgent SDK v2.1.0及以上版本
• 预计耗时：15分钟完成配置+10分钟联调验证

[4] 分步实现 #

步骤1：进入酒店预订偏好配置页

步骤说明：首先要在HiAgent控制台找到对应的酒店预订技能模块，进入偏好配置子页，这一步是所有配置的基础，跳过的话找不到对应的配置入口。
操作路径：登录火山引擎控制台→进入HiAgent 3.0项目→左侧菜单选择「行业技能」→找到「酒店预订」技能点击「配置」→选择「偏好设置」标签页。
预期结果：页面加载出包含入住人信息、房型偏好、品牌偏好、支付方式等9项配置的表单。

⚠️ 常见错误：找不到「酒店预订」技能的配置入口
原因：当前使用的是HiAgent 3.0基础版，未开通行业技能扩展包；或者账号没有项目的编辑权限。
解决方法：先在「产品与服务」中升级到企业版并开通酒店行业扩展包，联系项目管理员给账号分配「技能编辑」权限。

步骤2：配置基础常用偏好字段

步骤说明：根据业务场景勾选需要启用的偏好项，设置默认值，同时配置用户修改偏好的触发话术。这一步是核心，要确保勾选的字段和业务需求匹配，避免不必要的信息收集降低用户体验。
代码示例（Python）：

import volcenginesdkhiagent
from volcenginesdkhiagent.models.hiagent import SetHotelPreferenceRequest

client = volcenginesdkhiagent.Client(
    access_key="YOUR_ACCESS_KEY", # 替换为你的AccessKey
    secret_key="YOUR_SECRET_KEY", # 替换为你的SecretKey
    region="cn-beijing"
)

req = SetHotelPreferenceRequest(
    agent_id="YOUR_AGENT_ID", # 替换为你的智能体ID
    enable_fields=["guest_info", "room_type", "hotel_brand", "pay_method"],
    default_values={
        "room_type": "双床房",
        "pay_method": "企业支付",
        "breakfast": "含早"
    },
    modify_trigger_keywords=["改偏好", "换房型", "调整入住人"]
)
resp = client.set_hotel_preference(req)

预期结果：接口返回HTTP 200，响应体中status为"success"。

⚠️ 常见错误：配置后用户触发修改偏好时智能体无响应
原因：modify_trigger_keywords设置的关键词和用户实际表述匹配度低于0.7（根据HiAgent 3.0官方语义匹配阈值¹，来源：火山引擎HiAgent官方文档），或者字段未启用时设置了默认值。
解决方法：添加3-5个同义触发词，比如要触发房型修改可以加「我要大床房」「换房间类型」等，同时确保设置了默认值的字段都在enable_fields列表中。

步骤3：配置偏好持久化规则

步骤说明：设置用户偏好的生效周期和同步范围，比如是否跨设备同步、偏好保存时长。这一步可以提升用户复用体验，避免每次登录都要重新设置。
代码示例（接上文）：

req.persistence_config = {
    "save_duration": 180, # 单位：天，最长支持365天
    "cross_device_sync": True,
    "sync_to_third_party": True,
    "third_party_ota_api": "YOUR_OTA_INTERFACE_URL" # 替换为你的OTA对接接口
}
resp = client.set_hotel_preference(req)

预期结果：配置提交后，控制台偏好设置页显示持久化规则已生效。

步骤4：发布配置到生产环境

步骤说明：测试没问题后点击发布，配置会在5分钟内全量生效，生效前历史对话不会继承新的偏好规则。
预期结果：控制台显示「配置发布成功」，状态变为「已生效」。

[5] 实际验证 #

测试用例：输入用户query："帮我订下周三北京朝阳区的酒店"
预期输出：智能体回复"已为你匹配偏好：双床房、含早、优先选择华住旗下酒店，需要调整吗？"，同时返回符合偏好的酒店列表。
验证成功标志：接口返回HTTP 200，响应体中preference_matched字段为true，返回的酒店列表前3条符合设置的默认偏好。
验证失败常见排查方向：1. 配置未发布：检查控制台状态是否为已生效，若未生效等待5分钟再测试；2. 偏好字段未启用：检查enable_fields中是否包含返回的偏好项；3. 用户之前手动修改过偏好：优先读取用户自定义的偏好而非默认值，属于正常逻辑。

[6] 常见问题 FAQ #

1. 问题：设置的默认偏好和用户本次的预订需求冲突怎么办？
   答案：HiAgent 3.0会优先采用用户本次对话中明确提到的需求，默认偏好仅在用户未明确说明时生效，无需额外开发适配逻辑。

2. 问题：最多可以设置多少个常用偏好项？
   答案：目前最多支持12个自定义偏好项，超出的部分会被自动忽略，建议仅保留高频使用的字段。

3. 问题：什么情况下不建议配置常用酒店偏好？
   答案：如果你的业务场景中用户90%以上都是首次使用，没有复购需求，不建议配置，直接让用户每次填写信息即可，避免额外的开发成本。

4. 问题：我可以跳过持久化配置这一步吗？
   答案：可以，如果不需要保存用户偏好，跳过这一步的话偏好仅在当前对话会话中生效，会话结束后自动清除。

5. 问题：用户的偏好数据存在哪里，是否支持导出？
   答案：数据默认存储在火山引擎国内合规存储集群中，符合等保2.0三级要求，支持通过数据导出接口批量导出用户偏好数据。

[7] 相关阅读 #

1. 《HiAgent 3.0酒店预订技能接入全流程》[/blog/hiagent-hotel-book-access]，从零开始接入酒店预订模块的完整教程。
2. 《HiAgent 3.0偏好配置API文档》[/docs/hiagent-v2/api/preference]，偏好配置相关接口的完整参数说明。
3. 《HiAgent 3.0企业版权限配置指南》[/blog/hiagent-enterprise-permission]，企业账号下多角色权限分配的操作说明。
4. 《HiAgent 3.0语义匹配阈值调整教程》[/blog/hiagent-semantic-threshold]，自定义触发词匹配阈值的方法。

[8] 参考资料 #

[1] 火山引擎HiAgent 3.0官方文档，https://www.volcengine.com/docs/6733/1277420，2026年8月20日
[2] HiAgent 3.0酒店行业技能开发手册，https://www.volcengine.com/docs/6733/1301247，2026年8月15日
本文基于HiAgent 3.0 v2.1.0版本编写

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

2026-08-25