遇到过几次在不能联网的机器上装PyTorch你就知道什么叫“网络时代最原始的工作”。明明联网时一条pip install torch就搞定的事到了离线环境得小心翼翼地把驱动、CUDA、cuDNN、Python解释器、几十个依赖包一个个搬过去中间任何一个版本对不上就是一路报错。这篇文章就围绕“离线搭建深度学习环境”这个场景把我实际踩过、填过的坑都写下来包括离线包的准备、本地源的配置、CUDA与框架版本怎么对齐、多台机器怎么复制环境给正在内网折腾的同学一份可以直接抄的作业。不论你是企业AI平台运维、高校实验室的服务器管理员还是想在自己的离线工作站上跑模型的研究人员这些步骤基本都适用。整体思路核心就一句话在联网机器上把一切能下载的都准备好然后把这些“离线物料”搬到目标机器上安装。1. 离线环境整体方案与核心思路很多人一上来就要装CUDA装完GPU驱动发现系统已经有大版本CUDA了再装Python包时又跟已有环境冲突最后整个机器搞得一塌糊涂。离线安装最大的问题不是“装不上”而是“不知道该装什么版本”以及“装了之后才知道顺序错了”。1.1 离线安装到底难在哪联网环境下包管理工具会自动帮我们解析依赖、匹配版本、下载合适的安装包整个链路是透明的。但在离线环境里这种“自动解析”完全失效你必须自己在联网机器上完成依赖收集并且保证版本组合在目标机器上也能正确工作。真正的复杂度来自三个方面硬件环境不确定目标机是ARM还是x86有没有NVIDIA GPUGPU的算力版本是多少这直接决定CUDA和框架的构建上限。系统软件栈不统一操作系统的版本决定glibc版本glibc版本决定预编译的wheel包能不能跑。同一个Python库在不同glibc版本下会有不同的兼容层级。依赖关系难梳理一个深度学习框架背后往往有几十个传递依赖torch需要numpy、typing-extensions、filelock等而numpy又对编译器和底层BLAS库敏感。少一个包安装后第一次运行就崩。所以我给所有离线安装场景定的规矩是先把所有版本关系想清楚再动手装系统底层的东西最后一个环节才碰Python包。1.2 三条可行路线的取舍我在不同离线环境里试过几种方案各有优缺点。方案适用场景优点缺点搭建本地软件源需要长期维护、多台机器共用可复用性最高后续装新包方便前期准备量大系统源和Python源都要配置全量下载依赖包拷贝安装一次性部署、机器数量少简单直接一步到位后期加装新包又要重新收集依赖Docker镜像打包迁移环境统一要求高、有容器平台支持隔离性好迁移时依赖完整对GPU透传和数据卷有额外要求部分内网环境不支持其中本地软件源是我最推荐的做法尤其是机器数量超过两台时它的长期收益非常明显。但实际执行时我最常用的组合是“本地系统源 一次性pip包目录”也就是系统层用ISO做成离线源Python层打包wheelhouse。这样既不需要在内网额外部署复杂的私有源服务又保证了pip安装时速度极快。1.3 环境定版是离线安装的第一原则联网环境里“conflict resolved”只是重新装一个版本的事离线环境下你会发现根本没有重装的机会因为安装包不一定能临时下载。所以正式准备离线物料前必须先做一份“环境定版清单”明确记录操作系统版本和内核版本Python解释器版本3.8还是3.10这差别太大了CUDA版本注意区分GPU驱动版本和运行时版本深度学习框架版本PyTorch还是TensorFlow具体到小版本号其他关键依赖如numpy、opencv、transformers这份清单不仅是给你自己看的更要让团队里其他人也看懂。否则等你把离线包都准备好了别人告诉你“我们这边要用CUDA 11.8”那就全部重来。2. 离线路料准备在联网机器上收集一切正式安装之前最耗功夫的是“物料准备阶段”。这个阶段全部在联网机器上进行等你摸清目标机器情况开始下载的那一刻就要记得把所有需要的东西一口气备齐。2.1 先摸清目标机器的底细很多人在准备物料时犯的第一个错误就是“不问机器情况就开始下载”。我有一个固定做法先在目标离线机器上执行一串命令把系统信息记录下来然后带着这些信息回联网机器准备包。# 查看操作系统信息 cat /etc/os-release uname -a # 查看CPU架构 lscpu | grep Architecture # 查看GPU型号 lspci | grep -i nvidia # 查看当前Python版本 python3 -V which python3 # 查看是否已有CUDA相关库 ls /usr/local/ | grep cuda nvcc -V 2/dev/null || echo nvcc not found这些信息直接决定后面的所有选型。比如lscpu输出x86_64那你下载wheel时就要指定--platform manylinux2014_x86_64如果是aarch64那么很多预编译包根本没有可能要直接用源码包编译工作量会大很多。2.2 CUDA、驱动和框架的“三角恋爱”这是离线环境里最容易被忽视的关系。很多刚接触的人以为“装深度学习环境 装CUDA”其实CUDA只是运行时库它的安装还依赖显卡驱动而显卡驱动版本又决定了你最高能用到哪个CUDA版本。如果目标机器已经装有显卡驱动用nvidia-smi输出的右上角可以看到“CUDA Version: xx.x”这是当前驱动支持的最大CUDA版本。GPU驱动实际决定了CUDA Runtime可以在哪个版本上正常运行但也别忘记新版CUDA可能支持旧几代的驱动——准确判断方法还是看NVIDIA官方兼容表。PyTorch等框架发布时往往是预编译好的针对特定CUDA版本如cu118、cu121你需要这个版本号与本地驱动匹配。举个例子目标机器nvidia-smi显示支持CUDA 12.4那你可以放心用PyTorch的cu121版本因为驱动支持的上限大于等于框架要求的版本即可不需要跟框架构建版本完全一致。实际操作中我的推荐顺序是确认驱动已装好并可用nvidia-smi能正常输出根据驱动支持的CUDA上限确定CUDA Toolkit版本和框架版本离线安装时CUDA Toolkit与框架的CUDA完全匹配即可不必追求“最高版本”。2.3 用pip download批量收集Python依赖联网机器上收集Python依赖我最常用的命令就是pip download它可以把目标包及其所有依赖原样保存到指定目录。pip download torch torchvision torchaudio \ --index-url https://pypi.org/simple \ --extra-index-url https://download.pytorch.org/whl/cu121 \ --dest ./wheelhouse \ --no-deps后面加上--no-deps是提醒你自己只下载这几个主包依赖包再单独拉。但实际我建议不要一上来就--no-deps更好的方式是pip download torch torchvision torchaudio \ --dest ./wheelhouse让它自动解析并下载所有依赖然后你再用pip wheel或pip download配合--no-deps补齐缺失的包。如果你已经知道依赖全名也可以一次性写全。这里有两个关键参数要注意--platform指定目标平台必须与目标机器一致。比如联网机器是Windows目标机器是Linux就需要加--platform manylinux2014_x86_64。--python-version指定目标Python版本比如--python-version 310就是Python 3.10。还有一种更省心的方法在联网机器上直接准备一个虚拟环境用pip freeze requirements.txt导出依赖清单再从另外一台通用环境里拉取这些包。但这个方法对平台不敏感的场景才可靠跨平台时还是要手动核实。2.4 离线系统源ISO镜像的用法系统源是很多Python包安装的前提。比如torch的预编译包依赖一些系统库libgomp、libpython等你从ISO镜像或离线软件源里安装这些库可以省掉大量编译工作。在CentOS/RHEL系列系统里最简单的方式是把系统ISO镜像挂载成本地源mount -o loop CentOS-7-x86_64-Everything.iso /mnt/cdrom然后写一个.repo文件指向本地路径比如[local-base] nameLocal ISO Base baseurlfile:///mnt/cdrom gpgcheck0 enabled1yum的仓库允许file://协议这样你不需要额外装HTTP服务就能用。Ubuntu/Debian则相对特殊一点离线安装除了ISO软件包可以用apt-rdepends提前计算依赖树。但整体上Ubuntu的离线依赖解析比RHEL系繁琐一些所以我更多时候会把Python相关依赖尽量在pip层解决减少对系统库的依赖。3. 实操全流程从系统层到Python层的完整搭建这一节是真正的“现场实录”我按完整流程走一遍整个环节大概需要半小时到一小时具体取决于机器性能和包的数量。3.1 第一步系统源准备与基础依赖安装我假设你已经拿到了系统ISO镜像第一步是挂载并配置本地源。这里以常见Linux发行版为例。CentOS/RHEL系mkdir -p /mnt/iso mount -o loop /path/to/CentOS-7-x86_64-Everything.iso /mnt/iso cat /etc/yum.repos.d/local.repo EOF [local] nameLocal Repo baseurlfile:///mnt/iso gpgcheck0 enabled1 EOF yum clean all yum makecache安装基础开发工具链这会让你后面少踩很多“缺编译器”的坑yum install -y gcc gcc-c make kernel-develUbuntu/Debian系可以用ISO镜像挂载mount -o loop /path/to/ubuntu.iso /mnt/iso apt-cdrom add apt update或者把离线deb包目录做成sourceecho deb [trustedyes] file:///opt/debs ./ /etc/apt/sources.list.d/local-offline.list apt update注意这里不要用gpgcheck0来完全禁用校验安全起见至少保留本地包哈希校验。实际离线环境里做不到联网验证GPG密钥时可接受降级但要在机房管理制度上说明。基础依赖装完检查Python是否存在python3 -V如果输出没有或者版本太低比如3.6那就需要把目标Python版本也放进离线物料里。3.2 第二步Python解释器离线安装如果目标机器已经有Python 3.8这部分可以跳过。如果没有我一般从Python官网下载源码包然后离线编译安装。这里有个操作细节编译前要装zlib-devel、openssl-devel、libffi-devel等依赖否则Python运行时会出现很多诡异问题比如ssl模块不可用、pip装不了包。以Python 3.10.11为例tar -xf Python-3.10.11.tgz cd Python-3.10.11 ./configure --prefix/usr/local/python3.10 make -j$(nproc) make install然后把/usr/local/python3.10/bin加到PATH里并建立软链ln -s /usr/local/python3.10/bin/python3.10 /usr/local/bin/python3 ln -s /usr/local/python3.10/bin/pip3.10 /usr/local/bin/pip3这里有个所有离线安装都会遇到的坑如果编译机器和目标机器的glibc版本不一致编译出来的Python解释器搬到低版本glibc机器上可能直接启动不了。所以如果目标机器是老旧系统比如CentOS 7glibc 2.17最稳妥的方式是直接下载官方针对该平台发布的Python二进制包而不是自己从源码编译再搬运。3.3 第三步CUDA Toolkit与cuDNN离线安装这部分操作顺序非常重要。先装驱动再装CUDA Toolkit最后装cuDNN这个顺序不能乱。驱动通常由系统厂商或显卡驱动包单独管理执行nvidia-smi能识别GPU即可。CUDA Toolkit离线安装我一般用runfile方式安装。这个安装包里有驱动、工具库、样例代码等离线安装时可以只选Toolkit部分避免覆盖已有驱动sh cuda_12.4.0_550.54.15_linux.run --toolkit --toolkitpath/usr/local/cuda-12.4 \ --silent --override如果不加--toolkitpath默认会装到/usr/local/cuda-12.4然后需要手动建立/usr/local/cuda软链ln -s /usr/local/cuda-12.4 /usr/local/cuda接着是cuDNN它本质上是给CUDA用的库文件包安装方式简单粗暴tar -xf cudnn-linux-x86_64-8.9.7_cuda12-archive.tar.xz cp cudnn*/lib/* /usr/local/cuda-12.4/lib64/ cp cudnn*/include/* /usr/local/cuda-12.4/include/注意cp库文件时一定要看清楚CUDA版本要不要匹配cuDNN是为特定CUDA版本构建的CUDA 11和CUDA 12对应的cuDNN包无法混用。装完记得执行ldconfig刷新动态库缓存。最后在/etc/profile或~/.bashrc里加入环境变量export PATH/usr/local/cuda/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda/lib64:$LD_LIBRARY_PATH如果前面驱动已经支持这个CUDA版本那么终端执行nvcc -V和nvidia-smi应该都能正常输出版本信息。如果nvcc能用但nvidia-smi报错基本说明驱动没装好此时要回头检查驱动层。3.4 第四步pip离线安装全部Python依赖现在到了最核心的一步用之前准备好的离线包目录安装所有Python依赖。我一般把离线包放在/opt/wheelhouse下这样mkdir -p /opt/wheelhouse cp -r /path/to/offline_deps/* /opt/wheelhouse/然后安装时直接用--no-index --find-links意思是不去PyTorch官网和PyPI索引查找只用指定目录pip install --no-index --find-links/opt/wheelhouse torch torchvision torchaudio如果还有一些包不在这个目录安装会直接报错提示找不到对应的包版本。那就说明离线包没有收集完整需要回到联网机器上补下载。为了降低这种返工我在联网机器上收集依赖时会跑一遍pip download torch torchvision torchaudio --dest ./wheelhouse然后检查./wheelhouse里的文件数量是否完整。另外安装完基础包后再补装其他依赖比如pip install --no-index --find-links/opt/wheelhouse numpy pandas matplotlib如果中间报错提示某些包被已有版本阻止那就要检查依赖树。这里我有一个习惯离线安装成功前绝不删除/opt/wheelhouse里的任何文件最多是新增因为删掉一个six都可能引发连锁问题。3.5 第五步环境验证装完不等于能用必须做最小化验证。我用三段验证逻辑先验证系统库和CUDAldconfig -p | grep cuda nvcc -V再验证Python包是否能被importpython3 -c import torch; print(torch.__version__)最后验证GPU是否可用python3 -c import torch; print(torch.cuda.is_available())这里有个很典型的现象torch.__version__正常输出但torch.cuda.is_available()返回False大概率是以下几个原因CUDA驱动程序版本太低无法配合PyTorch构建的CUDA版本动态库路径不对libcudart.so.12找不到cuDNN库版本与CUDA不匹配torch安装成了CPU版本而不是cuXXX版本。用torch.version.cuda可以进一步确认PyTorch内嵌的CUDA版本python3 -c import torch; print(torch.version.cuda)如果这个输出是12.1但你安装的CUDA Toolkit是12.4其实没问题只要你驱动支持12.4以上PyTorch要求的最小运行版本已经满足。但如果输出是cpu那你就是装错wheel包了需要重新找对应的CUDA版本包。3.6 验证后的收尾操作最后把环境持久化让以后登录不需要每次手动设置环境变量。同时建议写一个一键加载脚本放在/opt下方便团队其他成员使用#!/bin/bash export PATH/usr/local/cuda/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda/lib64:$LD_LIBRARY_PATH export PYTHONPATH/opt/wheelhouse:$PYTHONPATH export CUDA_HOME/usr/local/cuda放到/etc/profile.d/deeplearning.sh后执行source /etc/profile整个环境就常驻了。4. 常见问题与排查技巧实录离线环境装多了很多错误一眼就知道问题在哪。下面这些是我遇到频率最高的坑按问题现象整理成表直接对着查。错误现象根本原因解决办法ImportError: libGL.so.1: cannot open shared object file系统缺少OpenGL相关库离线源里安装libgl、mesa-libGL或libgl1GLIBC_2.29 not found目标机器glibc版本过低使用目标平台对应的Python二进制包不要跨系统搬运No module named numpy.distutilsnumpy版本过新某些旧包需要老numpy根据框架依赖要求固定numpy大版本ModuleNotFoundError: No module named torch._Ctorch安装时依赖损坏或CUDA运行库缺失检查LD_LIBRARY_PATH确认libcudart库存在CUDA error: no kernel image is available for execution on the deviceGPU算力版本与CUDA不匹配检查GPU算力换用支持该算力的CUDA/框架版本pip install时提示找不到满足要求的版本依赖收集不完整回到联网机器用pip download补齐缺的包error: command gcc failed目标机器缺编译工具链安装gcc、gcc-c、make及对应开发头文件其中libGL.so.1这个问题特别容易出现在装了opencv的机器上opencv-python这个包内部依赖libGL很多人前脚刚装完torch后脚import cv2就崩了最后才发现是装opencv时没有对应系统库。所以离线准备阶段libgl1 libglib2.0-0 libsm6 libxext6 libxrender1这些库最好一并纳入系统源里备好。还有一个高频问题不是报错而是环境变大变慢。比如你直接把一个联网机器的全套site-packages拷到离线机器却发现import某些包时速度慢了几十倍。原因多半是包里面带了大量.pyc缓存文件和调试信息用pip install走正规流程可以自动编译生成合适的字节码直接拷贝则不一定兼容Python版本运行时边加载边编译肯定慢。所以我不建议把Python环境直接用tar打包搬运除非用conda-pack或venv的--copies参数帮你处理好了。5. 进阶玩法两台以上机器时怎么复制环境如果你的离线环境不止一台机器前面的“下载一次、安装一遍”方法就略显笨拙。我实际用过几种扩展方案这里分享两种相对好用的。5.1 用Docker离线镜像做环境复制Docker镜像天然是分层的可以在联网机器上构建好一个带完整深度学习环境的镜像然后导出为tar包再到离线机器上导入。联网机器构建镜像docker build -t deeplearning-env:1.0 . docker save -o deeplearning-env.tar deeplearning-env:1.0把tar包拷贝到离线机器docker load -i deeplearning-env.tar docker run --gpus all -it deeplearning-env:1.0 /bin/bash这种方式的优点是完全复刻依赖包含系统库、CUDA、Python包几乎不会出现版本不一致问题。但要注意GPU直通需要容器运行时支持且NVIDIA驱动不能在容器里重复安装宿主机驱动仍然要提前装好。5.2 用conda-pack做整包迁移如果你用conda管理环境conda-pack是非常适合离线迁移的工具。它能把一个conda环境完整打包成一个压缩文件并在目标机器上原样解压。在联网机器上conda install conda-pack conda pack -n py311-torch -o py311-torch.tar.gz拷贝到离线机器后mkdir -p /opt/conda/envs/py311-torch tar -xzf py311-torch.tar.gz -C /opt/conda/envs/py311-torch conda activate py311-torch这个方案比手动pip收集依赖可靠得多因为它连C扩展的编译配置、动态库依赖都一并固化了。不过它要求目标机器和源机器的操作系统底层库匹配性足够好跨大版本系统迁移时还是可能遇到glibc的兼容问题。5.3 建立一个“离线基线包”定期维护机器多起来之后我建议把离线物料当成一个持续维护的基线包而不是每次部署都临时准备。具体做法是维护一个目录结构/opt/offline-baseline/ ├── system-packages/ # 离线系统源或deb/rpm包 ├── wheelhouse/ # pip依赖包目录 ├── cuda/ # CUDA Toolkit和cuDNN安装包 ├── python-installers/ # Python安装包 └── README.md # 版本清单和安装顺序说明每次有新项目上线只需要在联网环境更新wheelhouse里的新包然后同步到离线机器最后在离线机器上执行增量pip安装即可。这样既控制了版本又不会增加过多维护成本。我个人在实际操作中体会最深的一点是离线环境最怕的不是某个具体错误而是整个“版本组合”本身就不稳定。同样的CUDA 12.1配PyTorch 2.1和配PyTorch 2.2行为可能完全不同只是因为有相邻版本依赖的微小差异。所以如果你要部署一个长期使用的环境在开始离线路料准备前就把版本全部锁死不要想着“到了目标机器再说”。先把环境定版再做物料准备最后执行安装同时在安装过程中完整记录每一步的版本输出这个记录会在后续排查问题时帮上大忙。另外关于多台机器怎么高效同步如果你不想每台都重装一遍可以把做好的一台机器的系统盘做成母盘用克隆工具批量复制再修改主机名和网络配置。这比逐台离线部署快得多只是需要提前统一硬件型号和驱动版本。希望这篇实操笔记能帮你在内网环境下少走一些弯路。离线搭建本身不复杂复杂的是把所有细节提前想清楚版本组合定下来之后剩下的就是机械式安装了。