LLaMA Factory本地部署与离线安装指南

LLaMA Factory本地部署与离线安装实战指南

在大模型定制化需求日益增长的今天，如何快速、安全地完成私有化部署，成为企业和科研团队面临的关键挑战。LLaMA Factory 正是为此而生——它不仅是一个开源微调框架，更像是一座“自动化工厂”，将原本复杂繁琐的模型训练流程封装成可配置、可复现、可视化的标准操作。

无论是金融行业的合规性要求，还是军工场景下的网络隔离，亦或是边缘计算资源受限的环境，我们都需要一套不依赖公网访问的完整部署方案。本文将带你深入一线实践，从零开始构建一个可在封闭内网稳定运行的 LLaMA Factory 环境，并分享多个真实项目中积累的经验技巧。

部署前的关键认知：为什么选择 Conda + pip 混合打包？

很多开发者尝试过纯pip freeze > requirements.txt的方式导出依赖，但在实际迁移时常常遇到问题：版本冲突、平台不兼容、C++ 扩展缺失……根本原因在于，PyTorch、vLLM 这类高性能库对 CUDA、cuDNN 甚至 GCC 编译器版本有严格要求。

相比之下，Conda 环境打包（conda-pack）提供了更高层次的抽象。它不仅能捕获 Python 包，还能包含二进制依赖、编译工具链和系统级库路径，真正实现“一次构建，处处运行”。

📌 小贴士：如果你的目标机器使用的是华为昇腾 NPU 或寒武纪 MLU，建议在联网机上预先安装对应的后端适配包（如torch-npu），再进行打包，避免后期手动替换。

在线安装：快速启动开发调试

对于拥有公网连接的开发环境，推荐采用标准流程快速搭建原型系统。

获取源码并安装核心依赖

git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory

使用-e模式安装，便于后续代码修改即时生效：

pip install -e ".[torch,metrics]" -i https://pypi.tuna.tsinghua.edu.cn/simple

这条命令会自动拉取以下关键组件：
-transformers,datasets,peft,accelerate：Hugging Face 生态基石
-torch：PyTorch 框架（需提前确认 CUDA 版本匹配）
- 中文处理支持：jieba,nltk,rouge-chinese

⚠️ 注意事项：不要直接用默认 PyPI 源！国内用户务必指定镜像站（清华、中科大等），否则可能因超时导致安装失败。

按需扩展功能模块

LLaMA Factory 支持高度模块化安装。以下是常见场景的追加命令：

建议根据硬件能力和任务类型按需安装。例如，在单卡 3090 上做 LoRA 微调，只需基础 + bitsandbytes 即可；若要部署高并发 API 服务，则必须加上 vLLM。

启动 WebUI 开始微调

一切就绪后，直接运行：

python webui.py

默认界面将在http://localhost:7860可访问。通过图形化操作即可完成：
- 模型选择（支持 HuggingFace Hub 或本地路径）
- 训练模式设定（SFT、DPO、PPO 等）
- LoRA 参数配置（rank、alpha、dropout）
- 数据集上传与预览
- 实时监控 loss 和 GPU 利用率

整个过程无需写一行代码，非常适合非算法背景的工程人员上手。

离线部署全流程：从外网打包到内网还原

当服务器处于完全断网状态时，我们必须借助“跳板机”完成依赖预置。这个过程看似简单，实则暗藏陷阱。下面是一套经过多次生产验证的安全流程。

准备工作

你需要准备两台机器：
1.联网操作机：用于下载依赖、创建环境
2.目标离线机：待部署的服务节点

以及两个必要文件：
-LLaMA-Factory-main.zip：项目源码包（建议从 GitHub Releases 下载稳定版）
- 已知可用的 Python 环境基础（推荐 Anaconda 或 Miniforge）

💡 推荐使用 Python 3.10 或 3.11，部分新特性（如 Adam-Mini）在 3.12 下可能存在兼容性问题。

第一步：创建独立 Conda 环境

conda create -n llamafactory python=3.11 conda activate llamafactory conda install -c conda-forge conda-pack

进入解压后的项目目录：

unzip LLaMA-Factory-main.zip -d LLaMA-Factory cd LLaMA-Factory

然后依次安装所需依赖。这里给出一个适用于大多数 GPU 场景的组合命令：

# 基础训练支持 pip install -e ".[torch,metrics]" -i https://mirrors.ustc.edu.cn/pypi/web/simple # QLoRA 必备（4-bit 量化） pip install -e ".[bitsandbytes]" -i https://mirrors.ustc.edu.cn/pypi/web/simple # 分布式训练（多卡/多节点） pip install -e ".[deepspeed]" -i https://mirrors.ustc.edu.cn/pypi/web/simple # 推理加速（vLLM） pip install -e ".[vllm]" -i https://pypi.tuna.tsinghua.edu.cn/simple # 可选：Xinference 支持 pip install "xinference[transformers,vllm]" -i https://pypi.tuna.tsinghua.edu.cn/simple

🔍 经验之谈：所有 pip 安装都应指定国内镜像源。中科大源（mirrors.ustc.edu.cn）对科学计算包优化较好，清华源（tuna.tsinghua.edu.cn）则更适合深度学习生态。

第二步：打包运行时环境

回到上级目录执行打包：

cd /opt/unicloud/env mkdir -p /opt/unicloud/env conda pack -n llamafactory -o llamafactory.tar.gz

生成的llamafactory.tar.gz文件即为完整的 Python 运行时环境，通常大小在 3~6GB 之间（取决于安装的扩展模块数量）。

如何减小包体积？实用瘦身技巧

默认打包会包含大量非运行必需文件（测试代码、文档、.pyc缓存）。可通过过滤规则压缩约 25% 空间：

conda pack -n llamafactory \ --exclude "*.pyc" \ --exclude "__pycache__" \ --exclude "tests" \ --exclude "test" \ --exclude "*.tgz" \ --exclude "*.egg-info" \ -o llamafactory-light.tar.gz

这对带宽紧张或存储有限的场景非常友好。

第三步：传输至离线机器

通过 U盘、SCP、内网文件共享等方式，将以下两个文件拷贝到目标机器：

• llamafactory.tar.gz
• LLaMA-Factory-main.zip

建议统一存放于/opt/llamafactory/目录下：

mkdir -p /opt/llamafactory cp /path/to/*.tar.gz /opt/llamafactory/ cp /path/to/*.zip /opt/llamafactory/

第四步：解压并激活环境

cd /opt/llamafactory # 创建环境目录并解压 mkdir llamafactory-env tar -xzf llamafactory.tar.gz -C llamafactory-env # 激活环境（无需安装 Conda） source llamafactory-env/bin/activate

✅ 成功激活后，终端提示符前会出现(llamafactory)标识。

第五步：部署项目代码并验证

unzip LLaMA-Factory-main.zip -d LLaMA-Factory cd LLaMA-Factory

编写一个简单的测试脚本test_env.py来检查关键组件是否正常：

import torch print("✅ PyTorch version:", torch.__version__) print("✅ CUDA available:", torch.cuda.is_available()) if torch.cuda.is_available(): print("GPU devices:", torch.cuda.device_count()) print("Current device:", torch.cuda.current_device()) print("Device name:", torch.cuda.get_device_name(0)) # 测试核心库导入 try: from transformers import AutoModel print("✅ Transformers imported") except Exception as e: print("❌ Transformers failed:", e) try: import peft print("✅ PEFT (LoRA) imported") except Exception as e: print("❌ PEFT failed:", e)

运行结果应显示无报错，并正确识别 GPU 设备。

启动服务与常见问题应对

确保环境激活后，进入项目目录启动 WebUI：

cd /opt/llamafactory/LLaMA-Factory python webui.py --host 0.0.0.0 --port 7860

添加--host 0.0.0.0可使服务对外网开放（需配合防火墙放行 7860 端口）。

首次启动后，可通过浏览器访问http://<server-ip>:7860完成以下操作：
- 选择本地模型路径（见下文）
- 配置 SFT/DPO/PPO 训练参数
- 设置 LoRA rank/alpha/dropout
- 上传 JSON 格式的指令数据集
- 实时查看训练曲线和资源占用

实战问答：那些文档里没说清楚的事

如何加载本地模型？彻底摆脱 HuggingFace 依赖

当你无法访问 HuggingFace Hub 时，可以在联网机器上提前下载模型：

huggingface-cli download qwen/Qwen-7B --local-dir ./Qwen-7B

然后将整个目录复制到离线机，例如/models/Qwen-7B。

在 WebUI 的“Model”页签中填写：

Model Name or Path: /models/Qwen-7B

支持的所有主流架构包括：LLaMA-3、Qwen、ChatGLM3、Baichuan2、InternLM、Mistral、Mixtral 等 HF 格式模型。

✅ 提示：也可以使用 ModelScope 的snapshot_download工具批量下载通义千问系列模型。

多 GPU 如何启用 DeepSpeed 分布式训练？

要在多卡环境下高效训练大模型，请按以下步骤操作：

1. 确保已安装deepspeed依赖
2. 在 WebUI 中设置：
   - Parallel Type:DeepSpeed
   - DeepSpeed Config: 选择合适的配置文件（如ds_z3_offload.json）
3. 启动命令会自动适配多卡并行

也可通过 CLI 模式更精细控制：

CUDA_VISIBLE_DEVICES=0,1,2,3 llamafactory-cli train \ --stage sft \ --do_train \ --model_name_or_path /models/Qwen-7B \ --dataset my_instruct_data \ --deepspeed ds_config.json \ --output_dir /output/qwen-sft

这种方式更适合自动化流水线集成。

QLoRA 训练需要哪些条件？4-bit 也能跑 13B 模型！

要启用 4-bit 量化微调，请确保满足以下条件：

• 安装bitsandbytes>=0.41.0
• GPU 显存 ≥ 24GB（如 A100、3090、4090）
• 在 WebUI 中设置：
• Quantization Bit:4
• LoRA Rank: ≥ 64（推荐 64~128）
• Double Quantization: ✅ 启用

这样就可以在单张消费级显卡上微调 13B 级别的模型，极大降低硬件门槛。

🛠 调参建议：QLoRA 下 batch size 不宜过大，否则容易 OOM；可适当增加 gradient accumulation steps 来模拟大 batch 效果。

写在最后：让大模型真正落地

LLaMA Factory 的价值远不止于“能跑起来”。它的设计理念是降低大模型工程化的边际成本——无论你是高校研究员、AI 初创公司，还是传统企业的数字化部门，都可以用极低的学习曲线完成专业级模型训练。

更重要的是，这套离线部署方案已经在多个金融风控、政务知识库、工业质检项目中成功应用。其稳定性、安全性、可维护性都经受住了真实业务的考验。

未来，随着 MoE 架构、多模态训练、强化学习对齐等高级功能不断完善，LLaMA Factory 有望成为企业级 AI 基础设施的核心组件之一。

🌐 想了解更多？官方文档始终是最权威的信息来源：
https://llamafactory.readthedocs.io/zh-cn/latest/

附录：高频命令速查表

现在就开始你的本地大模型之旅吧！