> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monostate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LoRA & PEFT

> 使用适配器进行高效微调

# LoRA & PEFT

参数高效微调让您可以用更少的内存训练大型模型。

## 什么是 LoRA？

LoRA（Low-Rank Adaptation）向模型添加小的可训练矩阵，同时保持基础权重冻结。这大大减少了内存使用和训练时间。

## 快速开始

```bash theme={null}
aitraining llm --train \
  --model meta-llama/Llama-3.2-1B \
  --data-path ./data.jsonl \
  --project-name lora-model \
  --peft \
  --lora-r 16 \
  --lora-alpha 32
```

## Python API

```python theme={null}
from autotrain.trainers.clm.params import LLMTrainingParams
from autotrain.project import AutoTrainProject

params = LLMTrainingParams(
    model="meta-llama/Llama-3.2-1B",
    data_path="./data.jsonl",
    project_name="lora-model",

    trainer="sft",

    # LoRA configuration
    peft=True,
    lora_r=16,
    lora_alpha=32,
    lora_dropout=0.05,
    target_modules="all-linear",  # Default: all-linear

    epochs=3,
    batch_size=4,
    lr=2e-4,  # Higher LR works with LoRA
)

project = AutoTrainProject(params=params, backend="local", process=True)
project.create()
```

## 参数

| 参数               | 描述        | 默认值          |
| ---------------- | --------- | ------------ |
| `peft`           | 启用 LoRA   | `False`      |
| `lora_r`         | 秩（适配器大小）  | `16`         |
| `lora_alpha`     | 缩放因子      | `32`         |
| `lora_dropout`   | Dropout 率 | `0.05`       |
| `target_modules` | 要适配的模块    | `all-linear` |

### 秩 (lora\_r)

更高的秩 = 更多参数 = 更大容量：

| 秩     | 使用场景        |
| ----- | ----------- |
| 8     | 简单任务，内存非常受限 |
| 16    | 标准（推荐）      |
| 32-64 | 复杂任务，更多可用内存 |
| 128+  | 接近完整微调容量    |

### Alpha

alpha/秩 比率影响学习：

```python theme={null}
# 标准缩放
lora_r=16
lora_alpha=32  # alpha/r = 2

# 更激进
lora_r=16
lora_alpha=64  # alpha/r = 4

# 保守
lora_r=16
lora_alpha=16  # alpha/r = 1
```

### 目标模块

默认情况下，LoRA 针对所有线性层（`all-linear`）。您可以自定义：

```python theme={null}
# All linear layers (default)
target_modules="all-linear"

# Attention layers only
target_modules="q_proj,k_proj,v_proj,o_proj"

# Include MLP
target_modules="q_proj,k_proj,v_proj,o_proj,gate_proj,up_proj,down_proj"
```

## 与量化结合

将 LoRA 与量化结合以获得最大内存节省：

```bash theme={null}
aitraining llm --train \
  --model meta-llama/Llama-3.2-8B \
  --data-path ./data.jsonl \
  --project-name quantized-lora \
  --peft \
  --quantization int4
```

```python theme={null}
params = LLMTrainingParams(
    model="meta-llama/Llama-3.2-8B",
    data_path="./data.jsonl",
    project_name="quantized-lora",

    peft=True,
    lora_r=16,
    quantization="int4",  # or "int8"
)
```

## 内存对比

| 模型  | 完整微调   | LoRA  | LoRA + 4bit |
| --- | ------ | ----- | ----------- |
| 1B  | 8 GB   | 4 GB  | 3 GB        |
| 7B  | 56 GB  | 16 GB | 8 GB        |
| 13B | 104 GB | 32 GB | 16 GB       |

## 合并适配器

默认情况下，LoRA 适配器在训练后**自动合并**到基础模型中。这简化了推理 - 您得到一个可以直接使用的单一模型文件。

### 默认行为（合并）

```python theme={null}
params = LLMTrainingParams(
    ...
    peft=True,
    # merge_adapter=True is the default
)
```

### 仅保存适配器

仅保存适配器文件（更小，但推理需要基础模型）：

```bash theme={null}
aitraining llm --train \
  --model meta-llama/Llama-3.2-1B \
  --data-path ./data.jsonl \
  --project-name lora-model \
  --peft \
  --no-merge-adapter
```

### 稍后手动合并

```bash theme={null}
aitraining tools merge-llm-adapter \
  --base-model-path meta-llama/Llama-3.2-1B \
  --adapter-path ./lora-model \
  --output-folder ./merged-model
```

<Note>
  您必须指定 `--output-folder` 以本地保存，或 `--push-to-hub` 以上传到 Hugging Face Hub。
</Note>

#### 合并工具参数

| 参数                     | 描述                            | 必需   |
| ---------------------- | ----------------------------- | ---- |
| `--base-model-path`    | 要合并适配器的基础模型                   | 是    |
| `--adapter-path`       | LoRA 适配器路径                    | 是    |
| `--output-folder`      | 本地输出目录                        | 其中之一 |
| `--push-to-hub`        | 推送到 Hugging Face Hub          | 必需   |
| `--token`              | Hugging Face token（用于 hub 推送） | 否    |
| `--pad-to-multiple-of` | 填充词汇表大小                       | 否    |

或在 Python 中：

```python theme={null}
from peft import PeftModel
from transformers import AutoModelForCausalLM

# Load base model
model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-1B")

# Load and merge adapter
model = PeftModel.from_pretrained(model, "./lora-model")
model = model.merge_and_unload()

# Save merged model
model.save_pretrained("./merged-model")
```

### 转换为 Kohya 格式

将 LoRA 适配器转换为 Kohya 兼容的 `.safetensors` 格式：

```bash theme={null}
aitraining tools convert_to_kohya \
  --adapter-path ./lora-model \
  --output-path ./kohya-lora.safetensors
```

## 加载适配器

不合并使用适配器：

```python theme={null}
from peft import PeftModel
from transformers import AutoModelForCausalLM, AutoTokenizer

# Load base model
model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-1B")
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.2-1B")

# Load adapter
model = PeftModel.from_pretrained(model, "./lora-model")

# Use for inference
inputs = tokenizer("Hello", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=50)
```

## 最佳实践

### 训练

* 使用更高的学习率（2e-4 到 1e-3）
* LoRA 受益于更长的训练
* 对于复杂任务，考虑针对所有线性层

### 内存

* 从 `lora_r=16` 开始
* 如果需要，添加量化
* 使用梯度检查点（默认开启）

### 质量

* 更高的秩通常 = 更好的质量
* 在您的特定任务上测试
* 如果内存允许，与完整微调进行比较

## 下一步

<CardGroup cols={2}>
  <Card title="Quantization" href="/advanced/quantization">
    进一步减少内存
  </Card>

  <Card title="DPO Training" href="/advanced/dpo-training">
    偏好优化
  </Card>
</CardGroup>