# LLaMA-Factory LLaMA-Factory 是最全面的开源微调框架，支持 100+ 模型，包括所有 LLaMA 变体、Qwen、Mistral、Phi、Falcon、ChatGLM 等。它提供 LoRA、QLoRA、全量微调、RLHF、DPO 和 PPO —— 可通过直观的网页界面（LLaMA Board）或 CLI 使用。CLORE.AI 的按需 GPU 服务器使其成为以远低于云服务提供商成本启动微调任务的理想平台。 {% hint style="success" %} 所有示例都可以在通过以下方式租用的 GPU 服务器上运行 [CLORE.AI 市场](https://clore.ai/marketplace). {% endhint %} ## 服务器要求 | 参数 | 最低要求 | 推荐配置 | | -------- | ---------------- | ------------- | | 内存（RAM） | 16 GB | 32 GB+ | | 显存（VRAM） | 8 GB（QLoRA） | 24 GB 以上 | | 磁盘 | 50 GB | 200 GB+ | | GPU | NVIDIA RTX 2080+ | A100、RTX 4090 | {% hint style="info" %} **训练方式决定 GPU 要求：** * **QLoRA（4 位）**：7B 模型需 8 GB VRAM，13B 需 16 GB * **LoRA（float16）**：7B 模型需 16 GB VRAM，13B 需 40 GB * **全量微调**：每 7B 参数约需 \~14 GB VRAM（外加优化器状态） * 多 GPU（DeepSpeed/FSDP）可横向扩展到任意数量的 GPU {% endhint %} ## 在 CLORE.AI 上快速部署 **Docker 镜像：** `hiyouga/llamafactory:latest` **端口：** `22/tcp`, `7860/http` **环境变量：** | 变量 | 示例 | 描述 | | ---------------------- | ----------- | ------------------------ | | `HF_TOKEN` | `hf_xxx...` | 用于受限模型的 HuggingFace 令牌 | | `WANDB_API_KEY` | `xxx...` | 用于实验追踪的 Weights & Biases | | `CUDA_VISIBLE_DEVICES` | `0,1` | 要使用的 GPU | ## 逐步设置 ### 1. 在 CLORE.AI 上租用 GPU 服务器访问 [CLORE.AI 市场](https://clore.ai/marketplace) 并根据你的任务进行选择： | 任务 | 显存（VRAM） | 开发/测试 | | --------- | -------- | ----------------- | | QLoRA 7B | 8 GB | RTX 3070/2080 | | QLoRA 13B | 16 GB | RTX 3090/A4000 | | LoRA 7B | 16 GB | RTX 3090/A4000 | | LoRA 13B | 40 GB | A6000/A100 40GB | | 全量微调 7B | 80 GB | 💡 本指南中的所有示例均可部署在 | | 多 GPU | 视情况而定 | 2-8× 任意 GPU | ### 2. SSH 登录到您的服务器 ```bash ssh -p root@ ``` ### 3. 创建工作目录 ```bash mkdir -p /root/llamafactory/{data,models,output,saves} ``` ### 4. 拉取 Docker 镜像 ```bash docker pull hiyouga/llamafactory:latest ``` ### 5. 启动 LLaMA-Factory **通过网页 UI（LLaMA Board）启动：** ```bash docker run -d \ --name llamafactory \ --gpus all \ -p 7860:7860 \ -v /root/llamafactory/data:/app/LLaMA-Factory/data \ -v /root/llamafactory/models:/root/.cache/huggingface \ -v /root/llamafactory/output:/app/LLaMA-Factory/output \ -v /root/llamafactory/saves:/app/LLaMA-Factory/saves \ -e HF_TOKEN=hf_your_token_here \ hiyouga/llamafactory:latest \ llamafactory-cli webui ``` **使用 Weights & Biases 追踪：** ```bash docker run -d \ --name llamafactory \ --gpus all \ -p 7860:7860 \ -v /root/llamafactory/data:/app/LLaMA-Factory/data \ -v /root/llamafactory/models:/root/.cache/huggingface \ -v /root/llamafactory/output:/app/LLaMA-Factory/output \ -v /root/llamafactory/saves:/app/LLaMA-Factory/saves \ -e HF_TOKEN=hf_your_token_here \ -e WANDB_API_KEY=your_wandb_key \ hiyouga/llamafactory:latest \ llamafactory-cli webui ``` **使用 DeepSpeed 的多 GPU（4 GPUs）：** ```bash docker run -d \ --name llamafactory \ --gpus all \ --shm-size 16g \ --ipc host \ -p 7860:7860 \ -v /root/llamafactory/data:/app/LLaMA-Factory/data \ -v /root/llamafactory/models:/root/.cache/huggingface \ -v /root/llamafactory/output:/app/LLaMA-Factory/output \ -e CUDA_VISIBLE_DEVICES=0,1,2,3 \ hiyouga/llamafactory:latest \ bash -c "llamafactory-cli webui" ``` ### 6. 访问网页界面检查日志并获取 URL： ```bash docker logs -f llamafactory ``` 你用于端口 7860 的 CLORE.AI http\_pub URL： ``` https://-7860.clore.ai/ ``` *** ## 使用示例 ### 示例 1：通过网页 UI（LLaMA Board）进行 LoRA 微调 1. 在你的 CLORE.AI URL 打开 LLaMA Board 2. 转到 **训练** 选项卡 3. 配置： * **模型名称**: `LLaMA-3` → `Meta-Llama-3-8B-Instruct` * **训练阶段**: `监督微调` * **数据集**：选择你的数据集（或上传自定义） * **微调方法**: `lora` * **LoRA rank**: `8` （更高 = 训练更多参数） * **学习率**: `1e-4` * **训练轮次**: `3` * **输出目录**: `llama3-finetuned` 4. 点击 **开始** 以开始训练 5. 在 **损失** 图表中监控损失曲线 ### 示例 2：基于 CLI 的 QLoRA 微调准备训练配置 YAML： ```bash docker exec -it llamafactory bash cat > /app/LLaMA-Factory/configs/qlora_mistral.yaml << 'EOF' ### 模型 model_name_or_path: mistralai/Mistral-7B-Instruct-v0.3 ### 方法 stage: sft do_train: true finetuning_type: lora lora_target: all lora_rank: 16 lora_alpha: 32 lora_dropout: 0.05 ### 数据集 dataset: alpaca_en template: mistral cutoff_len: 2048 max_samples: 1000 overwrite_cache: true preprocessing_num_workers: 16 ### 输出 output_dir: saves/mistral-qlora logging_steps: 10 save_steps: 500 plot_loss: true overwrite_output_dir: true ### 训练 per_device_train_batch_size: 2 gradient_accumulation_steps: 8 learning_rate: 0.0001 num_train_epochs: 3.0 lr_scheduler_type: cosine warmup_ratio: 0.1 fp16: true ### 量化 quantization_method: bitsandbytes quantization_bit: 4 EOF # 运行训练 llamafactory-cli train /app/LLaMA-Factory/configs/qlora_mistral.yaml ``` ### 示例 3：上传自定义数据集以 Alpaca 格式创建自定义数据集： ```bash # 创建数据集文件 cat > /root/llamafactory/data/my_dataset.json << 'EOF' [ { "instruction": "你是一个科技公司的客户服务代表。请给出有帮助的回答。", "input": "更新后我的笔记本电脑无法开机。我该怎么办？", "output": "我理解这会让人感到沮丧。让我们一步步排查：\n\n1. **按住电源键 10 秒** 强制关机\n2. **拔掉电源线**，如果电池可拆卸则拆下，等待 30 秒\n3. **重新连接电源** 然后尝试开机\n4. 如果仍无反应，在启动时按 **F8/F11** 进入恢复模式\n\n你想让我详细引导你执行上述某一步吗？" }, { "instruction": "你是一个科技公司的客户服务代表。", "input": "我如何重置我的密码？", "output": "重置密码很简单！步骤如下：\n\n1. 进入登录页面并点击 **‘忘记密码’**\n2. 输入你的 **注册邮箱地址**\n3. 检查邮箱中的重置链接（也检查垃圾邮件文件夹）\n4. 点击链接并 **创建新密码**\n\n重置链接在 24 小时后过期。如果 5 分钟内未收到邮件，请联系支持团队。" } ] EOF # 在 dataset_info.json 中注册数据集 docker exec -it llamafactory bash -c " cat >> /app/LLaMA-Factory/data/dataset_info.json << 'EOF2' , \"my_dataset\": { \"file_name\": \"/root/llamafactory/data/my_dataset.json\" } EOF2 " ``` 然后选择 `my_dataset` 在 LLaMA Board 的数据集下拉菜单中。 ### 示例 4：DPO（直接偏好优化） ```yaml ### configs/dpo_llama.yaml model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct ### 方法 - DPO stage: dpo do_train: true finetuning_type: lora lora_rank: 8 ### DPO 专用 pref_beta: 0.1 pref_loss: sigmoid # sigmoid、hinge、ipo ### 数据集（必须为偏好格式） dataset: dpo_en_demo template: llama3 cutoff_len: 2048 ### 输出 output_dir: saves/llama3-dpo logging_steps: 10 save_steps: 100 ### 训练 per_device_train_batch_size: 1 gradient_accumulation_steps: 8 learning_rate: 5e-5 num_train_epochs: 1.0 fp16: true ``` ```bash docker exec -it llamafactory bash -c "llamafactory-cli train /configs/dpo_llama.yaml" ``` ### 示例 5：使用微调模型进行推理训练后，测试你的模型： ```bash docker exec -it llamafactory bash # 交互式聊天 llamafactory-cli chat \ --model_name_or_path mistralai/Mistral-7B-Instruct-v0.3 \ --adapter_name_or_path /app/LLaMA-Factory/saves/mistral-qlora \ --template mistral \ --finetuning_type lora ``` 或导出合并后的模型： ```bash llamafactory-cli export \ --model_name_or_path mistralai/Mistral-7B-Instruct-v0.3 \ --adapter_name_or_path /app/LLaMA-Factory/saves/mistral-qlora \ --template mistral \ --finetuning_type lora \ --export_dir /app/LLaMA-Factory/output/mistral-merged \ --export_size 4 \ --export_legacy_format false ``` *** ## invokeai.yaml 配置文件 ### 关键训练参数 | 参数 | 典型值 | 描述 | | ----------------------------- | --------- | --------------------- | | `lora_rank` | 8–64 | LoRA rank（更高 = 更有表达力） | | `lora_alpha` | 2× rank | LoRA alpha 缩放 | | `lora_dropout` | 0.0–0.1 | LoRA 层的 dropout | | `lora_target` | `all` | 应用 LoRA 的层级 | | `learning_rate` | `1e-4` | 起始学习率 | | `num_train_epochs` | 1–5 | 训练轮次 | | `per_device_train_batch_size` | 1–4 | 每 GPU 的批量大小 | | `gradient_accumulation_steps` | 4–16 | 有效批量放大倍数 | | `cutoff_len` | 1024–4096 | 最大序列长度 | | `quantization_bit` | 4 或 8 | QLoRA 量化位数 | | `warmup_ratio` | 0.05–0.1 | 学习率预热比例 | | `lr_scheduler_type` | `cosine` | 学习率调度 | ### 支持的微调方法 | 方法 | 内存使用 | 速度 | 何时使用 | | ----------------- | ---- | ---- | ------- | | `full` | 非常高 | 最佳选择 | 无限 VRAM | | `freeze` | 高细节 | 快速 | 冻结基础层 | | `lora` | 低 | 非常好 | 默认选择 | | `qlora` （lora+量化） | 最低 | 快速 | 有限 VRAM | ### 多 GPU DeepSpeed 训练在多 GPU 上训练时，用以下方式启动 `torchrun`: ```bash docker exec -it llamafactory bash -c " FORCE_TORCHRUN=1 NNODES=1 RANK=0 MASTER_ADDR=127.0.0.1 MASTER_PORT=29500 \ llamafactory-cli train configs/qlora_mistral.yaml \ --deepspeed examples/deepspeed/ds_z3_config.json " ``` *** ## 1. 使用 SDXL-Turbo 或 SDXL-Lightning 以实现快速生成 ### 1. 按 GPU 优化的 QLoRA 设置 **8 GB VRAM（RTX 3070）：** ```yaml quantization_bit: 4 per_device_train_batch_size: 1 gradient_accumulation_steps: 8 cutoff_len: 1024 ``` **24 GB VRAM（RTX 3090/4090）：** ```yaml quantization_bit: 4 # 对于更大批量仍使用 QLoRA per_device_train_batch_size: 4 gradient_accumulation_steps: 4 cutoff_len: 2048 ``` **80 GB VRAM（A100）：** ```yaml # 无需量化 — 可直接使用 LoRA finetuning_type: lora per_device_train_batch_size: 8 gradient_accumulation_steps: 2 cutoff_len: 4096 fp16: true ``` ### 2. 使用 Flash Attention 2 支持更长上下文 ```yaml flash_attn: fa2 # 需要 Ampere 及以上 GPU ``` 这可以在相同 VRAM 下实现 2× 更长的序列训练。 ### 3. 梯度检查点（Gradient Checkpointing）以约 20% 较慢的训练速度换取 VRAM 节省： ```yaml gradient_checkpointing: true ``` ### 4. 选择合适的 LoRA 目标 ```yaml lora_target: all # 所有线性层（默认，最佳质量） # 或 lora_target: q_proj,v_proj # 最小化、最快但质量较差 ``` ### 5. 冻结顶层以实现快速适配 ```yaml finetuning_type: freeze freeze_trainable_layers: 2 # 只训练最上面的 2 层 freeze_trainable_modules: all ``` 对于简单任务适配，比完全 LoRA 快得多。 ### 6. 使用 TensorBoard 监控 ```bash # 在另一个终端中 docker exec -it llamafactory bash -c " tensorboard --logdir /app/LLaMA-Factory/saves --host 0.0.0.0 --port 6006 " ``` 在你的 CLORE.AI 订单中添加端口 6006 以访问 TensorBoard。 *** ## 故障排除 ### 问题：“训练过程中 CUDA 内存不足（out of memory）” 1. 减少批量大小： `per_device_train_batch_size: 1` 2. 启用梯度检查点： `gradient_checkpointing: true` 3. 减少上下文长度： `cutoff_len: 512` 4. 使用 QLoRA（4 位）： `quantization_bit: 4` 5. 减少 LoRA rank： `lora_rank: 4` ### 问题：训练损失没有下降 * 检查学习率 — 尝试 `5e-5` 或 `2e-4` * 确认数据集格式与模板匹配 * 增加 `lora_rank` （8→16→32） * 检查是否已设置 `lora_target: all` 已设置 ### 问题：训练速度慢 ```bash # 在容器内检查 GPU 利用率 docker exec -it llamafactory bash -c "watch -n 1 nvidia-smi" ``` 如果 GPU 利用率 < 80%： * 增加批量大小 * 使用 Flash Attention： `flash_attn: fa2` * 移除 `gradient_checkpointing` 如果 VRAM 允许 ### 问题：在 Web UI 中找不到模型 ```bash # 预先下载到缓存卷 docker exec -it llamafactory bash -c " huggingface-cli download mistralai/Mistral-7B-Instruct-v0.3 " ``` 然后在 LLaMA Board 中刷新模型列表。 ### 问题：数据集格式错误所有数据集格式必须符合 `dataset_info.json` 规范： ```bash # 验证数据集 docker exec -it llamafactory python3 -c " import json with open('/app/LLaMA-Factory/data/my_dataset.json') as f: data = json.load(f) print(f'Dataset has {len(data)} samples') print('First sample keys:', list(data[0].keys())) " ``` ### 问题：WebUI 端口无法访问确保 LLaMA-Factory 已启动 Gradio 服务器： ```bash docker logs llamafactory 2>&1 | grep -E "Running on|Error|Traceback" ``` 将 `--share` 作为替代，可使用 --share 标志获取公开的 Gradio URL。 *** ## 文档 * [GitHub](https://github.com/hiyouga/LLaMA-Factory) * [文档](https://llamafactory.readthedocs.io) * [Docker Hub（hiyouga）](https://hub.docker.com/r/hiyouga/llamafactory) * [支持的模型](https://github.com/hiyouga/LLaMA-Factory?tab=readme-ov-file#supported-models) * [数据集格式](https://github.com/hiyouga/LLaMA-Factory/blob/main/data/README.md) * [CLORE.AI 市场](https://clore.ai/marketplace) *** ## Clore.ai 的 GPU 建议 | 在 Clore.ai 上的预估费用 | 开发/测试 | RTX 3090（24GB） | | ----------------- | ----------------- | ---------------- | | \~$0.12/每 GPU/每小时 | 生产 | RTX 4090（24GB） | | 微调（7B–13B） | 大规模 | A100 80GB | | 大型模型（70B+） | 💡 本指南中的所有示例均可部署在 | Clore.ai | | 多 GPU 训练 | 2-4x A100 80GB | \~$2.40–$4.80/小时 | > GPU 服务器上。浏览可用 GPU 并按小时租用 — 无需承诺，提供完整的 root 访问权限。 [Clore.ai](https://clore.ai/marketplace) GPU 服务器。浏览可用 GPU 并按小时租用 — 无需承诺，提供完整的 root 访问权限。 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.clore.ai/guides/guides_v2-zh/xun-lian/llama-factory.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.