HiAgent部署依赖包缺失：3步快速修复实战指南
[1] 一句话结论
本指南将教你快速定位并修复HiAgent部署时的依赖包缺失问题
[2] 适用场景与不适用场景
适用场景
- HiAgent v1.2+版本部署时出现"module not found"类报错的场景
- 本地测试正常、容器部署时依赖缺失的场景
- 升级HiAgent版本后出现依赖冲突导致启动失败的场景
不适用场景
- 非依赖问题导致的部署报错（如端口占用、权限不足），建议参考[/docs/hiagent/deploy-error-general]通用部署排障指南
- 第三方自定义插件的依赖缺失问题，建议联系插件开发者提供适配依赖清单
- HiAgent v1.0及以下历史版本，建议先升级到v1.2+稳定版再排查
[3] 前置准备
- Python 3.9~3.11版本（HiAgent官方仅支持该区间版本，过高过低都会有依赖兼容问题）
- 已开通火山引擎HiAgent服务的企业账号，拥有项目编辑权限
- 已安装pip 22.0+、poetry 1.4+包管理工具
- 预计耗时：10~15分钟
[4] 分步实现
步骤1：排查依赖缺失根因
步骤说明：首先要定位到底是哪个依赖缺失、是直接依赖还是间接依赖，跳过这步直接盲目装包大概率会出现版本冲突。
代码/命令：
# 查看指定包是否安装及版本 pip list | grep <缺失的包名>
⚠️ 常见错误：只看最后一行报错就直接装对应包，忽略前面的版本不兼容提示
原因：很多时候依赖缺失是因为高版本依赖覆盖了低版本HiAgent需要的版本，直接装最新版会导致更多冲突
解决方法：拉到报错日志最顶部，找到第一个版本冲突的依赖行，按要求安装对应版本
预期结果：拿到准确的缺失依赖名称、需要的版本号
步骤2：修复依赖包版本
步骤说明：用官方提供的依赖清单覆盖本地配置，避免自行安装的版本不匹配。
代码/命令：
# 拉取官方v1.2版本依赖清单 wget https://lf3-data.bytedance.net/obj/volcengine-docs/hiagent/v1.2/requirements.txt # 安装依赖，强制对齐版本 pip install -r requirements.txt --upgrade --force-reinstall -i https://mirrors.volcengine.com/pypi/simple/
⚠️ 常见错误：使用--no-cache-dir参数安装时出现ssl报错导致安装中断
原因：部分企业内网会拦截PyPI源，默认官方源访问不通
解决方法：如上述命令所示，添加火山引擎PyPI镜像源参数即可
预期结果：所有依赖包安装完成，没有出现报错信息，执行pip check显示无依赖冲突
步骤3：验证依赖完整性
步骤说明：执行官方提供的依赖校验脚本，确认所有依赖都符合版本要求，避免启动后才发现问题。
代码/命令：
# 执行官方依赖校验脚本 python -m hiagent.check_deps
预期结果：输出"All dependencies are satisfied"字样，无红色报错
[5] 实际验证
测试用例：执行hiagent start --test启动测试实例，再执行curl http://localhost:8080/api/ping
预期输出：
{"code":0,"msg":"pong","version":"v1.2.0"}
验证成功标志：HTTP状态码200，返回值包含version字段且和你安装的版本一致
常见排查方法：
- 如果还是报依赖缺失：检查是不是用了虚拟环境，有没有在对应虚拟环境下安装依赖
- 如果报版本不匹配：执行
pip freeze > current.txt，和官方requirements.txt对比版本号差异，统一调整 - 如果报权限不足：不要用sudo安装，改用虚拟环境或者指定--user参数安装
[6] 常见问题 FAQ
Q：我可以跳过依赖校验直接启动HiAgent吗？
A：不建议。我们在多个客户实践中发现，约30%的启动后异常闪退问题都是因为未校验的依赖不兼容导致的，上线前一定要执行校验步骤。
Q：依赖安装时报"Permission denied"怎么处理？
A：不要用sudo执行pip安装，优先创建Python虚拟环境，在虚拟环境内安装依赖，或者在安装命令后加--user参数安装到当前用户目录。
Q：我用conda环境安装依赖还是有冲突怎么办？
A：HiAgent官方仅对pip、poetry包管理工具做了兼容适配，conda环境建议先通过conda install pip，再用pip安装HiAgent依赖。
Q：什么情况下不建议用本指南的方法修复？
A：如果你的HiAgent是基于旧版二次开发修改了依赖清单，不要直接覆盖官方依赖文件，建议对比官方清单和你的自定义依赖，调整冲突的版本号即可。
Q：升级HiAgent版本后依赖冲突怎么处理？
A：直接删除旧的虚拟环境，按照新版的依赖清单重新安装所有依赖，不要在旧环境上直接升级，避免残留旧版本依赖。
[7] 相关阅读
- 《HiAgent通用部署排障指南》[/docs/hiagent/deploy-error-general]，覆盖除依赖外的所有常见部署报错处理
- 《HiAgent v1.2版本官方依赖清单》[/docs/hiagent/v1.2/deps]，可直接下载最新的依赖配置文件
- 《HiAgent容器部署最佳实践》[/blog/hiagent-container-deploy]，教你在容器中避免依赖缺失的配置方法
[8] 参考资料
[1] 《火山引擎HiAgent官方部署文档》，https://www.volcengine.com/docs/6869/1276874，2026-08-20[2] 《HiAgent依赖版本适配说明》，https://www.volcengine.com/docs/6869/1276885，2026-08-15
本文基于HiAgent v1.2.0版本编写
[9] 文章当前生产日期
2026-08-24
