内网环境下搭建大模型微调平台实战指南

Python 虚拟环境隔离

进入 Docker 容器后，不建议直接使用系统 Python，应使用 Python 自带的 venv 模块创建虚拟环境，以隔离项目依赖，防止覆盖系统包或与其他项目冲突。

初始化虚拟环境：

python3 -m venv apienv

激活环境：

source apienv/bin/activate

验证环境：

which python
python --version

离线依赖包管理策略

在内网环境下，无法直接使用 pip install xxx 在线安装。必须采用离线包管理方案。主要有两种策略：

1. 先下载后安装：使用 pip download 下载所有依赖，再使用 --no-index --find-links 进行本地安装。
2. 指定路径安装：使用 --target 参数直接将包安装到指定目录。

推荐操作流程：

1. 在联网虚拟机上生成依赖列表： 首先确定项目所需的依赖版本，避免版本冲突。

   pip freeze > requirements.txt
   

2. 下载所有依赖包： 创建一个临时虚拟环境，指定国内镜像源下载所需包及 requirements.txt 中的所有依赖。

   # 下载特定包
   pip install pandas -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
   
   # 下载 requirements 依赖并指定目录
   pip download -r requirements.txt -d /home/sitepackage/ --index-url http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
   
   # 下载特定版本包（如 gradio）
   pip3 download -d /home/sitepackage/ gradio==4.21.0 -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
   
   # 注意：torch 和 torchvision 可能需要单独下载 wheel 包，因为 CUDA 版本需匹配
   pip download torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 -d /home/sitepackage/
   

3. 拷贝至内网服务器： 将下载的 /home/sitepackage/ 目录完整拷贝至内网服务器的对应路径。

4. 内网离线安装： 在内网虚拟环境中执行安装命令。

   # 离线安装依赖
   pip install --no-index --find-links=/home/sitepackage/ -r requirements.txt
   
   # 安装 Llama-Factory 源码（解决 llamafactory-cli 不存在问题）
   pip install -e . --no-build-isolation --no-index --find-links=/home/sitepackage/
   

LLaMA-Factory 常见问题处理

1. llamafactory-cli 命令不存在

新版 Llama-Factory 将命令行入口改为 llamafactory-cli。在离线环境下，直接运行源码安装可能因缺少构建依赖而报错。 解决方案：确保已下载所有构建依赖包，并在源码目录下执行：

pip install -e . --no-build-isolation --no-index --find-links=/home/sitepackage/

若仍报错，请检查是否拉取了最新版本的源码，部分旧版本存在已知 Issue。

2. Docker 共享内存不足

报错信息通常涉及 nccl 或 distributed training 失败，提示 CUDA error: device-side assert triggered 或 shm size 相关错误。 原因：Docker 默认共享内存为 64MB，多卡训练需要更多空间。 解决方案：在 docker-compose.yml 中显式设置 shm_size：

shm_size: 16GB

或者指定单卡训练以减少资源需求：

CUDA_VISIBLE_DEVICES=0 llamafactory-cli train xxx

3. Transformers 版本不兼容

报错示例：ValueError: too many values to unpack (expected 2) 原因：Llama-Factory 对 transformers 库的版本有严格要求，不同版本 API 变动较大。 解决方案：强制安装指定版本（如 4.41.2）。

pip install transformers==4.41.2 --no-index --find-links=/home/sitepackage/

4. Torch 版本不匹配

原因：CPU 版与 GPU 版 Torch 混用会导致 CUDA 错误。 解决方案：根据服务器 CUDA 版本选择对应的 Torch Wheel 包进行离线安装。

# 示例：CUDA 11.8
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

数据准备与格式规范

微调前需准备好指令微调数据，推荐使用 JSONL 格式。 数据示例：

{"instruction": "请解释什么是人工智能", "input": "", "output": "人工智能是..."}

确保数据集中无特殊字符干扰，且 instruction、input、output 字段齐全。

验证与总结

完成上述步骤后，可通过以下命令验证环境是否就绪：

llamafactory-cli export --help

若显示帮助信息则说明安装成功。

总结： Llama-Factory 新版功能强大，但在内网环境下搭建确实面临依赖管理的挑战。主要难点在于离线包的完整性校验、Docker 共享内存配置、Torch 版本匹配以及 CLI 命令的生成。按照上述流程走一遍，可以有效规避常见坑点，顺利完成微调环境搭建。对于后续的微调任务，建议优先确认显存分配与数据格式兼容性，并根据实际硬件情况调整 batch size 和 gradient accumulation steps。