1. 项目概述为什么选择LLaMA-Factory如果你正在国内研究大模型尤其是想自己动手微调一个专属的AI助手那么“环境配置”这第一步很可能就让你卡了三天三夜。从GitHub拉取代码时那令人绝望的“Connection timed out”到安装PyTorch时因为网络问题找不到匹配的CUDA版本再到各种依赖包因为源的问题安装失败——这几乎是每个国内开发者的必经之痛。今天要聊的LLaMA-Factory就是一个能极大缓解这些痛苦的利器。它不是一个新模型而是一个一站式的大模型微调与部署框架把数据准备、模型训练、评估、部署这些繁琐流程封装成了清晰的Web界面和命令行工具。简单来说它让你能像搭积木一样基于Llama、Qwen、Baichuan、ChatGLM等主流开源大模型快速定制自己的模型而无需从零开始搭建整个训练流水线。但它的官方安装指南默认你拥有一个“畅通无阻”的网络环境。这篇内容就是要把这个“默认”打破结合我多次在本地和云服务器上部署的经验手把手带你走通LLaMA-Factory在国内网络环境下的完整安装、部署和使用流程。我们会用到镜像、换源、环境变量设置等一系列“生存技巧”目标只有一个让你把精力真正花在模型调优上而不是和网络错误斗智斗勇。2. 前期准备打造一个稳定的基础环境在直接运行pip install之前我们需要先为整个项目搭建一个受控的、可复现的环境。这一步做得好后面能避免至少80%的玄学错误。2.1 关键工具安装与配置Python环境管理强烈推荐使用Conda为什么是Conda而不是直接用系统Python首先大模型训练依赖的PyTorch版本与CUDA驱动版本必须严格匹配Conda可以轻松创建相互隔离的Python环境避免版本冲突。其次Conda的包管理在解决科学计算库的依赖时通常比pip更稳健。安装Miniconda去清华大学开源软件镜像站下载Miniconda安装包速度比官网快得多。选择与你的系统对应的版本比如Linux就是Miniconda3-latest-Linux-x86_64.sh。# 下载安装脚本 wget https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/Miniconda3-latest-Linux-x86_64.sh # 运行安装 bash Miniconda3-latest-Linux-x86_64.sh安装过程中注意看提示建议将Conda初始化到你的shell配置中通常是~/.bashrc或~/.zshrc。配置Conda镜像源安装后立即配置国内镜像后续创建环境和安装包会飞速。conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/ conda config --set show_channel_urls yesGit的安装与代理配置LLaMA-Factory的代码托管在GitHub上直接克隆大概率会失败。安装Git通过系统包管理器安装即可如Ubuntu/Debian用sudo apt install gitCentOS用sudo yum install git。为Git配置代理如果可用这是解决克隆问题的核心。如果你有可用的HTTP/HTTPS代理将其配置给Git。git config --global http.proxy http://你的代理地址:端口 git config --global https.proxy http://你的代理地址:端口注意这里填写的是你的本地或网络代理地址请务必使用合法合规的网络服务。如果无法配置代理备用方案是使用GitHub的镜像站或直接下载ZIP包但后续更新会麻烦一些。Docker可选但推荐Docker能提供绝对一致的环境特别适合团队协作或生产部署。安装Docker后同样需要配置国内镜像加速器否则拉取镜像慢如蜗牛。安装Docker参考官方文档不同系统步骤不同。配置镜像加速器修改或创建/etc/docker/daemon.json加入国内镜像站地址。{ registry-mirrors: [ https://docker.mirrors.ustc.edu.cn, https://hub-mirror.c.163.com ] }然后重启Docker服务sudo systemctl restart docker。2.2 硬件与驱动检查大模型训练吃硬件尤其是GPU。在开始前请确认你的装备。GPU检查运行nvidia-smi。这个命令能告诉你显卡型号、驱动版本以及CUDA版本。如果命令未找到说明NVIDIA驱动未安装你需要先根据显卡型号和操作系统安装合适的驱动。CUDA与PyTorch版本对应这是最重要的兼容性检查。访问PyTorch官网查看其支持的CUDA版本。例如PyTorch 2.1可能支持CUDA 11.8和12.1。你的nvidia-smi显示的CUDA版本是驱动支持的最高CUDA版本你需要安装一个≤此版本的CUDA Toolkit。通常通过Conda安装PyTorch时会自动解决CUDA依赖但心里要有数。显存评估nvidia-smi也会显示显存大小。全参数微调Full Fine-tuning7B模型可能需要16GB以上显存。而更流行的LoRA、QLoRA等参数高效微调方法可以将7B模型的微调需求降低到8GB甚至更低。根据你的显存提前规划微调方法。实操心得在个人开发机上我强烈建议先使用LoRA等轻量级微调方法上手。用RTX 309024GB微调7B模型的全参数虽然可以但非常吃力batch size只能设得很小训练慢且容易OOM内存溢出。而使用QLoRA同样的任务显存占用可以控制在10GB以内训练速度也更快。3. LLaMA-Factory的安装实战基础环境打牢后我们开始攻克LLaMA-Factory本身。3.1 源码获取与项目初始化首先我们需要把代码弄到本地。方法一通过Git克隆推荐便于更新如果你已经为Git配置了代理那么直接克隆即可git clone https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory如果克隆失败可以尝试使用GitHub的镜像链接或者使用ghproxy.com等加速服务git clone https://ghproxy.com/https://github.com/hiyouga/LLaMA-Factory.git方法二直接下载ZIP包网络困难时的选择在项目GitHub页面点击Code按钮选择Download ZIP。下载后解压到本地目录。缺点是后续难以通过git pull更新。进入项目目录后我们创建一个专属的Conda环境。# 创建一个名为 llama_factory 的Python 3.10环境 conda create -n llama_factory python3.10 -y conda activate llama_factory选择Python 3.10是因为它在兼容性和稳定性上是一个广泛支持的选择。3.2 依赖安装解决“pip install”的痛点项目根目录下通常有requirements.txt文件。直接pip install -r requirements.txt在国内大概率会因网络超时而失败。我们必须配置pip镜像源。永久配置pip镜像源pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn或者你也可以在安装时临时指定源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple安装PyTorch的特殊处理requirements.txt里的PyTorch安装命令如torch2.0.0会从PyPI拉取但有时我们需要特定CUDA版本的PyTorch。更稳妥的方式是去PyTorch官网根据你的CUDA版本生成对应的Conda或pip安装命令。例如对于CUDA 11.8# 使用Conda安装优先推荐能更好地处理CUDA相关依赖 conda install pytorch2.1.0 torchvision0.16.0 torchaudio2.1.0 pytorch-cuda11.8 -c pytorch -c nvidia # 或者使用pip安装 pip install torch2.1.0 torchvision0.16.0 torchaudio2.1.0 --index-url https://download.pytorch.org/whl/cu118关键点安装完PyTorch后务必在Python交互环境中验证CUDA是否可用import torch print(torch.__version__) # 查看PyTorch版本 print(torch.cuda.is_available()) # 必须为True print(torch.cuda.get_device_name(0)) # 显示你的GPU型号如果torch.cuda.is_available()返回False说明PyTorch安装的是CPU版本或者与CUDA驱动不兼容需要重新安装。安装其他依赖解决了PyTorch剩下的依赖安装就顺畅了。pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple这个过程可能会花费一些时间请耐心等待。3.3 模型下载从Hugging Face到本地LLaMA-Factory本身不包含模型权重它需要你指定一个本地模型路径。我们需要提前将预训练模型从Hugging Face Hub下载到本地。挑战直接使用transformers的from_pretrained在线下载对于几个GB甚至几十GB的大模型在国内网络环境下几乎不可能成功。解决方案一使用镜像站推荐Hugging Face在国内有社区维护的镜像站。我们通过设置环境变量让所有HF相关的工具都走镜像。# Linux/Mac export HF_ENDPOINThttps://hf-mirror.com # Windows (PowerShell) $env:HF_ENDPOINThttps://hf-mirror.com设置之后就可以使用huggingface-cli命令行工具下载了。首先安装这个工具pip install -U huggingface-hub。 然后使用huggingface-cli download命令下载模型例如下载Qwen2.5-7B-Instructhuggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./models/Qwen2.5-7B-Instruct --local-dir-use-symlinks False参数解释--local-dir指定本地存储目录--local-dir-use-symlinks False表示直接下载文件而不是创建符号链接避免一些权限问题。解决方案二使用第三方工具或网站如果镜像站速度也不理想可以考虑一些第三方模型下载网站它们提供了网盘或BT链接。下载后你需要按照Hugging Face的模型仓库结构包含config.json,model.safetensors,tokenizer.json等文件将模型文件放置到对应的本地目录中。解决方案三从魔搭社区ModelScope下载对于国内开发者和一些国产模型魔搭社区是更好的选择。首先安装ModelScope库pip install modelscope。然后在Python脚本中from modelscope import snapshot_download model_dir snapshot_download(qwen/Qwen2.5-7B-Instruct, cache_dir./models)下载的模型文件结构与Hugging Face兼容LLaMA-Factory可以直接读取。注意事项模型文件非常大请确保你的磁盘有足够空间一个7B模型约15GB。下载过程可能中断可以使用--resume-download参数如果工具支持进行断点续传。将下载好的模型路径如./models/Qwen2.5-7B-Instruct记下来后面配置要用。4. 配置与启动让Web界面跑起来LLaMA-Factory提供了两种主要的使用方式命令行工具和Web图形界面。对于初学者和快速实验Web界面直观得多。4.1 关键配置文件解析在启动前我们需要关注几个核心配置文件它们通常在src/llamafactory目录下或项目根目录。模型配置文件LLaMA-Factory支持众多模型其配置定义在src/llamafactory/model目录下的各个Python文件中。你通常不需要修改它们但需要知道你的模型是否在支持列表里。主流的Llama、Qwen、Baichuan、ChatGLM、InternLM等都在支持范围内。数据集配置文件自定义训练数据需要配置。参考data/dataset_info.json或src/llamafactory/data下的例子。你需要定义数据集的路径、格式如alpaca、sharegpt和预处理方式。训练参数配置文件Web UI的配置背后对应着各种训练参数。理解这些参数对微调效果至关重要我们会在下一章详细展开。4.2 启动Web UI服务这是最简单直接的启动方式。在项目根目录下运行python src/train_web.py或者使用项目提供的脚本CUDA_VISIBLE_DEVICES0 python src/train_web.pyCUDA_VISIBLE_DEVICES0指定使用第一块GPU索引为0。如果你有多块GPU可以指定0,1等。如果一切顺利终端会输出类似以下的信息Running on local URL: http://127.0.0.1:7860 Running on public URL: https://xxxxx.gradio.live此时在你的浏览器中访问http://127.0.0.1:7860就能看到LLaMA-Factory的Web界面了。首次启动的常见问题与解决端口占用默认端口7860可能被其他程序占用。可以通过--port参数指定其他端口如python src/train_web.py --port 8000。导入错误ImportError通常是某个依赖包没有安装成功或者环境不对。请确认已激活正确的Conda环境并重新检查requirements.txt的安装日志。CUDA Out of Memory启动时就OOM可能是默认加载的模型太大。在Web UI的“模型”标签页确保你正确选择了已下载到本地的、尺寸合适的模型路径。对于显存有限的机器可以考虑先尝试更小的模型如1.8B、3B或者使用量化模型如GPTQ、AWQ格式。4.3 Web界面核心功能导览成功进入Web界面后你会看到几个主要标签页模型 (Model)在这里加载或卸载模型。你需要填写“模型名称或路径”这就是你之前下载的模型本地目录路径如./models/Qwen2.5-7B-Instruct。点击“加载模型”下方会显示模型参数信息。这里还可以选择是否进行量化加载如bitsandbytes的8-bit/4-bit量化以节省显存。训练 (Training)微调的核心区域。数据集 (Dataset)选择或配置你的训练数据集。训练配置设置训练轮次Epochs、学习率Learning rate、批处理大小Batch size等超参数。方法选择关键包括全参数微调、LoRA、QLoRA等。对于资源有限的用户QLoRA是首选它能以极低的显存开销实现接近全参数微调的效果。开始训练配置好后点击即可开始。训练日志会在下方控制台显示。聊天 (Chat)在训练前后你可以在这里与原始模型或你微调后的模型进行对话直观感受效果。评估 (Evaluation)使用标准基准如MMLU、C-Eval或你自己的数据对模型性能进行评估。导出 (Export)将训练好的模型尤其是LoRA适配器与基础模型合并导出成完整的、可独立部署的模型文件如Hugging Face格式或GGUF格式。5. 核心微调流程详解现在我们以一个具体的例子——使用自定义指令数据集微调Qwen2.5-7B-Instruct模型——来走通全流程。5.1 数据准备格式是关键模型微调的效果一半取决于数据。LLaMA-Factory支持多种数据格式最常见的是Alpaca格式和ShareGPT格式。Alpaca格式指令微调常用这是一个JSON列表每个元素是一个字典包含instruction指令input可选输入output期望输出。[ { instruction: 将以下中文翻译成英文。, input: 今天天气真好。, output: The weather is really nice today. }, { instruction: 解释什么是人工智能。, input: , output: 人工智能是计算机科学的一个分支旨在创造能够执行通常需要人类智能的任务的机器或软件。 } ]ShareGPT格式多轮对话模拟聊天记录每个对话包含多轮conversations每轮由fromhuman/gpt和value内容组成。[ { conversations: [ { from: human, value: 你好请介绍一下你自己。 }, { from: gpt, value: 你好我是一个人工智能助手由Qwen大模型驱动。我乐于回答你的问题并提供帮助。 }, { from: human, value: 你能做什么 }, { from: gpt, value: 我可以进行对话、回答问题、总结信息、翻译语言、编写代码等等。请随时告诉我你需要什么。 } ] } ]数据准备建议质量高于数量几百条高质量、多样化的数据远胜于几万条重复、低质的数据。清洗数据去除HTML标签、特殊乱码、无关信息。划分数据集将数据按比例如8:1:1划分为训练集train.json、验证集validation.json和测试集test.json。LLaMA-Factory在训练过程中会用验证集监控模型表现防止过拟合。5.2 训练配置参数背后的逻辑在Web UI的“训练”标签页面对众多参数新手容易眼花。我们聚焦几个最关键的学习率 (Learning Rate)这是最重要的超参数之一。对于使用AdamW优化器的QLoRA微调学习率通常在1e-4到5e-5之间。太大容易训练不稳定损失值剧烈震荡太小则收敛慢。可以从2e-4开始尝试。训练轮次 (Num Epochs)你的数据集会被完整遍历多少次。对于小数据集几千条可能需要10-20个轮次对于大数据集3-5个轮次可能就够了。观察验证集损失当它不再下降甚至开始上升时过拟合就应该提前停止。批处理大小 (Batch Size)一次训练输入多少样本。受显存限制。在显存允许的情况下较大的Batch Size如32, 64通常训练更稳定。可以使用梯度累积来模拟大Batch Size效果例如实际Batch Size4但梯度累积步数8效果就类似于Batch Size32。LoRA参数lora_rankLoRA秩决定适配器的大小常见值为8、16、32。越大能力越强但参数越多。一般从8开始。lora_alpha缩放因子通常设为秩的2倍如秩为8alpha设为16这是一个经验值。lora_dropout防止过拟合的丢弃率可以设为0.1。target_modules将LoRA适配器应用到哪些模型层对于大多数Transformer模型选择q_proj, v_proj查询和值投影层是一个好的起点。LLaMA-Factory通常会自动根据模型类型选择。一个典型的QLoRA启动配置示例 在Web UI中你可以这样设置方法选择QLoRA学习率2e-4训练轮次5最大序列长度1024(根据你的数据长度调整)批处理大小4(根据显存调整)梯度累积步数8LoRA秩8LoRA Alpha16目标模块q_proj, v_proj5.3 启动训练与监控配置好数据和参数后点击“开始训练”。此时Web UI下方或终端会开始输出训练日志。关键监控指标损失 (Loss)训练损失应该随着步数增加而稳步下降。验证损失则先下降后可能缓慢上升最低点通常是保存最佳模型的时机。学习率曲线如果使用了学习率调度器如余弦退火可以看到学习率按计划变化。显存占用使用nvidia-smi命令或在日志中查看确保没有超出GPU显存。训练完成后模型检查点包含LoRA权重会保存在你指定的输出目录中默认为./saves。6. 模型测试、导出与部署训练结束不是终点让模型用起来才是。6.1 在Web界面中测试训练时或训练后你可以切换到“聊天”标签页。在“模型适配器”选项中选择你刚刚训练得到的检查点目录例如./saves/qwen2.5-7b-instruct-lora/lora。然后加载模型就可以与微调后的模型进行对话测试其在新任务上的表现。6.2 合并与导出模型LoRA训练产生的是一个小型的适配器文件而不是完整的模型。要部署为一个独立模型需要将其与基础模型合并。在Web UI的“导出”标签页选择你训练好的适配器路径。选择基础模型路径即你最开始下载的原始模型。选择导出格式Hugging Face格式这是最通用的格式可以继续用transformers库加载。适合后续的Python API服务部署。GGUF格式这是llama.cpp项目推出的量化格式可以在CPU或边缘设备上高效运行非常适合本地桌面应用或资源受限的环境。导出时可以选择量化精度如Q4_K_M, Q5_K_S等。点击“开始导出”。合并后的模型会保存在指定目录。6.3 简易API服务部署LLaMA-Factory内置了基于Gradio或FastAPI的部署脚本。最简单的是使用其WebUI的“聊天”页面本身作为演示。对于生产环境更推荐使用其提供的API脚本。例如使用FastAPI部署python src/api_demo.py \ --model_name_or_path ./models/Qwen2.5-7B-Instruct \ # 基础模型路径 --adapter_name_or_path ./saves/qwen2.5-7b-instruct-lora/lora \ # (可选) LoRA适配器路径 --template qwen \ # 使用Qwen的对话模板 --finetuning_type lora \ # 微调类型 --server_name 0.0.0.0 \ # 允许外部访问 --server_port 8000 # 指定端口运行后你就拥有了一个提供/chat/completions等标准接口的本地大模型API服务可以被其他应用程序调用。7. 避坑指南与实战经验走通流程不难但想高效、稳定地训练出好模型需要避开很多坑。环境与安装类问题“Torch not compiled with CUDA enabled”PyTorch安装成了CPU版本。严格按照CUDA版本去PyTorch官网找安装命令并用python -c “import torch; print(torch.cuda.is_available())”验证。“Out of Memory”这是常态。解决方案1) 使用QLoRA而不是全量微调2) 减小batch_size和max_length3) 开启梯度检查点gradient_checkpointingTrue用计算时间换显存4) 使用更激进的量化如4-bit。下载模型中断使用huggingface-cli的--resume-download参数。或者用wget或curl配合镜像站地址直接下载大文件。训练过程类问题损失值为NaN或无限大通常是学习率设置过高。尝试将学习率降低一个数量级例如从2e-4降到2e-5。也可能是数据中存在异常值检查数据清洗。模型“学废了”输出乱码或重复可能是数据质量差、数据格式不对、或者学习率/轮次设置不当。从小数据集、低学习率开始调试。确保你的数据格式与选择的“数据集格式”完全匹配。验证损失不降反升这是明显的过拟合。立即停止训练。增加训练数据量、为模型添加Dropout、使用更早的检查点验证损失最低的那个、或者减少训练轮次。资源与效率优化使用Flash Attention 2如果你的GPU架构支持如Ampere架构的RTX 30系列及以上安装flash-attn库可以显著加速训练并减少显存占用。但它的安装有时比较麻烦需要预编译。混合精度训练LLaMA-Factory默认开启fp16或bf16混合精度训练在保持精度的情况下加速并节省显存。确保你的硬件支持现代GPU都支持。多GPU训练如果你有多张GPU可以使用accelerate或deepspeed进行分布式训练。在LLaMA-Factory中可以通过配置accelerate配置文件来实现。这对于大规模全参数微调是必要的。一个真实的调试案例我曾经用一批法律问答数据微调一个模型训练损失正常下降但模型在测试时总是生成与法律无关的通用回答。排查后发现是数据中“instruction”字段写得太模糊例如“回答以下问题”而“input”字段包含了具体的法律问题。模型只关注了“instruction”而忽略了“input”。将问题内容合并到“instruction”中例如“根据中国合同法回答以下问题…”问题就解决了。数据格式的细节直接决定了模型学习的目标。最后大模型微调既是科学也是艺术。LLaMA-Factory为我们提供了强大的工具但如何准备数据、如何调参、如何评估仍然需要大量的实践和迭代。从一个小而精的数据集开始跑通整个流程获得第一个微调成功的模型这种正反馈是学习的最佳动力。然后再逐步挑战更复杂的任务和更大的模型。记住每次训练都是一次实验详细记录你的配置、数据和结果这是你积累经验、形成直觉的最宝贵财富。
LLaMA-Factory国内网络环境部署与微调实战指南
1. 项目概述为什么选择LLaMA-Factory如果你正在国内研究大模型尤其是想自己动手微调一个专属的AI助手那么“环境配置”这第一步很可能就让你卡了三天三夜。从GitHub拉取代码时那令人绝望的“Connection timed out”到安装PyTorch时因为网络问题找不到匹配的CUDA版本再到各种依赖包因为源的问题安装失败——这几乎是每个国内开发者的必经之痛。今天要聊的LLaMA-Factory就是一个能极大缓解这些痛苦的利器。它不是一个新模型而是一个一站式的大模型微调与部署框架把数据准备、模型训练、评估、部署这些繁琐流程封装成了清晰的Web界面和命令行工具。简单来说它让你能像搭积木一样基于Llama、Qwen、Baichuan、ChatGLM等主流开源大模型快速定制自己的模型而无需从零开始搭建整个训练流水线。但它的官方安装指南默认你拥有一个“畅通无阻”的网络环境。这篇内容就是要把这个“默认”打破结合我多次在本地和云服务器上部署的经验手把手带你走通LLaMA-Factory在国内网络环境下的完整安装、部署和使用流程。我们会用到镜像、换源、环境变量设置等一系列“生存技巧”目标只有一个让你把精力真正花在模型调优上而不是和网络错误斗智斗勇。2. 前期准备打造一个稳定的基础环境在直接运行pip install之前我们需要先为整个项目搭建一个受控的、可复现的环境。这一步做得好后面能避免至少80%的玄学错误。2.1 关键工具安装与配置Python环境管理强烈推荐使用Conda为什么是Conda而不是直接用系统Python首先大模型训练依赖的PyTorch版本与CUDA驱动版本必须严格匹配Conda可以轻松创建相互隔离的Python环境避免版本冲突。其次Conda的包管理在解决科学计算库的依赖时通常比pip更稳健。安装Miniconda去清华大学开源软件镜像站下载Miniconda安装包速度比官网快得多。选择与你的系统对应的版本比如Linux就是Miniconda3-latest-Linux-x86_64.sh。# 下载安装脚本 wget https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/Miniconda3-latest-Linux-x86_64.sh # 运行安装 bash Miniconda3-latest-Linux-x86_64.sh安装过程中注意看提示建议将Conda初始化到你的shell配置中通常是~/.bashrc或~/.zshrc。配置Conda镜像源安装后立即配置国内镜像后续创建环境和安装包会飞速。conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/ conda config --set show_channel_urls yesGit的安装与代理配置LLaMA-Factory的代码托管在GitHub上直接克隆大概率会失败。安装Git通过系统包管理器安装即可如Ubuntu/Debian用sudo apt install gitCentOS用sudo yum install git。为Git配置代理如果可用这是解决克隆问题的核心。如果你有可用的HTTP/HTTPS代理将其配置给Git。git config --global http.proxy http://你的代理地址:端口 git config --global https.proxy http://你的代理地址:端口注意这里填写的是你的本地或网络代理地址请务必使用合法合规的网络服务。如果无法配置代理备用方案是使用GitHub的镜像站或直接下载ZIP包但后续更新会麻烦一些。Docker可选但推荐Docker能提供绝对一致的环境特别适合团队协作或生产部署。安装Docker后同样需要配置国内镜像加速器否则拉取镜像慢如蜗牛。安装Docker参考官方文档不同系统步骤不同。配置镜像加速器修改或创建/etc/docker/daemon.json加入国内镜像站地址。{ registry-mirrors: [ https://docker.mirrors.ustc.edu.cn, https://hub-mirror.c.163.com ] }然后重启Docker服务sudo systemctl restart docker。2.2 硬件与驱动检查大模型训练吃硬件尤其是GPU。在开始前请确认你的装备。GPU检查运行nvidia-smi。这个命令能告诉你显卡型号、驱动版本以及CUDA版本。如果命令未找到说明NVIDIA驱动未安装你需要先根据显卡型号和操作系统安装合适的驱动。CUDA与PyTorch版本对应这是最重要的兼容性检查。访问PyTorch官网查看其支持的CUDA版本。例如PyTorch 2.1可能支持CUDA 11.8和12.1。你的nvidia-smi显示的CUDA版本是驱动支持的最高CUDA版本你需要安装一个≤此版本的CUDA Toolkit。通常通过Conda安装PyTorch时会自动解决CUDA依赖但心里要有数。显存评估nvidia-smi也会显示显存大小。全参数微调Full Fine-tuning7B模型可能需要16GB以上显存。而更流行的LoRA、QLoRA等参数高效微调方法可以将7B模型的微调需求降低到8GB甚至更低。根据你的显存提前规划微调方法。实操心得在个人开发机上我强烈建议先使用LoRA等轻量级微调方法上手。用RTX 309024GB微调7B模型的全参数虽然可以但非常吃力batch size只能设得很小训练慢且容易OOM内存溢出。而使用QLoRA同样的任务显存占用可以控制在10GB以内训练速度也更快。3. LLaMA-Factory的安装实战基础环境打牢后我们开始攻克LLaMA-Factory本身。3.1 源码获取与项目初始化首先我们需要把代码弄到本地。方法一通过Git克隆推荐便于更新如果你已经为Git配置了代理那么直接克隆即可git clone https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory如果克隆失败可以尝试使用GitHub的镜像链接或者使用ghproxy.com等加速服务git clone https://ghproxy.com/https://github.com/hiyouga/LLaMA-Factory.git方法二直接下载ZIP包网络困难时的选择在项目GitHub页面点击Code按钮选择Download ZIP。下载后解压到本地目录。缺点是后续难以通过git pull更新。进入项目目录后我们创建一个专属的Conda环境。# 创建一个名为 llama_factory 的Python 3.10环境 conda create -n llama_factory python3.10 -y conda activate llama_factory选择Python 3.10是因为它在兼容性和稳定性上是一个广泛支持的选择。3.2 依赖安装解决“pip install”的痛点项目根目录下通常有requirements.txt文件。直接pip install -r requirements.txt在国内大概率会因网络超时而失败。我们必须配置pip镜像源。永久配置pip镜像源pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn或者你也可以在安装时临时指定源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple安装PyTorch的特殊处理requirements.txt里的PyTorch安装命令如torch2.0.0会从PyPI拉取但有时我们需要特定CUDA版本的PyTorch。更稳妥的方式是去PyTorch官网根据你的CUDA版本生成对应的Conda或pip安装命令。例如对于CUDA 11.8# 使用Conda安装优先推荐能更好地处理CUDA相关依赖 conda install pytorch2.1.0 torchvision0.16.0 torchaudio2.1.0 pytorch-cuda11.8 -c pytorch -c nvidia # 或者使用pip安装 pip install torch2.1.0 torchvision0.16.0 torchaudio2.1.0 --index-url https://download.pytorch.org/whl/cu118关键点安装完PyTorch后务必在Python交互环境中验证CUDA是否可用import torch print(torch.__version__) # 查看PyTorch版本 print(torch.cuda.is_available()) # 必须为True print(torch.cuda.get_device_name(0)) # 显示你的GPU型号如果torch.cuda.is_available()返回False说明PyTorch安装的是CPU版本或者与CUDA驱动不兼容需要重新安装。安装其他依赖解决了PyTorch剩下的依赖安装就顺畅了。pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple这个过程可能会花费一些时间请耐心等待。3.3 模型下载从Hugging Face到本地LLaMA-Factory本身不包含模型权重它需要你指定一个本地模型路径。我们需要提前将预训练模型从Hugging Face Hub下载到本地。挑战直接使用transformers的from_pretrained在线下载对于几个GB甚至几十GB的大模型在国内网络环境下几乎不可能成功。解决方案一使用镜像站推荐Hugging Face在国内有社区维护的镜像站。我们通过设置环境变量让所有HF相关的工具都走镜像。# Linux/Mac export HF_ENDPOINThttps://hf-mirror.com # Windows (PowerShell) $env:HF_ENDPOINThttps://hf-mirror.com设置之后就可以使用huggingface-cli命令行工具下载了。首先安装这个工具pip install -U huggingface-hub。 然后使用huggingface-cli download命令下载模型例如下载Qwen2.5-7B-Instructhuggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./models/Qwen2.5-7B-Instruct --local-dir-use-symlinks False参数解释--local-dir指定本地存储目录--local-dir-use-symlinks False表示直接下载文件而不是创建符号链接避免一些权限问题。解决方案二使用第三方工具或网站如果镜像站速度也不理想可以考虑一些第三方模型下载网站它们提供了网盘或BT链接。下载后你需要按照Hugging Face的模型仓库结构包含config.json,model.safetensors,tokenizer.json等文件将模型文件放置到对应的本地目录中。解决方案三从魔搭社区ModelScope下载对于国内开发者和一些国产模型魔搭社区是更好的选择。首先安装ModelScope库pip install modelscope。然后在Python脚本中from modelscope import snapshot_download model_dir snapshot_download(qwen/Qwen2.5-7B-Instruct, cache_dir./models)下载的模型文件结构与Hugging Face兼容LLaMA-Factory可以直接读取。注意事项模型文件非常大请确保你的磁盘有足够空间一个7B模型约15GB。下载过程可能中断可以使用--resume-download参数如果工具支持进行断点续传。将下载好的模型路径如./models/Qwen2.5-7B-Instruct记下来后面配置要用。4. 配置与启动让Web界面跑起来LLaMA-Factory提供了两种主要的使用方式命令行工具和Web图形界面。对于初学者和快速实验Web界面直观得多。4.1 关键配置文件解析在启动前我们需要关注几个核心配置文件它们通常在src/llamafactory目录下或项目根目录。模型配置文件LLaMA-Factory支持众多模型其配置定义在src/llamafactory/model目录下的各个Python文件中。你通常不需要修改它们但需要知道你的模型是否在支持列表里。主流的Llama、Qwen、Baichuan、ChatGLM、InternLM等都在支持范围内。数据集配置文件自定义训练数据需要配置。参考data/dataset_info.json或src/llamafactory/data下的例子。你需要定义数据集的路径、格式如alpaca、sharegpt和预处理方式。训练参数配置文件Web UI的配置背后对应着各种训练参数。理解这些参数对微调效果至关重要我们会在下一章详细展开。4.2 启动Web UI服务这是最简单直接的启动方式。在项目根目录下运行python src/train_web.py或者使用项目提供的脚本CUDA_VISIBLE_DEVICES0 python src/train_web.pyCUDA_VISIBLE_DEVICES0指定使用第一块GPU索引为0。如果你有多块GPU可以指定0,1等。如果一切顺利终端会输出类似以下的信息Running on local URL: http://127.0.0.1:7860 Running on public URL: https://xxxxx.gradio.live此时在你的浏览器中访问http://127.0.0.1:7860就能看到LLaMA-Factory的Web界面了。首次启动的常见问题与解决端口占用默认端口7860可能被其他程序占用。可以通过--port参数指定其他端口如python src/train_web.py --port 8000。导入错误ImportError通常是某个依赖包没有安装成功或者环境不对。请确认已激活正确的Conda环境并重新检查requirements.txt的安装日志。CUDA Out of Memory启动时就OOM可能是默认加载的模型太大。在Web UI的“模型”标签页确保你正确选择了已下载到本地的、尺寸合适的模型路径。对于显存有限的机器可以考虑先尝试更小的模型如1.8B、3B或者使用量化模型如GPTQ、AWQ格式。4.3 Web界面核心功能导览成功进入Web界面后你会看到几个主要标签页模型 (Model)在这里加载或卸载模型。你需要填写“模型名称或路径”这就是你之前下载的模型本地目录路径如./models/Qwen2.5-7B-Instruct。点击“加载模型”下方会显示模型参数信息。这里还可以选择是否进行量化加载如bitsandbytes的8-bit/4-bit量化以节省显存。训练 (Training)微调的核心区域。数据集 (Dataset)选择或配置你的训练数据集。训练配置设置训练轮次Epochs、学习率Learning rate、批处理大小Batch size等超参数。方法选择关键包括全参数微调、LoRA、QLoRA等。对于资源有限的用户QLoRA是首选它能以极低的显存开销实现接近全参数微调的效果。开始训练配置好后点击即可开始。训练日志会在下方控制台显示。聊天 (Chat)在训练前后你可以在这里与原始模型或你微调后的模型进行对话直观感受效果。评估 (Evaluation)使用标准基准如MMLU、C-Eval或你自己的数据对模型性能进行评估。导出 (Export)将训练好的模型尤其是LoRA适配器与基础模型合并导出成完整的、可独立部署的模型文件如Hugging Face格式或GGUF格式。5. 核心微调流程详解现在我们以一个具体的例子——使用自定义指令数据集微调Qwen2.5-7B-Instruct模型——来走通全流程。5.1 数据准备格式是关键模型微调的效果一半取决于数据。LLaMA-Factory支持多种数据格式最常见的是Alpaca格式和ShareGPT格式。Alpaca格式指令微调常用这是一个JSON列表每个元素是一个字典包含instruction指令input可选输入output期望输出。[ { instruction: 将以下中文翻译成英文。, input: 今天天气真好。, output: The weather is really nice today. }, { instruction: 解释什么是人工智能。, input: , output: 人工智能是计算机科学的一个分支旨在创造能够执行通常需要人类智能的任务的机器或软件。 } ]ShareGPT格式多轮对话模拟聊天记录每个对话包含多轮conversations每轮由fromhuman/gpt和value内容组成。[ { conversations: [ { from: human, value: 你好请介绍一下你自己。 }, { from: gpt, value: 你好我是一个人工智能助手由Qwen大模型驱动。我乐于回答你的问题并提供帮助。 }, { from: human, value: 你能做什么 }, { from: gpt, value: 我可以进行对话、回答问题、总结信息、翻译语言、编写代码等等。请随时告诉我你需要什么。 } ] } ]数据准备建议质量高于数量几百条高质量、多样化的数据远胜于几万条重复、低质的数据。清洗数据去除HTML标签、特殊乱码、无关信息。划分数据集将数据按比例如8:1:1划分为训练集train.json、验证集validation.json和测试集test.json。LLaMA-Factory在训练过程中会用验证集监控模型表现防止过拟合。5.2 训练配置参数背后的逻辑在Web UI的“训练”标签页面对众多参数新手容易眼花。我们聚焦几个最关键的学习率 (Learning Rate)这是最重要的超参数之一。对于使用AdamW优化器的QLoRA微调学习率通常在1e-4到5e-5之间。太大容易训练不稳定损失值剧烈震荡太小则收敛慢。可以从2e-4开始尝试。训练轮次 (Num Epochs)你的数据集会被完整遍历多少次。对于小数据集几千条可能需要10-20个轮次对于大数据集3-5个轮次可能就够了。观察验证集损失当它不再下降甚至开始上升时过拟合就应该提前停止。批处理大小 (Batch Size)一次训练输入多少样本。受显存限制。在显存允许的情况下较大的Batch Size如32, 64通常训练更稳定。可以使用梯度累积来模拟大Batch Size效果例如实际Batch Size4但梯度累积步数8效果就类似于Batch Size32。LoRA参数lora_rankLoRA秩决定适配器的大小常见值为8、16、32。越大能力越强但参数越多。一般从8开始。lora_alpha缩放因子通常设为秩的2倍如秩为8alpha设为16这是一个经验值。lora_dropout防止过拟合的丢弃率可以设为0.1。target_modules将LoRA适配器应用到哪些模型层对于大多数Transformer模型选择q_proj, v_proj查询和值投影层是一个好的起点。LLaMA-Factory通常会自动根据模型类型选择。一个典型的QLoRA启动配置示例 在Web UI中你可以这样设置方法选择QLoRA学习率2e-4训练轮次5最大序列长度1024(根据你的数据长度调整)批处理大小4(根据显存调整)梯度累积步数8LoRA秩8LoRA Alpha16目标模块q_proj, v_proj5.3 启动训练与监控配置好数据和参数后点击“开始训练”。此时Web UI下方或终端会开始输出训练日志。关键监控指标损失 (Loss)训练损失应该随着步数增加而稳步下降。验证损失则先下降后可能缓慢上升最低点通常是保存最佳模型的时机。学习率曲线如果使用了学习率调度器如余弦退火可以看到学习率按计划变化。显存占用使用nvidia-smi命令或在日志中查看确保没有超出GPU显存。训练完成后模型检查点包含LoRA权重会保存在你指定的输出目录中默认为./saves。6. 模型测试、导出与部署训练结束不是终点让模型用起来才是。6.1 在Web界面中测试训练时或训练后你可以切换到“聊天”标签页。在“模型适配器”选项中选择你刚刚训练得到的检查点目录例如./saves/qwen2.5-7b-instruct-lora/lora。然后加载模型就可以与微调后的模型进行对话测试其在新任务上的表现。6.2 合并与导出模型LoRA训练产生的是一个小型的适配器文件而不是完整的模型。要部署为一个独立模型需要将其与基础模型合并。在Web UI的“导出”标签页选择你训练好的适配器路径。选择基础模型路径即你最开始下载的原始模型。选择导出格式Hugging Face格式这是最通用的格式可以继续用transformers库加载。适合后续的Python API服务部署。GGUF格式这是llama.cpp项目推出的量化格式可以在CPU或边缘设备上高效运行非常适合本地桌面应用或资源受限的环境。导出时可以选择量化精度如Q4_K_M, Q5_K_S等。点击“开始导出”。合并后的模型会保存在指定目录。6.3 简易API服务部署LLaMA-Factory内置了基于Gradio或FastAPI的部署脚本。最简单的是使用其WebUI的“聊天”页面本身作为演示。对于生产环境更推荐使用其提供的API脚本。例如使用FastAPI部署python src/api_demo.py \ --model_name_or_path ./models/Qwen2.5-7B-Instruct \ # 基础模型路径 --adapter_name_or_path ./saves/qwen2.5-7b-instruct-lora/lora \ # (可选) LoRA适配器路径 --template qwen \ # 使用Qwen的对话模板 --finetuning_type lora \ # 微调类型 --server_name 0.0.0.0 \ # 允许外部访问 --server_port 8000 # 指定端口运行后你就拥有了一个提供/chat/completions等标准接口的本地大模型API服务可以被其他应用程序调用。7. 避坑指南与实战经验走通流程不难但想高效、稳定地训练出好模型需要避开很多坑。环境与安装类问题“Torch not compiled with CUDA enabled”PyTorch安装成了CPU版本。严格按照CUDA版本去PyTorch官网找安装命令并用python -c “import torch; print(torch.cuda.is_available())”验证。“Out of Memory”这是常态。解决方案1) 使用QLoRA而不是全量微调2) 减小batch_size和max_length3) 开启梯度检查点gradient_checkpointingTrue用计算时间换显存4) 使用更激进的量化如4-bit。下载模型中断使用huggingface-cli的--resume-download参数。或者用wget或curl配合镜像站地址直接下载大文件。训练过程类问题损失值为NaN或无限大通常是学习率设置过高。尝试将学习率降低一个数量级例如从2e-4降到2e-5。也可能是数据中存在异常值检查数据清洗。模型“学废了”输出乱码或重复可能是数据质量差、数据格式不对、或者学习率/轮次设置不当。从小数据集、低学习率开始调试。确保你的数据格式与选择的“数据集格式”完全匹配。验证损失不降反升这是明显的过拟合。立即停止训练。增加训练数据量、为模型添加Dropout、使用更早的检查点验证损失最低的那个、或者减少训练轮次。资源与效率优化使用Flash Attention 2如果你的GPU架构支持如Ampere架构的RTX 30系列及以上安装flash-attn库可以显著加速训练并减少显存占用。但它的安装有时比较麻烦需要预编译。混合精度训练LLaMA-Factory默认开启fp16或bf16混合精度训练在保持精度的情况下加速并节省显存。确保你的硬件支持现代GPU都支持。多GPU训练如果你有多张GPU可以使用accelerate或deepspeed进行分布式训练。在LLaMA-Factory中可以通过配置accelerate配置文件来实现。这对于大规模全参数微调是必要的。一个真实的调试案例我曾经用一批法律问答数据微调一个模型训练损失正常下降但模型在测试时总是生成与法律无关的通用回答。排查后发现是数据中“instruction”字段写得太模糊例如“回答以下问题”而“input”字段包含了具体的法律问题。模型只关注了“instruction”而忽略了“input”。将问题内容合并到“instruction”中例如“根据中国合同法回答以下问题…”问题就解决了。数据格式的细节直接决定了模型学习的目标。最后大模型微调既是科学也是艺术。LLaMA-Factory为我们提供了强大的工具但如何准备数据、如何调参、如何评估仍然需要大量的实践和迭代。从一个小而精的数据集开始跑通整个流程获得第一个微调成功的模型这种正反馈是学习的最佳动力。然后再逐步挑战更复杂的任务和更大的模型。记住每次训练都是一次实验详细记录你的配置、数据和结果这是你积累经验、形成直觉的最宝贵财富。
