LLaMA-Factory本地部署与离线安装指南
LLaMA-Factory本地部署与离线安装实战指南
在大模型技术飞速发展的今天，越来越多企业和开发者希望基于主流预训练模型构建专属的垂直领域AI能力。然而，从环境配置到微调训练，整个流程往往伴随着复杂的依赖管理和网络限制问题——尤其是在内网部署、数据安全要求严格的生产环境中。
LLaMA-Factory 正是为解决这一痛点而生。它不仅集成了全参数微调、LoRA、QLoRA 等多种高效微调方法，还提供了直观的 WebUI 操作界面，真正实现了“开箱即用”。更关键的是，其对多后端推理引擎（如 vLLM）、量化格式（GPTQ/AWQ/HQQ）和优化技术（FlashAttention-2、Unsloth）的全面支持，让资源受限场景下的高性能训练成为可能。
但如果你所在的服务器无法访问公网？如何确保在防火墙之后依然能顺利搭建这套系统？本文将带你一步步完成 本地化部署 与 完全离线安装 的全过程，尤其适用于金融、政务、制造等对网络隔离有严格要求的行业环境。
我们先从最简单的在线安装说起，再深入剖析无网环境下的完整迁移方案。你会发现，只要掌握核心思路，即使是跨机器的复杂部署，也能变得清晰可控。
若目标机器具备外网连接能力，推荐采用标准在线方式快速启动。整个过程分为四个步骤：克隆代码、创建虚拟环境、安装依赖、启动服务。
首先执行项目拉取：
git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory --depth 1 参数可以显著减少下载体积和时间，特别适合仅需最新版本的场景。
接下来建议使用 Conda 创建独立 Python 环境以避免依赖冲突：
conda create -n llamafactory python=3.11 -y conda activate llamafactory Python 3.10+ 是必须的，因为部分底层库（如 transformers 和 peft）已不再兼容旧版本。
然后安装主包及其扩展组件：
pip install -e ".[torch,metrics]" 这里的 -e 表示可编辑模式安装，便于后续调试源码；[torch,metrics] 则包含了 PyTorch 基础运行时以及评估指标所需库（如 evaluate, nltk）。
根据实际需求，你还可以追加更多功能模块。例如：
| 组件 | 功能说明 |
|---|---|
deepspeed | 支持 ZeRO 分布式优化策略，适用于大规模模型或多卡训练 |
bitsandbytes | 实现 4-bit/8-bit 量化训练（NF4/FP4），大幅降低显存占用 |
gptq, awq, hqq, eetq | 兼容不同厂商或社区推出的量化模型加载 |
vllm | 集成 PagedAttention 技术的高速推理后端，提升吞吐量 |
galore, badam | 新型优化器支持，适合长序列或低秩更新场景 |
qwen, modelscope | 加载通义千问系列模型所需的阿里云工具链 |
一个典型的完整安装命令如下：
pip install -e ".[torch,metrics,bitsandbytes,vllm,gptq]" 等待所有依赖安装完成后，即可通过以下命令启动图形化界面：
python webui.py 默认服务监听在 http://localhost:7860。如果需要远程访问，应绑定开放地址并指定端口：
python webui.py --host 0.0.0.0 --port 8080 此时打开浏览器输入对应 IP 和端口，就能看到熟悉的 LLaMA-Factory 页面，开始进行数据集上传、模型选择和训练配置了。
然而，在真实的企业环境中，事情往往没这么简单。许多计算节点处于物理隔离或逻辑隔离的内网中，既不能访问 GitHub，也无法连接 PyPI 镜像站。这时候就需要一套可靠的 离线部署流程。
我们的策略是：借助一台可联网的“中转机”预先构建好完整运行环境，打包后迁移到目标机器上解压复用。这种方法本质上是将“安装行为”转化为“文件传输”，绕过了网络限制。
整个流程包括五个阶段：
1. 在中转机准备代码和依赖
2. 缓存所有 pip 包并安装
3. 使用 conda-pack 打包 Python 环境
4. 将环境与项目文件一并传输至目标机
5. 解压、激活、验证并启动服务
前提条件如下：
- 一台可上网的 Linux x86_64 中转机（Ubuntu/CentOS 均可）
- 一台架构相同的离线目标机
- 已手动下载 LLaMA-Factory 主分支压缩包
- 目标机已安装基础工具：tar, unzip, conda 或 miniconda
首先在中转机创建专用环境：
conda create -n llamafactory python=3.11 -y conda activate llamafactory 接着安装用于环境打包的工具：
conda install -c conda-forge conda-pack -y 然后解压项目代码：
unzip LLaMA-Factory-main.zip -d LLaMA-Factory cd LLaMA-Factory 最关键的一步是提前缓存所有 Python 依赖包。由于目标机无网，我们必须在中转机上把所有 pip 安装项下载到本地目录，供后续离线安装使用：
mkdir -p ~/llamafactory-offline-pkgs pip download ".[torch,metrics,bitsandbytes,vllm]" \ -d ~/llamafactory-offline-pkgs \ -i https://pypi.tuna.tsinghua.edu.cn/simple \ --find-links ~/llamafactory-offline-pkgs \ --no-index --prefer-binary 这里使用清华 TUNA 镜像源提高下载成功率，并通过 --no-index 强制只从本地查找，防止意外联网尝试。
下载完成后，正常执行一次安装操作，确保中转机环境可用（这也有助于检测缺失项）：
pip install ".[torch,metrics,bitsandbytes,vllm]" \ -i https://pypi.tuna.tsinghua.edu.cn/simple 如有需要，还可额外安装推理服务支持库：
pip install "xinference[transformers,vllm]" -i https://pypi.tuna.tsinghua.edu.cn/simple 现在进入打包阶段。退出项目目录，使用 conda pack 将整个环境压缩成单个 .tar.gz 文件：
cd ~ mkdir -p /opt/llamafactory/env conda pack -n llamafactory -o /opt/llamafactory/env/llamafactory.tar.gz 这个压缩包包含了 Python 解释器、已安装的所有第三方库（含 CUDA 相关动态链接库 .so 文件）、环境变量脚本等，几乎相当于一个“便携式运行时”。
为了方便管理，我们可以进一步将环境包和 pip 缓存合并归档：
cd /opt/llamafactory tar -czf offline-deps.tar.gz env/llamafactory.tar.gz ../llamafactory-offline-pkgs/ 最终得到的 offline-deps.tar.gz 即为可用于离线部署的完整资源包，可通过 SCP、U盘、内网传输等方式送入目标机器。
在目标机上，首先解压该文件：
cd /opt/llamafactory tar -xzf offline-deps.tar.gz 然后解压 Conda 环境：
cd env mkdir llamafactory tar -xzf llamafactory.tar.gz -C llamafactory 注意不要直接解压到根目录，否则会污染当前 shell 环境。
接下来激活环境：
source /opt/llamafactory/env/llamafactory/bin/activate 激活成功后，可通过以下命令验证：
which python pip list | grep torch 预期应返回正确的路径和已安装的包列表。
为进一步确认环境完整性，建议编写一个简单的测试脚本 test_env.py：
import torch import sys print("✅ Python Version:", sys.version) print("✅ Torch Version:", torch.__version__) print("✅ CUDA Available:", torch.cuda.is_available()) if torch.cuda.is_available(): print("✅ GPU Device:", torch.cuda.get_device_name(0)) print("✅ Current Device ID:", torch.cuda.current_device()) else: print("⚠️ CUDA not available. Running on CPU.") try: import transformers print("✅ transformers imported") except ImportError as e: print("❌ Failed to import transformers:", e) try: import peft print("✅ PEFT (LoRA support) imported") except ImportError as e: print("❌ Failed to import peft:", e) try: from vllm import LLM print("✅ vLLM imported (if installed)") except ImportError: pass 运行：
python test_env.py 理想输出应显示 Python 版本正确、PyTorch 可用、CUDA 正常识别 GPU（如有），且关键库均可导入。
一旦验证通过，就可以进入项目目录并启动 WebUI：
cd /opt/llamafactory/LLaMA-Factory source /opt/llamafactory/env/llamafactory/bin/activate python webui.py --host 0.0.0.0 --port 7860 访问 http://<server-ip>:7860，你应该能看到完整的图形界面，可以自由选择模型、上传数据集、设置 LoRA 参数并提交训练任务。
在实际部署过程中，可能会遇到一些典型问题，以下是常见情况及应对建议。
❌ 模块找不到：ModuleNotFoundError: No module named 'xxx'
这类错误通常源于两个原因：一是环境未正确激活，二是某些原生扩展（如 .so 文件）在打包时被遗漏。
解决方案：
- 每次使用前务必执行 source <path>/bin/activate
- 若仍报错，回到中转机重新安装该模块后再打包
- 对于 NCCL、cuDNN 等硬件级依赖，建议目标机安装匹配版本的 NVIDIA 驱动和 CUDA Toolkit
⚠️ 显存映射警告：UserWarning: nvidia_gpu_memory_maps is not enabled
此提示意味着 GPU 显存映射未开启，可能影响多卡通信效率，特别是在使用 DeepSpeed 时。
建议启用持久模式并设置功率上限：
sudo nvidia-smi -pm 1 # 启用持久模式 sudo nvidia-smi -i 0 -pl 300 # 设置 GPU0 功率上限为 300W（按显卡型号调整） 这不仅能改善性能，还能加快设备初始化速度。
💡 如何更新离线环境？
当需要升级框架版本或添加新依赖时，无需从头再来。只需在中转机上：
1. 拉取新版代码或更新 requirements.txt
2. 使用 pip download 获取新增包
3. 重新执行 conda pack
4. 替换目标机原有环境包并解压
需要注意的是，不建议跨 Python 大版本或 CUDA 架构迁移环境。例如，Python 3.10 打包的环境不应在 3.12 上解压使用，否则可能导致 ABI 不兼容问题。
最后分享几点来自工程实践的最佳建议，帮助你在不同场景下更高效地利用 LLaMA-Factory。
| 应用场景 | 推荐做法 |
|---|---|
| 多用户共享平台 | 使用 Docker 容器封装环境，结合 Nginx 实现反向代理与多实例负载均衡 |
| 大规模分布式训练 | 配合 DeepSpeed + SSH 免密登录，启用 ZeRO-3 分片策略以支持百亿级以上模型 |
| 生产环境长期运行 | 集成 MLflow 记录实验日志，定期将 checkpoints 备份至对象存储（如 MinIO/S3） |
| 多项目并行开发 | 为每个项目创建独立虚拟环境或容器，避免依赖版本冲突 |
此外，对于安全性要求较高的单位，建议在容器或虚拟机中运行微调任务，实现资源与权限的双重隔离。
LLaMA-Factory 的价值不仅在于其强大的功能整合，更体现在它对“易用性”的极致追求。无论是个人开发者想快速验证 SFT 效果，还是企业团队要在内网构建私有化 AI 平台，这套工具都能显著缩短从想法到落地的时间周期。
更重要的是，它的离线部署能力为企业级应用打开了大门。只要掌握了“中转机制包 + conda-pack 迁移”这一核心范式，哪怕面对最严格的网络管控环境，也能从容应对。
📚 官方文档：https://llamafactory.readthedocs.io
💬 项目地址：GitHub - hiyouga/LLaMA-Factory
动手试试吧，你的专属大模型可能只需要一次部署、一次点击。
