搞深度学习的人多数时候装环境都靠联网一把梭conda create 一下pip install 一下几分钟搞定。但真正站到一台内网隔离的机器前面你会发现这些常规操作全都卡在“网络请求超时”上。离线搭建深度学习环境这个事操作本身并不神秘难的是把所有依赖在离线之前就准备到位。这篇文章把我实际踩过一遍的完整流程整理出来覆盖显卡驱动、CUDA、cuDNN、Python 运行时、PyTorch 以及Python 依赖包从物料准备到现场安装再到问题排查一条龙讲清楚希望能帮到正被内网环境折腾的人。1. 离线环境的核心难点与方案选型1.1 为什么离线安装比在线安装麻烦这么多在线安装时安装器可以自动从软件源拉取依赖版本冲突时也能即时解析。离线环境下所有依赖都必须预先准备好而且版本必须严丝合缝地对上任何一个环节漏了都要返工。具体来说有三个难点。依赖关系的传递性。装一个 PyTorch 看上去只是一个包实际会牵连 numpy、pillow、typing-extensions、filelock 等几十个 Python 依赖再往上一层还有 CUDA 运行时库、cuDNN、显卡驱动这些系统层面的依赖。这些依赖之间还有依赖形成一个树状结构人工一个个去猜很容易漏。版本匹配的粒度。显卡驱动支持的最高 CUDA 版本、CUDA Toolkit 的版本、cuDNN 的版本、PyTorch 编译时使用的 CUDA 版本这四个版本只要有一个对不上跑起来就各种莫名其妙的问题。在线时框架会提示你版本不匹配离线时往往只给你一段读不懂的底层报错。平台架构的差异。同一套安装包在 x86_64 和 ARM 上是完全不同的文件在 Windows 和 Linux 下也不互通甚至 Python 3.10 和 3.11 对应的 wheel 包都不能混用。所以离线搭建的第一步不是在目标机器上动手而是在一台能联网的机器上做一次完整的“物料采购”。1.2 两条技术路线一次性搬运与私有源同步动手之前先想清楚自己的需求规模再选路线。如果只是临时部署一两台机器或者机器之间网络也不互通最实用的做法是在一台能联网的工作站上把所有安装包抓齐用移动硬盘带到现场逐台离线安装。我习惯把这种方案叫“整包搬运”。它的优点是思路简单、不依赖内网基础设施缺点是一旦要更新版本又得重新跑一趟流程。如果是长期维护、机器数量多、内网又有独立服务器的情况就应该考虑在内网搭建私有软件源让每台机器像在线安装一样从内网源拉包。Python 侧可以部署私有 PyPI 服务conda 侧可以搭建本地 channel最简单的开局方式是在局域网共享目录里开一个只读文件服务把离线包目录共享出去效果也差不多。私有源方案的前期工作量比整包搬运大但后续每台机器安装和更新的成本会低很多。这两条路线不是互斥的。我通常的做法是首次部署用“整包搬运”快速打通把环境跑起来验证没问题之后再逐步往私有源迁移用于后续的补丁和版本更新。下面重点讲整包搬运的完整流程因为它覆盖了离线场景里八成会遇到的坑。2. 在线机器上的物料准备清单2.1 一张随手可用的离线物料清单在动手下载之前建议先按下面这张表把清单列出来逐项打勾别想着边下边想。离线环境里少一个包就是一次往返跑腿。物料常见可选项关键注意点Linux 基础系统Ubuntu 20.04 / 22.04 等提前确认内核版本和 glibc 版本显卡驱动与显卡型号匹配的 .run 文件驱动版本决定 CUDA 运行环境上限CUDA Toolkit与驱动兼容的 runfile 版本离线环境不要用 deb 仓库形态cuDNN与 CUDA 小版本对应的 tgz 包具体版本以框架要求为准Python 运行时Miniconda 离线安装包自带 conda省去单独装 Python 的麻烦深度学习框架torch / tensorflow 的 wheel 包必须与 CUDA 版本严格对应Python 依赖所有第三方依赖的 wheel 包用 pip download 一次性抓齐我建议所有物料都只选“确定能用的版本”不要盲目追新。PyTorch 官方会给出每个版本对应的 CUDA 版本组合确认好组合之后再动手下载。版本组合确定后把操作系统、驱动、CUDA、cuDNN、Python、框架这六个维度写成一张版本矩阵表后面所有的下载和安装步骤都跟着这张表走能省掉大量试错时间。2.2 pip 离线依赖包的正确抓取姿势对 Python 侧的依赖标准做法是用 pip download 在在线机器上把包抓下来而不是去 PyPI 网页上一个个手动下载。我拿一个带 PyTorch 的项目举例pip download -r requirements.txt -d ./offline_packages \ --platform manylinux2014_x86_64 \ --python-version 3.10 \ --only-binary:all:几个参数的意思要搞清楚。-d指定输出目录所有 wheel 包都会集中在这一个文件夹里。--platform和--python-version用来指定目标平台的架构和 Python 版本避免抓到本机平台才能用的包。比如你在线机器是 Python 3.12目标是 3.10不指定这两个参数的话抓下来的包很可能到了现场全是“不支持的 wheel 格式”。--only-binary:all:强制只要编译好的二进制包不要源码包因为离线环境没有网络源码包无法拉取编译依赖。PyTorch 本身因为带 CUDA 依赖不能从普通 PyPI 源直接抓到完整版本。需要在在线机器上从 PyTorch 官方对应的 wheel 索引地址下载pip download torch torchvision torchaudio \ --index-url https://download.pytorch.org/whl/cu118 \ -d ./offline_packages这里还要提醒一句torch、torchvision、torchaudio 三个包必须使用完全相同的版本号它们之间有强对应关系混版本安装会在运行时直接报错。下载完成后有个容易被忽略的动作检查每个 wheel 包的 SHA256 校验值并把校验结果记录在物料清单里。移动介质拷贝大文件时偶尔会发生静默损坏到现场才发现包坏了非常浪费时间。2.3 conda 环境整体打包方案如果你平时习惯用 conda 管理环境离线部署时最省事的方法不是在新机器上一步步创建环境而是直接把一个现成环境打包带走。conda install -n base conda-pack conda pack -n your_env_name -o deeplearning_env.tar.gz打包产物是一个单独的 tar.gz 文件。到了目标机器解压到某个路径并激活即可mkdir -p /opt/dl_env tar -xzf deeplearning_env.tar.gz -C /opt/dl_env source /opt/dl_env/bin/activateconda-pack 的原理是把环境中所有文件连同 conda 元数据一起归档目标机器不需要联网也不需要安装相同版本的 conda。它最大的限制是跨 glibc 兼容性如果打包机器系统较新目标机器系统较老解压后部分库会报版本不兼容。所以打包之前务必确认两边系统版本相近或者目标系统版本不低于打包机器。3. 目标机器上的离线安装实操3.1 显卡驱动与 CUDA 的离线安装目标机器装好 Linux 系统后第一件事是离线安装显卡驱动。驱动安装包有两种常见形态一种是 .run 文件一种是 deb 仓库形式。离线场景下强烈建议用 .run 文件因为 deb 仓库形式依赖联网添加源离线基本用不了。sudo chmod x NVIDIA-Linux-x86_64-xxx.run sudo sh NVIDIA-Linux-x86_64-xxx.run --silent安装过程如果报类似 “The driver installation is incomplete” 的错误多数原因是缺少内核头文件和编译工具。离线环境里没有网络需要提前把 linux-headers-$(uname -r) 对应的包以及 gcc、make 一并下载到移动介质里。这一步是离线装驱动最常见的坑驱动本身没问题而是编译内核模块时缺了依赖。CUDA Toolkit 同样建议使用 runfile 安装sudo sh cuda_xxx_linux.run --toolkit --silent --override安装完成后配置环境变量我习惯把下面几行写进 /etc/profile.d/cuda.shexport PATH/usr/local/cuda/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda/lib64:$LD_LIBRARY_PATHcuDNN 相对简单它本质是一个库文件压缩包把对应文件拷贝到 CUDA 安装目录即可tar -xzvf cudnn-linux-x86_64-xxx.tgz sudo cp cudnn-xxx/include/cudnn*.h /usr/local/cuda/include/ sudo cp cudnn-xxx/lib/libcudnn* /usr/local/cuda/lib64/ sudo ldconfig装完先验证两个命令nvidia-smi能看到显卡信息nvcc -V能输出 CUDA 版本。两个命令都通过再继续往下走。3.2 Python 运行时与 conda 配置Python 侧我推荐用 Miniconda 离线安装包体积小、依赖干净。安装时用静默模式bash Miniconda3-py310_xx-Linux-x86_64.sh -b -p /opt/miniconda3-b是无交互模式-p指定安装路径。安装结束后建议立刻执行一条命令conda config --set offline true这样 conda 后续操作默认不联网避免在之后解析环境时反复超时等待。这一步是我自己踩过的坑不设置 offlineconda 在创建环境时即使本地有缓存包也还是会尝试访问源内网下每次都卡到超时。3.3 框架与依赖包的本地安装把之前抓取的 offline_packages 目录整体拷贝到目标机器然后安装pip install --no-index --find-links./offline_packages \ torch torchvision torchaudio这里有两个关键参数必须理解。--no-index告诉 pip 不要访问任何包索引彻底禁止联网。--find-links指定本地查找目录pip 会在这个目录里扫描所有可用的 wheel 包并根据依赖关系自动解析。如果项目里还有自己的依赖清单直接加一个文件参数pip install --no-index --find-links./offline_packages -r requirements.txt如果之前用 conda-pack 打包了环境这一步就直接解压激活无需再 pip 安装。注意两种方案不要混着来conda-pack 的环境里用 pip 再装一遍同名包很容易把动态库链接弄乱。3.4 环境验证与基准测试框架装完别急着直接跑训练脚本先用几分钟做最小验证。我的固定流程是这样nvidia-smi # 驱动层正常 nvcc -V # CUDA toolkit 正常 python -c import torch; print(torch.__version__, torch.cuda.is_available())如果 torch.cuda.is_available() 返回 False先不要急着查框架配置多半是驱动与 CUDA 版本不匹配或者依赖库缺失。验证 CUDA 可用后再跑一个简单的矩阵运算确认 GPU 计算链路真的通了import torch x torch.randn(10000, 10000, devicecuda) y torch.mm(x, x) print(y.sum().item())能正常输出数字说明 GPU 链路已经打通这时候再跑项目代码就稳妥得多。整个验证过程建议写进部署文档里后面每台机器装完都照这个流程过一遍。4. 常见问题与排查经验记录4.1 驱动正常但 CUDA 不可用现象nvidia-smi 正常nvcc 正常但 torch.cuda.is_available() 返回 False。原因大概率是 PyTorch 编译时使用的 CUDA 版本和当前系统的 CUDA 运行时版本不匹配或者显卡驱动版本低于框架要求的最低驱动版本。比如某个较新的 PyTorch 版本要求驱动不低于某一版本旧驱动即使 CUDA Toolkit 装的是新版也无法正常使用。另一个容易忽略的问题是显卡的计算能力也就是 compute capability。较新的 PyTorch 默认只编译了主流架构的二进制如果你的显卡是较老或较新的架构离线安装时最好选择官方提供的与显卡架构匹配的 wheel 包否则 import 时会出现类似 “no kernel image is available” 的报错。4.2 pip 总是尝试联网导致卡死现象明明指定了本地目录pip 还是会报连接错误或者长时间卡在超时等待。解决思路是彻底禁用索引。除了命令行加--no-index之外可以把配置写进 pip.conf一劳永逸。Linux 下配置文件路径是 ~/.pip/pip.conf 或 /etc/pip.conf[global] no-index true find-links /path/to/offline_packages这样即使某次命令漏写了参数pip 也会优先从本地目录找包。另外要记住离线包目录里的 wheel 文件名不能改。pip 依赖文件名里的版本信息来解析依赖关系一改名pip 就认不出这个包了。4.3 系统库版本不兼容现象import torch 时提示找不到 libgomp.so.1或者类似 GLIBCXX_3.4.30 not found 的报错。这类问题属于系统基础库缺失和 Python 包本身无关。缺失的基础库可以提前在在线机器上把对应发行版的系统包抓下来统一拷到目标机器安装。找包时要注意目标机器的发行版版本Ubuntu 18.04 和 20.04 的包不通用。glibc 的问题更棘手一些glibc 只能升级不能降级目标机器 glibc 太旧时只能选用兼容性标识更老的 wheel 包比如 manylinux2010 或 manylinux2014 对应的包或者直接在旧系统里用 conda-pack 打包环境。4.4 传输环节的坑移动介质拷贝时大文件可能静默损坏。建议在在线机器上下载完成后用下面的命令生成校验文件find ./offline_packages -type f -exec sha256sum {} checksums.txt到达现场后先执行一次校验确认全部通过再开始安装。如果你有多个目标机器校验完拷到下一台比每台都重新算一遍省时间。另外超过 4GB 的单个文件要注意移动介质文件系统格式。FAT32 不支持大于 4GB 的文件传输会直接失败这类 U 盘建议提前格式化为 NTFS 或 exFAT。搞深度学习环境的大文件经常就是好几个 GB这一步别省。5. 离线部署的经验与心得补遗离线搭建深度学习环境这件事做一次和做十次的体验完全不同。我的体会是把版本矩阵钉死是整件事里最重要的一环。下载之前确定好六个维度的版本组合后面所有步骤都跟着组合表走能过滤掉绝大部分坑。实际操作中我还会在虚拟机里先把整个离线流程完整跑一遍再带着移动硬盘去现场。不要嫌这一步多余现场机器没有网络任何一个小问题都可能变成很长时间的反复排查。预演一次现场基本就是照抄命令。最后分享一个小技巧多台机器需要部署同一套环境时第一台完整安装并验证通过后可以用 tar 打包整个 /opt/miniconda3 和 /usr/local/cuda 目录带走后面几台机器直接解压速度比逐台安装快得多。前提是这些机器的操作系统版本一致否则 glibc 级别的差异会让这个快捷方案变成新的麻烦。离线环境维护没有太多玄学准备充分、版本固定、流程可复制你就已经赢了八成。