很多搞机器学习的开发者第一次接手生产环境服务器都会懵内网隔离、没外网、没法直接pip install连系统包管理器都访问不了镜像源但业务偏偏要求在这个 Linux 环境里离线安装机器学习环境跑训练和推理。这个需求我接过不止一次踩过的坑足够写一篇长文今天就把整套思路和实操流程梳理一遍。先说结论Linux 环境离线安装机器学习环境并不神秘本质上是把“安装”拆成“准备物料”和“执行安装”两步。凡是能在联网机器上提前下载好的东西都在联网机器上搞定离线机器只做安装、配置和验证。这篇文章适合刚接触离线部署的开发者、需要搭内网 AI 环境的运维同学也适合想把这套过程固化成脚本的算法工程师。我会从整体思路讲起再到 Python 基础环境、依赖库批量安装、GPU 版本的版本匹配最后是常见坑位和排查实录。1. 离线安装的整体思路离线不等于难装只是换一条路1.1 离线安装的本质是什么可以先想一个生活化的类比离线装软件就像家里没超市你不可能等着楼下外卖送到家门口只能先跑到有超市的地方把菜、调料、锅碗瓢盆一次性买齐再回家做饭。服务器也一样它没有外网唯一的“采购方式”是你在另一台能联网的机器上准备好所有安装包、依赖包、配置文件然后通过 U 盘、内网文件服务器或者安全管控通道拷贝过去。所以整个离线安装的核心就两点物料齐全不只是主程序本身还包括它依赖的所有底层库、系统库、动态链接库。顺序正确先装系统级依赖再装 Python再装第三方包再装 GPU 组件顺序错了就会出现“缺东墙补西墙”的连环问题。这两点看起来简单但实际执行时很多人都是被“顺序”和“依赖闭环”卡住的。比如 Python 装好了结果发现没有 openssl后续pip install连 https 的包索引都访问不了只能返工重编再比如机器学习包装好了一import numpy就报二进制不兼容就是因为在联网机器上下载包时没有锁定版本。1.2 三种主流离线安装方案怎么选针对 Linux 环境离线安装机器学习环境通常有下面三种做法各有利弊我实际用下来基本就围绕它们做组合方案操作方式优点缺点推荐场景源码编译安装下载 Python、各依赖库源码包离线机器上configure make install可定制性强能适配非标准环境耗时长需要完整的编译工具链且容易缺底层依赖系统较老、没有现成二进制包的环境二进制包 pip 离线源在联网机器用pip download收集 whl离线机器用--no-index --find-links安装速度快、版本可控、可批量操作依赖关系需要自己梳理平台标签容易踩坑绝大多数常规场景我最推荐容器镜像整体迁移联网机器上构建好整个机器学习镜像导出 tar 包离线机器docker load交付最简单环境完全一致需要离线机器有容器环境镜像体积大GPU 透传配置麻烦整个团队统一开发环境、交付部署镜像很多人一开始会迷信源码编译觉得“源码总不会缺东西”。实际上源码编译对离线环境才是最不友好的因为编译过程会不断探测系统里有没有某个开发库缺一个就报一个错报错信息还不直观。而二进制 wheel 包只要平台标签对上了装上就能用遇到依赖缺失也只是 pip 层面报错排查起来清楚得多。1.3 开工之前先列一份环境物料清单不管选哪条路我拿到一台离线机器后的第一件事不是下载任何包而是先采集环境信息。把下面几项记录清楚后面所有下载和安装都围绕这份清单来操作系统发行版和版本号用cat /etc/os-release查看区分是哪种发行版还是不能混用的比如基于某发行版体系包管理和依赖差异很大。CPU 架构用uname -m查看常见是x86_64也有些机器是aarch64很多包的安装包是分架构的下错了直接装不上。glibc 版本用ldd --version查看新版本机器学习框架对 glibc 版本有硬性要求老版本系统会直接报“versionGLIBC_2.27not found”。当前 Python 版本用python3 --version查看后续要么基于系统 Python 装包要么自己编译一个新的。GPU 型号和驱动版本用lspci | grep -i nvidia类似命令查看注意这里是通用陈述具体命令要看机器情况。这份清单就是整个离线安装的“菜谱”后面每一步的选择都要围绕它展开。比如你的系统是较老的发行版glibc 版本太旧那在选机器学习框架版本时就要刻意选老版本而不是下载一个最新版去碰运气。2. 从零开始离线准备一套可用的 Python 基础环境2.1 先补齐系统级依赖否则后面处处碰壁很多人在离线服务器上直接用系统自带的 Python 开始装包结果装到一半发现缺gcc、缺python3-devel、缺各种_ssl模块根本原因就是系统级依赖没有提前准备。系统级依赖的离线准备思路是这样的在联网机器上把需要的 rpm 或 deb 包连同依赖全部下载下来复制到离线机器用包管理器本地安装。以基于某发行版体系的环境为例可以用yumdownloader工具配合--resolve参数把依赖一并拉下来在某 deb 系发行版上用apt-get download逐个下载一个软件包再加apt-cache depends手动分析依赖关系。注意缺了gcc、make这类编译工具后续很多 Python 包只要编译安装就会失败缺了openssl-devel编译出的 Python 会没有_ssl模块pip 连包索引地址都访问不了缺了zlib-develpip 和 Python 包安装时会报压缩和解压相关错误。这三件套是离线安装 Python 环境的地基优先确认。2.2 编译安装一个干净、可控的 Python系统自带 Python 通常会被系统自身管理直接往里面装机器学习库容易和系统包冲突也不好隔离版本。我的习惯是在离线机器上编译一个专用的 Python安装到独立目录比如/usr/local/python3后面所有机器学习依赖都往这里装。编译安装的步骤如下在联网机器上下载 Python 源码包比如Python-3.9.18.tgz拷贝到离线机器。解压后进入源码目录执行配置命令./configure --prefix/usr/local/python3 --enable-shared --with-ssl编译安装make -j$(nproc) make install配置动态库路径因为--enable-shared编译出来的libpython3.9.so不在默认搜索路径里echo /usr/local/python3/lib /etc/ld.so.conf.d/python3.conf ldconfig这里重点解释几个参数的选择原因。--enable-shared是必须的很多机器学习库是 C/C 扩展它们在运行时需要动态链接libpython如果编译成静态链接后面import各种扩展模块时经常出现诡异崩溃。--with-ssl则是为了给 pip 提供 HTTPS 支持没有它 pip 基本就是残废状态。--prefix指定安装目录是为了不对系统 Python 造成干扰也方便后续整体打包迁移。2.3 搭建 pip 离线安装源wheelhouse 目录Python 编译好之后还没法直接装第三方包因为离线机器没有网络。这时候就要引入一个关键概念wheelhouse本质就是一个装满.whl文件的本地目录pip 通过--no-index --find-links参数把它当作唯一依赖来源。在联网机器上通常会先把固定版本的所有包下载到这个目录里。命令大概长这样mkdir wheelhouse pip download -r requirements.txt -d wheelhouse --no-cache-dir这里requirements.txt里写的是你需要的机器学习库以及严格锁定的版本号。下载完成后把整个wheelhouse目录拷贝到离线机器安装时就非常简单pip install --no-index --find-links/path/to/wheelhouse -r requirements.txt--no-index的意思是让 pip 彻底不要访问默认的包索引只从本地目录找--find-links则指定本地目录的位置。这两个参数组合起来就是 pip 离线安装的标准姿势。3. 机器学习依赖库的批量离线安装从手动到自动化3.1 为什么必须先把版本矩阵锁死机器学习库之间的依赖关系远比普通 Python 项目敏感。最典型的就是numpy它的 C 语言 ABI二进制应用接口会随着版本变化而scipy、scikit-learn、pandas等库在编译时又是基于某个特定版本的numpy做的运行时如果找不到一致版本就会报类型错误、段错误甚至直接进程崩溃。我见过最多的报错之一就是numpy.dtype size changed, may indicate binary incompatibility这个报错几乎都是因为numpy版本不一致导致的。所以在离线部署场景下版本锁定不是洁癖而是刚需。我一般会在requirements.txt里精确到小版本号例如numpy1.23.5 scipy1.9.3 pandas1.5.3 scikit-learn1.1.3 xgboost1.7.6如果是 GPU 版本再加上对应的深度学习框架比如某个带cu118标识的版本。这样做的目的是让所有包在联网机器上解析出的依赖关系与离线机器上完全一致避免“在联网机器上能装离线机器上装不上”的意外。3.2 联网机器上的下载细节pip download在不加任何参数时默认只下载当前执行环境的平台对应的 wheel 包。这个默认行为在“下载机器和离线机器环境相同”时没问题但两台机器架构或 Python 版本不同时就会出偏差。跨平台下载时需要显式指定平台信息比如在 x86_64 的机器上为另一台 aarch64 机器下载pip download -r requirements.txt -d wheelhouse \ --platform manylinux2014_aarch64 \ --python-version 39 \ --implementation cp \ --abi cp39 \ --only-binary:all:解释一下这几个参数的含义--platform是指定目标平台的兼容标签--python-version是指定目标 Python 版本--implementation和--abi是配合 Python 实现和 ABI 使用--only-binary:all:则是强制只下载编译好的二进制包不下载源码包。提示在联网机器上下载依赖时强烈建议加--no-cache-dir。因为 pip 缓存里可能混了旧版本或错误平台的包没有缓存时它才会老老实实从包索引服务器上重新拉取保证 wheelhouse 目录里的物料干净可靠。3.3 离线机器上的批量安装实战把wheelhouse目录整个拷贝到离线机器后安装流程如下把requirements.txt和wheelhouse放在同一个目录方便路径引用。执行安装命令/usr/local/python3/bin/pip install \ --no-index \ --find-links/data/wheelhouse \ -r /data/requirements.txt看到类似Successfully installed numpy-1.23.5 ...的输出后进行基础验证/usr/local/python3/bin/python -c \ import numpy, pandas, sklearn; print(numpy.__version__, pandas.__version__, sklearn.__version__)如果一切顺利能看到三个版本号输出说明基础机器学习环境已经可用。但这里有个容易忽略的点pip install在离线场景下对安装顺序是有要求的比如scipy需要先装好numpy。不过 pip 本身会解析依赖并自动处理只要 wheelhouse 里所有依赖包都齐全顺序不是问题如果某个包缺失pip 会报一个明确的错误指向具体缺哪个包按图索骥补下载即可。3.4 从包索引到依赖树的更深一层问题有经验的运维拿到 requirements 后会先画一遍依赖树而不是盲下载。比如scikit-learn依赖scipy和joblibxgboost依赖numpy和scipy这些依赖又可能分别依赖更底层的库。只写主包不写全依赖pip download会自动补全当前的依赖分支但这有时候会漏掉一些“非默认依赖”。举一个实际场景某个包在安装时提供了可选依赖比如pip install package[extra]这种方括号写法对应的额外依赖不会被默认下载。离线安装时要格外注意这个细节把package[extra]也写进 requirements或者在联网机器上先按完整安装方式跑一遍再用pip freeze把实际装好的版本固化下来。4. GPU 加速版本的离线安装与版本匹配4.1 三个组件的版本匹配逻辑如果离线机器上有 GPU 且需要跑深度学习训练那离线安装的复杂度还要再上一个台阶。这里要理清三个组件的角色驱动、计算平台、深度学习框架三者之间是严格的版本对应关系。可以这样理解驱动是硬件提供的能力入口计算平台是建立在驱动之上的编程接口和运行库深度学习框架则是调用计算平台 API 来做张量运算的应用程序。驱动负责识别硬件指令计算平台把这些指令封装成统一 API框架再到计算平台上来回搬运数据。任何一层版本不匹配最终都会在框架层报出一堆看不懂的库缺失错误。具体匹配要点有两条驱动版本必须大于等于计算平台要求的最低驱动版本否则框架初始化时直接检测不到计算设备。深度学习框架对应的计算平台标识要和机器上装的计算平台主版本一致比如某个深度学习框架包名带cu118标识就要求机器上有计算平台 11.8 的对应运行库。4.2 驱动的离线安装步骤驱动包通常体积很大需要在能联网的机器上从 GPU 厂商官网按型号和操作系统版本下载对应安装包。下载时注意选择与目标系统一致的发行版和架构否则装到一半会报内核头文件或系统版本不匹配。安装步骤大概如下卸载可能存在的旧驱动避免冲突。将新驱动包拷贝到离线机器解压后执行安装脚本或本地包安装命令。如果是脚本安装一般用静默模式加上--silent参数如果是包管理器安装用rpm -ivh或dpkg -i配合本地目录。安装完成后执行nvidia-smi命令确认驱动是否正常识别 GPU。注意安装驱动前如果系统里有开源的兼容驱动最好先禁用掉否则两者会抢占设备节点导致nvidia-smi能显示设备但程序无法申请显存。这一步在不同发行版上操作不同但思路都是通过内核引导参数或模块黑名单把开源驱动屏蔽。4.3 计算平台的离线安装和环境变量配置计算平台安装包同样通过离线安装脚本完成。安装时不要全选组件通常只需要运行时相关的核心组件就够深度学习库真正需要的是运行库和工具链不是全套 IDE 插件。安装完成后需要配置两个关键环境变量确认库文件路径写进系统搜索目录export CUDA_HOME/usr/local/cuda export LD_LIBRARY_PATH/usr/local/cuda/lib64:${LD_LIBRARY_PATH}但环境变量默认只在当前 shell 生效重启后就会丢。所以要把它们写进系统级配置例如echo export CUDA_HOME/usr/local/cuda /etc/profile.d/cuda.sh echo export LD_LIBRARY_PATH/usr/local/cuda/lib64:${LD_LIBRARY_PATH} /etc/profile.d/cuda.sh另外还需要把计算平台的库路径写进动态链接器配置echo /usr/local/cuda/lib64 /etc/ld.so.conf.d/cuda.conf ldconfigldconfig这一步很多人会忘掉导致深度学习框架启动时找不到计算平台的.so文件。它做的事是让系统知道去哪找动态库相当于给系统发了一张“库文件地图”。4.4 深度学习框架的离线 wheel 安装深度学习框架的离线安装和常规机器学习库一样也是通过 wheelhouse 目录。但关键点是下载时要选对 wheel 名字。比如在联网机器上下载某个深度学习框架时会发现它同时提供多个版本文件名里带有cu118、cu121之类的标识这些标识就对应不同的计算平台版本。下载命令示例pip download torch torchvision torchaudio \ -d wheelhouse \ --index-url 某个配置好的包索引地址 \ --extra-index-url 某个对应的扩展索引地址这里的--index-url和--extra-index-url是为了让 pip 同时从两个来源下载因为深度学习框架的主包和配套扩展往往不在同一个索引里。具体地址要看你用的是哪个包索引服务离线环境部署文档里通常都会写清楚。离线机器上的安装命令和前面一样pip install --no-index --find-links/data/wheelhouse torch torchvision torchaudio安装完成后用 Python 验证一下是不是识别到了 GPU 设备和计算能力python -c import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.device_count())这一行命令会分别输出框架版本号、计算设备能否被识别、以及设备数量。正常输出是版本号 True 1。4.5 版本不匹配问题速查我整理了一份离线 GPU 环境下最常见的版本不匹配情况方便直接对照排查现象可能原因排查方式框架初始化时提示找不到某个.so文件计算平台运行库没装或ldconfig没执行用ldd检查框架库依赖确认库文件存在且路径正确torch.cuda.is_available()返回False驱动版本太旧不满足框架对应的计算平台最低要求查看驱动版本与框架对应计算平台要求是否一致驱动能识别 GPU但显存申请失败有多个驱动版本混乱混装卸载重装驱动确保没有旧驱动残留编译原生扩展时报错找不到头文件只有运行时库没装开发组件重新安装计算平台补充开发库组件5. 离线安装常见坑与排查实录5.1 wheel 平台标签不匹配Python wheel 包的文件名里包含平台兼容标签比如numpy-1.23.5-cp39-cp39-manylinux2014_x86_64.whl。其中cp39表示 CPython 3.9manylinux2014表示 Linux 平台兼容标准x86_64表示架构。离线安装最常见的错误之一就是下载了错误的平台标签尤其当联网机器和离线机器架构不一致或者联网机器的 Python 版本和离线机器的 Python 版本不一致时。解决方法就是前面提到的下载时用--platform、--python-version、--implementation、--abi显式指定目标平台不要偷懒直接用默认值。5.2 glibc 版本过低导致的新框架装不上新版深度学习框架对系统运行库的要求越来越高。你在一台老发行版服务器上用ldd --version看到的 glibc 版本如果是 2.17 或 2.28 这类较低版本那很多新版框架根本起不来报错信息通常长这样/lib64/libm.so.6: version GLIBC_2.27 not found遇到这种问题有两条路可以走一是升级操作系统这在内网环境下往往不现实二是选择老版本的框架比如换个更稳定的、对系统版本要求更低的版本组合。这种时候提前记录离线机器 glibc 版本的价值就体现出来了选择依赖版本时可以直接过滤掉不满足条件的包。5.3 编译 Python 时缺了 ssl 和 zlib编译 Python 是最容易埋雷的阶段。configure 阶段看起来没问题结果 make 完了之后发现_ssl模块没有编译进去pip 无法工作。这个坑我见过太多次了。所以在编译之前一定要确认系统里面有openssl-devel、zlib-devel、libffi-devel这几个开发库。openssl管 pip 的 HTTPS 访问zlib管压缩解压libffi管 ctypes这三个缺一个后面都会变成疑难杂症。检查办法也很简单编译完 Python 后执行python -c import ssl, zlib, ctypes; print(ok)如果能输出ok这段地基才算打牢了。5.4 依赖包不全导致安装中断离线安装时pip 遇到缺依赖会直接报错并终止安装。比如装scikit-learn时提示No matching distribution found for scipy十有八九是因为联网机器上下载时scipy 因为某种原因没有被拉进 wheelhouse。这种问题的排查思路是先看错误的完整信息找到具体缺哪个包、哪个版本然后在联网机器上单独下载这个包重新拷贝到离线机器。如果你不确认一个包还依赖哪些子依赖可以用依赖树分析工具先打印完整的依赖关系再逐一下载。实操心得我在实际项目里已经把 “联网机器pip download- 离线机器pip install- 版本验证” 这套流程固化成脚本。结果证明离线部署不出问题的最好姿势是提前在联网容器里先完整安装一遍同一份 requirements确认无冲突再把 wheelhouse 打包。这样能提前暴露 90% 的版本兼容问题而不是把不确定性带到离线现场。5.5 一个典型的排查过程实录举个之前帮某开发者排查的例子A 同学的离线服务器是某发行版系老系统Python 3.8GPU 驱动正常nvidia-smi能看到设备但import torch时报错提示找不到某个动态库文件。排查步骤是这样的先用ldd检查深度学习框架原生库的依赖看哪个.so文件找不到。发现缺失的库其实在计算平台安装目录里存在但系统的动态链接器没有登记。执行ldconfig -p确认库里没有对应路径于是把该路径写进/etc/ld.so.conf.d/下的配置并重新执行ldconfig。再次import torch完美通过。这类问题本质上不属于“版本不匹配”而是“路径没登记”绝大多数人都能想到检查但第一次接触时很容易被报错信息带偏误以为是驱动或框架版本问题。排查这类离线环境问题时记住一条原则先查动态库路径再查版本匹配最后查依赖关系。6. 离线安装完成后的验证清单与实操习惯6.1 一套可复用的最终验证清单装完环境不是结束验证才是。我每次离线部署完成都会按下面这个清单走一遍缺一不可检查项命令预期结果Python 版本python --version输出预期版本号pip 可用python -m pip --version显示 pip 版本且无警告基础库导入python -c import numpy, pandas, sklearn无ImportError深度学习框架导入python -c import torch; print(torch.__version__)输出框架版本GPU 可用python -c import torch; print(torch.cuda.is_available())输出True环境变量持久化重新登录机器后执行echo $LD_LIBRARY_PATH能看到计算平台路径快速训练测试跑一个极小的线性回归或单步训练训练流程完整走通第 6 项看起来不起眼但很多人就是栽在这里装完环境后当前 shell 能跑重启或换一个登录终端后又不行了。配置文件里的环境变量没有写好等于白装了一半。6.2 我的几个实操习惯第一所有离线安装物料统一归档命名。我习惯把每个版本的依赖包放在以版本号命名的目录里比如ml-stack-py39-1.0/里面再分system/、python/、wheels/、gpu/子目录。这样无论过了多久谁拿到的都是一份自解释的物料包而不是一堆散落的 whl 文件。第二耗时操作优先在联网机器上模拟验证。既然联网机器能访问包索引为什么不先建一个和离线机器相同版本的 Python 环境把同一个 requirements 完整装一遍这一步能提前验证依赖关系和版本兼容性把问题拦在拷贝物料之前省掉离线机器上反复调试的无效时间。第三写环境说明文档。离线环境里能查的资料本来就少部署方和运维方交接时如果只有命令没有上下文后面排查问题会非常痛苦。我在文档里会写清楚系统版本、glibc 版本、Python 路径、wheelhouse 位置、GPU 版本矩阵、环境变量配置位置甚至包括当时踩过哪几个坑。这些东西在半年后回看价值比任何一键脚本都高。6.3 最后分享一个小技巧离线安装后如果遇到莫名其妙的运行库问题与其反复猜不如先看动态库依赖关系。比如某个扩展模块导入失败执行ldd /usr/local/python3/lib/python3.9/site-packages/某个扩展库.cpython-39-x86_64-linux-gnu.soldd会列出这个.so文件依赖的所有动态库以及它们的查找状态。缺哪个库、哪个库路径没找到、哪个库版本不匹配一眼就能看清楚。这个命令在在线环境里好像没什么存在感但在离线环境里它就是最趁手的诊断工具没有之一。离线部署这种事真的经历过一两次完整的流程后面就会觉得很简单。核心就三句话物料备齐、版本锁死、环境变量配好。做到这三条你基本不会再被离线安装机器学习环境这件事折磨。