1. 环境准备：从零开始的第一个脚印

想玩转LLaMaFactory，第一步就是把环境搭好。这听起来可能有点技术门槛，但别担心，跟着我的步骤走，十分钟内你就能搞定。我自己刚开始用的时候，也踩过几个小坑，比如Python版本不对、依赖包冲突，后来总结了一套最稳的流程，保证你一次成功。

首先，你得有个Python环境。我强烈建议使用Anaconda或者Miniconda来管理，它能帮你把不同项目的环境隔离开，避免“包打架”的惨剧。如果你还没装，去官网下一个，安装过程一路点“下一步”就行。装好之后，打开你的终端（Windows叫命令提示符或PowerShell，Mac/Linux叫Terminal），我们正式开始。

第一步，创建一个专属于LLaMaFactory的虚拟环境。为什么非要创建？因为大模型相关的库版本要求很严格，直接用你系统里可能已经有的Python环境，很容易出问题。我们用下面这个命令创建一个叫llamafactory的新环境，并指定Python版本为3.10（这是目前兼容性最好的版本之一）：

conda create -n llamafactory python=3.10

创建完成后，激活这个环境。激活的意思就是“进入”这个环境，之后你安装的所有包，都只在这个“小房间”里，不会影响到外面。

conda activate llamafactory

看到命令行前面出现(llamafactory)的提示了吗？这就说明你已经成功进来了。接下来，我们需要把LLaMaFactory这个工具本身“请”到你的电脑里。最直接的方式就是从GitHub上克隆它的代码仓库。确保你还在一个合适的目录下（比如你的用户主目录或者一个专门的项目文件夹），然后执行：

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

进入项目目录后，安装项目依赖。这里有个关键点：LLaMaFactory依赖一个叫torch（PyTorch）的深度学习框架，而PyTorch的安装命令和你的电脑是否有GPU、是什么型号的GPU息息相关。如果你有一张NVIDIA的显卡，并且想利用它来加速（这非常重要，否则模型跑起来会像蜗牛），你需要先去PyTorch官网根据你的CUDA版本（一个GPU计算平台）生成对应的安装命令。假设你的CUDA版本是11.8，那么安装命令大概是这样的：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

如果你没有GPU，或者暂时不想折腾，那就安装CPU版本的PyTorch，不过后续运行模型会非常慢，只适合体验流程：

pip install torch torchvision torchaudio

安装好PyTorch后，再安装LLaMaFactory所需的其他依赖就简单了。项目提供了一个requirements.txt文件，里面列出了所有需要的包和版本。直接运行：

pip install -r requirements.txt

这个过程可能会花上几分钟，取决于你的网速。安装完成后，我建议你再顺手安装一个modelscope库，它是阿里开源的模型社区，很多国内优秀的模型（比如通义千问Qwen系列）都托管在上面，用它的工具下载模型会非常方便：

pip install modelscope

好了，至此，你的LLaMaFactory“作战基地”就已经搭建完毕了。你可以通过一个简单的命令来验证安装是否成功：

llamafactory-cli version

如果它输出了类似LLaMA-Factory, version 0.7.0这样的版本信息，那么恭喜你，环境准备这一关，你已经满分通过了。接下来，我们就可以去“搬”一个真正的大模型过来了。

2. 模型获取与加载：给你的引擎装上“大脑”

环境好了，工具齐了，现在缺的就是核心——大语言模型本身。你可以把模型理解为一辆超级跑车的引擎，没有它，再好的工具（车身）也跑不起来。LLaMaFactory本身不提供模型，但它是一个超级好用的“引擎适配器和调试台”，支持市面上绝大多数主流开源模型。

获取模型主要有两种方式：从Hugging Face Hub下载，或者从ModelScope下载。前者是国际主流社区，模型最全；后者是国内镜像，下载速度往往更快，尤其对于Qwen、ChatGLM、Yi等国产优秀模型支持很好。我两种都用，通常看哪个快用哪个。

从ModelScope下载：比如我们想试试最新的Qwen2.5-0.5B-Instruct模型（一个非常小巧但能力不错的指令微调模型）。在之前安装好的llamafactory环境中，你可以打开一个Python交互界面，或者创建一个.py脚本文件，运行以下代码：

from modelscope import snapshot_download
model_dir = snapshot_download('Qwen/Qwen2.5-0.5B-Instruct')
print(f"模型已下载到：{model_dir}")

这段代码会启动下载流程，并将模型保存到本地缓存目录（通常是~/.cache/modelscope/hub/）。下载完成后，它会打印出模型在本地的具体路径，比如/home/username/.cache/modelscope/hub/Qwen/Qwen2.5-0.5B-Instruct。这个路径非常重要，待会儿启动服务时需要用到。

从Hugging Face下载：LLaMaFactory原生支持Hugging Face格式的模型。你甚至可以不预先下载，直接在命令中指定模型名称，工具会在第一次运行时自动帮你下载。例如，你想使用Meta的Llama 3 8B模型：

CUDA_VISIBLE_DEVICES=0 llamafactory-cli webchat \
  --model_name_or_path meta-llama/Meta-Llama-3-8B-Instruct \
  --template llama3

当你执行这个命令时，它会检查本地缓存是否有这个模型，如果没有，就会从Hugging Face下载。这对于快速尝鲜非常方便。但如果你网络不稳定，或者想离线使用，我更推荐先用git lfs或huggingface-cli工具把模型完整地克隆到本地，然后再用本地路径加载。

模型下载下来后，我们来看看怎么把它“启动”成一个能聊天的服务。这里就要用到LLaMaFactory最核心的命令行工具llamafactory-cli了。我们以一个实际的例子，启动刚下载的Qwen3-0.6B模型的网页聊天界面：

CUDA_VISIBLE_DEVICES=0 llamafactory-cli webchat \
  --model_name_or_path /root/.cache/modelscope/hub/Qwen/Qwen3-0.6B \
  --template qwen

让我拆解一下这个命令的每个部分：

  • CUDA_VISIBLE_DEVICES=0：这行告诉系统，只使用我电脑上的第一张GPU（编号0）。如果你有多张卡，比如想用第0和第1张卡，就写成0,1。如果没有GPU，去掉这行前缀，程序会使用CPU运行（但会很慢）。
  • llamafactory-cli webchat：这是调用LLaMaFactory的Web聊天功能，它会启动一个本地的Web服务器，并自动打开你的浏览器。
  • --model_name_or_path：后面跟的就是模型在你电脑上的本地路径，或者Hugging Face上的模型ID。一定要确保路径正确。
  • --template qwen：这是至关重要的一个参数。它指定了使用“qwen”这个对话模板。模板决定了如何将你的对话内容（比如“你好”）转换成模型能理解的格式（加上特定的角色标记、特殊符号等）。用错了模板，模型可能无法正确理解你的意图，或者输出乱码。

执行这条命令后，终端会开始加载模型到显存，你会看到一些加载进度条和日志。加载完成后，通常会默认在浏览器中打开一个地址，比如http://127.0.0.1:7860。一个简洁的聊天界面就出现在你面前了！你可以在输入框里问它问题，比如“用Python写一个快速排序函数”，它就会像ChatGPT一样给你生成答案。第一次看到自己部署的模型在本地回答问题，那种成就感是非常棒的。

3. 理解与配置对话模板：让模型“说人话”的关键

刚才我们反复提到了--template参数，它可能是在使用LLaMaFactory时，除了模型本身之外，最重要的一个配置了。很多新手朋友部署完模型，发现模型回答得驴唇不对马嘴，或者干脆不按指令格式输出，十有八九就是模板没选对。

那么，模板到底是什么？你可以把它想象成模型与人类之间的翻译官和协议。大语言模型在训练时，接收的输入并不是纯文本，而是一种结构化的、带有特殊标记的序列。例如，在Qwen模型的训练数据中，一段对话可能被格式化成这样： <|im_start|>user\n你好<|im_end|>\n<|im_start|>assistant\n你好！有什么可以帮助你的吗？<|im_end|>\n

这里的<|im_start|>、<|im_end|>、user、assistant就是Qwen模型能识别的特殊标记和角色定义。template的作用，就是当我们输入“你好”时，自动帮我们把这些标记按正确的顺序和格式拼接好，再送给模型。模型看到它熟悉的格式，就知道“哦，这是一个用户的问题，我需要以助手的身份来回答”，然后它生成的输出，模板再帮我们把assistant角色之后的内容提取出来，展示给我们看。

LLaMaFactory内置了海量模型的模板，几乎覆盖了所有主流开源模型。怎么知道我的模型该用哪个模板呢？主要有三个方法：

  1. 查官方文档或列表：LLaMaFactory的GitHub Wiki或源码里通常有一个模型与模板的对应表。就像原始文章里列出的那个简表一样，你可以快速查找。
  2. 看模型来源的说明：在Hugging Face或ModelScope的模型卡片页面，作者通常会注明推荐的对话格式或chat_template。比如Qwen的页面就会写“请使用chatml格式”，而在LLaMaFactory中，qwen模板就是对chatml格式的实现。
  3. 试错法：如果实在不确定，可以先用一个猜测的模板（比如同系列模型的通用模板）启动聊天，然后问模型一个简单的问题，比如“你是谁？”。如果模型能正确回答出自己的身份，说明模板基本正确。如果它输出一堆乱码、重复你的问题、或者前言不搭后语，那就换个模板再试。

这里我分享一个我常用的模板选择速查经验：

  • Qwen系列（千问）：一律用 --template qwen。从Qwen1.5到Qwen2.5，再到Qwen3，这个模板都适用。
  • Llama系列（羊驼）：这是个大家族，要仔细区分。
    • 原始的Llama（v1）：--template llama（但很少用了）。
    • Llama 2：--template llama2。
    • Llama 3 / Llama 3.1 / Llama 3.2：--template llama3。这是目前最常用的。
  • ChatGLM系列（智谱）：--template chatglm3。对于ChatGLM3模型，这个模板是必须的。
  • Yi系列（零一万物）：--template yi。
  • DeepSeek系列：--template deepseek。注意，DeepSeek-V2（MoE模型）和DeepSeek-R1（推理模型）有专门的模板deepseek3和deepseekr1，不要搞混。
  • 通用保底：如果你用的模型非常小众，找不到对应模板，可以尝试 --template default。这是一个最基础的模板，可能不完美，但有时能让模型跑起来。

配置模板不仅仅在webchat中使用，在后续的训练、评测、API服务等所有需要与模型交互的场景中，都必须正确指定。它是你和模型能够顺利沟通的基石，花点时间理解它，绝对值得。

4. 核心功能实战：不止于聊天

LLaMaFactory之所以强大，是因为它远不止一个聊天界面。它是一套完整的、从模型微调、评估到部署的流水线工具。掌握了这些，你才算是真正玩转了LLaMaFactory。下面我挑几个最实用的功能，带你实际操作一遍。

4.1 模型训练与微调：打造专属模型

你可能会想，我直接用现成的模型不就好了，为什么要训练？因为通用模型可能不了解你专业领域的知识，或者不符合你想要的对话风格。微调（Fine-tuning）就是用你自己的数据，对预训练好的大模型进行“二次教育”，让它更擅长某个特定任务。

LLaMaFactory让微调变得异常简单。假设我们有一些高质量的指令-回答对数据（格式类似Alpaca数据集），我们想用这些数据在Qwen1.5-4B模型上做微调。单张GPU的训练命令如下：

CUDA_VISIBLE_DEVICES=0 llamafactory-cli train \
  --model_name_or_path Qwen/Qwen1.5-4B \
  --dataset alpaca_en \
  --template qwen \
  --finetuning_type lora \
  --output_dir ./qwen_lora_output

这个命令做了以下几件事：

  1. 加载Qwen1.5-4B模型作为基座。
  2. 使用内置的alpaca_en（英文Alpaca格式）数据集。你也可以通过--dataset my_data指定自己的数据文件。
  3. 指定使用qwen模板来处理数据格式。
  4. --finetuning_type lora 是关键！它表示我们采用LoRA这种高效的微调方法。LoRA只训练模型中新增的一小部分参数，而不是整个巨大的模型，因此速度极快、显存占用极小，效果却接近全参数微调。这是个人开发者微调大模型的首选技术。
  5. 训练过程中的检查点和最终模型会保存到./qwen_lora_output目录。

如果你的机器有多张GPU，可以利用起来加速训练。比如用两张卡训练Llama3-8B模型，并启用BF16混合精度和DeepSpeed优化来节省显存：

CUDA_VISIBLE_DEVICES=0,1 llamafactory-cli train \
  --model_name_or_path meta-llama/Llama3-8B-Instruct \
  --dataset alpaca_en,code_alpaca \
  --template llama3 \
  --finetuning_type lora \
  --bf16 true \
  --deepspeed configs/ds_config.json \
  --output_dir ./llama3_lora_output

训练开始后，终端会显示损失（loss）下降的曲线。你可以随时按Ctrl+C中断训练，模型会保存最后一个检查点。训练好的LoRA适配器文件就保存在输出目录里，它很小（通常只有几十MB），方便分享和部署。

4.2 模型推理与评测：检验成果

训练完之后，我们肯定要试试效果。LLaMaFactory提供了多种推理方式。

命令行聊天：最轻量快捷的方式。加载我们刚刚微调好的模型（假设检查点步数是1000）进行对话：

llamafactory-cli chat \
  --model_name_or_path ./qwen_lora_output/checkpoint-1000 \
  --template qwen \
  --quantization_bit 4

注意，这里--model_name_or_path指向的是训练输出目录下的具体检查点。--quantization_bit 4表示使用4位量化加载模型，这能大幅减少模型运行时的显存占用（可能从8G降到4G），让大模型在消费级显卡上跑起来，代价是精度有轻微损失，但对于对话通常感知不强。

启动API服务：如果你想把你微调好的模型集成到自己的应用里，比如做个微信机器人或者内部知识问答系统，启动一个API服务是最佳选择。

CUDA_VISIBLE_DEVICES=0 llamafactory-cli api \
  --model_name_or_path ./qwen_lora_output/checkpoint-1000 \
  --template qwen \
  --port 8080

执行后，一个遵循OpenAI API格式的接口服务就在本地的8080端口启动了。你可以用curl、Postman或者任何编程语言来调用它。例如，用curl发送一个请求：

curl -X POST http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [{"role": "user", "content": "你好，介绍一下你自己"}],
    "temperature": 0.7
  }'

模型评测：光靠感觉不行，我们需要定量评估模型的能力。LLaMaFactory集成了对标准学术数据集（如MMLU、C-Eval）的评测功能。

llamafactory-cli eval \
  --model_name_or_path ./qwen_lora_output/checkpoint-1000 \
  --eval_dataset mmlu \
  --template qwen \
  --batch_size 4

这个命令会在MMLU（一个涵盖57个学科的多选题数据集）上测试你的模型，并给出一个准确率分数。你可以用这个分数来比较不同微调策略的效果，或者对比其他模型。

4.3 模型合并与导出：生成最终产品

我们之前用LoRA微调，得到的是一个独立的“小补丁”（适配器）。要把它变成一个可以独立加载、方便分发的完整模型文件，就需要进行“合并”操作。

llamafactory-cli export \
  --model_name_or_path Qwen/Qwen1.5-4B \
  --adapter_name_or_path ./qwen_lora_output \
  --template qwen \
  --export_dir ./my_finetuned_qwen1.5-4b

这个命令将基座模型（Qwen1.5-4B）和LoRA适配器的权重合并，生成一个完整的、全新的模型，保存在./my_finetuned_qwen1.5-4b目录下。这个目录的结构和原始Hugging Face模型一模一样，你可以像使用任何原生模型一样使用它。

更进一步，如果你想在手机端（比如通过llama.cpp）或者资源更受限的环境下运行模型，可以将其导出为GGUF格式。GGUF是一种高效、跨平台的模型格式，支持多种量化等级。

llamafactory-cli export \
  --model_name_or_path ./my_finetuned_qwen1.5-4b \
  --export_gguf true \
  --quantization_bit q4_k_m \
  --export_dir ./my_finetuned_qwen1.5-4b-gguf

这里--quantization_bit q4_k_m指定了量化类型（4位，中等质量）。导出的.gguf文件就可以被llama.cpp、Ollama等轻量级推理引擎直接加载，在MacBook甚至树莓派上运行。

5. 可视化利器：WebUI与LlamaBoard

如果你觉得命令行不够直观，LLaMaFactory还提供了强大的可视化界面，几乎涵盖了所有核心功能。

一体化WebUI：这是我最推荐新手使用的入口。一个命令，启动包含训练、聊天、评测、模型合并等所有功能的图形化界面。

llamafactory-cli webui \
  --model_name_or_path Qwen/Qwen1.5-7B \
  --template qwen

启动后，在浏览器中你会看到一个非常专业的界面。在“训练”标签页，你可以通过点选的方式配置模型、数据集、训练参数（学习率、批次大小等），然后点击“开始训练”，下方会实时显示训练损失曲线和日志。在“聊天”标签页，可以方便地对话。在“模型”标签页，可以可视化地合并模型、导出GGUF。这大大降低了操作门槛，让你能更专注于任务本身，而不是记忆复杂的命令参数。

LlamaBoard（高级WebUI）：webui命令启动的是较新的界面。项目有时也将更早的、功能更丰富的可视化界面称为LlamaBoard，它可能通过llamafactory-cli webui --llamaboard或独立的命令启动。这个界面通常提供更详细的训练监控、实验对比等功能，适合进行严肃的模型迭代研究。

从我自己的使用经验来看，命令行（CLI）适合自动化、可重复的流程和集成到脚本中，比如你有一套固定的微调流水线。而WebUI适合探索、实验和快速原型验证，特别是当你需要频繁调整参数看效果的时候。两者结合，让LLaMaFactory既能满足工程化的需求，又能提供友好的用户体验。

6. 常见问题与避坑指南

玩了这么久LLaMaFactory，坑肯定没少踩。这里我把一些典型问题和解决方案分享给你，希望能帮你节省大量折腾的时间。

问题一：显存不足（CUDA out of memory） 这是最常见的问题。大模型就是“显存吞噬兽”。解决方案有组合拳：

  1. 使用量化：在命令中添加--quantization_bit 4或8。这是最有效的一招。
  2. 使用更小的模型：从7B、8B模型开始尝试，而不是一上来就搞70B的。
  3. 启用梯度检查点：在训练命令中加--gradient_checkpointing true，用计算时间换显存空间。
  4. 减小批次大小：降低--per_device_train_batch_size的值（比如从4降到2）。
  5. 使用LoRA：微调时务必使用--finetuning_type lora，全参数微调（full）的显存需求是LoRA的很多倍。

问题二：模型回答乱码或不符合预期 首先，99%的情况是模板（--template）选错了。请严格按照第三节的方法核对。其次，检查你的输入是否包含奇怪的字符或格式。最后，有些模型需要特定的“系统提示词”（system prompt）来引导行为，你可以在聊天或API调用时，在messages列表的最开始加入{"role": "system", "content": "你是一个乐于助人的助手。"}这样的消息。

问题三：下载模型速度慢或失败 对于国内用户，下载Hugging Face模型可能很慢。解决办法：

  1. 优先使用ModelScope上的镜像模型（如果有的话）。
  2. 配置Hugging Face镜像源。在终端设置环境变量：export HF_ENDPOINT=https://hf-mirror.com，然后再运行下载命令。
  3. 对于特别大的模型，可以尝试先用下载工具（如huggingface-cli download或git lfs）单独下载，然后再用本地路径加载。

问题四：训练损失（loss）不下降或为NaN 这可能是学习率设置不当、数据格式有问题或梯度爆炸导致的。

  1. 尝试降低学习率--learning_rate，比如从2e-4降到1e-5。
  2. 检查你的训练数据格式是否与所选模板匹配。LLaMaFactory通常要求数据是instruction-input-output的JSON格式。
  3. 尝试加入梯度裁剪：--max_grad_norm 1.0。
  4. 如果是LoRA训练，可以尝试调整--lora_rank（如设为8或16）和--lora_alpha（如设为32）参数。

问题五：如何管理多个模型和实验 随着你玩的模型越来越多，会产生很多缓存文件、训练输出目录。建议做好文件管理：

  • 模型缓存：Hugging Face的默认缓存路径是~/.cache/huggingface/hub/，ModelScope的是~/.cache/modelscope/hub/。你可以通过环境变量HF_HOME和MODELSCOPE_CACHE来修改它们的位置，比如放到一块大容量的硬盘上。
  • 实验记录：每次训练，在--output_dir中使用有意义的名称，例如./output_qwen1.5-4b_lora_alpaca_20250101，并最好能在一个README文件里简单记录下使用的参数和数据集。

说到底，LLaMaFactory就像一个功能极其丰富的“大模型瑞士军刀”。从下载、对话、微调到部署，它把原本需要深厚工程背景才能完成的工作，封装成了简单的命令和点击操作。我亲眼看着它从一个简陋的工具，成长到现在这个几乎能一站式解决大部分开源大模型使用需求的平台。对于任何想深入接触和实践大语言模型的开发者来说，花时间熟练掌握LLaMaFactory，绝对是性价比最高的投资之一。它让你能跳过繁琐的环境搭建和底层代码，直接聚焦于模型的应用、优化和创新本身。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

终极优化：Qwen3-VL-8B-Instruct-w8a8-llmcompressor-v0.12.0的OpenMP配置与ZenDNN加速技巧

Qwen3-VL-8B-Instruct-w8a8-llmcompressor-v0.12.0是一款高效的多模态大模型，通过8位量化（W8A8）技术实现了性能与效率的平衡。本文将介绍如何通过OpenMP配置和ZenDNN加速技术，充分发挥AMD硬件优势，让模型在保持精度的同时获得更快推理速度。## 模型量化基础：W8A8方案解析该模型采用了创新的8位量化方案，通过[config.json]

avatar DeepSeek技术社区

为什么选择mlx-community/DeepSeek-V4-Pro-Qwen3.5-9B-4bit？4bit量化如何实现高效推理与多模态融合

mlx-community/DeepSeek-V4-Pro-Qwen3.5-9B-4bit是一款基于MLX框架优化的4bit量化模型，专为Apple Silicon设备打造，通过高效压缩技术实现了大模型在本地设备上的快速部署与多模态融合能力。该模型源自Jackrong/DeepSeek-V4-Pro-Qwen3.5-9B基础模型，保留了原始模型的文本编码、图像理解和视频处理功能，同时通过4bit量

avatar DeepSeek技术社区

告别图层混乱：如何用Qwen-Image-Layered实现真正的无损图像编辑

你有没有遇到过这样的烦恼？想要修改一张图片中的某个元素，却发现这个元素和其他内容紧密融合，一动就会破坏整个画面。传统的图像编辑工具常常让你在"牵一发而动全身"的困境中挣扎，要么接受不完美的修改，要么花费数小时进行繁琐的选区工作。现在，想象一下这样的场景：你上传一张照片，AI能自动识别并分离出其中的不同元素——人物、背景、文字、装饰物——每个元素都成为一个独立的透明图层。你可以单独调整任何一个图

avatar DeepSeek技术社区