内网部署的兼容链与离线包
一句话收获：部署方案从现场事实开始，不从开发机假设开始。
这个场景在解决什么问题
目标（goal）很简单：从目标环境的事实，生成一个可重复的部署包。也就是说，不是"我在开发机跑得好好的，打包给你"，而是"我摸清了你的现场长什么样，再照着现场事实做出一个能在你那儿反复安装成功的包"。
观察方式（observation）是逐层验证：沿着硬件、驱动、运行时、模型、服务、应用这一条链，一层一层往下确认，而不是只看某一层。
这个场景值得单独学，是因为内网部署最容易翻车的地方，恰恰是你以为"开发机都验证过了"的那些环节。开发机能联网、有缓存、有熟悉的依赖，客户内网没有这些东西，任何一处缺失都会当场卡住。
先理清这条判断链（文字版）
部署这件事，逻辑是一条从"摸底"到"复现"的链：
- 先环境勘测：把设备、驱动、系统、网络、证书、账号、数据源、变更窗口这些事实一条条问清楚、记下来，有证据有责任；
- 再验证兼容链：从硬件、驱动、运行库，一直到模型格式、推理服务、真实任务，逐层确认都能通过；
- 然后离线制包：把镜像、模型、依赖、迁移脚本、配置、测试、回滚方案全部打进版本清单，做校验、锁版本；
- 最后在干净环境里安装：拿一台没有开发缓存、没有外网的机器，按手册从头装一遍，把漏掉的依赖暴露出来再补上。
一句话：先摸清现场 → 再验证链 → 打成离线包 → 在干净环境复现。每一步都是上一步的闸门，缺一条事实就会在下一环卡住。
逐层详解
第 1 步：环境勘测
原文：确认设备、驱动、系统、网络、证书、账号、数据源和变更窗口。
白话：别急着搬东西，先把你家底摸清楚。设备是什么型号、驱动什么版本、操作系统什么版本、网络通不通外网、证书有没有、账号权限够不够、数据源在哪、允许你在什么时间段动服务器（变更窗口），这些都要一条条确认并记录。
类比：像装修前先量房——你不能直接照着样板间下单，得先到现场量尺寸、看承重墙、确认水电位置，否则材料买回来也对不上。
举例：你要给某政务内网部署一套 AI Agent。先确认服务器是不是国产 CPU/GPU（比如鲲鹏 CPU + 昇腾 NPU）、系统是不是麒麟/UOS、能不能连外网、有没有内部 CA 证书、账号是不是只读、数据库是不是 Oracle、以及只能在周末凌晨 2 点到 6 点停机变更。这些没问清，后面每一步都可能是坑。
为什么重要：缺失事实会变成现场阻塞。勘测阶段漏一条，到了安装那天就可能卡一整天，而且是在客户现场卡，代价完全不同。
怎么验证（证据点）：
- 已确认项：哪些事实已经拿到证据、有人负责；
- 待确认项：哪些还没问清，要列出来继续追；
- 阻塞项：哪些东西目前根本拿不到，会直接挡住部署。
别踩的坑（边界）：服务器型号不能代表完整环境。一台"XX 型号服务器"不代表它的驱动、系统版本、网络策略、证书都跟你以为的一样，型号只是整条链的第一环。
落地检查：每项都要有证据和责任。每一条事实不光要写下来，还要注明"证据是什么（截图/文档/命令输出）"和"谁来负责确认"，不能停留在口头描述。
第 2 步：兼容链验证
原文：硬件、驱动、运行库、模型格式、推理服务和真实任务逐层通过。
白话：光确认了硬件不够，要顺着一条链验下去：硬件能被系统识别 → 驱动装对 → 运行库（推理框架、依赖库）版本匹配 → 模型格式能转/能加载 → 推理服务能起来 → 最后拿一个真实任务跑通。每一层都通过，才算兼容。
类比：像链条上的一环扣一环——你买回来的车能不能开，不是看轮胎好，而是看发动机、变速箱、油箱、点火系统一路都通。任何一环断了，车都动不了。
举例：内网用昇腾 NPU，你要部署一个 vLLM 或 MindIE 推理服务。要先确认 NPU 驱动装好（npu-smi 能看见设备），CANN 版本对得上，模型是 ONNX/昇腾可加载的格式，推理服务能拉起，最后用一个真实的 Agent 请求（带工具调用）跑通才算兼容链验证完成。
为什么重要：模型加载只是兼容链中间一步。很多人以为"模型能加载"就等于部署成功，其实它前面有硬件驱动、后面有服务和真实任务，任何一环没通都不算数。
怎么验证（证据点）：
- 设备可见：硬件能被系统识别到；
- 模型可加载：模型能成功加载进内存；
- 真实调用通过：拿真实请求打一遍能返回正确结果。
别踩的坑（边界）：成功加载不证明结构化输出和工具调用正常。模型能 load 起来，不代表它能稳定输出合法 JSON、能正确调用工具，这两件事要单独验。
落地检查：验证一直到应用层。别停在"模型加载成功"就收工，要一路验到真实业务调用能跑通为止。
第 3 步：离线制包
原文：镜像、模型、依赖、迁移、配置、测试和回滚进入版本清单。
白话：把要搬到现场的所有东西，全部打包并登记成一份版本清单：容器镜像、模型文件、依赖包、数据库迁移脚本、配置文件、测试用例、回滚方案，一个都不能漏，还要做校验和、锁死版本。
类比：像搬家打包——不是只把大件家具搬上车，连插座、螺丝、说明书、备用钥匙都要清点装箱，少了任何一样，到了新家都装不起来。
举例：你要交付一个 Agent 系统，离线包里要包含：Docker/镜像文件（或 OCI 镜像 tar 包）、模型权重文件、Python 依赖 wheel 包、数据库 schema 迁移脚本、环境配置文件、冒烟测试脚本，以及回滚用的上一版镜像。每样都记进清单并算好 SHA256 校验和。
为什么重要：现场不能依赖临时联网下载。内网没外网，你到现场才发现某个依赖没带、需要联网拉，那就是灾难现场——因为根本拉不了。
怎么验证（证据点）：
- 包完整：清单里每一项都实际存在、没漏；
- 校验和：每样都有校验和，能验证没损坏、没被篡改；
- 版本锁定：所有依赖都锁死具体版本，不会装出别的版本。
别踩的坑（边界）：在开发机打包成功不证明可重复安装。你在自己机器上打包成功，可能只是因为你机器上已经有缓存和依赖，到了干净机器上不一定装得出来。
落地检查：使用干净环境重放。拿一台干净的机器（或容器），只靠这个离线包按手册重装一遍，能装成功才算包是完整的。
第 4 步：干净环境安装
原文：无开发缓存环境按手册安装，缺失依赖被暴露并修订。
白话：找一台没有开发缓存、没有外网的"干净"环境，完全按照安装手册从头装一遍。这一装，你之前漏掉的任何依赖都会被当场暴露出来，然后你再把这些漏掉的东西补进包里、修订手册。
类比：像新员工照着说明书第一次组装家具——如果连一个从没装过的人都能只凭说明书装好，说明说明书和零件清单是完整的；装到一半发现少零件，说明书就得改。
举例：用一台全新的内网虚机（或干净容器），断网、清空 pip 缓存，只导入你的离线包和手册，让另一个同事照着装。装到某一步发现缺了某个系统库，就说明制包时漏了，补进去、更新手册、重新来过。
为什么重要：第二环境验证真实可交付性。一台机器装成功不算数，因为可能沾了开发机的光；换第二台干净环境能重放，才证明这套包和手册真的可交付。
怎么验证（证据点）：
- 无外网：安装过程全程不连外网；
- 无本地缓存：环境里没有提前放好的依赖缓存；
- 安装可重复：照着手册装，能装出一样的结果。
别踩的坑（边界）：一次安装成功不证明升级和回滚可用。首次装通只证明"从零能装"，不代表以后升级到新版、或出问题回滚到旧版也走得通。
落地检查：继续验证运行和回退。装完之后不能停，还要接着验证服务能正常运行、能顺利回退，才算这一环闭环。
落地可行性小结
这个场景涉及的技术栈和真实落地要点：
- 硬件与驱动：CPU/GPU/NPU 的识别（如
nvidia-smi、npu-smi、lscpu），驱动版本与系统内核匹配，国产芯片（鲲鹏、昇腾）要提前确认驱动和固件版本【待核实：不同芯片厂商的驱动与系统兼容矩阵需查官方文档】。 - 运行库与推理框架：CANN/ROCm/CUDA 等工具链版本要和推理服务（vLLM、MindIE、TGI 等）严格匹配，常见坑是工具链和框架版本错配导致加载失败。
- 模型格式：要确认现场推理服务支持什么格式（ONNX、SafeTensors、自研格式等），必要时提前转换。
- 离线制包：镜像（docker save / OCI tar）、模型、依赖（pip wheel / conda 包）、迁移脚本、配置、测试、回滚方案全部进清单，并用 SHA256 校验和锁定版本。
- 常见坑：漏带某个隐式依赖、版本没锁死导致现场装出不同版本、只在开发机验证过就以为能交付。
- 落地动作：所有事实要有证据和责任；兼容链验到应用层；制包后必须在断网、清缓存的干净环境重放一遍；装通后还要验证升级和回滚。
回顾
- 部署方案从现场事实出发，不从开发机假设出发。
- 先环境勘测，把事实、证据、责任逐条确认，型号不能代表完整环境。
- 兼容链要从硬件一路验到真实任务，模型能加载只是中间一步。
- 离线包要完整、有校验和、锁版本，并在干净环境里重放，才能证明可重复交付。