做国产化环境项目交付的朋友应该都有同感机器一到手没外网。我前阵子接了一批ARM64的麒麟V10服务器CPU是鲲鹏920系统是Kylin Linux Advanced Server V10 SP3网络策略隔离得严严实实。PyTorch这种平时一条pip命令就能装的框架在这种环境下硬是折腾了两天问题出在“离线”和“架构”两个词叠在一起既要去理解aarch64平台标签还要准备一堆容易被漏掉的系统动态库。这篇文章是我把整个流程重新捋清楚之后的一份完整笔记覆盖环境检查、方案选型、资源准备、安装验证和排坑适合运维、算法工程师以及需要在国产化环境中交付AI项目的同学直接抄作业。文章里的所有命令我都按内网场景验证过版本号写的是当前比较稳定的组合你拿到麒麟V10 ARM64机器上可以照着走。1. 装之前先摸清环境和版本别急着找包很多人拿到一台机器就开始下载PyTorch安装包结果装到一半才发现架构不对、系统版本不支持。离线安装最怕的不是命令复杂而是基础信息没确认就开始动手。先把下面几件事搞清楚后面会省很多事。1.1 先跑一条命令确认CPU架构ARM64、aarch64、arm64、armv8这些词在软件包的世界里基本可以划等号但在不同平台上的显示方式不一样。最直接的办法是登录机器执行uname -m在麒麟V10 ARM64机器上输出通常是aarch64。如果输出是x86_64那这篇攻略的很多命令就不适用因为x86_64对应的是AMD64/Intel 64架构安装包完全不通用。经常有同事把这两个架构搞混。简单说x86_64是复杂指令集CISC的64位扩展而ARM64是精简指令集RISC的64位架构两者指令集不同二进制包无法互相运行。PyPI上的平台标签里ARM64一般写作aarch64conda的部分频道写作arm64但指的是同一个东西。建议把下面几条命令一次性跑完留个底uname -m cat /proc/cpuinfo | grep -i model name | head -1 nproc这样你既能确认架构又能看到CPU型号和核心数。核心数在设置线程数的时候会用到后面我会提到。1.2 麒麟V10的版本也决定安装方式麒麟V10不是一个单一版本它分为桌面版和服务器版服务器版又分SP1、SP2、SP3等多个补丁版本底层内核和系统库版本有差异。越新的SP版本自带的glibc和其他系统库越新对PyTorch这类预编译包的支持越好。查看系统版本信息cat /etc/os-release cat /etc/kylin-release uname -r为什么要关心这个因为PyTorch官方Linux wheel是采用manylinux规范的预编译包它要求系统的glibc版本不低于某个阈值。目前ARM64上常见的wheel标签是manylinux2014对应的glibc要求是2.17以上。麒麟V10服务器版自带的glibc通常都在2.28及以上所以能满足要求。但如果你手头是特别老的版本就要提前确认否则装完import时才会报错。还有一点要提醒如果你暂时没有真机想用QEMU模拟一个arm64环境来测试安装流程这个思路是可以的。我在早期验证的时候也这么干过能跑通基本安装流程。但模拟器的性能很差而且网络设备和驱动与真机有差异所以模拟环境跑通了不代表真机一定顺利最终必须以真机为准。1.3 Python环境检查用系统Python还是独立环境麒麟V10系统自带Python 3但版本通常偏旧而且系统包管理器对Python的依赖管理很脆弱不建议直接在系统Python里安装PyTorch。我的建议是要么用Miniconda创建独立环境要么用venv创建虚拟环境。先看看当前环境python3 -V pip3 -V如果Python版本在3.8到3.11之间用venv就够了如果版本过低建议先装Miniconda。Miniconda官方提供aarch64版本的安装脚本在有网的时候提前下载好拷到内网机器安装即可。这里有个安装思路上的选择如果你只需要PyTorch这一个框架用python3 -m venv就够了环境轻、好维护如果你后续还要装TensorFlow、scikit-learn、OpenCV等一堆库建议用conda管理依赖解决能力更强。2. 离线安装方案怎么选比较三条路离线安装PyTorch有三条主流路线pip wheel离线安装、conda-pack环境迁移、源码编译。三条路我都试过各有优劣适合的场景完全不同。2.1 三条路线的横向对比方案适用场景优点缺点pip wheel离线安装单机安装、轻量化交付依赖清晰、体积小、可选择性高需要手动处理系统级依赖conda-pack环境迁移已有一台同架构开发机一键激活、几乎免配置体积大、对glibc版本敏感源码编译非官方支持的特殊平台可针对性优化耗时长、依赖极多、不推荐源码编译这条路线除非你的芯片没有官方wheel可用否则千万别碰。PyTorch从源码编译需要下载大量依赖还要编译llvm、OpenBLAS这些底层库在ARM64机器上动辄几个小时起步而且要装cmake、ninja、gcc-c等一整套工具链基本告别“离线”二字。2.2 为什么我优先推荐pip wheel方案在ARM64加麒麟V10这个组合下我首选pip wheel离线安装理由有三点。第一PyTorch官方已经发布Linux aarch64的CPU预编译包基于OpenBLAS不需要额外安装MKL普通ARM服务器上直接能跑。这意味着我们不需要自己编译只需要把wheel文件下载好带进内网。第二pip的--no-index和--find-links参数已经非常成熟只要把wheel和依赖放到同一个目录离线安装的成功率几乎等于联网安装。第三pip wheel方案对系统污染小装错了直接删掉虚拟环境重来不会影响同一台机器上的其他应用。这一点在项目交付时很重要因为你不知道用户机器上已经跑了什么服务。2.3 什么场景下适合用conda-pack整包迁移如果你已经有一台和线上同架构的开发机并且把PyTorch以及torchvision、torchaudio等依赖都用conda装好了那么conda-pack是效率最高的方案。它能把整个conda环境打包成一个tar.gz文件拷到内网机器上解压后直接激活不用在目标机器上安装conda。但要注意conda-pack对环境的要求比pip wheel更严格。打包机的glibc版本不能高于目标机否则解压后的Python解释器可能无法正常启动。在实际项目中麒麟V10的SP版本之间迁移问题不大但如果目标机是老SP版本、打包机是新版本就可能踩坑。另外conda环境体积通常有3到5GB传输成本高适合一次打包多台机器复用的场景。3. 完整实操从准备离线包到验证运行下面进入正题我把整个离线安装过程拆成四步下载离线包、准备系统依赖、内网安装、验证运行。每一步都可复现命令直接复制就能用。3.1 在有网机器上正确下载ARM64离线包有外网的机器可以是x86架构的普通Linux甚至是Windows电脑因为我们用pip download指定平台参数不依赖当前机器的架构。假设我们要安装PyTorch 2.1.0Python版本用3.9命令如下mkdir -p /tmp/pytorch_offline pip download torch2.1.0 \ --only-binary:all: \ --platform manylinux2014_aarch64 \ --python-version 3.9 \ --dest /tmp/pytorch_offline这里每项参数都有讲究。--only-binary:all:表示只下载预编译的wheel不下载源码包--platform manylinux2014_aarch64锁定ARM64平台--python-version 3.9锁定Python版本。pip会根据这些条件自动解析torch的依赖numpy、typing-extensions、filelock等一并下载到目标目录。如果你还需要torchvision和torchaudio直接追加包名pip download torch2.1.0 torchvision0.16.0 torchaudio2.1.0 \ --only-binary:all: \ --platform manylinux2014_aarch64 \ --python-version 3.9 \ --dest /tmp/pytorch_offline注意torchvision和torchaudio的版本必须与torch严格对应否则import时会报undefined symbol之类的错误。下表是官方推荐的对应关系下载前确认一下torch版本torchvision版本torchaudio版本2.1.00.16.02.1.02.0.10.15.22.0.21.13.10.14.10.13.1在下载时如果pip解析依赖失败可能是因为某个依赖包无法匹配aarch64平台。解决办法是分两次操作先只下载torch本身然后用同样的命令逐个下载依赖包。依赖包常见的就那几个numpy、typing-extensions、filelock、sympy、networkx、jinja2、fsspec、setuptools。3.2 别忘了系统级依赖libgomp、libatomicPython层面的依赖由pip解决但PyTorch的wheel还会链接一些系统动态库最常见的是libgomp.so.1OpenMP运行时和libatomic.so.1原子操作库。麒麟V10如果是最小化安装这些库可能没有。在目标机上可以通过ldd检查缺失情况ldd /你的虚拟环境路径/lib/python3.9/site-packages/torch/lib/libtorch_cpu.so 2/dev/null | grep not found建议在准备阶段就直接下载好rpm包免得到时候再折腾。在有网的麒麟机器上执行mkdir -p /tmp/rpms yumdownloader --resolve --archlistaarch64 libgomp libatomic如果没有yumdownloader先用yum install -y yum-utils安装。下载完把rpm文件拷到内网执行rpm -ivh /tmp/rpms/*.rpm如果是conda环境也可以在有网的时候通过conda install -c conda-forge libgomp提前装好这样环境包里自带libgomp就不需要动系统库了。3.3 内网机器上的安装命令与验证把pytorch_offline目录和rpm包拷贝到内网机器例如放到/tmp/pytorch_offline然后开始安装。第一步创建虚拟环境假设系统Python版本满足要求python3 -m venv /opt/pytorch-env source /opt/pytorch-env/bin/activate如果执行python3 -m venv时报错缺少ensurepip可以安装python3-virtualenv后改用virtualenv或者直接用Miniconda创建环境。第二步离线安装pip install --no-index --find-links/tmp/pytorch_offline torch加--no-index是为了不访问PyPI--find-links指定本地wheel目录。pip会自动从这个目录里解析torch和所有依赖不需要网络。如果目录里有多个版本的torch指定版本号更稳妥pip install --no-index --find-links/tmp/pytorch_offline torch2.1.0第三步验证安装结果python -c import torch; x torch.rand(3, 3); print(x); print(PyTorch版本:, torch.__version__)能打印出版本号说明安装成功。如果要确认底层BLAS库可以执行python -c import torch; print(torch.__config__.show())正常会看到BLAS信息为OpenBLAS这是PyTorch在ARM64平台上的默认配置。3.4 conda-pack方式的完整流程conda-pack方案适合已经有同架构开发机的场景。在有网的机器上操作conda create -n kylin-torch python3.9 conda activate kylin-torch conda install pytorch2.1.0 torchvision0.16.0 torchaudio2.1.0 -c pytorch conda install -c conda-forge conda-pack conda pack -n kylin-torch -o kylin-torch.tar.gz打包出来的kylin-torch.tar.gz可能有好几个GB。拷到内网机器后mkdir -p /opt/kylin-torch tar -xzf kylin-torch.tar.gz -C /opt/kylin-torch source /opt/kylin-torch/bin/activate python -c import torch; print(torch.__version__)这里有个细节conda-pack打出来的环境不需要目标机器安装conda解压后直接用脚本激活就行。但激活脚本对bash兼容性有要求麒麟V10默认的bash没问题。如果目标想要更干净的隔离这个方案比pip wheel省心因为所有依赖已经在包里了。4. 离线安装常见报错与排查技巧离线安装PyTorch真正让人头疼的是报错。我把项目里遇到的几个典型问题整理出来基本都是高频问题每个都附了排查思路和解决办法。4.1 “is not a supported wheel on this platform”多半是平台标签不对安装时如果出现类似下面的报错ERROR: torch-2.1.0-cp39-cp39-manylinux_2_17_x86_64.whl is not a supported wheel on this platform.原因很明显wheel文件是x86_64架构的而目标机器是aarch64。这种情况通常是在有网机器上下载时没有指定--platform manylinux2014_aarch64默认下载了当前机器的架构版本。解决办法是重新执行下载命令严格带上平台参数。如果已经下载了一堆错误文件直接删掉重来不要在错误文件的基础上强制安装否则依赖关系也会错乱。另一个强制安装的临时办法是pip install --no-index --force-reinstall --no-deps /path/to/torch-xxx.whl这种方法只适合应急验证不建议作为常规手段因为你跳过了依赖检查很可能装完import时报别的错。4.2 import torch报GLIBCXX_3.4.29 not found这个报错是离线安装里最隐蔽的一个。ImportError: /lib/aarch64-linux-gnu/libstdc.so.6: version GLIBCXX_3.4.29 not found原因很简单PyTorch的wheel编译时用了较新的GLIBCXX符号而目标机器系统自带的libstdc.so.6版本太旧。用下面的命令查看系统支持的GLIBCXX版本strings /usr/lib64/libstdc.so.6 | grep GLIBCXX如果列表里没有GLIBCXX_3.4.29就需要升级libstdc或用conda环境自带的库。我的建议是安装libstdc-devel开发包版本合适时可以直接补齐如果系统源里没有就要在有网时下载对应的rpm包。如果你用的是conda环境问题通常更好解决因为conda环境自带一套较新的libstdc.so.6导入torch时优先使用的就是环境里的库。这也是我推荐用conda的重要原因之一。4.3 缺少libgomp.so.1、libatomic.so.1怎么处理报错通常长这样ImportError: libgomp.so.1: cannot open shared object file: No such file or directory这是系统级动态库缺失pip管不了。解决办法就是下载rpm安装具体命令在前面第3.2节已经写过。这里补充一个排查技巧ldd /opt/pytorch-env/lib/python3.9/site-packages/torch/lib/libtorch_cpu.so | grep not found这个命令能一次性列出所有缺失的动态库不用等程序运行时报错才知道缺什么。把这个命令作为安装后的常规检查项能提前发现大部分隐患。4.4 安装后CPU利用率只有单核模型推理特别慢大模型在CPU上推理慢是正常的但如果比同类机器明显慢一个数量级就要检查线程配置和BLAS库了。先看BLASpython -c import torch; print(torch.__config__.show())确认是OpenBLAS而不是Reference或Generic之类。然后在程序入口处手动设置线程数import torch torch.set_num_threads(8) # 根据你的核心数调整或者在启动前设置环境变量export OMP_NUM_THREADS8这里要解释一下为什么需要手动设置。在部分虚拟化环境和容器环境里PyTorch检测到的CPU拓扑不准确默认线程数可能只有1导致跑矩阵运算时只用一个核。手动设置能绕过这个问题性能差距非常明显。4.5 torchvision/torchaudio版本错配这个比较容易排查。ImportError: /usr/lib/python3.9/site-packages/torchvision/_C.so: undefined symbol: _ZN2at7Tensor...出现这种问题基本都是torchvision和torch版本不对应。torch 2.1.0必须配torchvision 0.16.0torch 2.0.1必须配torchvision 0.15.2不能乱配。下载离线包的时候三个包必须同一批次、同一版本系列。这里我还想再强调一次千万别搞“最新版”思想在离线项目交付里稳定比版本新重要得多。5. 离线资源管理经验下载、校验、复用最后这部分聊点项目管理层面的经验。给客户交付或者公司内部多台机器部署时离线包不是下载一次就完了要当成一种交付物来管理。我见过太多因为离线包版本混乱导致的问题这里分享一些我自己定的规矩。5.1 资源渠道与wheel文件名识别ARM64上PyTorch的wheel来自PyTorch官方可以通过PyPI或国内镜像站下载。在有网机器上将镜像配置到pip源后下载速度会快很多。文件名是判断离线包是否正确的第一道关卡下面拆解一个典型的官方wheel文件名torch-2.1.0-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl逐段看torch-2.1.0包名和版本号。cp39表示CPython 3.9必须与目标机器的Python主版本一致。manylinux_2_17_aarch64.manylinux2014_aarch64兼容glibc 2.17以上、支持aarch64架构。如果你下载的文件名里没有aarch64或者Python版本号对不上就不要继续装了直接回炉重下。5.2 哈希校验不能省离线文件拷贝过程中U盘、移动硬盘或者内网传输都有可能让文件损坏。大文件尤其容易出现这种问题。我现在的习惯是在下载完成后立刻用sha256sum生成校验值拷贝到内网后再核对# 在有网机器上 sha256sum /tmp/pytorch_offline/*.whl /tmp/pytorch_offline/checksums.txt # 在内网机器上 cd /tmp/pytorch_offline sha256sum -c checksums.txt看到每个文件都显示OK再进行安装。这一步能省掉很多莫名其妙的报错。别看它简单踩过文件损坏的坑之后才会明白它的价值。5.3 固化版本清单批量部署事半功倍如果你的项目不止一台机器建议每次部署都在内网的一台样板机上完整跑通一次然后把以下信息记录下来目标机器系统版本和内核版本cat /etc/kylin-release、uname -rPython版本和虚拟环境工具PyTorch、torchvision、torchaudio的版本号和wheel完整文件名系统级依赖rpm包的名称和版本完整安装命令列表我当时是直接在root目录下建了一个文档项目交付时直接照着文档操作一台机器大约十五分钟就能装完并验证通过。比临时查资料、反复试错效率高得多。另外如果条件允许可以把整套环境做成容器镜像在内网部署时直接加载镜像连系统依赖都不用管。这是最省心的交付方式不过前提是你的内网环境支持运行容器。最后再分享一个经验离线安装PyTorch这种框架最大的敌人不是网络而是信息差。对平台标签的理解、对依赖关系的管理、对系统库的认知每一项都比“下载哪个包”更重要。我第一次在麒麟V10 ARM64上装PyTorch时就是因为不知道GLIBCXX的坑白折腾了一整天。后来学乖了每次动手前先在样板机上把环境跑一遍确认没有隐患再批量部署。希望这篇文章能让你少走这些弯路一次就装成功。