LLaMA-Factory离线迁移与内网pip源搭建

脚本专家

问题背景：需要在联网电脑上为 LLaMA-Factory 创建虚拟环境并下载全部依赖，再把环境迁移到无法联网的离线电脑运行。如果还涉及 CentOS 7 与 Ubuntu 跨系统迁移，就要处理 glibc 兼容问题；如果离线机器要长期使用，还可以在内网搭建 pip 源，让后续安装不再依赖外网。

一、conda-pack 方案：同系统迁移优先

conda-pack 的核心流程是：联网机装好环境，用 conda-pack 打包，离线机解压后用 conda-unpack 修复路径。它适合两台机器操作系统类型一致、CPU 架构一致、Python 大版本一致的场景。若离线机要跑 GPU 训练，需要本地安装匹配的 NVIDIA 驱动，驱动不能随环境迁移。

联网机操作：

2. conda create -n llama-factory python=3.10 -y
3. conda activate llama-factory
4. git clone https://github.com/hiyouga/LlamaFactory.git
5. cd LlamaFactory
6. pip install -e .
7. python -c 'import torch; print(torch.__version__)'
8. llamafactory-cli version
9. conda activate base
10. conda install -c conda-forge conda-pack -y
11. conda pack -n llama-factory -o llama-factory.tar.gz

复制代码

离线机操作：

2. mkdir -p ~/miniconda3/envs/llama-factory
3. tar -xzf llama-factory.tar.gz -C ~/miniconda3/envs/llama-factory
4. conda activate llama-factory
5. conda-unpack
6. python -c 'import torch; print(torch.__version__)'
7. llamafactory-cli version

复制代码

其中 conda-unpack 是关键步骤，不能省略。它用于修复解压后环境里的路径信息，否则激活环境后可能仍然指向联网机路径。

二、pip 离线 wheel 包方案：跨系统推荐

如果两台机器系统或平台标签不完全一致，pip wheel 离线包更灵活。联网机先下载依赖：

2. cd LlamaFactory
3. mkdir wheels
4. pip download -r requirements.txt -d wheels
5. pip download -e . -d wheels
6. # 若 -e . 报错，改用：
7. pip download . -d wheels

复制代码

离线机创建环境后，从本地 wheels 目录安装：

2. conda create -n llama-factory python=3.10 -y
3. conda activate llama-factory
4. pip install --no-index --find-links=wheels -e .

复制代码

注意：下载 wheel 的联网机和离线机的操作系统、CPU 架构、Python 版本必须一致，否则平台标签不匹配会导致安装失败。

三、CentOS 7 与 Ubuntu 的 glibc 陷阱

CentOS 7 的 glibc 版本是 2.17，Ubuntu 22.04/24.04 分别是 2.35/2.39。glibc 只能向下兼容，不能向上兼容。也就是说，在 Ubuntu 上编译的二进制包拿到 CentOS 7 上运行，可能报 version 'GLIBC_2.xx' not found。

各方案兼容性可这样理解：
1. conda-pack：不可行。它打包了解释器和 .so，跨发行版时 glibc 不兼容。
2. pip wheel 离线包：看情况。纯 Python 包通常没问题；带 C 扩展的包需要平台标签小于等于目标机 glibc 能力。
3. conda YAML 导出重建：可行，但目标机需要联网重新下载构建，绕开二进制兼容问题。

如果离线机是 CentOS 7，也就是 glibc 2.17 这种最受限环境，联网机下载时强制指定 manylinux2014 标签：

2. pip download -r requirements.txt -d wheels --platform manylinux2014_x86_64 --python-version 310 --abi cp310 --only-binary=:all:

复制代码

manylinux2014 对应 glibc 2.17，可以通吃 CentOS 7 和所有更高版本的 Linux 发行版。如果离线机是 Ubuntu 且 glibc 大于等于 2.28，可以放宽到 manylinux_2_28。

更稳妥的离线安装方式是：联网机导出依赖清单，离线机用同一份 requirements.txt 从本地 wheel 目录安装。

2. pip freeze > requirements.txt
3. pip install --no-index --find-links=/path/to/wheels -r requirements.txt

复制代码

第一行在联网机执行，第二行在离线机执行。前提是离线机已装好 conda 或 Python，并准备好了对应 wheel 目录。

四、内网 pip 源方案怎么选

如果离线环境需要长期维护，每次拷 wheel 会很麻烦，可以在内网搭 pip 源。常见方案如下：
1. pypiserver：部署简单，适合简单离线分发；私有包上传需要 twine。
2. devpi：原生支持私有包上传，适合长期团队使用。
3. Nginx 反向代理：适合已有跳板机或静态文件分发场景，但不支持私有包上传。
4. Nexus Pro：原生支持 PyPI，适合已有 Pro 授权的环境。
5. Nexus OSS：开源免费版不支持 PyPI 仓库类型，只有 Pro 版支持。如果用的是 OSS 版，建议改用 devpi 或 pypiserver。

五、pypiserver 完整部署：离线机准备

2. pip install --no-index --find-links=/path/to/wheels pypiserver passlib
3. sudo useradd -r -s /sbin/nologin -d /data/packages pypi
4. sudo chown -R pypi:pypi /data/packages
5. sudo chmod -R 755 /data/packages

复制代码

生成 htpasswd 认证文件：

2. sudo htpasswd -c /etc/pypiserver/htpasswd pypiuser
3. python -c "from passlib.apache import HtpasswdFile; hf = HtpasswdFile('/etc/pypiserver/htpasswd', new=True); hf.set_password('pypiuser', '你的密码'); hf.save()"
4. sudo chown pypi:pypi /etc/pypiserver/htpasswd
5. sudo chmod 640 /etc/pypiserver/htpasswd

复制代码

如果没有 htpasswd 命令，可用上面的 Python passlib 方式生成。随后创建 systemd 服务文件 /etc/systemd/system/pypiserver.service：

2. [Unit]
3. Description=PyPI Server (Offline Package Repository)
4. After=network.target
6. [Service]
7. Type=simple
8. User=pypi
9. Group=pypi
10. ExecStart=/usr/local/bin/pypi-server run -p 8080 -P /etc/pypiserver/htpasswd -a /etc/pypiserver/htpasswd --verbose /data/packages
11. Restart=on-failure
12. RestartSec=5
13. NoNewPrivileges=true
14. ProtectSystem=strict
15. ProtectHome=true
16. ReadWritePaths=/data/packages
18. [Install]
19. WantedBy=multi-user.target

复制代码

如果不需要认证，只做纯内网隔离，可将 -P 和 -a 改为 -P . 和 -a .。

六、启动与客户端配置

2. sudo systemctl daemon-reload
3. sudo systemctl start pypiserver
4. sudo systemctl enable pypiserver
5. sudo systemctl status pypiserver
6. sudo journalctl -u pypiserver -f

复制代码

客户端无认证版配置：

2. pip config set global.index-url http://<server_ip>:8080/simple
3. pip config set global.trusted-host <server_ip>

复制代码

认证版配置：

2. pip config set global.index-url http://pypiuser:密码@<server_ip>:8080/simple
3. pip config set global.trusted-host <server_ip>

复制代码

验证方式：

2. pip install requests --dry-run

复制代码

防火墙放行：

2. # CentOS 7
3. sudo firewall-cmd --permanent --add-port=8080/tcp
4. sudo firewall-cmd --reload
5. # Ubuntu
6. sudo ufw allow 8080/tcp

复制代码

后续添加新包有两种方式。方式 A 直接拷文件，立即可用，无需重启：

2. cp new-package-1.0.0-cp310-manylinux2014_x86_64.whl /data/packages/

复制代码

方式 B 通过 twine 上传：

2. pip install twine
3. twine upload --repository-url http://<server_ip>:8080/ -u pypiuser -p 密码 dist/*.whl

复制代码

七、完整流程总结

联网机阶段：conda create 创建环境，pip install -e . 安装 LLaMA-Factory 依赖并验证；同系统迁移用 conda pack 生成 llama-factory.tar.gz；跨系统迁移用 pip download 下载 wheels，必要时指定 manylinux2014。

离线机阶段：如果走 conda-pack，就解压到 conda envs 目录，conda activate 后执行 conda-unpack，再验证 torch 和 llamafactory-cli；如果走 pip wheel，就创建环境后用 pip install --no-index --find-links=wheels -e . 安装。

长期维护阶段：部署 pypiserver，配置 systemd 自启，客户端设置 index-url 和 trusted-host，后续直接 pip install 即可。

一句话选择：同系统用 conda-pack 最省事；跨系统用 pip wheel 加 manylinux2014 标签保底；长期维护搭 pypiserver 做内网源，一次部署永久可用。

热心网友3

这篇总结挺到位的，把 conda-pack 和 pip wheel 两条路线的适用边界讲得很清楚。conda-unpack 确实不能偷懒，漏了之后环境路径会指回原机器，这个坑很典型。CentOS 7 的 glibc 2.17 和 manylinux2014 那段也很实用，跨发行版迁移时确实不能只看 Python 版本。NVIDIA 驱动不能随环境迁移这点也值得反复强调，离线 GPU 机器得先把驱动准备好。内网 pip 源部分，Nexus OSS 不支持 PyPI 的提醒很省事，能少走弯路。pypiserver 部署看起来还没写完，如果后面能把上传私有包和权限认证补全就更完整了。感谢分享。

热心网友6

整理得很清楚，conda-pack、pip wheel、glibc 兼容和内网 pip 源这几块基本覆盖了离线迁移的主要坑。特别是强调 conda-unpack 不能省、驱动不随环境迁移、CentOS 7 优先 manylinux2014，这些点很实用。想确认两个细节：一是如果离线机是 CentOS 7，用 pip download 指定 manylinux2014 时，像 torch 这种包有时还分 CUDA 版本，是不是还要根据离线机驱动能力提前选好对应 wheel？二是 pypiserver 那段末尾好像断在 python -c 这里，后面 htpasswd 和启动参数如果方便的话可以补全。整体思路对我帮助很大，感谢分享。

热心网友5

这套整理挺清晰的，同系统优先 conda-pack，跨系统走 pip wheel，再考虑内网源，基本把离线迁移常见的坑都串起来了。CentOS 7 的 glibc 2.17 确实是最容易卡住的地方，conda-pack 跨发行版基本别硬上，带 C 扩展的包用 manylinux2014 标签下载会稳很多。conda-unpack 那步也很关键，漏了之后环境路径还指着原机器，激活了也可能出问题。内网源选型说得挺实在，Nexus OSS 不支持 PyPI 的话就没必要折腾，pypiserver 和 devpi 更贴近实际需求。帖子最后 pypiserver 部分好像没贴完，如果能补上 htpasswd 后面的启动参数和客户端配置，就更方便照着做了。