AI Agent 离线部署：模型、镜像和依赖如何做断网验收
内网运行过不等于离线交付完成。梳理模型文件、容器镜像、软件依赖与外联边界，用干净环境冷启动和故障用例检查部署包是否完整。
一套智能体在内网演示过，并不代表交付包可以在新机器上独立运行。模型权重已经复制，分词器配置却留在旧缓存中；首页可以打开，首次解析文档时才尝试下载组件。这些可能的缺口，往往要到断开公网、重新部署并走完业务链路时才会暴露。
AI Agent 离线部署的验收，重点不是证明“拔掉网线还能聊天”，而是检查约定环境中的制品、依赖和恢复步骤是否齐备。以下是通用验收建议，不代表本站产品实测结果，也不预设所有模型和软件都支持同一种离线模式。
先约定离线边界和内网依赖
先把“离线”写成可执行的网络条件。例如，应用禁止访问公网，但允许访问指定内网模型服务、数据库、身份认证、DNS 和时间同步服务。这与单机完全隔离不是同一目标，也不能把必要的内网 ERP 接口一并切断后，直接判定系统不可用。
验收前列出每项依赖的地址、用途、连接方向、责任方，以及不可用时的预期行为。本站私有化部署说明也区分了约定网络边界与具体外联需求：模型来源、授权校验、更新和运维方式都可能影响最终方案。需要外联的环节应明确处理办法，而不是在验收时临时放行。
测试应在获得授权的隔离环境进行，保留必要的内网通道，不直接修改生产网络规则。先画清数据流转和连接边界，再讨论哪些链路需要断、哪些服务必须保留。
交付清单不只包含模型权重
检查离线包时，可以按以下四类建立清单。每一项都标明版本、来源、目标平台、文件位置和验收方式，不需要使用的组件则明确标记为不适用。
- 运行环境：应用和基础服务镜像、启动配置，以及宿主机操作系统、CPU 架构、GPU 驱动和运行时的要求。镜像能导入，不等于目标机器具备正确的硬件与驱动条件。
- 模型相关制品：模型权重、配置、分词器等必需文件；如果业务链路使用向量模型、重排模型或 OCR，也要分别检查，不能只清点对话模型。
- 应用依赖：锁定的软件包、安装所需的二进制文件、前端静态资源，以及实际用到的字体和文档转换组件。开发机器已有缓存，不能作为交付完整性的证据。
- 业务与恢复材料：经过授权的测试文档、索引初始化或重建步骤、数据库结构、配置模板和恢复说明。账号、密钥、许可证等按约定的安全渠道单独交接，不把生产凭据目录打进普通安装包。
还要区分“运行所需”和“有权分发”。应用源码交付不自动包含模型权重所有权或第三方再分发授权，能否携带模型和依赖进入目标环境，应逐项依据适用许可与合同范围确认。
固定版本、平台与文件校验值
验收清单需要能够定位同一组制品：记录应用版本、模型修订版本、镜像摘要、依赖锁定文件和目标平台。不要只写一个可能被覆盖的镜像标签，或者用“最新版”代替交付版本。
Docker 的 image save 和 image load 可用于导出、导入镜像及标签，但这不等于迁移了完整应用状态、数据库卷和宿主机驱动。导出时需要的架构变体必须已存在；导入镜像也不会把一种 CPU 架构自动转换成另一种。相关边界见 Docker 官方的 save 与 load 说明。
Python 依赖可提前准备本地 wheelhouse，安装时不再依赖软件包索引。但包含编译产物的 wheel 与操作系统、架构等条件有关，不能把一台开发机上的包直接视为所有服务器通用。若使用 pip 的 --require-hashes，直接依赖和传递依赖都需要满足固定版本与哈希要求，不能只给顶层包补几个校验值。
将校验清单与可信来源、交接记录配套保存。文件哈希一致只能说明文件与该清单匹配，不单独证明供应方可信，也不代表制品没有漏洞。
用干净环境验证冷启动
“智能体断网后为什么启动失败”往往需要从隐藏依赖排查。可以使用新建虚拟机、独立测试节点或隔离缓存目录，明确记录初始状态，只提供交付清单中的材料。不要为测试去清空生产缓存或删除生产数据。
- 记录操作系统、架构、驱动、可用内网服务和网络限制，确认测试环境符合约定前提。
- 按文档导入镜像、安装依赖、装载模型并初始化必要的数据，不临时借用开发机目录或公网下载链接。
- 从首次启动开始，执行登录、文档处理、检索、推理和约定工具调用，记录每一步的结果与失败位置。
- 重启相关进程或测试节点后再执行核心链路，检查是否依赖未写入交付说明的临时文件和手工操作。
如果所用组件依赖 Hugging Face Hub，可按其官方说明，在启动进程前设置 HF_HUB_OFFLINE=1。该模式禁止 Hub 库发出 HTTP 请求，并使用已有本地缓存；缺少所需缓存时会报错。它有助于暴露遗漏，但不是整个应用的断网开关，也不能约束其他库或业务代码的网络访问。
通过标准应是“在已记录的前提下，交付材料足以完成约定链路”，而不是只截取服务启动成功或聊天窗口正常的画面。响应时间和资源占用如需验收，应另外约定样本与口径，不凭一次启动给出性能承诺。
外联检查要覆盖实际业务链路
离线模型部署如何验证外联边界？除了限制公网出口，还应在授权范围内观察 DNS 查询、连接尝试、重试和应用错误。被网络规则拦截的请求，仍然属于一次外联尝试；没有观察到流量，也只能说明已覆盖的时间与测试路径中没有发现，不能推断所有隐藏路径都已检查。
测试用例要覆盖实际启用的功能。例如，普通文本问答可能正常，扫描件 OCR、首次向量化、重排、身份认证或审计上传却走另一条链路。对每项功能明确预期：使用内网替代服务、从本地加载材料，还是在依赖不可用时给出可理解的错误。
不要用静默切换到外部模型掩盖离线失败。如果业务确实允许某种外部服务，应把它写入允许清单和数据边界，不能仍将该链路描述为完全离线。日志优先保留时间、组件、目标地址、错误类型和结果标记，避免记录文档正文、完整提示词或令牌。
用缺件、重启和更新场景验收
一次正常路径不足以检查交付可维护性。可以在测试副本中增加几类故障用例，并事先写好期望结果：
- 缺少制品：暂不提供某个必需模型配置、依赖包或镜像，检查系统能否明确指出缺失项，而非无限重试或偷偷下载。
- 平台不匹配：核对架构和驱动不满足前提时的识别与提示，不把“文件都在”当作环境兼容。
- 冷启动与重启：分别覆盖无历史缓存的首次部署和正常运行后的重启，区分交付缺件、初始化失败与持久化问题。
- 授权依赖不可用：按约定检查许可证或授权服务不可达时的行为，确认离线授权流程是否适用，不绕过软件的授权限制。
- 离线更新与回退：检查更新包是否齐备，以及旧版本恢复步骤。涉及数据库结构变更时，镜像换回旧版本未必足以回退，还要确认数据兼容性与恢复方案。
最终验收记录应包含环境与制品版本、文件校验结果、网络允许清单、用例和实际结果、失败后的恢复证据，以及尚未覆盖的边界。有关业务效果的衡量，可另参考试点指标与验收口径；离线部署通过与业务效果达标，是需要分别举证的两件事。
参考资料
以下官方文档查阅于 2026 年 9 月 10 日。文中的清单和测试步骤是基于这些工具边界整理的通用建议，具体支持范围仍应以实际软件版本、模型许可和项目约定为准。
