在一个 GPU 上微调一个 32B 的 QLoRA 模型，或者一个 7B 的端到端模型。然后将其部署到 Ollama 中

在单个 GPU 上进行反向传播，以微调大型语言模型，GPU 的大小应与您实际拥有的显卡相匹配。只需三行 Python 代码，即可在一个具有 32GB 内存的消费级显卡（RTX 5090）上对一个 7B-34B 模型进行 QLoRA 微调；使用一个标志 --full-ft-offload，可以将优化器状态溢出到主机 RAM 中，从而对一个 7B 级别的模型进行完全微调。再添加一条命令即可导出到 Ollama，然后使用 ollama run 命令运行您的微调模型。可以很好地扩展到 16GB。在 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 文件，那么你只需三行代码就可以完成一个可用的微调。

安装

# Recommended: isolated Python install (no conflicts with system Python or other projects)
pipx install backpropagate

# Or via uv (faster install, same isolation)
uv tool install backpropagate

# Standard pip (if you manage your own 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 用户可以获得原生镜像。一个标准的 compose.yaml 文件，用于“在容器中运行 UI”，位于仓库的根目录中——docker compose up 命令将在 http://localhost:7860 上启动 Web UI，并挂载一个持久的 ~/.backpropagate 卷。

Backpropagate 在这个领域中的定位

有几个优秀的库可以用于微调 LLM。它们各自擅长不同的方面：

• Axolotl——如果你喜欢 YAML 配置文件，并且想要一个可以从中复制配方的社区。
• LLaMA-Factory——如果你想要 DPO/PPO/RLHF 和一个 Web GUI。
• Unsloth——如果你需要最快的训练速度，并且使用的是受支持的模型系列。
• torchtune——如果你想要 Meta 提供的、可以编辑的 PyTorch 原生配方。

Backpropagate 是缺失的选项：一个 3 行 Python API，适用于在单个消费级 GPU 上进行操作的个人用户，他们想要训练一个适配器并将其部署。 没有 YAML，没有 GUI，没有在线 RL（PPO/GRPO），也没有多节点。只有每个人真正需要的循环和阻碍流程的导出步骤。

如果你尝试了上述库中的一个，但因为配置文件的复杂性而放弃，或者遇到了模型系列的问题，或者想要默认支持 Windows——那么 Backpropagate 适合你。

您可以在单个 GPU 上微调的内容

反向传播会根据您的显卡调整运行大小。以下是在具有 64GB 主机 RAM 的 32 GB 消费级 GPU（RTX 5090）上的实际限制：

| 模型大小 | 方法 | 在 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 位 AdamW，4096 ctx。 | | 24B (Mistral-Small-24B) | QLoRA | 约 18 GB。在 4096 ctx 下运行，仍有余量。 | | 32B (Qwen2.5-32B) | QLoRA | 刚好可以运行——在 max_len 2048 + 分页 8 位 AdamW 下，约 26 GB。达到了极限。 | | ≤6B | mode="full"（完全微调） | 纯 GPU 完全微调——bf16 权重，不使用适配器。在 32 GB 上，显卡能够支持的上限是 6B。 | | 7B 级别 (Qwen 2.5 7B / Llama-3.1-8B / Mistral 7B) | mode="full" --full-ft-offload | 通过 FSDP2 CPU 卸载进行完全微调——将参数 + 优化器溢出到 64 GB 主机 RAM 中。速度较慢（受带宽限制）；Linux/WSL2。 |

大多数单 GPU 库都会让您使用其他方法来处理两件事——24–34B QLoRA 和 单个显卡上的 7B 级别完全微调——反向传播可以在一个消费级显卡上完成，然后将结果直接导出到 Ollama。

**完全微调的上限取决于显卡。**它基于以下训练内存算术（权重 + 梯度 + 优化器 + 激活值）与您检测到的 VRAM：16 GB → 4B，24 GB → 5B，32 GB → 6B 纯 GPU。--full-ft-offload 通过将参数 + 优化器状态溢出到主机 RAM 中（通过 FSDP2 fully_shard + CPUOffloadPolicy），将其提升到 7B 级别（速度较慢，受 PCIe/CPU 带宽限制；需要约 64 GB 主机 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 的质量比较。

可以扩展到 16 GB

即使是 16 GB（RTX 4080 / 5080 / 4070 Ti Super）的配置仍然表现出色：7B QLoRA 占用约 7–8 GB，并且可以在 16 GB 中完全微调一个真正的 ~3B 模型（SmolLM3-3B、Qwen2.5-3B、Llama-3.2-3B/1B），通过 mode="full" 实现（bf16 权重 + 梯度检查点 + 分页 8 位 AdamW）。相同的代码会选择适合检测到的任何显卡的批大小和完全微调上限——无需更改标志。

2 位量化 (AQLM / QuIP#) 不在本次讨论范围内——一个 2 位的基模型无法干净地合并回全精度权重，这会破坏可合并的适配器 → GGUF → Ollama 导出流程（这是整个流水线的目的）。反向传播提供的替代方案是——QLoRA、mode="full"、--full-ft-offload 和 FP8 计算路径 (--fp8, Blackwell/Hopper)——所有这些都保持可合并和可导出。

Backpropagate 不适用于以下情况

如果你的用例如下，你最好使用不同的库——Backpropagate 不是正确的选择，并且尝试使其工作会花费更多的时间。在开始之前阅读本部分可以节省安装和放弃的周期：

• 超出卸载上限的全参数微调（≈13B+）——在 32GB 的显卡上，通过 --full-ft-offload 将全参数微调回溯到最多 ~6GB 的纯 GPU 和 ~7GB 级别的模型（参见此处）。对 13B+ 模型进行真正的完整微调已经超出了这个范围——它需要多 GPU FSDP 或更大的显卡（使用 transformers.Trainer 在多个 GPU 上运行，或租用 A100/H100）。但在投入大量计算资源之前：最近的研究（Biderman 2024，Thinking Machines 2025）表明，在大多数后训练任务（指令遵循、领域适应、个性/风格）中，LoRA 在正确的配置下可以达到与完整微调相同的质量，并且计算量仅为 ~67%——因此，QLoRA 可以扩展到 34B，Backpropagate 在单个显卡上运行，对于大多数用户实际需要的任务来说，不会有任何损失。
• 在线强化学习——PPO / GRPO / RLVR——Backpropagate 执行单阶段 SFT 以及无参考偏好调整（v1.5 中的 ORPO；v1.6 中的 SimPO + KTO）。它不执行在线强化学习——PPO、GRPO 或 RLVR——这些方法需要一个奖励模型或在训练步骤之上进行生成和评分循环。对于这些，请直接使用 TRL 或 LLaMA-Factory。（无参考偏好调整符合单阶段的范围，因为不需要将单独的参考模型保存在内存中；参见快速入门中的 ORPO 注释。）
• 多节点训练——仅支持单个机器上的单个 GPU。单个机器上的多 GPU 也可以工作（通过 accelerate launch），但未正式支持。
• macOS 上基于 CUDA 的训练——Apple Silicon 没有 CUDA，因此 CUDA 路径在配备 NVIDIA GPU 的 Linux 或 Windows 系统上运行。您仍然可以通过 Ollama 在 Mac 上运行经过训练的模型。一个实验性的、未经验证的预览版 MLX 框架（--backend mlx）可以在 Apple Silicon 上本地训练 LoRA 适配器——参见Apple Silicon (MLX)。它仅支持 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，无需配置文件即可运行。 本文档顶部的代码片段可以端到端地运行。无需 accelerate config、YAML 或 Hydra 覆盖。只需 Trainer(model).train(data)，您就可以进行微调。

2. 真正支持 Windows。 大多数机器学习库都将 Windows 视为次要考虑。Backpropagate 在 Windows + RTX 5080 上进行了第一类测试。该库会处理运行时中的一些问题——它知道如何预先标记您的数据，以便 Windows 多进程不会崩溃，它会自动禁用 RTX 40/50 显卡上的 xformers，因为这会导致错误，并且它会选择不会导致错误的 dataloader 设置。您不必了解所有这些。它只是可以运行。

3. 专为无人值守运行而设计。 训练需要几个小时。您不想一直监控它。Backpropagate 旨在让其运行：

• 如果您耗尽了 GPU 内存，它会自动将批处理大小减半并重试——最多三次。无需手动调整。
• 如果您的 GPU 过热，它会暂停，直到温度降下来，然后继续。
• 每个检查点都会以原子方式写入——如果您的笔记本电脑在保存过程中崩溃，则之前的良好检查点仍然完好无损。
• 每次训练运行都会获得一个唯一的 ID，该 ID 会被标记到每条日志行、每个检查点以及每个 Weights & Biases 条目上。如果出现问题，一个 ID 可以让维护者关联所有内容。
• 错误会带有稳定的代码（RUNTIME_GPU_OOM、DEP_OLLAMA_REGISTRATION_FAILED 等），因此您可以搜索日志和 故障排除指南 以查找解决方法。特定于 CUDA 的错误具有专门的 CUDA 故障排除页面。

4. 从训练好的适配器到 ollama run，只需一个命令。 许多库都会训练一个模型。很少有库会在您想要实际使用它时让您摆脱麻烦。Backpropagate 导出到 GGUF（Ollama 使用的格式），并使用一个命令注册一个 Ollama 模型。从“训练完成”到“我可以与我的微调模型进行聊天”，大约需要 30 秒。

快速入门

该存储库包含一个小型示例数据集，因此本文档顶部的代码片段可以在全新安装的环境中运行：

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 适配器，然后将结果导出到 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 聊天（messages）和原始文本格式也可以工作——Backpropagate 会自动检测格式。

偏好调整（ORPO、SimPO、KTO）

v1.5 版本的新功能：使用偏好而不是纯演示进行训练。ORPO 是无参考且单阶段的——它将偏好信号折叠到 SFT 步骤中，因此没有单独的奖励或参考模型，并且 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

默认学习率会自动降低到 8e-6 用于 ORPO（损失比普通的 SFT 更陡峭）；调整 --orpo-beta（默认为 0.1），以调整优势比惩罚的权重。ORPO 仅为 mode="lora"。

v1.6 中的新功能——SimPO 和 KTO。 --method simpo (Meng et al. 2024) 是无参考的，具有长度归一化的奖励，并使用与 ORPO 相同的配对 {prompt, chosen, rejected} 数据（--simpo-beta、--simpo-gamma）。--method kto (Ethayarajh et al. 2024) 使用未配对的 {prompt, completion, label} 数据——每个示例的“赞成”/“反对”，用于处理大量不是经过策划的 A/B 对比的数据；它会自动平衡来自标签计数的理想/非理想损失权重。两者都仅为 mode="lora"，并且停留在单个 GPU SFT 的范围内（没有单独的参考模型）。请参见偏好调整手册 以了解应该使用哪种方法。对于在线强化学习（PPO/GRPO），请参见Backpropagate 不适用于哪些场景。

基于推理轨迹的 SFT（R1 蒸馏）

v1.5 中的新功能：以简单的方式蒸馏一个推理模型。传递 --reasoning-trace（命令行界面）或 Trainer(..., reasoning_trace=True)（Python），并提供包含 <think>...</think> 链式思维的轨迹，这些轨迹位于助手回复中——这是 DeepSeek-R1 蒸馏的纯 SFT 部分，无需 RL。反向传播会在训练目标中保留 <think>，删除空/过长的轨迹（轨迹长度过滤），并将默认 max_seq_length 提高到 8192，以适应更长的 CoT。重要的是，<think> 保持为纯文本——没有特殊的令牌，没有嵌入调整——因此合并后的 GGUF 仍然可以导出到 Ollama，就像任何其他微调模型一样。仅 SFT。请参阅 reasoning-trace 配方，了解数据集的形状和可调整的令牌范围。

Apple Silicon (MLX)——未经验证的预览版

⚠️ 未经验证的预览版——不属于受支持的功能集。 MLX 框架已经构建并进行了单元测试，但尚未在实际 Apple Silicon 上进行测试（mlx-lm 仅适用于 Apple 设备，无法在 Backpropagate 开发所使用的 NVIDIA 系统上运行）。请将以下所有内容视为实验性的，自行承担风险，如果您在 M 系列 Mac 上运行它，请报告异常。

v1.5 中的新功能：一个 API，两种框架。 CUDA 仍然是经过验证的、标准的后端；MLX 是第二个框架，它通过 Apple 的 mlx_lm.lora 工具链在 M 系列 Mac 上进行训练（统一内存，无需 CUDA）。相同的 3 行代码可以根据硬件选择框架——backend='auto'（默认值）在 NVIDIA 上路由到 CUDA，在 Apple Silicon 上路由到 MLX，因此现有的 CUDA 设置在字节级别上是相同的：

from backpropagate import Trainer

# On an M-series Mac with `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

在 v1.5 中，MLX 框架仅支持 LoRA SFT——不支持 ORPO、不支持 FP8、不支持 mode='full'，目前也不支持在 MLX 上进行多轮训练（每轮都会出现 CONFIG_INVALID_SETTING 错误；如果需要这些功能，请在 NVIDIA 机器上使用 backend='cuda'/'auto'）。生成的适配器是纯 safetensors 格式，并通过与 CUDA 框架相同的路径导出到 Ollama。

在非 Apple 主机上强制使用 --backend mlx 会出现 CONFIG_INVALID_SETTING 错误；Mac 上缺少 mlx_lm 工具链会引发 DEP_MLX_UNAVAILABLE。

有关更多端到端的流程（微调并推送到 HF Hub、在 OOM 之后恢复、在长时间的训练过程中进行多轮 SLAO 等），请参阅 手册配方页面。

Web UI（可选）

如果您更喜欢点击而不是输入 Python 代码，请安装 UI 扩展并启动：

pipx install "backpropagate[ui]"
backprop ui --port 7862

一个本地 Web 界面将在 http://localhost:7862 上打开，用于浏览数据集、验证格式和以图形方式组装训练配置。训练本身通过 backprop train 运行（UI 驱动的训练计划在未来推出——“开始”按钮当前显示该说明）。默认情况下，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,
)

这将运行五个训练周期，并在周期之间合并适配器，从而在合并新示例的同时保留早期知识。该技术基于最近的持续学习研究——请参阅本 README 文档底部的 参考文献。

命令行版本：

backprop multi-run --data my_data.jsonl --runs 5 --steps 100 --samples 1000

从检查点恢复

如果在第 4 轮训练中崩溃，则可以恢复 5 轮训练。每个多轮会话都会将其运行 ID 写入磁盘上的历史记录和检查点清单中，因此您可以执行以下命令来从中断的地方继续：

backprop resume <run-id>
backprop multi-run --data ... --resume <run-id>
backprop train --data ... --resume <run-id>     # single-run resume

backprop multi-run 的默认行为（没有 --resume）会自动检测相同输出目录中的进行中条目并继续。要强制从头开始，请指向一个新的输出目录。

训练历史记录

每次 backprop train 和 backprop multi-run 调用都会在 <output>/run_history.json 中记录一行——使用的模型、数据集、超参数、状态、最终损失、损失历史记录。您可以列出并检查过去的运行：

backprop list-runs                         # last 20 runs
backprop list-runs --status failed         # filter by status
backprop list-runs --json --limit 100      # machine-readable
backprop show-run abcd1234                 # detail view (partial ID is fine)

实验跟踪

Backpropagate 会自动检测已安装的实验跟踪器（Weights & Biases、TensorBoard、MLflow）并将其连接起来。如果安装了 wandb 并且您已登录，则每次运行都会自动记录到 W&B，并且运行名称与磁盘上的运行 ID 匹配——因此您可以使用一个标识符在 W&B、日志和 run_history.json 中进行搜索。

pip install backpropagate[monitoring]   # installs wandb + psutil
wandb login                             # one-time setup
backprop train --data my_data.jsonl

使用 Trainer(report_to=["wandb"])、Trainer(report_to=["tensorboard"]) 或 Trainer(report_to="none") 进行覆盖，以选择退出。

Web UI

Reflex Web 界面是可选的——使用 pipx install "backpropagate[ui]" 安装并启动：

backprop ui --port 7862

UI 在 http://localhost:7862 上本地运行。今天，它涵盖了工作流程的浏览/验证/配置部分——将其指向一个数据集，检查自动检测到的格式和统计信息，选择一个模型，并组装一个运行配置。运行的启动是通过 CLI 完成的（backprop train / backprop multi-run）；UI 上的“开始”按钮会显示一个说明，指向该位置。UI 驱动的训练是计划中的后续步骤——在此之前，UI 是启动平台，CLI 是触发器。

为了使其能够被其他设备访问（例如，您网络中的其他设备、公共 URL 等），您必须将 --share（或 --host）与 --auth 结合使用：

backprop ui --share --auth alice:hunter2

在不使用 --auth 的情况下，backprop ui --share 会报错并退出。原因是：--share 会发布一个互联网上的任何人都可以访问的 URL，如果没有身份验证，这意味着任何人都可以驱动您的训练流水线并读取您的 HuggingFace 令牌。对于此项，没有可选的禁用设置——如果您不想设置凭据，请改用 SSH 端口转发：

# On the client:
ssh -L 7860:localhost:7860 <your-training-host>
# On the server:
backprop ui                             # no --share
# Then open http://localhost:7860 in your local browser

有关完整的威胁模型，请参阅 handbook/security.md。

UI 中的文件系统写入操作被限制在一个目录中：

• 默认：~/.backpropagate/ui-outputs
• 覆盖：设置 BACKPROPAGATE_UI__OUTPUT_DIR=/path/you/own
• 覆盖设置会进行白名单验证——系统或凭据路径（/etc、~/.ssh、~/.aws、C:\Windows\System32 等）将被拒绝。

平台说明

要求： Python 3.10+ · CUDA GPU（8GB+ VRAM）· PyTorch 2.0+

Python 3.10 至少在 v1.6 中受支持；它将在 2026 年 10 月达到上游生命周期结束，并且计划在之后的第一个版本中删除。对于新安装，请首选 Python 3.11 或 3.12——3.11 是经过最多测试的最低版本。

Backpropagate 处理不同平台上训练时出现的一些运行时问题，但它无法修复安装时出现的问题。最常见的问题有两个：

• 错误的 CUDA wheel。 PyTorch 为每个 CUDA 版本发布一个二进制文件。如果您选择了错误的版本，您将默默地获得仅使用 CPU 的 PyTorch，并且训练速度将非常慢。使用 https://pytorch.org/get-started/locally/ 上的 wheel 选择器来选择适合您驱动程序的版本。运行 nvidia-smi 以查看您的驱动程序/CUDA 版本。
• Windows + GGUF 导出。 [export] 附加组件会从源代码构建 llama-cpp-python，这需要 Visual Studio Build Tools（C++ 组件）和 CMake。

macOS： 不支持 CUDA 轨道（没有 CUDA）——使用 CUDA 的 trainer.train() 会引发 DEP_GPU_NOT_AVAILABLE 错误，您可以通过 Ollama 在 Mac 上运行训练后的适配器。v1.5 中的新功能： 一个实验性的 MLX 轨道（--backend mlx，pip install 'backpropagate[mlx]'）使用 mlx_lm.lora 在 Apple Silicon 上本地训练 LoRA 适配器——仅支持 LoRA SFT，并且已构建和单元测试，但尚未在实际硬件上进行验证（请参阅 Apple Silicon (MLX)）。对于 CUDA 路径，或者对于 ORPO / 完全微调 / FP8 / 多次运行，请使用 CUDA Linux 或 Windows 机器。

请参阅 故障排除手册页面，了解完整的安装修复指南，并参阅专门的 CUDA 故障排除页面，了解驱动程序/VRAM/xformers/bf16 与 fp16 相关的问题。

CLI

每个 Python API 都有一个 CLI 镜像：

backprop train --data my_data.jsonl --model Qwen/Qwen2.5-7B-Instruct --steps 100
backprop multi-run --data my_data.jsonl --runs 5 --steps 100
backprop export ./output/lora --format gguf --quantization q4_k_m --ollama --ollama-name my-model
backprop ui --port 7862
backprop info                          # environment + version snapshot
backprop list-runs                     # past training runs
backprop show-run <run-id>             # detail view
backprop resume <run-id>               # resume a crashed run
backprop push ./output/lora --repo me/my-model    # push adapter to HuggingFace Hub
backprop diff-runs <run-a> <run-b>     # diff two runs side by side
backprop replay <run-id>               # re-run with same config / dataset
backprop export-runs --format jsonl    # bulk export run history

完整的参考资料请参见 CLI 手册页面，或者使用 backprop <子命令> --help。

配置

可以使用带有 BACKPROPAGATE_ 前缀的环境变量来覆盖每个设置：

| 变量 | 默认值 | 说明 | |---|---|---| | BACKPROPAGATE_LOG_LEVEL | INFO | DEBUG / INFO / WARNING / ERROR | | BACKPROPAGATE_LOG_JSON | 自动 | 强制使用 JSON 或控制台日志 | | BACKPROPAGATE_MODEL__NAME | Qwen/Qwen2.5-7B-Instruct | 默认模型 | | BACKPROPAGATE_TRAINING__LEARNING_RATE | 2e-4 | 学习率 | | BACKPROPAGATE_LORA__R | 256 | LoRA 秩（v1.3 默认值；如果需要 v1.2.x 的默认值 16，请传递 --lora-preset=fast） | | BACKPROPAGATE_UI__OUTPUT_DIR | ~/.backpropagate/ui-outputs | UI 文件系统沙盒 |

嵌套键使用双下划线（MODEL__NAME，而不是 MODEL_NAME）。完整的参考资料请参见 环境变量手册页面。

模型预设

| 预设 | VRAM | 许可证 | 说明 | |---|---|---|---| | Qwen-3.5-4B | ~8GB | Apache 2.0 | 推荐用于小于 5B 的模型。在该尺寸下，质量最佳。 | | Phi-4-mini-3.8B | ~8GB | MIT | 在推理/数学/代码方面表现出色。许可证限制严格。 | | SmolLM3-3B | ~6GB | Apache 2.0 | 完全开放的配方。原生 64K 上下文。 | | Qwen 2.5 7B | ~12GB | Apache 2.0 | 现有的默认值。这是旧版 7B 预设中质量最好的。 | | Qwen 2.5 3B | ~8GB | Qwen-Research | ⚠ 研究许可证——在商业用途之前，请查看 Qwen 许可证条款。 | | Llama 3.2 3B | ~8GB | Llama Community | 是 Qwen 3B 的一个不错的替代方案，但有一些宽松的限制。 | | Llama 3.2 1B | ~6GB | Llama Community | 用于在小型设备上进行快速实验。 | | Mistral 7B | ~12GB | Apache 2.0 | 与 Qwen 7B 相当，但使用了不同的聊天模板。 | | Llama-3.1-8B | ~7-8GB（QLoRA） | Llama-3.1-Community | 8B QLoRA，128K 本地上下文（>700M-MAU 条款需要单独的 Meta 许可证）。 | | Qwen2.5-14B | ~8.5GB（QLoRA） | Apache 2.0 | 32 GB 日常使用最佳配置——rank/alpha 32，分页 8 位 AdamW，4096 ctx。 | | Mistral-Small-24B | ~18GB（QLoRA） | Apache 2.0 | 在 32 GB 显卡上使用 4096-ctx，可以进行 24B QLoRA 微调。 | | Qwen2.5-32B | ~26GB（QLoRA） | Apache 2.0 | 达到 32 GB 范围的上限——仅在 max_len 2048 + 分页 8 位 AdamW 时才能容纳。 |

其他模型通常也可以工作；上述行是经过策划的预设——14B–32B 级别针对 32 GB 显卡进行了 QLoRA 调整（测量的范围）。传递 --lora-preset=quality（默认值），以使用 Biderman 2024 + Thinking Machines 2025 中定义的 rank-256 / 所有线性目标，或者如果需要 v1.2.x 的占用空间，则传递 --lora-preset=fast 以使用旧的 rank-16 / q+v 目标。

故障排除

这是最常见首次运行失败的简短索引。完整的反向索引请参见 故障排除手册页面。有关驱动程序/VRAM/混合精度深入分析，请参见 CUDA 故障排除页面。

| 症状 | 错误代码 | 解决方法 | |---|---|---| | GPU 在训练过程中耗尽内存 | RUNTIME_GPU_OOM | 自动模式——反向传播会将批次大小减半，并重试最多 3 次。要禁用此功能：Trainer(oom_recovery=False)。要强制使用较小的值：--batch-size 1。 | | HuggingFace 返回 401 /“未找到模型”。 | DEP_MODEL_LOAD_FAILED | 运行 huggingface-cli login 并重试。如果存在拼写错误，请从 https://huggingface.co/models 复制确切的 ID。 | | register_with_ollama 连接被拒绝。 | DEP_OLLAMA_REGISTRATION_FAILED | 启动守护进程：ollama serve。从 https://ollama.com 安装。可重试。 | | 在保存检查点时，磁盘空间不足。 | STATE_CHECKPOINT_INVALID | 原子写入会在崩溃时留下一个 .partial 目录——可以安全地删除。之前的有效检查点完好无损。 | | 训练因 GPU 过热而暂停。 | RUNTIME_GPU_TEMPERATURE_CRITICAL | 自动模式——反向传播会在达到温度阈值时暂停，并在 GPU 冷却后恢复。如果问题持续发生，请改善散热。 | | backprop ui --share 被拒绝。 | RUNTIME_UI_AUTH_NOT_ENFORCED | 传递 --auth user:password，或者使用 SSH 端口转发（请参阅 Web UI）。 | | 首次尝试 GGUF 导出失败。 | RUNTIME_GGUF_EXPORT_FAILED | pip install backpropagate[export]；在 Windows 上，还需要 Visual C++ 构建工具 + CMake。 |

报告错误

当出现故障时，Backpropagate 会在启动时打印一行，例如 run_started run_id=<uuid>，并将相同的 ID 绑定到每条日志行、每个检查点以及每个 Weights & Biases 条目。在任何错误报告中包含 run_id——这可以让维护者关联同一运行的所有内容。

一份好的错误报告包括：

1. run_id——启动时打印的 UUID。一个 UUID 允许维护者关联同一运行的每条日志行、每个检查点以及每个 Weights & Biases 条目。
2. 错误代码——stderr 中的 [CODE_NAME]: message 行。请参阅 错误代码，以获取稳定代码的目录。
3. 已编辑的堆栈跟踪。 在非详细模式下，stderr 会自动进行编辑（删除 Bearer 令牌、sk-*、hf_*、AWS 密钥、password= / token= / api_key= 对）。可以安全地粘贴。对于完整的未编辑堆栈跟踪，请使用 BACKPROPAGATE_DEBUG=1（或 --verbose）重新运行；在发布之前进行审核。
4. backprop info 输出。 一个命令会打印 Python / PyTorch / CUDA / GPU 模型 / VRAM / OS / 已安装的附加组件——维护者需要的所有内容，以隔离特定平台的回归。

错误报告模板 明确提示了这些内容，以便快速进行分类。问题、想法或“这是预期的吗？”的讨论应该在 GitHub Discussions 中进行。安全问题应通过 GitHub 安全咨询 表单私下报告——请参阅 SECURITY.md，了解策略和响应时间。

隐私

所有训练都在您的 GPU 上本地进行。Backpropagate 不会进行任何网络请求，除非是从 HuggingFace 下载模型（您会主动发起）。没有遥测，没有云依赖。

参考文献

Backpropagate 的默认设置和多运行训练模式是基于最近的研究。如果您对底层技术感兴趣：

• Hu et al. 2021. LoRA: Low-Rank Adaptation of Large Language Models. arXiv:2106.09685——介绍 LoRA 的基础论文，Backpropagate 通过这种方式高效地训练适配器。
• Biderman et al. 2024. LoRA Learns Less and Forgets Less. arXiv:2405.09673——经验证据表明，在秩为 256 且所有线性目标的情况下，LoRA 在大多数后训练任务中与完全微调的质量相匹配，并且计算量减少了 67%。这驱动了 Backpropagate v1.3 的默认 LoRA 配置。
• Thinking Machines 2025. LoRA Without Regret. thinkingmachines.ai/blog/lora——实际的后续研究，确定了在高 LoRA 秩下所需的 10 倍学习率与完全微调的校正。
• Kirkpatrick et al. 2017. Overcoming catastrophic forgetting in neural networks. arXiv:1612.00796——最初的表征，解释了为什么神经网络在对新数据进行微调时会“忘记”之前的训练（EWC——弹性权重巩固）。
• Wang et al. 2023. Orthogonal Subspace Learning for Language Model Continual Learning. arXiv:2310.14152——O-LoRA，一种较早的方法，通过将新的适配器限制在正交子空间中，用于语言模型的持续学习。
• Yadav et al. 2023. TIES-Merging: Resolving Interference When Merging Models. arXiv:2306.01708——一种用于合并多个微调模型而不会产生干扰的基础技术。
• Qiao & Mahdavi 2025. Merge before Forget: A Single LoRA Continual Learning via Continual Merging. arXiv:2512.23017——Backpropagate 的多运行合并器实现的具体算法。这是一篇 2025 年 12 月的预印本；Backpropagate 是该论文已知的第一个下游采用者。

许可证

MIT——请参阅 LICENSE。