HiAgent依赖包缺失部署失败：30分钟快速修复指南
[1] 一句话结论
本指南将教你快速排查修复HiAgent部署时依赖包缺失类失败问题。
[2] 适用场景与不适用场景
适用场景
- 适合通过火山引擎控制台/CLI部署HiAgent v1.2+版本时，出现
ModuleNotFoundError/pip install failed类报错的场景 - 适合本地调试HiAgent自定义插件时，依赖版本冲突导致启动失败的场景
- 适合日均调用量10万以下的中小规模HiAgent实例部署排障
不适用场景
- 如果是镜像拉取失败、权限不足导致的部署失败，建议参考[HiAgent镜像部署排障指南]
- 如果是大模型API调用权限问题导致的启动失败，建议参考[豆包API授权配置教程]
- 如果是集群资源不足（CPU/内存<2核4G）导致的依赖安装超时，建议优先扩容集群资源
[3] 前置准备
- 开发环境：Python 3.9~3.11（HiAgent v1.2+仅支持该版本范围），Node.js 18+（如有前端自定义组件需求）
- 账号权限：火山引擎账号拥有HiAgentFullAccess权限、容器镜像服务CR的读写权限
- 依赖项：提前安装火山引擎Python SDK v0.18.0+、hiagent-cli v1.2.1版本
- 预计耗时：30分钟以内
[4] 分步实现
步骤1：采集部署报错日志
步骤说明：首先要定位具体缺失的依赖包名和版本要求，跳过这一步会盲目修复导致更多版本冲突。
代码/命令：
# 控制台部署场景查看日志 hiagent-cli logs --instance-id YOUR_INSTANCE_ID --tail 100 # 本地部署场景直接查看终端报错输出
预期结果：拿到类似ModuleNotFoundError: No module named 'pydantic-core==2.18.0'的明确报错信息。
⚠️ 常见错误：只看报错摘要没看完整依赖链，误以为只是缺顶层包
原因：很多依赖缺失是间接依赖版本冲突导致，顶层包安装成功但子依赖版本不符合要求
解决方法：用pip show YOUR_TOP_PACKAGE查看完整依赖链，确认冲突的子依赖版本
步骤2：核对官方依赖白名单
步骤说明：HiAgent对第三方依赖有安全校验，不在白名单内的依赖会被拦截安装，这一步是确认缺失的包是否允许使用。
代码/命令：
# 命令行查询允许的依赖列表 hiagent-cli list-allowed-deps
预期结果：能查到对应包名和支持的版本范围。
⚠️ 常见错误：私自安装不在白名单内的依赖，部署时被安全策略拦截报错
原因：我们为了保障HiAgent实例的运行安全，对未经过安全审计的第三方依赖默认禁止安装，数据来源：2025年火山引擎HiAgent安全规范v2.0
解决方法：如果是必需的依赖，提交工单申请依赖白名单加白，审核周期通常为1个工作日
步骤3：修改requirements.txt指定兼容版本
步骤说明：明确依赖版本后，修改部署包中的requirements.txt，避免pip自动拉取最新版本导致冲突。
代码/命令：
# requirements.txt中添加对应依赖，优先指定明确版本 pydantic-core==2.18.0 # 如有版本范围需求可指定范围 requests>=2.31.0,<2.33.0
预期结果：requirements.txt文件更新完成，无语法错误。
步骤4：本地预安装依赖验证
步骤说明：部署前先在本地相同Python版本环境下安装依赖，避免线上部署反复失败浪费时间。
代码/命令：
# 安装依赖 pip install -r requirements.txt --no-cache-dir # 检查依赖冲突 pip check
预期结果：pip install执行无报错，pip check输出"No broken requirements found."
步骤5：清理缓存重新提交部署
步骤说明：清理旧的部署缓存后重新提交，避免旧缓存导致的依赖问题。
代码/命令：
hiagent-cli deploy --instance-id YOUR_INSTANCE_ID --clear-cache
预期结果：控制台部署状态显示"运行中"，启动日志无依赖相关报错。
[5] 实际验证
测试用例：执行健康检查接口调用
curl https://YOUR_INSTANCE_ID.maas-api.cn-beijing.volces.com/health
预期输出：返回HTTP 200状态码，响应体为{"status":"ok","version":"v1.2.1"}
验证成功标志：健康检查接口返回正常，自定义功能可以正常调用。
排查方法：
- 如果还是报依赖缺失：检查requirements.txt的包名/版本是否和白名单一致，是否有拼写错误
- 如果报依赖冲突：执行
pip freeze对比本地和线上的依赖版本，删除多余的依赖声明 - 如果安装超时：检查集群是否能访问PyPI镜像源，建议替换为火山引擎公共PyPI源https://mirrors.volces.com/pypi/simple/
[6] 常见问题 FAQ
Q1：我可以直接在部署时用--force参数强制安装未加白的依赖吗？
A：不可以，强制安装也会被安全策略拦截，甚至会导致实例被封禁。如果确实需要使用该依赖，请先提交工单申请加白，我们会在1个工作日内完成安全审核。
Q2：为什么本地安装依赖正常，线上部署就失败？
A：大概率是本地Python版本和线上运行环境版本不一致，HiAgent线上运行环境默认是Python 3.10，你可以在本地用Python 3.10的虚拟环境重新测试安装。
Q3：什么情况下不建议按照本指南排查？
A：如果你的部署报错是OutOfMemory或者ImagePullBackOff，说明是资源或镜像问题，不是依赖包问题，建议优先查看集群资源配置和镜像地址是否正确。
Q4：依赖白名单申请有没有次数限制？
A：没有次数限制，但单次申请最多可以提交10个依赖包，我们建议你把需要的依赖整理后一次性提交，减少审核等待时间。
Q5：我可以自定义HiAgent的运行Python版本吗？
A：目前HiAgent v1.2版本仅支持Python 3.9~3.11，如果你需要更低或更高的Python版本，建议使用自定义镜像部署的方式，参考官方自定义镜像文档。
[7] 相关阅读
- 《HiAgent官方部署文档》[/docs/hiagent/latest/deploy]，介绍HiAgent的标准部署流程和全量配置项说明
- 《HiAgent依赖白名单申请指南》[/docs/hiagent/latest/whitelist]，教你如何提交依赖加白申请、填写申请材料
- 《HiAgent常见部署报错排障大全》[/blog/hiagent-debug]，覆盖除依赖外的其他12类常见部署失败问题
[8] 参考资料
[1] 《HiAgent v1.2 部署操作指南》，https://www.volcengine.com/docs/6867/1296377，2026-06-15[2] 《火山引擎HiAgent安全规范v2.0》，https://www.volcengine.com/docs/6867/1301245，2025-12-01
本文基于HiAgent v1.2版本编写。
[9] 文章当前生产日期
2026-08-24
