@mcptoolshop/backpropagate 1.5.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 +37 -24
- package/README.fr.md +37 -24
- package/README.hi.md +37 -24
- package/README.it.md +120 -107
- package/README.ja.md +37 -24
- package/README.md +40 -27
- package/README.pt-BR.md +37 -24
- package/README.zh.md +36 -23
- package/package.json +1 -1
package/README.ja.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
|
+
# 320億パラメータのQLoRAモデル、または70億パラメータのエンドツーエンドモデルを1つのGPUで微調整します。Ollamaにデプロイします
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
大規模言語モデルの微調整を**単一の**GPU上で実行し、実際に使用しているカードに合わせてサイズを調整します。3行のPythonコードで、70億～340億パラメータのモデルを1つの32GBのコンシューマーカード（RTX 5090）で実行できます。`--full-ft-offload`フラグを使用すると、最適化の状態をホストRAMにオフロードすることで、70億パラメータ規模のモデルを完全に微調整できます。さらにコマンドを実行してOllamaにエクスポートし、`ollama run`で微調整したモデルを実行します。16GBまでスムーズにスケールダウンできます。Windowsでも優れたパフォーマンスを発揮します。
|
|
21
21
|
|
|
22
22
|
```python
|
|
23
23
|
from backpropagate import Trainer
|
|
@@ -69,33 +69,38 @@ Backpropagateは、不足している選択肢です。**単一のコンシュ
|
|
|
69
69
|
|
|
70
70
|
上記のいずれかのライブラリを試して、設定ファイルの操作に苦労したり、モデルファミリーの制限に遭遇したり、Windowsを優先するデフォルト設定が必要になった場合は、Backpropagateが最適です。
|
|
71
71
|
|
|
72
|
-
##
|
|
72
|
+
## 1つのGPUで微調整できるもの
|
|
73
73
|
|
|
74
|
-
|
|
74
|
+
Backpropagateは、実行に必要なリソースをカードに合わせて調整します。以下は、64GBのホストRAMを備えた**32GB**のコンシューマーGPU（RTX 5090）での実用的な上限です。
|
|
75
75
|
|
|
76
|
-
|
|
|
76
|
+
| モデルサイズ | 方法 | 32GBカードでの状況 |
|
|
77
77
|
|---|---|---|
|
|
78
|
-
| Qwen
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
|
|
|
78
|
+
| 70億パラメータ（Qwen 2.5 7B / Llama-3.1-8B / Mistral 7B） | QLoRA | 快適に動作します。約7～8GBを使用し、十分な余裕があります。完全なシーケンス長で実行できます。 |
|
|
79
|
+
| **140億パラメータ（Qwen2.5-14B）** | QLoRA | **日常的な使用に最適なサイズ — 約8.5GB**。rank/alpha 32、ページングされた8ビットAdamW、4096のコンテキスト長で測定。 |
|
|
80
|
+
| 240億パラメータ（Mistral-Small-24B） | QLoRA | 約18GBを使用します。4096のコンテキスト長で実行しても余裕があります。 |
|
|
81
|
+
| **320億パラメータ（Qwen2.5-32B）** | QLoRA | **ギリギリ動作するサイズ — `max_len 2048` + ページングされた8ビットAdamWで約26GB**。上限に近い状態です。 |
|
|
82
|
+
| 60億パラメータ以下 | `mode="full"`（完全な微調整） | GPUのみを使用した完全な微調整 — bf16の重みを使用し、アダプターは使用しません。32GBでは、カードがサポートできる上限は60億パラメータです。 |
|
|
83
|
+
| **70億パラメータ規模（Qwen 2.5 7B / Llama-3.1-8B / Mistral 7B）** | `mode="full" --full-ft-offload` | **FSDP2を使用したCPUオフロードによる完全な微調整** — パラメータと最適化の状態を64GBのホストRAMにオフロードします。速度は遅くなります（帯域幅がボトルネック）。Linux/WSL2でのみ動作します。 |
|
|
83
84
|
|
|
84
|
-
|
|
85
|
+
ほとんどの単一GPUライブラリでは、**24～340億パラメータのQLoRA**と**単一カードでの70億パラメータ規模の完全な微調整**のために別の場所に誘導しますが、Backpropagateはこれらを1つのコンシューマーカードで実行し、結果をOllamaに直接エクスポートします。
|
|
85
86
|
|
|
86
|
-
|
|
87
|
+
**完全な微調整の上限は、カードに合わせて調整されます。** これは、4つの要素（重み + 勾配 + 最適化器 + 活性化）のトレーニングメモリ計算に基づいており、*検出された*VRAMに対して行われます。**16GB → 40億パラメータ、24GB → 50億パラメータ、32GB → 60億パラメータ**がGPUのみで使用できる上限です。`--full-ft-offload`を使用すると、パラメータと最適化の状態をFSDP2の`fully_shard` + `CPUOffloadPolicy`を通じてホストRAMにオフロードすることで、**70億パラメータ規模**まで拡張できます（速度は遅くなり、PCIe/CPU帯域幅がボトルネックになります。約64GBのホスト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
|
+
### 16GBまでスケールダウン可能
|
|
90
|
+
|
|
91
|
+
16GB（RTX 4080 / 5080 / 4070 Ti Super）の環境でも優れたパフォーマンスを発揮します。70億パラメータのQLoRAは約7～8GBを使用し、真の完全な微調整を約30億パラメータ（SmolLM3-3B、Qwen2.5-3B、Llama-3.2-3B/1B）に対して16GB内で`mode="full"`を使用して実行できます（bf16の重み + 勾配チェックポイント + ページングされた8ビットAdamW）。同じコードは、検出されたカードに合わせてバッチサイズと完全な微調整の上限を自動的に選択します。設定を変更する必要はありません。
|
|
92
|
+
|
|
93
|
+
2ビット量子化（AQLM / QuIP#）は**対象外**です — 2ビットのベースモデルを完全に精度の高い重みにクリーンにマージすることはできず、マージ可能なアダプター → GGUF → Ollamaのエクスポートという一連の流れが中断されます（このパイプライン全体の目的）。Backpropagateでは、代わりにQLoRA、`mode="full"`、`--full-ft-offload`、およびFP8計算パス（`--fp8`、Blackwell/Hopper）などの機能を提供し、これらはすべてマージ可能でエクスポート可能です。
|
|
89
94
|
|
|
90
95
|
## Backpropagateが適さない場合
|
|
91
96
|
|
|
92
97
|
以下のユースケースに該当する場合は、別のライブラリを使用する方が良い結果が得られます。Backpropagateは適切な選択肢ではなく、無理に使用しようとすると、適切なツールを選択するよりも多くの労力がかかります。インストールを開始する前に、このセクションを読んでください。
|
|
93
98
|
|
|
94
|
-
-
|
|
95
|
-
-
|
|
96
|
-
- **マルチノードトレーニング** —
|
|
97
|
-
- **CUDA
|
|
98
|
-
-
|
|
99
|
+
- **フルパラメータの微調整を、オフロードの上限を超えて行う（約13B以上）** — 最大で**〜6GBの純粋なGPUと〜7Bクラスを`--full-ft-offload`オプションを使用して、32GBのカード上で実行し、フル微調整を行う**（[この範囲](#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%で済む。したがって、最大34Bまで可能なQLoRAは、Backpropagateが単一のカード上で実行する場合、ほとんどのユーザーが求めるタスクに対してパフォーマンスを損なうことはない。
|
|
100
|
+
- **オンライン強化学習 — PPO / GRPO / RLVR** — Backpropagateは、シングルステージSFTと参照不要の嗜好調整（v1.5ではORPO、v1.6ではSimPO + KTO）を実行する。ただし、オンライン強化学習—PPO、GRPO、またはRLVR—は実行しない。これらは、報酬モデルまたはトレーニングステップに加えて、生成とスコアリングを行うループを必要とする。これらの場合は、TRLを直接使用するか、LLaMA-Factoryを使用する（参照不要の嗜好調整は、メモリ内に保持する必要のある個別の参照モデルがないため、シングルステージの範囲に適合する。詳細は[Quick Start](#quick-start)のORPOに関する注を参照）。
|
|
101
|
+
- **マルチノードトレーニング** — 単一のマシン上の単一GPUのみ。単一のマシン上で複数のGPUを使用することも可能（`accelerate launch`経由）だが、公式にはサポートされていない。
|
|
102
|
+
- **CUDA環境でのmacOSトレーニング** — 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
|
|
|
@@ -145,7 +150,7 @@ trainer.export('gguf', quantization='q4_k_m')
|
|
|
145
150
|
|
|
146
151
|
Alpaca（`instruction` / `output`）、OpenAIチャット（`messages`）、および生のテキスト形式も機能します。Backpropagateは、形式を自動的に検出します。
|
|
147
152
|
|
|
148
|
-
###
|
|
153
|
+
### 嗜好性チューニング（ORPO、SimPO、KTO）
|
|
149
154
|
|
|
150
155
|
v1.5の新機能：プレーンなデモンストレーションではなく、優先度に基づいてトレーニングします。ORPOは参照なしで、単一ステージです。優先度のシグナルをSFTステップに組み込むため、個別の報酬モデルや参照モデルはなく、3行の構造は変わりません。`--method orpo`（CLI）または`method="orpo"`（Python）を渡し、`{prompt, chosen, rejected}`（または`{chosen, rejected}`のみ）の行のデータセットを渡します。
|
|
151
156
|
|
|
@@ -166,13 +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
|
-
デフォルトの学習率は、ORPO
|
|
174
|
+
デフォルトの学習率は、ORPOに対して自動的に`8e-6`まで低下します（損失は単純なSFTよりも急峻です）。オッズ比ペナルティの重みを調整するために、`--orpo-beta`（デフォルトは`0.1`）を調整してください。ORPOは`mode="lora"`でのみ使用できます。
|
|
175
|
+
|
|
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/)を参照してください。オンラインRL（PPO/GRPO）については、[Backpropagateが適さない理由](#what-backpropagate-is-not-for)をご覧ください。
|
|
170
177
|
|
|
171
178
|
### 推論トレースSFT（R1蒸留）
|
|
172
179
|
|
|
173
180
|
v1.5の新機能：推論モデルを簡単に蒸留します。`--reasoning-trace`（CLI）または `Trainer(..., reasoning_trace=True)`（Python）を渡し、アシスタントの応答内に `<think>...</think>` の連鎖的な思考を保持するトレースを入力します。これは、[DeepSeek-R1](https://arxiv.org/abs/2501.12948) 蒸留の純粋なSFT部分であり、RLは必要ありません。バックプロパゲーションは `<think>` をトレーニングターゲットに保持し、空の/長すぎるトレースを削除（トレース長フィルタリング）、およびより長いCoTのためにデフォルトの `max_seq_length` を8192に引き上げます。重要な点として、`<think>` は **プレーンテキスト** のままです。特別なトークンや、埋め込みのリサイズは行われません。そのため、マージされたGGUFは、他のファインチューンと同様にOllamaにエクスポートできます。SFTのみです。データセットの形状と調整可能なトークンバンドについては、[reasoning-trace recipe](https://mcp-tool-shop-org.github.io/backpropagate/handbook/recipes/#reasoning-trace-sft-r1-distillation) を参照してください。
|
|
174
181
|
|
|
175
|
-
### Apple Silicon
|
|
182
|
+
### Apple Silicon (MLX) — 検証されていないプレビュー
|
|
183
|
+
|
|
184
|
+
> ⚠️ **検証されていないプレビュー — サポートされている機能セットの一部ではない。** MLXレールは構築され、ユニットテストも行われているが、**実際のApple Silicon上での検証（`mlx-lm`はApple専用であり、Backpropagateの開発に使用されるNVIDIAリグでは実行できない）は行われていない**。以下すべてを実験的なものとして扱い、自己責任で使用し、MシリーズのMacで実行した場合は[バグ報告](#reporting-bugs)を行うこと。
|
|
176
185
|
|
|
177
186
|
v1.5の新機能：**1つのAPI、2つのレール。** CUDAは、引き続き標準で検証済みのバックエンドです。MLXは、Appleの [`mlx_lm.lora`](https://github.com/ml-explore/mlx-lm) ツールチェーンを介して、MシリーズMacでトレーニングを行う2番目のレールです（統合メモリ、CUDAは不要）。同じ3行のコードで、ハードウェアによってレールを選択します。`backend='auto'`（デフォルト）は、NVIDIAではCUDAに、Apple SiliconではMLXにルーティングするため、既存のCUDA環境はバイト単位で同一です。
|
|
178
187
|
|
|
@@ -190,7 +199,7 @@ backprop train --data my_data.jsonl --backend mlx --steps 100
|
|
|
190
199
|
|
|
191
200
|
v1.5では、MLXレールは **LoRA SFTのみ** です。ORPO、FP8、`mode='full'`、MLXでのマルチランはまだサポートされていません（それぞれ `CONFIG_INVALID_SETTING` で拒否されます。それらの機能を使用する場合は、NVIDIA環境で `backend='cuda'` / `'auto'` を使用してください）。結果として得られるアダプターは、プレーンなsafetensorsであり、CUDAレールと同じパスを通じてOllamaにエクスポートされます。
|
|
192
201
|
|
|
193
|
-
>
|
|
202
|
+
> `--backend mlx`をApple以外のホストに強制的に適用すると、`CONFIG_INVALID_SETTING`エラーが発生する。Mac上に`mlx_lm`ツールチェーンがない場合、`DEP_MLX_UNAVAILABLE`エラーが発生する。
|
|
194
203
|
|
|
195
204
|
よりエンドツーエンドのワークフロー（ファインチューンとHF Hubへのプッシュ、OOM後の再開、長期間のキャンペーンにおけるマルチランSLAOなど）については、[ハンドブックのレシピページ](https://mcp-tool-shop-org.github.io/backpropagate/handbook/recipes/) を参照してください。
|
|
196
205
|
|
|
@@ -303,7 +312,7 @@ UIからのファイルシステムへの書き込みは、単一のディレク
|
|
|
303
312
|
|
|
304
313
|
**要件：** Python 3.10+、CUDA GPU（8GB以上のVRAM）、PyTorch 2.0+
|
|
305
314
|
|
|
306
|
-
Python 3.10
|
|
315
|
+
Python 3.10は少なくともv1.6までサポートされます。2026年10月にアップストリームのサポートが終了し、その後最初のリリースで削除される予定です。新しいインストールでは、Python 3.11または3.12を推奨します。3.11は最もテストされたバージョンです。
|
|
307
316
|
|
|
308
317
|
Backpropagateは、さまざまなプラットフォームでのトレーニングにおける実行時の癖に対処しますが、インストール時の問題を修正することはできません。最も一般的な問題は次の2つです。
|
|
309
318
|
|
|
@@ -362,8 +371,12 @@ backprop export-runs --format jsonl # bulk export run history
|
|
|
362
371
|
| Llama 3.2 3B | 約8GB | Llama Community | Qwen 3Bの優れた代替手段で、許可に関する制限があります。 |
|
|
363
372
|
| Llama 3.2 1B | 約6GB | Llama Community | 小さなカードで迅速な実験を行うためのものです。 |
|
|
364
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 | **32GBのカードで最適なパフォーマンスを発揮するポイント** — ランク/アルファ32、ページングされた8ビットAdamW、4096 ctx。 |
|
|
376
|
+
| Mistral-Small-24B | 〜18GB（QLoRA） | Apache 2.0 | 4096-ctxの余裕がある状態で、32GBのカード上で24B QLoRAを実行。 |
|
|
377
|
+
| **Qwen2.5-32B** | 〜26GB（QLoRA） | Apache 2.0 | **32GBの範囲で最大限に活用できる設定** — `max_len 2048` + ページングされた8ビットAdamWで、ギリギリ収まる。 |
|
|
365
378
|
|
|
366
|
-
|
|
379
|
+
他のモデルも多くの場合動作する。上記の行は、調整済みのプリセットである。14B〜32Bの範囲は、32GBのカード用にQLoRAが調整されている（測定された範囲）。Biderman 2024 + Thinking Machines 2025に従い、ランク256 / すべての線形ターゲットに対して`--lora-preset=quality`（デフォルト）を渡すか、v1.2.xのフットプリントが必要な場合は、レガシーのランク16 / q+vターゲットに対して`--lora-preset=fast`を渡す。
|
|
367
380
|
|
|
368
381
|
## トラブルシューティング
|
|
369
382
|
|
package/README.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
|
+
# Fine-tune a 32B QLoRA — or a 7B end to end — on one GPU. Ship it to Ollama.
|
|
19
19
|
|
|
20
|
-
Backpropagate
|
|
20
|
+
Backpropagate fine-tunes large language models on a **single** GPU, sized for the card you actually have. Three lines of Python QLoRA a 7B–34B model on one 32 GB consumer card (RTX 5090); one flag — `--full-ft-offload` — full-fine-tunes a 7B-class model by spilling the optimizer state to host RAM. One more command exports to Ollama, then `ollama run` your finetune. Scales cleanly down to 16 GB. First-class on Windows.
|
|
21
21
|
|
|
22
22
|
```python
|
|
23
23
|
from backpropagate import Trainer
|
|
@@ -69,32 +69,37 @@ Backpropagate is the missing option: **a 3-line Python API for solo operators on
|
|
|
69
69
|
|
|
70
70
|
If you tried one of the libraries above and bounced off the config-file ceremony, or hit a model-family gap, or wanted Windows-first defaults — Backpropagate is for you.
|
|
71
71
|
|
|
72
|
-
## What you can fine-tune on
|
|
72
|
+
## What you can fine-tune on one GPU
|
|
73
73
|
|
|
74
|
-
Here's the practical envelope on a
|
|
74
|
+
Backpropagate sizes the run to your card. Here's the practical envelope on a **32 GB** consumer GPU (RTX 5090) with 64 GB host RAM — the rig it's tuned on:
|
|
75
75
|
|
|
76
|
-
| Model | Method | Status |
|
|
76
|
+
| Model size | Method | Status on a 32 GB card |
|
|
77
77
|
|---|---|---|
|
|
78
|
-
| Qwen
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
|
|
|
78
|
+
| 7B (Qwen 2.5 7B / Llama-3.1-8B / Mistral 7B) | QLoRA | Comfortable — ~7–8 GB. Full sequence length, lots of headroom. |
|
|
79
|
+
| **14B** (Qwen2.5-14B) | QLoRA | **The daily-driver sweet spot — ~8.5 GB** measured. rank/alpha 32, paged 8-bit AdamW, 4096 ctx. |
|
|
80
|
+
| 24B (Mistral-Small-24B) | QLoRA | ~18 GB. Fits with headroom at 4096 ctx. |
|
|
81
|
+
| **32B** (Qwen2.5-32B) | QLoRA | **Just fits — ~26 GB** at `max_len 2048` + paged 8-bit AdamW. Top of the envelope. |
|
|
82
|
+
| ≤6B | `mode="full"` (true full fine-tuning) | Pure-GPU full FT — bf16 weights, no adapter. The card-aware ceiling is 6B on 32 GB. |
|
|
83
|
+
| **7B-class** (Qwen 2.5 7B / Llama-3.1-8B / Mistral 7B) | `mode="full" --full-ft-offload` | **Full fine-tuning via FSDP2 CPU-offload** — spills params + optimizer to 64 GB host RAM. Slower (bandwidth-bound); Linux/WSL2. |
|
|
83
84
|
|
|
84
|
-
|
|
85
|
+
Two things most single-GPU libraries send you elsewhere for — **24–34B QLoRA** and **single-card 7B-class full fine-tuning** — Backpropagate does on one consumer card, then exports the result straight to Ollama.
|
|
85
86
|
|
|
86
|
-
|
|
87
|
+
**The full-FT ceiling is card-aware.** It's derived from the 4-addend training-memory arithmetic (weights + gradients + optimizer + activations) against your *detected* VRAM: **16 GB → 4B, 24 GB → 5B, 32 GB → 6B** pure-GPU. `--full-ft-offload` lifts it to **7B-class** by spilling params + optimizer state into host RAM via FSDP2 `fully_shard` + `CPUOffloadPolicy` (slower, PCIe/CPU-bandwidth-bound; needs ~64 GB host RAM and an NCCL backend, i.e. Linux/WSL2). Override the ceiling explicitly with `--full-ft-ceiling-billions`. A model past even the offload ceiling exits with `RUNTIME_FULL_FT_MODEL_TOO_LARGE`, naming the recovery (`--full-ft-offload`, or LoRA/QLoRA). See [the full fine-tuning handbook page](https://mcp-tool-shop-org.github.io/backpropagate/handbook/full-fine-tuning/) for the VRAM math + the Biderman 2024 / Thinking Machines 2025 quality comparison.
|
|
87
88
|
|
|
88
|
-
|
|
89
|
+
### Scales down to 16 GB
|
|
90
|
+
|
|
91
|
+
The 16 GB envelope (RTX 4080 / 5080 / 4070 Ti Super) is still first-class: 7B QLoRA at ~7–8 GB, and true full fine-tuning of a genuine ~3B (SmolLM3-3B, Qwen2.5-3B, Llama-3.2-3B/1B) inside 16 GB via `mode="full"` (bf16 weights + gradient checkpointing + paged 8-bit AdamW). The same code picks the batch size and full-FT ceiling that fit whatever card it detects — no flags to change between rigs.
|
|
92
|
+
|
|
93
|
+
2-bit quantization (AQLM / QuIP#) stays **out of scope** — a 2-bit base can't be cleanly merged back into full-precision weights, which breaks the mergeable-adapter → GGUF → Ollama export contract (the whole point of the pipeline). The headroom levers Backpropagate ships instead — QLoRA, `mode="full"`, `--full-ft-offload`, and the FP8 compute path (`--fp8`, Blackwell/Hopper) — all stay mergeable and exportable.
|
|
89
94
|
|
|
90
95
|
## What Backpropagate is NOT for
|
|
91
96
|
|
|
92
97
|
If your use case is below, you'll have a better time with a different library — Backpropagate is not the right pick and trying to make it work would cost more than just reaching for the right tool. Reading this section before you start saves the install-and-bounce cycle:
|
|
93
98
|
|
|
94
|
-
- **Full-parameter fine-tuning
|
|
95
|
-
- **Online RL — PPO / GRPO / RLVR** — Backpropagate does single-stage SFT plus reference-free preference tuning (ORPO
|
|
99
|
+
- **Full-parameter fine-tuning past the offload ceiling (≈13B+)** — Backpropagate full-fine-tunes up to **~6B pure-GPU and ~7B-class via `--full-ft-offload`** on a 32 GB card (see [the envelope](#what-you-can-fine-tune-on-one-gpu)). A *true full* fine-tune of a 13B+ model is past that — it wants multi-GPU FSDP or a bigger card (reach for `transformers.Trainer` across multiple GPUs, or rent an A100/H100). Before spending that compute, though: recent research ([Biderman 2024](https://arxiv.org/abs/2405.09673), [Thinking Machines 2025](https://thinkingmachines.ai/blog/lora/)) shows LoRA at correct configuration matches full fine-tuning quality on most post-training tasks (instruction-following, domain adaptation, persona/style) at ~67% of the compute — so QLoRA up to 34B, which Backpropagate does on one card, loses nothing for the work most operators actually want.
|
|
100
|
+
- **Online RL — PPO / GRPO / RLVR** — Backpropagate does single-stage SFT plus reference-free preference tuning (ORPO in v1.5; SimPO + KTO in v1.6). What it does *not* do is online reinforcement learning — PPO, GRPO, or RLVR — which needs a reward model or a generation-and-scoring loop on top of the training step. For those, use TRL directly or LLaMA-Factory. (Reference-free preference tuning fits the single-stage envelope because there's no separate reference model to hold in memory; see the ORPO note under [Quick Start](#quick-start).)
|
|
96
101
|
- **Multi-node training** — single GPU on one machine only. Multi-GPU on one machine works (via `accelerate launch`) but isn't officially supported.
|
|
97
|
-
- **macOS training on the CUDA rail** — Apple Silicon doesn't have CUDA, so the CUDA path
|
|
102
|
+
- **macOS training on the CUDA rail** — Apple Silicon doesn't have CUDA, so the CUDA path runs on a Linux or Windows box with an NVIDIA GPU. You can still run the trained model on a Mac via Ollama. An **experimental, unverified-preview** MLX rail (`--backend mlx`) trains a LoRA adapter natively on Apple Silicon — see [Apple Silicon (MLX)](#apple-silicon-mlx--unverified-preview). It is LoRA-SFT-only and **not dogfood-verified on real silicon** (no support), so for anything beyond a LoRA SFT (ORPO, full fine-tune, FP8, multi-run) you want the CUDA rail.
|
|
98
103
|
- **Anything outside the tested model families** — Qwen 2.5 / 3.5 (7B / 4B), Phi-4-mini-3.8B, SmolLM3-3B, Llama 3.2 (3B / 1B), Mistral 7B. Other models often work but aren't pinned in CI.
|
|
99
104
|
|
|
100
105
|
If you need any of those things, reach for one of the libraries listed above. They're better at them.
|
|
@@ -145,9 +150,9 @@ This trains a Qwen 2.5 7B adapter on 5 short ShareGPT-format conversations, then
|
|
|
145
150
|
|
|
146
151
|
Alpaca (`instruction` / `output`), OpenAI chat (`messages`), and raw text formats also work — Backpropagate auto-detects the format.
|
|
147
152
|
|
|
148
|
-
### Preference tuning (ORPO)
|
|
153
|
+
### Preference tuning (ORPO, SimPO, KTO)
|
|
149
154
|
|
|
150
|
-
|
|
155
|
+
Train on preferences instead of plain demonstrations. ORPO is reference-free and single-stage — it folds the preference signal into the SFT step, so there's no separate reward or reference model and the 3-line shape is unchanged. Pass `--method orpo` (CLI) or `method="orpo"` (Python) and feed it a dataset of `{prompt, chosen, rejected}` (or just `{chosen, rejected}`) rows:
|
|
151
156
|
|
|
152
157
|
```jsonl
|
|
153
158
|
{"prompt": "What is Python?", "chosen": "A high-level programming language known for readability.", "rejected": "idk look it up"}
|
|
@@ -166,15 +171,19 @@ trainer.export("gguf", quantization="q4_k_m")
|
|
|
166
171
|
backprop train --data preferences.jsonl --method orpo --steps 100
|
|
167
172
|
```
|
|
168
173
|
|
|
169
|
-
The default learning rate auto-lowers to `8e-6` for ORPO (the loss is sharper than plain SFT); tune `--orpo-beta` (default `0.1`) to weight the odds-ratio penalty.
|
|
174
|
+
The default learning rate auto-lowers to `8e-6` for ORPO (the loss is sharper than plain SFT); tune `--orpo-beta` (default `0.1`) to weight the odds-ratio penalty. ORPO is `mode="lora"` only.
|
|
175
|
+
|
|
176
|
+
**New in v1.6 — SimPO and KTO.** `--method simpo` ([Meng et al. 2024](https://arxiv.org/abs/2405.14734)) is reference-free with a length-normalized reward and takes the same paired `{prompt, chosen, rejected}` data as ORPO (`--simpo-beta`, `--simpo-gamma`). `--method kto` ([Ethayarajh et al. 2024](https://arxiv.org/abs/2402.01306)) takes **unpaired** `{prompt, completion, label}` data — per-example thumbs-up/down — for the large class of feedback that isn't curated A/B pairs; it auto-balances the desirable/undesirable loss weights from your label counts. Both are `mode="lora"` only and stay in the single-GPU SFT envelope (no separate reference model). See the [preference-tuning handbook](https://mcp-tool-shop-org.github.io/backpropagate/handbook/preference-tuning/) for which to use. For online RL (PPO/GRPO) see [What Backpropagate is NOT for](#what-backpropagate-is-not-for).
|
|
170
177
|
|
|
171
178
|
### Reasoning-trace SFT (R1 distillation)
|
|
172
179
|
|
|
173
|
-
|
|
180
|
+
Distill a reasoning model the easy way. Pass `--reasoning-trace` (CLI) or `Trainer(..., reasoning_trace=True)` (Python) and feed it traces that keep a `<think>...</think>` chain-of-thought inside the assistant turn — the pure-SFT half of [DeepSeek-R1](https://arxiv.org/abs/2501.12948) distillation, no RL required. Backpropagate keeps `<think>` in the training target, drops empty / over-long traces (trace-length filtering), and raises the default `max_seq_length` to 8192 for the longer CoT. Critically, `<think>` stays **plain text** — no special tokens, no embedding resize — so the merged GGUF still exports to Ollama like any other fine-tune. SFT only. See the [reasoning-trace recipe](https://mcp-tool-shop-org.github.io/backpropagate/handbook/recipes/#reasoning-trace-sft-r1-distillation) for the dataset shape and the tunable token band.
|
|
181
|
+
|
|
182
|
+
### Apple Silicon (MLX) — unverified preview
|
|
174
183
|
|
|
175
|
-
|
|
184
|
+
> ⚠️ **Unverified preview — not part of the supported feature set.** The MLX rail is built and unit-tested but has **not** been dogfood-verified on real Apple Silicon (`mlx-lm` is Apple-only and can't run on the NVIDIA rigs Backpropagate is developed on). Treat everything below as experimental, use at your own risk, and [report anomalies](#reporting-bugs) if you run it on an M-series Mac.
|
|
176
185
|
|
|
177
|
-
|
|
186
|
+
**One API, two rails.** CUDA is the canonical, verified backend; MLX is a second rail that trains on an M-series Mac via Apple's [`mlx_lm.lora`](https://github.com/ml-explore/mlx-lm) toolchain (unified memory, no CUDA). The 3-line shape picks the rail by hardware — `backend='auto'` (the default) routes to CUDA on NVIDIA and to MLX on Apple Silicon, so existing CUDA rigs are byte-identical:
|
|
178
187
|
|
|
179
188
|
```python
|
|
180
189
|
from backpropagate import Trainer
|
|
@@ -188,9 +197,9 @@ trainer.train("examples/quickstart.jsonl", steps=100)
|
|
|
188
197
|
backprop train --data my_data.jsonl --backend mlx --steps 100
|
|
189
198
|
```
|
|
190
199
|
|
|
191
|
-
|
|
200
|
+
The MLX rail is **LoRA SFT only** — no ORPO, no FP8, no `mode='full'`, no multi-run (each is rejected with `CONFIG_INVALID_SETTING`; use `backend='cuda'`/`'auto'` on an NVIDIA box for those). The resulting adapter is plain safetensors and exports to Ollama through the same path as the CUDA rail.
|
|
192
201
|
|
|
193
|
-
>
|
|
202
|
+
> Forcing `--backend mlx` on a non-Apple host errors with `CONFIG_INVALID_SETTING`; a missing `mlx_lm` toolchain on a Mac raises `DEP_MLX_UNAVAILABLE`.
|
|
194
203
|
|
|
195
204
|
For more end-to-end workflows (fine-tune-and-push-to-HF-Hub, resume after OOM, multi-run SLAO across a long campaign, etc.) see the [handbook recipes page](https://mcp-tool-shop-org.github.io/backpropagate/handbook/recipes/).
|
|
196
205
|
|
|
@@ -303,14 +312,14 @@ Filesystem writes from the UI are sandboxed to a single directory:
|
|
|
303
312
|
|
|
304
313
|
**Requirements:** Python 3.10+ · CUDA GPU (8GB+ VRAM) · PyTorch 2.0+
|
|
305
314
|
|
|
306
|
-
Python 3.10 reaches upstream end-of-life in October 2026 and is scheduled for
|
|
315
|
+
Python 3.10 is supported through at least v1.6; it reaches upstream end-of-life in October 2026 and is scheduled for removal in the first release after that. For new installs, prefer Python 3.11 or 3.12 — 3.11 is the most-tested floor.
|
|
307
316
|
|
|
308
317
|
Backpropagate handles the runtime quirks of training on different platforms, but it can't fix install-time problems. The two most common are:
|
|
309
318
|
|
|
310
319
|
- **Wrong CUDA wheel.** PyTorch is published one binary per CUDA version. If you pick the wrong one, you silently get CPU-only PyTorch and training is impossibly slow. Use the wheel picker at <https://pytorch.org/get-started/locally/> for your driver. Run `nvidia-smi` to see your driver / CUDA version.
|
|
311
320
|
- **Windows + GGUF export.** The `[export]` extra builds `llama-cpp-python` from source, which needs Visual Studio Build Tools (C++ component) and CMake.
|
|
312
321
|
|
|
313
|
-
**macOS:** the CUDA rail is not supported (no CUDA) — a CUDA-routed `trainer.train()` raises `DEP_GPU_NOT_AVAILABLE`, and you can run the trained adapter on a Mac via Ollama. **
|
|
322
|
+
**macOS:** the CUDA rail is not supported (no CUDA) — a CUDA-routed `trainer.train()` raises `DEP_GPU_NOT_AVAILABLE`, and you can run the trained adapter on a Mac via Ollama. An **experimental, unverified-preview** MLX rail (`--backend mlx`, `pip install 'backpropagate[mlx]'`) trains a LoRA adapter natively on Apple Silicon via `mlx_lm.lora` — LoRA SFT only, and **not dogfood-verified on real silicon** (see [Apple Silicon (MLX)](#apple-silicon-mlx--unverified-preview)). For the CUDA path, or for ORPO / full fine-tune / FP8 / multi-run, use a CUDA Linux or Windows machine.
|
|
314
323
|
|
|
315
324
|
See the [troubleshooting handbook page](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/) for the long-form install fix-it guide, and the dedicated [CUDA troubleshooting page](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting-cuda/) for driver / VRAM / xformers / bf16-vs-fp16 issues.
|
|
316
325
|
|
|
@@ -362,8 +371,12 @@ Nested keys use double underscore (`MODEL__NAME`, not `MODEL_NAME`). The full re
|
|
|
362
371
|
| Llama 3.2 3B | ~8GB | Llama Community | Solid alternative to Qwen 3B with permissive caveats. |
|
|
363
372
|
| Llama 3.2 1B | ~6GB | Llama Community | For quick experiments on small cards. |
|
|
364
373
|
| Mistral 7B | ~12GB | Apache 2.0 | Comparable to Qwen 7B, different chat template. |
|
|
374
|
+
| Llama-3.1-8B | ~7-8GB (QLoRA) | Llama-3.1-Community | 8B QLoRA, 128K native context (the >700M-MAU clause needs a separate Meta license). |
|
|
375
|
+
| **Qwen2.5-14B** | ~8.5GB (QLoRA) | Apache 2.0 | **The 32 GB daily-driver sweet spot** — rank/alpha 32, paged 8-bit AdamW, 4096 ctx. |
|
|
376
|
+
| Mistral-Small-24B | ~18GB (QLoRA) | Apache 2.0 | 24B QLoRA on a 32 GB card with 4096-ctx headroom. |
|
|
377
|
+
| **Qwen2.5-32B** | ~26GB (QLoRA) | Apache 2.0 | **Top of the 32 GB envelope** — just fits at `max_len 2048` + paged 8-bit AdamW. |
|
|
365
378
|
|
|
366
|
-
Other models often work
|
|
379
|
+
Other models often work; the rows above are the curated presets — the 14B–32B tier is QLoRA-tuned for a 32 GB card (the measured envelope). Pass `--lora-preset=quality` (default) for rank-256 / all-linear targets per Biderman 2024 + Thinking Machines 2025, or `--lora-preset=fast` for the legacy rank-16 / q+v target if you need the v1.2.x footprint.
|
|
367
380
|
|
|
368
381
|
## Troubleshooting
|
|
369
382
|
|
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
|
|
|
@@ -145,7 +150,7 @@ Isso treina um adaptador Qwen 2.5 7B em 5 conversas curtas no formato ShareGPT e
|
|
|
145
150
|
|
|
146
151
|
Os formatos Alpaca (`instruction` / `output`), OpenAI chat (`messages`) e texto bruto também funcionam — Backpropagate detecta automaticamente o formato.
|
|
147
152
|
|
|
148
|
-
### Ajuste de
|
|
153
|
+
### Ajuste de preferências (ORPO, SimPO, KTO)
|
|
149
154
|
|
|
150
155
|
Novo na v1.5: treine com base em preferências em vez de demonstrações simples. ORPO não requer referência e é de estágio único — ele incorpora o sinal de preferência na etapa de ajuste fino SFT, portanto, não há um modelo de recompensa ou referência separado e a forma de 3 linhas permanece inalterada. Passe `--method orpo` (CLI) ou `method="orpo"` (Python) e forneça um conjunto de dados de linhas `{prompt, chosen, rejected}` (ou apenas `{chosen, rejected}`):
|
|
151
156
|
|
|
@@ -166,13 +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
|
-
A taxa de aprendizado padrão é automaticamente reduzida para `8e-6` para ORPO (a perda é mais acentuada do que
|
|
174
|
+
A taxa de aprendizado padrão é automaticamente reduzida para `8e-6` para ORPO (a perda é mais acentuada do que no SFT simples); ajuste `--orpo-beta` (padrão `0.1`) para ponderar a penalidade da razão de chances. ORPO é apenas em `mode="lora"`.
|
|
175
|
+
|
|
176
|
+
**Novo na v1.6 — SimPO e KTO.** `--method simpo` ([Meng et al. 2024](https://arxiv.org/abs/2405.14734)) não requer referência, utiliza uma recompensa normalizada pelo comprimento e usa os mesmos dados pareados `{prompt, chosen, rejected}` que o ORPO (`--simpo-beta`, `--simpo-gamma`). `--method kto` ([Ethayarajh et al. 2024](https://arxiv.org/abs/2402.01306)) usa dados **não pareados** `{prompt, completion, label}` — avaliações individuais de "gostei/não gostei" — para a grande classe de feedback que não é um conjunto curado de pares A/B; ele equilibra automaticamente os pesos desejáveis/indesejáveis da perda com base nas contagens dos seus rótulos. Ambos são apenas em `mode="lora"` e permanecem no ambiente SFT de GPU única (sem modelo de referência separado). Consulte o [manual de ajuste de preferências](https://mcp-tool-shop-org.github.io/backpropagate/handbook/preference-tuning/) para saber qual usar. Para RL online (PPO/GRPO), consulte [O que o Backpropagate NÃO é](#what-backpropagate-is-not-for).
|
|
170
177
|
|
|
171
178
|
### Rastreamento de raciocínio SFT (destilação R1)
|
|
172
179
|
|
|
173
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.
|
|
174
181
|
|
|
175
|
-
### 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.
|
|
176
185
|
|
|
177
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:
|
|
178
187
|
|
|
@@ -190,7 +199,7 @@ backprop train --data my_data.jsonl --backend mlx --steps 100
|
|
|
190
199
|
|
|
191
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.
|
|
192
201
|
|
|
193
|
-
>
|
|
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`.
|
|
194
203
|
|
|
195
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/).
|
|
196
205
|
|
|
@@ -303,7 +312,7 @@ As operações de escrita no sistema de arquivos a partir da interface do usuár
|
|
|
303
312
|
|
|
304
313
|
**Requisitos:** Python 3.10+ · GPU CUDA (8 GB+ de VRAM) · PyTorch 2.0+
|
|
305
314
|
|
|
306
|
-
O Python 3.10
|
|
315
|
+
O Python 3.10 é suportado até, pelo menos, a v1.6; seu suporte oficial termina em outubro de 2026 e está programado para ser removido na primeira versão após essa data. Para novas instalações, prefira o Python 3.11 ou 3.12 — o 3.11 é a versão mais testada.
|
|
307
316
|
|
|
308
317
|
O Backpropagate lida com as peculiaridades de tempo de execução do treinamento em diferentes plataformas, mas não pode corrigir problemas de tempo de instalação. Os dois mais comuns são:
|
|
309
318
|
|
|
@@ -362,8 +371,12 @@ Chaves aninhadas usam sublinhado duplo (`MODEL__NAME`, não `MODEL_NAME`). A ref
|
|
|
362
371
|
| Llama 3.2 3B | ~8GB | Llama Community | Alternativa sólida ao Qwen 3B com ressalvas permissivas. |
|
|
363
372
|
| Llama 3.2 1B | ~6GB | Llama Community | Para experimentos rápidos em placas pequenas. |
|
|
364
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. |
|
|
365
378
|
|
|
366
|
-
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.
|
|
367
380
|
|
|
368
381
|
## Solução de problemas
|
|
369
382
|
|