日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)
# 在单张 GPU 上微调 32B QLoRA —— 或端到端微调 7B 模型。打包部署到 Ollama。
Backpropagate 可以在**单张** GPU 上微调大型语言模型，并根据你实际拥有的显卡来调整规模。只需三行 Python 代码，即可在单张 32 GB 消费级显卡（RTX 5090）上对 7B–34B 模型进行 QLoRA；只需一个参数 —— `--full-ft-offload` —— 即可通过将 optimizer 状态卸载到 host RAM，实现 7B 级模型的完整全量微调。再通过一条命令即可导出到 Ollama，随后即可 `ollama run` 运行你的微调模型。最低可向下兼容至 16 GB 显存。在 Windows 上提供一流体验。
```
from backpropagate import Trainer
trainer = Trainer("Qwen/Qwen2.5-7B-Instruct")
trainer.train("my_data.jsonl", steps=100)
trainer.export("gguf", quantization="q4_k_m")
```
```
backprop export ./output/lora --format gguf --quantization q4_k_m --ollama --ollama-name my-model
ollama run my-model
```
就这么简单。无需 YAML 配置文件，无需 `accelerate launch` 仪式，也没有单独的“现在将其转换为 GGUF”教程。只要你有一张 CUDA GPU 和一个包含训练数据的 JSONL 文件，只需三行代码就能完成一个可用的微调。
## 安装
```
# 推荐：隔离的 Python 安装（与系统 Python 或其他项目不冲突）
pipx install backpropagate
# 或者通过 uv（安装更快，同样的隔离）
uv tool install backpropagate
# 标准 pip（如果您管理自己的 virtualenv）
pip install backpropagate
```
如果你需要可选功能，请将安装命令替换为以下之一：
```
pipx install "backpropagate[standard]" # adds Unsloth (2x faster training) + the web UI
pipx install "backpropagate[full]" # adds everything: unsloth, ui, monitoring, export, etc.
```
更喜欢 Docker？`docker pull ghcr.io/mcp-tool-shop-org/backpropagate:latest` 也可以。镜像同时提供 `linux/amd64` 和 `linux/arm64` 版本，因此 Apple Silicon 和 ARM Linux 用户可以获得原生镜像。一个用于“容器化 UI”的标准 `compose.yaml` 位于仓库根目录 —— 运行 `docker compose up` 即可在 `http://localhost:7860` 启动 Web UI，并挂载持久化的 `~/.backpropagate` 数据卷。
## Backpropagate 在该领域中的定位
目前已有几个优秀的 LLM 微调库。它们各有千秋：
- **[Axolotl](https://github.com/OpenAccess-AI-Collective/axolotl)** —— 如果你喜欢 YAML 配置，并希望有一个现成的社区方案库可供借鉴
- **[LLaMA-Factory](https://github.com/hiyouga/LLaMA-Factory)** —— 如果你需要 DPO/PPO/RLHF 和 Web GUI
- **[Unsloth](https://github.com/unslothai/unsloth)** —— 如果你追求极致的训练速度，且使用的是受支持的模型系列
- **[torchtune](https://github.com/pytorch/torchtune)** —— 如果你想要 Meta 官方的、原生基于 PyTorch 且可编辑的方案
Backpropagate 是那个缺失的选项：**专为单张消费级 GPU 上的个人开发者设计的 3 行 Python API，用于训练 adapter 并打包部署。** 无需 YAML，无需 GUI，无需在线 RL (PPO/GRPO)，也无需多节点。只有每个人都真正需要的核心循环，以及那个过去总是碍事的导出步骤。
如果你尝试过上述某个库，却受困于配置文件的繁文缛节，或是遇到了模型系列不支持的问题，又或者想要以 Windows 优先的默认设置 —— 那么 Backpropagate 就是为你而生的。
## 你可以在单张 GPU 上微调什么
Backpropagate 会根据你的显卡调整运行规模。以下是**32 GB** 消费级 GPU (RTX 5090) 配备 64 GB host RAM 的实际能力上限 —— 这也是它的调优基准平台：
| 模型大小 | 方法 | 在 32 GB 显卡上的状态 |
|---|---|---|
| 7B (Qwen 2.5 7B / Llama-3.1-8B / Mistral 7B) | QLoRA | 轻松应对 —— 约需 7–8 GB。支持完整序列长度，余量充足。 |
| **14B** (Qwen2.5-14B) | QLoRA | **日常使用的黄金甜点 —— 实测约需 8.5 GB**。rank/alpha 为 32，启用分页 8-bit AdamW，4096 ctx。 |
| 24B (Mistral-Small-24B) | QLoRA | 约 18 GB。在 4096 ctx 下游刃有余。 |
| **32B** (Qwen2.5-32B) | QLoRA | **刚好装下 —— 在 `max_len 2048` + 分页 8-bit AdamW 下约需 26 GB**。性能上限。 |
| ≤6B | `mode="full"` (真正的全量微调) | 纯 GPU 全量 FT —— bf16 权重，无 adapter。在 32 GB 显存下，显卡感知的上限为 6B。 |
| **7B 级别** (Qwen 2.5 7B / Llama-3.1-8B / Mistral 7B) | `mode="full" --full-ft-offload` | **基于 FSDP2 CPU-offload 的全量微调** —— 将参数和 optimizer 卸载到 64 GB host RAM。速度较慢（受带宽限制）；适用于 Linux/WSL2。 |
大多数单 GPU 库会让你去别处解决的两个难题 —— **24–34B QLoRA** 和 **单卡 7B 级别全量微调** —— Backpropagate 都能在一张消费级显卡上搞定，并将结果直接导出到 Ollama。
**全量 FT 的上限是根据显卡动态决定的。** 它是根据 4 部分训练内存算术公式（权重 + 梯度 + optimizer + activations）与你*检测到*的 VRAM 推导出来的：**16 GB → 4B, 24 GB → 5B, 32 GB → 6B** 纯 GPU。`--full-ft-offload` 通过 FSDP2 `fully_shard` + `CPUOffloadPolicy` 将参数 + optimizer 状态卸载到 host RAM，从而将上限提升至 **7B 级别**（速度较慢，受限于 PCIe/CPU 带宽；需要约 64 GB host RAM 和 NCCL 后端，即 Linux/WSL2）。你可以使用 `--full-ft-ceiling-billions` 显式覆盖该上限。如果模型超过了卸载上限，程序会以 `RUNTIME_FULL_FT_MODEL_TOO_LARGE` 错误退出，并提示恢复方法（`--full-ft-offload` 或 LoRA/QLoRA）。有关 VRAM 计算公式以及 Biderman 2024 / Thinking Machines 2025 的质量对比，请参阅[全量微调手册页面](https://mcp-tool-shop-org.github.io/backpropagate/handbook/full-fine-tuning/)。
### 可向下扩展至 16 GB
16 GB 显存（RTX 4080 / 5080 / 4070 Ti Super）仍然是第一梯队：约 7–8 GB 即可进行 7B QLoRA，并且可通过 `mode="full"`（bf16 权重 + gradient checkpointing + 分页 8-bit AdamW）在 16 GB 内对真正的约 3B 模型（SmolLM3-3B、Qwen2.5-3B、Llama-3.2-3B/1B）进行真正的全量微调。相同的代码会根据检测到的显卡自动选择合适的 batch size 和全量 FT 上限 —— 在不同的设备间切换无需更改任何参数标志。
2-bit 量化 (AQLM / QuIP#) 不在**支持范围内** —— 2-bit 基础模型无法干净地合并回全精度权重，这会破坏“可合并 adapter → GGUF → Ollama”的导出契约（这也是整个流水线的核心意义所在）。Backpropagate 提供的内存余量控制手段 —— QLoRA、`mode="full"`、`--full-ft-offload` 以及 FP8 计算路径（`--fp8`，适用于 Blackwell/Hopper）—— 均能保持可合并性和可导出性。
## Backpropagate 不适用的场景
如果你的使用场景如下，使用其他库会让你体验更好 —— Backpropagate 并非正确的选择，强行让它工作所花费的精力，还不如直接使用合适的工具。在开始之前阅读本节，可以帮你省去无谓的安装和试错：
- **超过卸载上限（≈13B+）的全参数微调** —— 在 32 GB 显卡上，Backpropagate 的全量微调最高支持 **纯 GPU 约 6B，以及通过 `--full-ft-offload` 支持约 7B 级别**（参见[性能上限](#what-you-can-fine-tune-on-one-gpu)）。对 13B+ 模型进行*真正的全量*微调已经超出此范围 —— 它需要多 GPU FSDP 或更大的显卡（请使用跨多 GPU 的 `transformers.Trainer`，或租用 A100/H100）。然而，在消耗这些算力之前：最近的研究（[Biderman 2024](https://arxiv.org/abs/2405.09673), [Thinking Machines 2025](https://thinkingmachines.ai/blog/lora/)）表明，配置正确的 LoRA 在大多数训练后任务（指令遵循、领域适应、人格/风格）中，能够以约 67% 的计算量达到与全量微调相当的质量 —— 因此，Backpropagate 能够在单卡上实现的最高 34B 的 QLoRA，对于大多数开发者实际想要完成的工作来说，不会有任何质量损失。
- **在线 RL —— PPO / GRPO / RLVR** —— Backpropagate 支持单阶段 SFT 以及无参考模型的偏好微调（v1.5 中的 ORPO；v1.6 中的 SimPO + KTO）。它*不支持*在线强化学习 —— PPO、GRPO 或 RLVR —— 这需要在训练步骤之上建立 reward model 或生成与评分循环。对于这些需求，请直接使用 TRL 或 LLaMA-Factory。（无参考模型的偏好微调符合单阶段资源限制，因为内存中不需要保留单独的参考模型；请参阅[快速开始](#quick-start)下的 ORPO 说明。）
- **多节点训练** —— 仅支持单机单 GPU。单机多 GPU 可以运行（通过 `accelerate launch`），但不属于官方支持范围。
- **在 CUDA 路径上进行 macOS 训练** —— Apple Silicon 没有 CUDA，因此 CUDA 路径只能在配备 NVIDIA GPU 的 Linux 或 Windows 设备上运行。你依然可以通过 Ollama 在 Mac 上运行训练好的模型。**处于实验阶段、未经充分验证的预览版** MLX 路径（`--backend mlx`）可在 Apple Silicon 上原生训练 LoRA adapter —— 参见 [Apple Silicon (MLX)](#apple-silicon-mlx--unverified-preview)。它仅支持 LoRA-SFT，并且**未在真实芯片上完成内部测试验证**（不提供支持），因此对于 LoRA SFT 以外的任何需求（ORPO、全量微调、FP8、多轮运行），请使用 CUDA 路径。
- **已测试模型系列以外的任何模型** —— Qwen 2.5 / 3.5 (7B / 4B)、Phi-4-mini-3.8B、SmolLM3-3B、Llama 3.2 (3B / 1B)、Mistral 7B。其他模型通常也能工作，但未在 CI 中固定测试。
如果你确实需要上述任何功能，请尝试前面列出的库。它们在这些方面做得更好。
## Backpropagate 能带给你什么
只需一次安装，即可获得四大特性：
**1. 无需配置文件即可运行的真正 3 行 API。**
本 README 顶部的代码片段是可以直接端到端运行的。无需 `accelerate config`，无需 YAML，无需 Hydra 覆盖配置。只需调用 `Trainer(model).train(data)`，你就能获得一个微调模型。
**2. 真正好用的 Windows 体验。**
大多数 ML 库将 Windows 视为附带支持。Backpropagate 在 Windows + RTX 5080 上经过了第一梯队的严格测试。该库会为你处理各种运行时的怪癖 —— 它知道如何预先对数据进行 tokenize，从而避免 Windows 多进程崩溃；它会自动在 RTX 40/50 显卡上禁用会导致错误的 xformers；它还会选择绝不会导致崩溃的 dataloader 设置。你完全不需要了解这些细节。它就能顺畅运行。
**3. 为无人值守运行而生。**
训练需要花费数小时。你肯定不想全程盯着它。Backpropagate 的设计理念就是让它自己运行：
- 如果你的 GPU 显存耗尽，它会自动将 batch size 减半并重试 —— 最多重试三次。完全无需手动调参。
- 如果你的 GPU 温度过高，它会自动暂停，等温度降下来后再继续。
- 每一个 checkpoint 都是以原子方式写入的 —— 即使你的笔记本在保存过程中死机，之前完好的 checkpoint 依然安全无损。
每次训练都会获得一个唯一的 ID，该 ID 会附加到每一行日志、每一个 checkpoint 以及每一次 Weights & Biases 记录中。如果出现问题，只需提供这一个 ID，维护人员就能关联所有信息。
- 错误均附带稳定的错误码（`RUNTIME_GPU_OOM`、`DEP_OLLAMA_REGISTRATION_FAILED` 等），方便你在日志和[故障排除指南](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/)中进行搜索以寻找修复方法。CUDA 相关的故障拥有专门的 [CUDA 故障排除页面](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting-cuda/)。
**4. 从训练好的 adapter 到 `ollama run` 仅需一条命令。**
许多库都能训练模型，但当你真正想使用模型时，却往往设置了重重障碍。Backpropagate 只需一条命令即可导出为 GGUF（Ollama 使用的格式）并注册 Ollama 模型。只需大约 30 秒，你就能从“训练完成”变为“与我的微调模型畅聊”。
## 快速开始
该仓库自带了一个极小的示例数据集，因此本 README 顶部的代码片段在全新安装后即可直接运行：
```
pipx install "backpropagate[standard]"
python -c "
from backpropagate import Trainer
trainer = Trainer('Qwen/Qwen2.5-7B-Instruct')
trainer.train('examples/quickstart.jsonl', steps=10)
trainer.export('gguf', quantization='q4_k_m')
"
```
这会在 5 段简短的 ShareGPT 格式对话上训练一个 Qwen 2.5 7B adapter，然后将结果导出为 GGUF。如果要使用你自己的数据，请按每行一个示例的格式编排你的 JSONL 文件：
```
{"conversations": [{"from": "human", "value": "What is Python?"}, {"from": "gpt", "value": "A programming language."}]}
{"conversations": [{"from": "human", "value": "Explain recursion."}, {"from": "gpt", "value": "A function that calls itself."}]}
```
此外，还支持 Alpaca (`instruction` / `output`)、OpenAI chat (`messages`) 和纯文本格式 —— Backpropagate 会自动检测格式。
### 偏好微调 (ORPO, SimPO, KTO)
基于偏好进行训练，而不是简单的演示。ORPO 是无参考模型且单阶段的 —— 它将偏好信号融入到 SFT 步骤中，因此无需单独的 reward 或参考模型，且 3 行代码的结构保持不变。传入 `--method orpo` (CLI) 或 `method="orpo"` (Python)，并为其提供由 `{prompt, chosen, rejected}`（或仅有 `{chosen, rejected}`）组成的数据集：
```
{"prompt": "What is Python?", "chosen": "A high-level programming language known for readability.", "rejected": "idk look it up"}
{"prompt": "Explain recursion.", "chosen": "A function that calls itself with a smaller input until a base case.", "rejected": "when something repeats"}
```
```
from backpropagate import Trainer
trainer = Trainer("Qwen/Qwen2.5-7B-Instruct", method="orpo")
trainer.train("preferences.jsonl", steps=100)
trainer.export("gguf", quantization="q4_k_m")
```
```
backprop train --data preferences.jsonl --method orpo --steps 100
```
对于 ORPO，默认学习率会自动降低至 `8e-6`（其 loss 比普通 SFT 更为陡峭）；可以通过调整 `--orpo-beta`（默认为 `0.1`）来改变 odds-ratio 惩罚的权重。ORPO 仅支持 `mode="lora"`。
**v1.6 新特性 —— SimPO 和 KTO。** `--method simpo` ([Meng et al. 2024](https://arxiv.org/abs/2405.14734)) 无需参考模型，采用长度归一化的奖励机制，并且接受与 ORPO 相同的成对 `{prompt, chosen, rejected}` 数据（`--simpo-beta`、`--simpo-gamma`）。`--method kto` ([Ethayarajh et al. 2024](https://arxiv.org/abs/2402.01306)) 接受**非成对的** `{prompt, completion, label}` 数据 —— 即针对每个示例的点赞/点踩 —— 适用于大量未经过精心整理为 A/B 对的反馈数据；它会根据你的标签计数自动平衡期望/非期望 loss 的权重。两者均仅支持 `mode="lora"`，并保持在单 GPU SFT 的资源上限内（无需单独的参考模型）。请参阅[偏好微调手册](https://mcp-tool-shop-org.github.io/backpropagate/handbook/preference-tuning/)了解何时该用哪种方法。关于在线 RL (PPO/GRPO)，请参阅 [Backpropagate 不适用的场景](#what-backpropagate-is-not-for)。
### 推理链 SFT (R1 蒸馏)
用最简单的方式蒸馏一个推理模型。传入 `--reasoning-trace` (CLI) 或 `Trainer(..., reasoning_trace=True)` (Python)，并提供在助手回合中包含 `
...` 思维链的轨迹 —— 这相当于 [DeepSeek-R1](https://arxiv.org/abs/2501.12948) 蒸馏的纯 SFT 部分，不需要 RL。Backpropagate 会将 `
` 保留在训练目标中，剔除空或过长的轨迹（轨迹长度过滤），并将默认的 `max_seq_length` 提高到 8192 以适应更长的 CoT。关键是，`` 保持为**纯文本**形式 —— 没有特殊的 token，也不需要调整 embedding 大小 —— 因此合并后的 GGUF 可以像其他任何微调模型一样导出到 Ollama。仅支持 SFT。有关数据集的结构和可调整的 token 区间，请参阅[推理链方案](https://mcp-tool-shop-org.github.io/backpropagate/handbook/recipes/#reasoning-trace-sft-r1-distillation)。
### Apple Silicon (MLX) —— 未经充分验证的预览版
**一套 API，两条路径。** CUDA 是标准且经过验证的后端；MLX 是第二条路径，它通过 Apple 的 [`mlx_lm.lora`](https://github.com/ml-explore/mlx-lm) 工具链在 M 系列 Mac 上进行训练（统一内存，无需 CUDA）。这 3 行代码结构会根据硬件自动选择路径 —— `backend='auto'`（默认值）会在 NVIDIA 设备上路由到 CUDA，在 Apple Silicon 上路由到 MLX，因此现有的 CUDA 环境不会受到任何影响：
```
from backpropagate import Trainer
# 在 M-series Mac 上使用 `pip install 'backpropagate[mlx]'`：
trainer = Trainer("mlx-community/Qwen2.5-0.5B-Instruct-4bit", backend="mlx")
trainer.train("examples/quickstart.jsonl", steps=100)
```
```
backprop train --data my_data.jsonl --backend mlx --steps 100
```
MLX 路径**仅支持 LoRA SFT** —— 不支持 ORPO、FP8、`mode='full'` 或多轮运行（以上尝试都会以 `CONFIG_INVALID_SETTING` 被拒绝；如果需要这些功能，请在 NVIDIA 设备上使用 `backend='cuda'`/`'auto'`）。生成的 adapter 为普通的 safetensors 格式，可通过与 CUDA 路径相同的流程导出到 Ollama。
有关更多端到端工作流（微调并推送到 HF-Hub、OOM 后恢复、在长周期任务中进行多轮 SLAO 等），请参阅[手册方案页面](https://mcp-tool-shop-org.github.io/backpropagate/handbook/recipes/)。
### Web UI（可选）
如果你更喜欢点击操作而不是编写 Python 代码，请安装 UI 扩展并启动：
```
pipx install "backpropagate[ui]"
backprop ui --port 7862
```
一个本地 Web 界面将在 `http://localhost:7862` 打开，用于浏览数据集、验证格式以及可视化地组装训练配置。训练本身是通过 `backprop train` 运行的（UI 驱动的训练已列入开发计划 —— 目前 Start 按钮只会显示相关的说明提示）。UI 默认仅在本地运行。如果需要将其暴露给其他设备，请参阅下方的 [Web UI](#web-ui) 了解 `--share` + `--auth` 安全契约。
## 多轮训练
如果你想在多个数据集上进行增量微调 —— 比如你每周都会获得新的训练数据，并希望在加入新数据的同时不遗忘之前学到的知识 —— 那么 Backpropagate 的 `multi_run` 模式就是为你准备的：
```
from backpropagate import Trainer
trainer = Trainer("Qwen/Qwen2.5-7B-Instruct")
result = trainer.multi_run(
dataset="HuggingFaceH4/ultrachat_200k",
num_runs=5,
steps_per_run=100,
samples_per_run=1000,
)
```
这将运行五次训练过程，并在两次训练之间合并 adapter，其合并方式能在吸收新示例的同时保留以前学到的知识。该技术基于最新的持续学习研究 —— 请参阅本 README 底部的[参考文献](#references)。
CLI 版本：
```
backprop multi-run --data my_data.jsonl --runs 5 --steps 100 --samples 1000
```
## 从 checkpoint 恢复
如果一个 5 轮训练在第 4 轮崩溃了，是完全可恢复的。每次多轮训练都会将其运行 ID 写入磁盘上的历史记录和 checkpoint 清单中，因此只需一条命令即可从上次中断的地方继续：
```
backprop resume
backprop multi-run --data ... --resume
backprop train --data ... --resume # single-run resume
```
`backprop multi-run` 的默认行为（不带 `--resume`）会自动检测同一输出目录中未完成的记录并继续运行。如果要强制全新开始，请指定一个新的输出目录。
## 训练历史
每次调用 `backprop train` 和 `backprop multi-run` 都会在 `