1.安装LLaMA Factory

git clone --depth 1 https://github.com/hiyouga/LlamaFactory.git
cd LlamaFactory
pip install -e .
pip install -r requirements/metrics.txt

2.快速开始

下面三行命令分别对 Qwen3-4B-Instruct 模型进行 LoRA 微调、推理和合并。

llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml
llamafactory-cli chat examples/inference/qwen3_lora_sft.yaml
llamafactory-cli export examples/merge_lora/qwen3_lora_sft.yaml

3.下载模型

https://modelscope.cn/models/Qwen/Qwen3-4B-Instruct-2507

4.关键文件介绍

这三个文件是 LLaMA-Factory 工作流中最核心的“三驾马车”。它们分别对应了大模型微调项目的三个关键阶段：训练、体验和部署。

简单来说，这是一个从“教模型”到“考模型”再到“带模型出门”的完整闭环。

以下是详细的介绍：

1. 训练阶段：examples/train_lora/qwen3_lora_sft.yaml

• 对应命令：llamafactory-cli train ...

• 核心作用：“教模型”。 这是整个流程的起点。这个文件定义了怎么学。

• 关键配置

### model
model_name_or_path: Qwen/Qwen3-4B-Instruct-2507
trust_remote_code: true

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 8
lora_target: all

### dataset
dataset: identity,alpaca_en_demo
template: qwen3_nothink
cutoff_len: 2048
max_samples: 1000
preprocessing_num_workers: 16
dataloader_num_workers: 4

### output
output_dir: saves/qwen3-4b/lora/sft
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true
save_only_model: false
report_to: none  # choices: [none, wandb, tensorboard, swanlab, mlflow]

### train
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 1.0e-4
num_train_epochs: 3.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: true
ddp_timeout: 180000000
resume_from_checkpoint: null

### eval
# eval_dataset: alpaca_en_demo
# val_size: 0.1
# per_device_eval_batch_size: 1
# eval_strategy: steps
# eval_steps: 500

学什么：指定数据集（dataset: sft_data）和对话模板（template: qwen3）。

怎么学：设定学习率（learning_rate）、训练轮数（num_train_epochs）、批次大小（per_device_train_batch_size）。

学多少：配置 LoRA 的参数，比如秩（lora_rank: 8）和目标模块（lora_target: all）。

产出：运行后，你会得到一个新的文件夹（通常在 saves/ 目录下），里面包含训练好的 LoRA 权重文件（adapter_model.bin）。

2. 体验/验证阶段：examples/inference/qwen3_lora_sft.yaml

• 对应命令：llamafactory-cli chat ...

• 核心作用：“考模型”。 训练完后，你不需要把模型部署到服务器，而是想先在命令行里跟它聊聊天，看看效果好不好。这个文件定义了怎么聊。

• 关键配置

model_name_or_path: Qwen/Qwen3-4B-Instruct-2507
adapter_name_or_path: saves/qwen3-4b/lora/sft
template: qwen3_nothink
infer_backend: huggingface  # choices: [huggingface, vllm, sglang, ktransformers]
trust_remote_code: true

加载谁：它需要同时指定**基础模型**（`model_name_or_path`）和刚才训练出来的 **LoRA 权重**（`adapter_name_or_path`）。
  用什么引擎：这里就是你刚才问到的 `infer_backend: huggingface` 或 `vllm`。
 格式：必须保持和训练时一样的对话模板（`template: qwen3`），否则模型会听不懂人话。

产出：一个交互式的命令行界面，你可以输入问题，模型实时回答。

3. 部署/导出阶段：examples/merge_lora/qwen3_lora_sft.yaml

• 对应命令：llamafactory-cli export ...

• 核心作用：“打包模型”。 LoRA 权重只是一个“补丁”，不能独立运行。如果你要把模型发给别人，或者部署到生产环境，通常希望它是一个独立的、完整的模型文件。这个文件定义了怎么合。

• 关键配置

### Note: DO NOT use quantized model or quantization_bit when merging lora adapters

### model
model_name_or_path: Qwen/Qwen3-4B-Instruct-2507
adapter_name_or_path: saves/qwen3-4b/lora/sft
template: qwen3_nothink
trust_remote_code: true

### export
export_dir: saves/qwen3_sft_merged
export_size: 5
export_device: cpu  # choices: [cpu, auto]
export_legacy_format: false

源文件：指定基础模型路径和 LoRA 权重路径。
去向：指定合并后的模型保存路径（`export_dir`）。
 注意：这里通常要求基础模型必须是 FP16/BF16 格式，**不能是量化过的（如 INT4/INT8）**，否则合并会失败或精度受损。

产出：一个**全新的、独立的模型文件夹**。这个文件夹里包含了所有权重，不再依赖 LoRA 插件，可以直接被任何支持该架构的工具加载。

5.参数介绍

1.safetesnsors 是什么？

        Safetensors 是一种用于安全存储张量（如模型权重）的新型文件格式，由 Hugging Face 团队开发，旨在解决传统格式（如 .pth 或 .bin）在安全性和加载效率上的不足。它不包含可执行代码，仅存储张量数据，因此在加载来自不可信来源的模型时更安全，且支持零拷贝加载，速度极快。

!pip install safetensors

from safetensors import safe_open

with safe_open("adapter_model.safetensors", framework="pt", device=0) as f:
    for key in f.keys():
        tensor = f.get_tensor(key)
        # 处理 tensor查看
        print(tensor)

6.interence参数介绍

infer_backend: huggingface # choices: [huggingface, vllm, sglang, ktransformers]

指定模型在推理（运行/对话）时，底层使用哪个“引擎”来驱动。

选项	特点描述	适用场景
huggingface	默认选项。兼容性最强，几乎支持所有模型，无需额外安装复杂依赖source_group_web_4。但推理速度相对较慢，显存利用率一般。	调试、开发、快速验证。
vllm	高性能。通过 PagedAttention 技术极大提升吞吐量，推理速度极快，显存占用更低source_group_web_6。	生产环境、批量处理。
sglang	极速/新架构。比 vLLM 更新，针对复杂提示词（如多轮对话、Agent）有专门优化，速度往往更快source_group_web_8。	追求极致速度、复杂 Agent 应用。适合对延迟极其敏感的场景。
ktransformers	特定优化。通常指针对特定硬件或架构优化的内核版本（较少见，视具体版本而定）。	特定硬件优化场景。

7.使用API进行批量推理

准备 API 配置文件api_config.yaml，用于告诉服务加载哪个模型、使用哪个推理后端以及端口是多少。

### model
# 这里填入你的本地绝对路径
model_name_or_path: /mnt/workspace/.cache/modelscope/models/Qwen/Qwen3-4B-Instruct-2507
​
# 如果有 LoRA 权重，也填入路径；如果是合并模型则留空或注释掉
# adapter_name_or_path: saves/qwen3-4b/lora/sft 
​
template: qwen3_nothink
trust_remote_code: true
infer_backend: vllm  # 推荐使用 vllm 以获得更快的推理速度

在根目录下使用命令行启动

# 指定端口为 8000，使用第 0 号 GPU
API_PORT=8000 CUDA_VISIBLE_DEVICES=0 llamafactory-cli api api_config.yaml

使用脚本进行批量推理

from openai import OpenAI
​
# 初始化客户端
client = OpenAI(
    api_key="0", 
    base_url="http://localhost:8000/v1"
)
​
# 1. 定义批量问题列表
questions = [
    "你好，请介绍一下你自己",
    "量子力学是什么？",
    "如何用 Python 写一个冒泡排序？"
]
​
print(f"开始批量推理，共 {len(questions)} 个问题...\n" + "-"*30)
​
# 2. 循环发送请求
for i, question in enumerate(questions):
    try:
        response = client.chat.completions.create(
            model="Qwen3-4B", 
            messages=[
                {"role": "user", "content": question}
            ],
            temperature=0.7
        )
        
        # 获取回答内容
        answer = response.choices[0].message.content
        
        # 打印结果
        print(f"[问题 {i+1}]: {question}")
        print(f"[回答]: {answer}")
        print("-" * 30)
        
    except Exception as e:
        print(f"请求 {i+1} 失败: {e}")
​
print("所有推理完成！")