@mcptoolshop/backpropagate 1.6.0 → 1.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.es.md +32 -21
- package/README.fr.md +36 -25
- package/README.hi.md +36 -25
- package/README.it.md +32 -21
- package/README.ja.md +32 -21
- package/README.md +33 -22
- package/README.pt-BR.md +32 -21
- package/README.zh.md +34 -23
- package/package.json +1 -1
package/README.pt-BR.md
CHANGED
|
@@ -15,9 +15,9 @@
|
|
|
15
15
|
<a href="https://mcp-tool-shop-org.github.io/backpropagate/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
|
|
16
16
|
</p>
|
|
17
17
|
|
|
18
|
-
#
|
|
18
|
+
# Ajuste um modelo QLoRA de 32 bilhões de parâmetros – ou um modelo completo de 7 bilhões de parâmetros – em uma única GPU. Envie-o para o Ollama
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
Realize o ajuste fino de grandes modelos de linguagem em uma **única** GPU, dimensionada para a placa que você realmente possui. Três linhas de código Python QLoRA para um modelo de 7–34 bilhões de parâmetros em uma única placa de consumidor de 32 GB (RTX 5090); uma flag – `--full-ft-offload` – realiza o ajuste fino completo de um modelo da classe 7B, transferindo o estado do otimizador para a RAM do host. Mais um comando exporta para o Ollama e, em seguida, `ollama run` executa o seu modelo ajustado. Escala de forma eficiente até 16 GB. Desempenho de primeira linha no Windows.
|
|
21
21
|
|
|
22
22
|
```python
|
|
23
23
|
from backpropagate import Trainer
|
|
@@ -69,33 +69,38 @@ O «backpropagation» é a funcionalidade que faltava: uma API Python de 3 linha
|
|
|
69
69
|
|
|
70
70
|
Se você experimentou uma das bibliotecas mencionadas acima e teve dificuldades com a configuração, ou encontrou uma lacuna na compatibilidade com determinados modelos, ou preferia configurações padrão otimizadas para o Windows, então o Backpropagate é a solução ideal para você.
|
|
71
71
|
|
|
72
|
-
##
|
|
72
|
+
## O que você pode ajustar em uma única GPU
|
|
73
73
|
|
|
74
|
-
|
|
74
|
+
A ferramenta Backpropagate dimensiona a execução para sua placa. Aqui está o limite prático em uma GPU de consumidor de **32 GB** (RTX 5090) com 64 GB de RAM do host – o hardware no qual ele é ajustado:
|
|
75
75
|
|
|
76
|
-
|
|
|
76
|
+
| Tamanho do modelo | Método | Status em uma placa de 32 GB |
|
|
77
77
|
|---|---|---|
|
|
78
|
-
| Qwen
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
|
|
|
78
|
+
| 7B (Qwen 2.5 7B / Llama-3.1-8B / Mistral 7B) | QLoRA | Confortável – ~7–8 GB. Comprimento total da sequência, bastante espaço livre. |
|
|
79
|
+
| **14B** (Qwen2.5-14B) | QLoRA | **O ponto ideal para uso diário – ~8,5 GB**, medido. rank/alpha 32, paged 8-bit AdamW, 4096 ctx. |
|
|
80
|
+
| 24B (Mistral-Small-24B) | QLoRA | ~18 GB. Encaixa com espaço livre em 4096 ctx. |
|
|
81
|
+
| **32B** (Qwen2.5-32B) | QLoRA | **Apenas encaixa – ~26 GB** em `max_len 2048` + paged 8-bit AdamW. Limite máximo. |
|
|
82
|
+
| ≤6B | `mode="full"` (ajuste fino completo) | Ajuste fino completo na GPU – pesos bf16, sem adaptador. O limite consciente da placa é de 6B em 32 GB. |
|
|
83
|
+
| **Classe 7B** (Qwen 2.5 7B / Llama-3.1-8B / Mistral 7B) | `mode="full" --full-ft-offload` | **Ajuste fino completo via FSDP2 com descarregamento para a CPU** – transfere parâmetros + otimizador para 64 GB de RAM do host. Mais lento (limitado pela largura de banda); Linux/WSL2. |
|
|
83
84
|
|
|
84
|
-
|
|
85
|
+
Duas coisas que a maioria das bibliotecas de GPU única exige que você faça em outro lugar – **QLoRA de 24–34B** e **ajuste fino completo de modelo da classe 7B em uma única placa** – Backpropagate faz em uma única placa de consumidor e, em seguida, exporta o resultado diretamente para o Ollama.
|
|
85
86
|
|
|
86
|
-
|
|
87
|
+
**O limite do ajuste fino completo é consciente da placa.** É derivado da aritmética de memória de treinamento de 4 termos (pesos + gradientes + otimizador + ativações) em relação à sua VRAM *detectada*: **16 GB → 4B, 24 GB → 5B, 32 GB → 6B** apenas na GPU. `--full-ft-offload` aumenta para **classe 7B**, transferindo parâmetros + estado do otimizador para a RAM do host via FSDP2 `fully_shard` + `CPUOffloadPolicy` (mais lento, limitado pela largura de banda PCIe/CPU; requer ~64 GB de RAM do host e um backend NCCL, ou seja, Linux/WSL2). Substitua o limite explicitamente com `--full-ft-ceiling-billions`. Um modelo que ultrapassa até mesmo o limite de descarregamento é interrompido com `RUNTIME_FULL_FT_MODEL_TOO_LARGE`, indicando a recuperação (`--full-ft-offload` ou LoRA/QLoRA). Consulte [a página completa do manual de ajuste fino](https://mcp-tool-shop-org.github.io/backpropagate/handbook/full-fine-tuning/) para os cálculos da VRAM + a comparação de qualidade Biderman 2024 / Thinking Machines 2025.
|
|
87
88
|
|
|
88
|
-
|
|
89
|
+
### Escala até 16 GB
|
|
90
|
+
|
|
91
|
+
O limite de 16 GB (RTX 4080 / 5080 / 4070 Ti Super) ainda oferece excelente desempenho: QLoRA de 7B em ~7–8 GB e ajuste fino completo de um modelo genuíno de ~3B (SmolLM3-3B, Qwen2.5-3B, Llama-3.2-3B/1B) dentro de 16 GB via `mode="full"` (pesos bf16 + checkpointing de gradiente + paged 8-bit AdamW). O mesmo código seleciona o tamanho do lote e o limite de ajuste fino completo que se ajustam a qualquer placa detectada – sem flags para alterar entre os hardwares.
|
|
92
|
+
|
|
93
|
+
A quantização de 2 bits (AQLM / QuIP#) está **fora do escopo** – uma base de 2 bits não pode ser mesclada de volta aos pesos de precisão total, o que interrompe o contrato de adaptador mesclável → GGUF → exportação para Ollama (o objetivo principal da pipeline). Em vez disso, a ferramenta Backpropagate oferece os recursos de QLoRA, `mode="full"`, `--full-ft-offload` e o caminho de computação FP8 (`--fp8`, Blackwell/Hopper) – todos permanecem mescláveis e exportáveis.
|
|
89
94
|
|
|
90
95
|
## Para que NÃO serve o algoritmo de retropropagação
|
|
91
96
|
|
|
92
97
|
Se o seu caso de uso for um dos seguintes, será mais vantajoso utilizar uma biblioteca diferente — a Backpropagate não é a escolha certa e tentar fazê-la funcionar custará mais do que simplesmente optar pela ferramenta adequada. Ler esta secção antes de começar evita o ciclo de instalação e tentativa frustrante:
|
|
93
98
|
|
|
94
|
-
- **Ajuste fino
|
|
95
|
-
- **RL online — PPO / GRPO / RLVR** — Backpropagate faz
|
|
96
|
-
- **Treinamento multi-nó** — GPU única em uma máquina. Multi-GPU em uma máquina funciona (via `accelerate launch`), mas não é oficialmente suportado.
|
|
97
|
-
- **Treinamento macOS
|
|
98
|
-
- **Qualquer coisa fora das famílias de modelos testadas** — Qwen 2.5 / 3.5 (7B / 4B), Phi-4-mini-3.8B, SmolLM3-3B, Llama 3.2 (3B / 1B), Mistral 7B. Outros modelos geralmente funcionam, mas não estão
|
|
99
|
+
- **Ajuste fino com todos os parâmetros além do limite de transferência (≈13B+)** — Propague o ajuste fino completo até **~6 GB de GPU pura e ~7 GB via `--full-ft-offload`** em uma placa de 32 GB (veja [o envelope](#what-you-can-fine-tune-on-one-gpu)). Um ajuste fino *verdadeiramente completo* de um modelo de 13B+ está além disso — ele requer FSDP multi-GPU ou uma placa maior (use `transformers.Trainer` em várias GPUs, ou alugue uma A100/H100). Antes de investir nesse poder computacional, no entanto: pesquisas recentes ([Biderman 2024](https://arxiv.org/abs/2405.09673), [Thinking Machines 2025](https://thinkingmachines.ai/blog/lora/)) mostram que o LoRA, com a configuração correta, corresponde à qualidade do ajuste fino completo na maioria das tarefas de pós-treinamento (seguimento de instruções, adaptação de domínio, persona/estilo) em cerca de 67% do poder computacional — portanto, QLoRA até 34B, que o Backpropagate executa em uma única placa, não perde nada para o trabalho que a maioria dos operadores realmente deseja.
|
|
100
|
+
- **RL online — PPO / GRPO / RLVR** — O Backpropagate faz ajuste fino de estágio único (SFT) mais ajuste de preferência sem referência (ORPO na v1.5; SimPO + KTO na v1.6). O que ele *não* faz é aprendizado por reforço online — PPO, GRPO ou RLVR —, o que requer um modelo de recompensa ou um loop de geração e pontuação no topo da etapa de treinamento. Para isso, use TRL diretamente ou LLaMA-Factory. (O ajuste de preferência sem referência se encaixa no envelope de estágio único porque não há um modelo de referência separado para manter na memória; veja a nota do ORPO em [Quick Start](#quick-start).)
|
|
101
|
+
- **Treinamento multi-nó** — GPU única em uma máquina apenas. Multi-GPU em uma máquina funciona (via `accelerate launch`), mas não é oficialmente suportado.
|
|
102
|
+
- **Treinamento no macOS na plataforma CUDA** — Apple Silicon não tem CUDA, então o caminho CUDA é executado em uma caixa Linux ou Windows com uma GPU NVIDIA. Você ainda pode executar o modelo treinado em um Mac via Ollama. Uma plataforma MLX **experimental e não verificada** (`--backend mlx`) treina um adaptador LoRA nativamente no Apple Silicon — veja [Apple Silicon (MLX)](#apple-silicon-mlx--unverified-preview). É apenas LoRA-SFT e **não foi verificado em silício real** (sem suporte), portanto, para qualquer coisa além de um SFT LoRA (ORPO, ajuste fino completo, FP8, execução múltipla), você deve usar a plataforma CUDA.
|
|
103
|
+
- **Qualquer coisa fora das famílias de modelos testadas** — Qwen 2.5 / 3.5 (7B / 4B), Phi-4-mini-3.8B, SmolLM3-3B, Llama 3.2 (3B / 1B), Mistral 7B. Outros modelos geralmente funcionam, mas não estão definidos no CI.
|
|
99
104
|
|
|
100
105
|
Se você precisar de alguma dessas coisas, use uma das bibliotecas listadas acima. Elas são melhores para isso.
|
|
101
106
|
|
|
@@ -174,7 +179,9 @@ A taxa de aprendizado padrão é automaticamente reduzida para `8e-6` para ORPO
|
|
|
174
179
|
|
|
175
180
|
Novo na v1.5: destile um modelo de raciocínio de forma fácil. Passe `--reasoning-trace` (CLI) ou `Trainer(..., reasoning_trace=True)` (Python) e forneça rastreamentos que mantenham uma cadeia de pensamento `<think>...</think>` dentro da interação do assistente — a metade pura de SFT de [DeepSeek-R1](https://arxiv.org/abs/2501.12948), sem necessidade de RL. Backpropagate mantém `<think>` no alvo de treinamento, remove rastreamentos vazios/muito longos (filtragem do comprimento do rastreamento) e aumenta o `max_seq_length` padrão para 8192 para o CoT mais longo. Fundamentalmente, `<think>` permanece como **texto simples** — sem tokens especiais, sem redimensionamento de incorporação — para que o GGUF mesclado ainda seja exportado para o Ollama como qualquer outro ajuste fino. Apenas SFT. Consulte a [receita de rastreamento de raciocínio](https://mcp-tool-shop-org.github.io/backpropagate/handbook/recipes/#reasoning-trace-sft-r1-distillation) para o formato do conjunto de dados e o intervalo de tokens ajustável.
|
|
176
181
|
|
|
177
|
-
### Apple Silicon (MLX) —
|
|
182
|
+
### Apple Silicon (MLX) — visualização não verificada
|
|
183
|
+
|
|
184
|
+
> ⚠️ **Visualização não verificada — não faz parte do conjunto de recursos suportados.** A plataforma MLX é construída e testada em nível de unidade, mas **não** foi verificada em silício Apple real (`mlx-lm` é exclusivo da Apple e não pode ser executado nos equipamentos NVIDIA nos quais o Backpropagate é desenvolvido). Considere tudo abaixo como experimental, use por sua conta e risco e [relate anomalias](#reporting-bugs) se você o executar em um Mac da série M.
|
|
178
185
|
|
|
179
186
|
Novo na v1.5: **uma API, dois caminhos.** CUDA permanece como o backend canônico e verificado; MLX é um segundo caminho que treina em um Mac da série M por meio do conjunto de ferramentas [`mlx_lm.lora`](https://github.com/ml-explore/mlx-lm) da Apple (memória unificada, sem CUDA). O mesmo formato de 3 linhas seleciona o caminho por hardware — `backend='auto'` (o padrão) direciona para CUDA em NVIDIA e para MLX em Apple Silicon, para que as configurações CUDA existentes sejam idênticas em termos de bytes:
|
|
180
187
|
|
|
@@ -192,7 +199,7 @@ backprop train --data my_data.jsonl --backend mlx --steps 100
|
|
|
192
199
|
|
|
193
200
|
Na v1.5, o caminho MLX é **apenas LoRA SFT** — sem ORPO, sem FP8, sem `mode='full'`, sem execução múltipla em MLX ainda (cada um é rejeitado com `CONFIG_INVALID_SETTING`; use `backend='cuda'`/`'auto'` em uma máquina NVIDIA para esses). O adaptador resultante é apenas safetensors e é exportado para o Ollama pelo mesmo caminho do caminho CUDA.
|
|
194
201
|
|
|
195
|
-
>
|
|
202
|
+
> Forçar `--backend mlx` em um host que não seja Apple gera um erro com `CONFIG_INVALID_SETTING`; a ausência de uma ferramenta `mlx_lm` em um Mac gera `DEP_MLX_UNAVAILABLE`.
|
|
196
203
|
|
|
197
204
|
Para fluxos de trabalho de ponta a ponta mais abrangentes (ajuste fino e envio para o HF-Hub, retomada após estouro de memória, SLAO de execução múltipla em uma campanha longa, etc.), consulte a [página de receitas do manual](https://mcp-tool-shop-org.github.io/backpropagate/handbook/recipes/).
|
|
198
205
|
|
|
@@ -364,8 +371,12 @@ Chaves aninhadas usam sublinhado duplo (`MODEL__NAME`, não `MODEL_NAME`). A ref
|
|
|
364
371
|
| Llama 3.2 3B | ~8GB | Llama Community | Alternativa sólida ao Qwen 3B com ressalvas permissivas. |
|
|
365
372
|
| Llama 3.2 1B | ~6GB | Llama Community | Para experimentos rápidos em placas pequenas. |
|
|
366
373
|
| Mistral 7B | ~12GB | Apache 2.0 | Comparável ao Qwen 7B, modelo de chat diferente. |
|
|
374
|
+
| Llama-3.1-8B | ~7-8 GB (QLoRA) | Llama-3.1-Community | 8B QLoRA, contexto nativo de 128 mil tokens (a cláusula >700M-MAU requer uma licença Meta separada). |
|
|
375
|
+
| **Qwen2.5-14B** | ~8,5 GB (QLoRA) | Apache 2.0 | **O ponto ideal para uso diário em uma placa de 32 GB** — classificação/alfa 32, AdamW de 8 bits com paginação, 4096 ctx. |
|
|
376
|
+
| Mistral-Small-24B | ~18 GB (QLoRA) | Apache 2.0 | 24B QLoRA em uma placa de 32 GB com margem de 4096 ctx. |
|
|
377
|
+
| **Qwen2.5-32B** | ~26 GB (QLoRA) | Apache 2.0 | **No limite da capacidade de uma placa de 32 GB** — apenas se encaixa em `max_len 2048` + AdamW de 8 bits com paginação. |
|
|
367
378
|
|
|
368
|
-
Outros modelos geralmente funcionam
|
|
379
|
+
Outros modelos geralmente funcionam; as linhas acima são os predefinições selecionadas — a camada de 14B–32B é ajustada com QLoRA para uma placa de 32 GB (o envelope medido). Passe `--lora-preset=quality` (padrão) para alvos de classificação 256 / totalmente linear, conforme Biderman 2024 + Thinking Machines 2025, ou `--lora-preset=fast` para o alvo de classificação 16 / q+v legado se você precisar da pegada da v1.2.x.
|
|
369
380
|
|
|
370
381
|
## Solução de problemas
|
|
371
382
|
|
package/README.zh.md
CHANGED
|
@@ -15,9 +15,9 @@
|
|
|
15
15
|
<a href="https://mcp-tool-shop-org.github.io/backpropagate/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
|
|
16
16
|
</p>
|
|
17
17
|
|
|
18
|
-
#
|
|
18
|
+
# 在一个 GPU 上微调一个 32B 的 QLoRA 模型，或者一个 7B 的端到端模型。然后将其部署到 Ollama 中
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
在单个 GPU 上进行反向传播，以微调大型语言模型，GPU 的大小应与您实际拥有的显卡相匹配。只需三行 Python 代码，即可在一个具有 32GB 内存的消费级显卡（RTX 5090）上对一个 7B-34B 模型进行 QLoRA 微调；使用一个标志 `--full-ft-offload`，可以将优化器状态溢出到主机 RAM 中，从而对一个 7B 级别的模型进行完全微调。再添加一条命令即可导出到 Ollama，然后使用 `ollama run` 命令运行您的微调模型。可以很好地扩展到 16GB。在 Windows 系统上表现出色。
|
|
21
21
|
|
|
22
22
|
```python
|
|
23
23
|
from backpropagate import Trainer
|
|
@@ -69,33 +69,38 @@ Backpropagate 是缺失的选项：**一个 3 行 Python API，适用于在单
|
|
|
69
69
|
|
|
70
70
|
如果你尝试了上述库中的一个，但因为配置文件的复杂性而放弃，或者遇到了模型系列的问题，或者想要默认支持 Windows——那么 Backpropagate 适合你。
|
|
71
71
|
|
|
72
|
-
##
|
|
72
|
+
## 您可以在单个 GPU 上微调的内容
|
|
73
73
|
|
|
74
|
-
|
|
74
|
+
反向传播会根据您的显卡调整运行大小。以下是在具有 64GB 主机 RAM 的 **32 GB** 消费级 GPU（RTX 5090）上的实际限制：
|
|
75
75
|
|
|
76
|
-
|
|
|
76
|
+
| 模型大小 | 方法 | 在 32 GB 显卡上的状态 |
|
|
77
77
|
|---|---|---|
|
|
78
|
-
| Qwen
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
|
|
|
78
|
+
| 7B (Qwen 2.5 7B / Llama-3.1-8B / Mistral 7B) | QLoRA | 运行流畅——约 7–8 GB。完整的序列长度，有充足的余量。 |
|
|
79
|
+
| **14B** (Qwen2.5-14B) | QLoRA | **日常使用的最佳选择——测量值为约 8.5 GB**。rank/alpha 32，分页 8 位 AdamW，4096 ctx。 |
|
|
80
|
+
| 24B (Mistral-Small-24B) | QLoRA | 约 18 GB。在 4096 ctx 下运行，仍有余量。 |
|
|
81
|
+
| **32B** (Qwen2.5-32B) | QLoRA | **刚好可以运行——在 `max_len 2048` + 分页 8 位 AdamW 下，约 26 GB**。达到了极限。 |
|
|
82
|
+
| ≤6B | `mode="full"`（完全微调） | 纯 GPU 完全微调——bf16 权重，不使用适配器。在 32 GB 上，显卡能够支持的上限是 6B。 |
|
|
83
|
+
| **7B 级别** (Qwen 2.5 7B / Llama-3.1-8B / Mistral 7B) | `mode="full" --full-ft-offload` | **通过 FSDP2 CPU 卸载进行完全微调**——将参数 + 优化器溢出到 64 GB 主机 RAM 中。速度较慢（受带宽限制）；Linux/WSL2。 |
|
|
83
84
|
|
|
84
|
-
|
|
85
|
+
大多数单 GPU 库都会让您使用其他方法来处理两件事——**24–34B QLoRA** 和 **单个显卡上的 7B 级别完全微调**——反向传播可以在一个消费级显卡上完成，然后将结果直接导出到 Ollama。
|
|
85
86
|
|
|
86
|
-
|
|
87
|
+
**完全微调的上限取决于显卡。**它基于以下训练内存算术（权重 + 梯度 + 优化器 + 激活值）与您*检测到的* 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）。请参阅[完整的微调手册页面](https://mcp-tool-shop-org.github.io/backpropagate/handbook/full-fine-tuning/)，了解 VRAM 计算 + Biderman 2024 / Thinking Machines 2025 的质量比较。
|
|
87
88
|
|
|
88
|
-
|
|
89
|
+
### 可以扩展到 16 GB
|
|
90
|
+
|
|
91
|
+
即使是 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）。相同的代码会选择适合检测到的任何显卡的批大小和完全微调上限——无需更改标志。
|
|
92
|
+
|
|
93
|
+
2 位量化 (AQLM / QuIP#) **不在本次讨论范围内**——一个 2 位的基模型无法干净地合并回全精度权重，这会破坏可合并的适配器 → GGUF → Ollama 导出流程（这是整个流水线的目的）。反向传播提供的替代方案是——QLoRA、`mode="full"`、`--full-ft-offload` 和 FP8 计算路径 (`--fp8`, Blackwell/Hopper)——所有这些都保持可合并和可导出。
|
|
89
94
|
|
|
90
95
|
## Backpropagate 不适用于以下情况
|
|
91
96
|
|
|
92
97
|
如果你的用例如下，你最好使用不同的库——Backpropagate 不是正确的选择，并且尝试使其工作会花费更多的时间。在开始之前阅读本部分可以节省安装和放弃的周期：
|
|
93
98
|
|
|
94
|
-
-
|
|
95
|
-
- **在线强化学习——PPO/GRPO/RLVR**——Backpropagate 执行单阶段 SFT 以及无参考偏好调整（
|
|
99
|
+
- **超出卸载上限的全参数微调（≈13B+）**——在 32GB 的显卡上，通过 `--full-ft-offload` 将全参数微调回溯到最多 **~6GB 的纯 GPU 和 ~7GB 级别的模型**（参见[此处](#what-you-can-fine-tune-on-one-gpu)）。对 13B+ 模型进行*真正的完整*微调已经超出了这个范围——它需要多 GPU FSDP 或更大的显卡（使用 `transformers.Trainer` 在多个 GPU 上运行，或租用 A100/H100）。但在投入大量计算资源之前：最近的研究（[Biderman 2024](https://arxiv.org/abs/2405.09673)，[Thinking Machines 2025](https://thinkingmachines.ai/blog/lora/)）表明，在大多数后训练任务（指令遵循、领域适应、个性/风格）中，LoRA 在正确的配置下可以达到与完整微调相同的质量，并且计算量仅为 ~67%——因此，QLoRA 可以扩展到 34B，Backpropagate 在单个显卡上运行，对于大多数用户实际需要的任务来说，不会有任何损失。
|
|
100
|
+
- **在线强化学习——PPO / GRPO / RLVR**——Backpropagate 执行单阶段 SFT 以及无参考偏好调整（v1.5 中的 ORPO；v1.6 中的 SimPO + KTO）。它*不*执行在线强化学习——PPO、GRPO 或 RLVR——这些方法需要一个奖励模型或在训练步骤之上进行生成和评分循环。对于这些，请直接使用 TRL 或 LLaMA-Factory。（无参考偏好调整符合单阶段的范围，因为不需要将单独的参考模型保存在内存中；参见[快速入门](#quick-start)中的 ORPO 注释。）
|
|
96
101
|
- **多节点训练**——仅支持单个机器上的单个 GPU。单个机器上的多 GPU 也可以工作（通过 `accelerate launch`），但未正式支持。
|
|
97
|
-
-
|
|
98
|
-
-
|
|
102
|
+
- **macOS 上基于 CUDA 的训练**——Apple Silicon 没有 CUDA，因此 CUDA 路径在配备 NVIDIA GPU 的 Linux 或 Windows 系统上运行。您仍然可以通过 Ollama 在 Mac 上运行经过训练的模型。一个**实验性的、未经验证的预览版** MLX 框架（`--backend mlx`）可以在 Apple Silicon 上本地训练 LoRA 适配器——参见[Apple Silicon (MLX)](#apple-silicon-mlx--unverified-preview)。它仅支持 LoRA-SFT，并且**尚未在实际硬件上进行测试**（没有支持），因此对于任何超出 LoRA SFT（ORPO、完整微调、FP8、多轮运行）的任务，您应该使用 CUDA 框架。
|
|
103
|
+
- **除经过测试的模型系列之外的任何模型**——Qwen 2.5 / 3.5 (7B / 4B)、Phi-4-mini-3.8B、SmolLM3-3B、Llama 3.2 (3B / 1B)、Mistral 7B。其他模型通常也可以工作，但未在 CI 中进行固定测试。
|
|
99
104
|
|
|
100
105
|
如果您需要上述任何功能，请使用上面列出的库之一。它们在这方面表现更好。
|
|
101
106
|
|
|
@@ -166,15 +171,17 @@ trainer.export("gguf", quantization="q4_k_m")
|
|
|
166
171
|
backprop train --data preferences.jsonl --method orpo --steps 100
|
|
167
172
|
```
|
|
168
173
|
|
|
169
|
-
|
|
174
|
+
默认学习率会自动降低到 `8e-6` 用于 ORPO（损失比普通的 SFT 更陡峭）；调整 `--orpo-beta`（默认为 `0.1`），以调整优势比惩罚的权重。ORPO 仅为 `mode="lora"`。
|
|
170
175
|
|
|
171
|
-
**v1.6
|
|
176
|
+
**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 对比的数据；它会自动平衡来自标签计数的理想/非理想损失权重。两者都仅为 `mode="lora"`，并且停留在单个 GPU SFT 的范围内（没有单独的参考模型）。请参见[偏好调整手册](https://mcp-tool-shop-org.github.io/backpropagate/handbook/preference-tuning/) 以了解应该使用哪种方法。对于在线强化学习（PPO/GRPO），请参见[Backpropagate 不适用于哪些场景](#what-backpropagate-is-not-for)。
|
|
172
177
|
|
|
173
178
|
### 基于推理轨迹的 SFT（R1 蒸馏）
|
|
174
179
|
|
|
175
180
|
v1.5 中的新功能：以简单的方式蒸馏一个推理模型。传递 `--reasoning-trace`（命令行界面）或 `Trainer(..., reasoning_trace=True)`（Python），并提供包含 `<think>...</think>` 链式思维的轨迹，这些轨迹位于助手回复中——这是 [DeepSeek-R1](https://arxiv.org/abs/2501.12948) 蒸馏的纯 SFT 部分，无需 RL。反向传播会在训练目标中保留 `<think>`，删除空/过长的轨迹（轨迹长度过滤），并将默认 `max_seq_length` 提高到 8192，以适应更长的 CoT。重要的是，`<think>` 保持为**纯文本**——没有特殊的令牌，没有嵌入调整——因此合并后的 GGUF 仍然可以导出到 Ollama，就像任何其他微调模型一样。仅 SFT。请参阅 [reasoning-trace 配方](https://mcp-tool-shop-org.github.io/backpropagate/handbook/recipes/#reasoning-trace-sft-r1-distillation)，了解数据集的形状和可调整的令牌范围。
|
|
176
181
|
|
|
177
|
-
### Apple Silicon (MLX)
|
|
182
|
+
### Apple Silicon (MLX)——未经验证的预览版
|
|
183
|
+
|
|
184
|
+
> ⚠️ **未经验证的预览版——不属于受支持的功能集。** MLX 框架已经构建并进行了单元测试，但尚未在实际 Apple Silicon 上进行测试（`mlx-lm` 仅适用于 Apple 设备，无法在 Backpropagate 开发所使用的 NVIDIA 系统上运行）。请将以下所有内容视为实验性的，自行承担风险，如果您在 M 系列 Mac 上运行它，请[报告异常](#reporting-bugs)。
|
|
178
185
|
|
|
179
186
|
v1.5 中的新功能：**一个 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 设置在字节级别上是相同的：
|
|
180
187
|
|
|
@@ -192,7 +199,7 @@ backprop train --data my_data.jsonl --backend mlx --steps 100
|
|
|
192
199
|
|
|
193
200
|
在 v1.5 中，MLX 框架**仅支持 LoRA SFT**——不支持 ORPO、不支持 FP8、不支持 `mode='full'`，目前也不支持在 MLX 上进行多轮训练（每轮都会出现 `CONFIG_INVALID_SETTING` 错误；如果需要这些功能，请在 NVIDIA 机器上使用 `backend='cuda'`/`'auto'`）。生成的适配器是纯 safetensors 格式，并通过与 CUDA 框架相同的路径导出到 Ollama。
|
|
194
201
|
|
|
195
|
-
>
|
|
202
|
+
> 在非 Apple 主机上强制使用 `--backend mlx` 会出现 `CONFIG_INVALID_SETTING` 错误；Mac 上缺少 `mlx_lm` 工具链会引发 `DEP_MLX_UNAVAILABLE`。
|
|
196
203
|
|
|
197
204
|
有关更多端到端的流程（微调并推送到 HF Hub、在 OOM 之后恢复、在长时间的训练过程中进行多轮 SLAO 等），请参阅 [手册配方页面](https://mcp-tool-shop-org.github.io/backpropagate/handbook/recipes/)。
|
|
198
205
|
|
|
@@ -305,7 +312,7 @@ UI 中的文件系统写入操作被限制在一个目录中：
|
|
|
305
312
|
|
|
306
313
|
**要求：** Python 3.10+ · CUDA GPU（8GB+ VRAM）· PyTorch 2.0+
|
|
307
314
|
|
|
308
|
-
Python 3.10
|
|
315
|
+
Python 3.10 至少在 v1.6 中受支持；它将在 2026 年 10 月达到上游生命周期结束，并且计划在之后的第一个版本中删除。对于新安装，请首选 Python 3.11 或 3.12——3.11 是经过最多测试的最低版本。
|
|
309
316
|
|
|
310
317
|
Backpropagate 处理不同平台上训练时出现的一些运行时问题，但它无法修复安装时出现的问题。最常见的问题有两个：
|
|
311
318
|
|
|
@@ -364,8 +371,12 @@ backprop export-runs --format jsonl # bulk export run history
|
|
|
364
371
|
| Llama 3.2 3B | ~8GB | Llama Community | 是 Qwen 3B 的一个不错的替代方案，但有一些宽松的限制。 |
|
|
365
372
|
| Llama 3.2 1B | ~6GB | Llama Community | 用于在小型设备上进行快速实验。 |
|
|
366
373
|
| Mistral 7B | ~12GB | Apache 2.0 | 与 Qwen 7B 相当，但使用了不同的聊天模板。 |
|
|
374
|
+
| Llama-3.1-8B | ~7-8GB（QLoRA） | Llama-3.1-Community | 8B QLoRA，128K 本地上下文（>700M-MAU 条款需要单独的 Meta 许可证）。 |
|
|
375
|
+
| **Qwen2.5-14B** | ~8.5GB（QLoRA） | Apache 2.0 | **32 GB 日常使用最佳配置**——rank/alpha 32，分页 8 位 AdamW，4096 ctx。 |
|
|
376
|
+
| Mistral-Small-24B | ~18GB（QLoRA） | Apache 2.0 | 在 32 GB 显卡上使用 4096-ctx，可以进行 24B QLoRA 微调。 |
|
|
377
|
+
| **Qwen2.5-32B** | ~26GB（QLoRA） | Apache 2.0 | **达到 32 GB 范围的上限**——仅在 `max_len 2048` + 分页 8 位 AdamW 时才能容纳。 |
|
|
367
378
|
|
|
368
|
-
|
|
379
|
+
其他模型通常也可以工作；上述行是经过策划的预设——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 目标。
|
|
369
380
|
|
|
370
381
|
## 故障排除
|
|
371
382
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mcptoolshop/backpropagate",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.7.0",
|
|
4
4
|
"description": "Deprecated npm distribution shim for backpropagate — prints install guidance for pipx/uv tool/pip. See https://github.com/mcp-tool-shop-org/backpropagate",
|
|
5
5
|
"type": "commonjs",
|
|
6
6
|
"license": "MIT",
|