@mcptoolshop/backpropagate 1.1.1 → 1.2.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 +51 -54
- package/README.fr.md +5 -8
- package/README.hi.md +5 -8
- package/README.it.md +58 -61
- package/README.ja.md +73 -76
- package/README.md +5 -8
- package/README.pt-BR.md +5 -8
- package/README.zh.md +5 -8
- package/bin/backpropagate.js +1 -1
- package/package.json +2 -2
package/README.ja.md
CHANGED
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
<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>
|
|
15
15
|
</p>
|
|
16
16
|
|
|
17
|
-
**わずか3
|
|
17
|
+
**わずか3行のコードでLLMをファインチューニング。最適なデフォルト設定、VRAMを考慮したバッチサイズ、複数回の学習によるSLAO、そしてOllamaへのワンクリックGGUFエクスポート機能。**
|
|
18
18
|
|
|
19
19
|
*SLAOは、非対称なマージによる継続学習（Single LoRA Continual Learning via Asymmetric Merging）であり、長期間のファインチューニング中に発生する破滅的な忘却を防ぐための手法です。（[論文](https://arxiv.org/abs/2512.23017)）*
|
|
20
20
|
|
|
@@ -34,18 +34,18 @@ trainer.train("examples/quickstart.jsonl", steps=10)
|
|
|
34
34
|
trainer.export("gguf", quantization="q4_k_m") # Ready for Ollama
|
|
35
35
|
```
|
|
36
36
|
|
|
37
|
-
このリポジトリには、`examples/quickstart.jsonl`という小さなファイル（ShareGPT形式の5
|
|
37
|
+
このリポジトリには、`examples/quickstart.jsonl`という小さなファイル（ShareGPT形式の5つの例）が含まれており、これにより、上記のコードスニペットをクリーンな環境でエンドツーエンドで実行できます。ご自身の学習を行う場合は、以下の「データセット形式」を参照してください。
|
|
38
38
|
|
|
39
39
|
### コード不要：Web UI
|
|
40
40
|
|
|
41
|
-
Python REPLではなく、UI
|
|
41
|
+
Python REPLではなく、UIを使用したいですか？同じ追加機能をインストールして実行してください。
|
|
42
42
|
|
|
43
43
|
```bash
|
|
44
44
|
pip install backpropagate[standard]
|
|
45
45
|
backprop ui --port 7862
|
|
46
46
|
```
|
|
47
47
|
|
|
48
|
-
Reflex (Radix UI)
|
|
48
|
+
Reflex (Radix UI)インターフェースを使用すると、JSONLファイルを選択し、モデルを選択し、学習を実行し、エクスポートすることができます。Pythonの知識は不要です。このUIはローカル環境での使用を前提としており、インターネット経由での公開については、以下の「Web UI」を参照してください。セキュリティ契約（`--share` + `--auth`）と、サポートされているトンネルオプション（Cloudflare Tunnel、ngrok）について説明しています。
|
|
49
49
|
|
|
50
50
|
## データセット形式
|
|
51
51
|
|
|
@@ -56,25 +56,25 @@ JSONL形式の学習ファイルは、各行に1つの例が記述されてい
|
|
|
56
56
|
{"conversations": [{"from": "human", "value": "Explain recursion."}, {"from": "gpt", "value": "A function that calls itself."}]}
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
Alpaca
|
|
59
|
+
Alpaca（`instruction`/`output`）、OpenAIのチャット（`messages`）、および生のテキスト形式もサポートされています。`examples/quickstart.jsonl`には、コピーしてすぐに使えるサンプルが含まれています。
|
|
60
60
|
|
|
61
61
|
## なぜバックプロパゲーションを行うのか？
|
|
62
62
|
|
|
63
63
|
| 問題点 | 解決策 |
|
|
64
64
|
|---------|----------|
|
|
65
65
|
| ファインチューニングは複雑 | 3行で完了：ロード、学習、保存 |
|
|
66
|
-
| Windowsは使い物にならない | Windows
|
|
66
|
+
| Windowsは使い物にならない | Windowsへの完全なサポート |
|
|
67
67
|
| VRAM管理は難しい | 自動バッチサイズ調整、GPU監視 |
|
|
68
|
-
|
|
|
68
|
+
| モデルのエクスポートは混乱を招く | ワンクリックでGGUF形式にエクスポートし、Ollamaに自動登録 |
|
|
69
69
|
| 長時間の学習は忘却を引き起こす | 複数回の学習によるSLAO |
|
|
70
70
|
|
|
71
71
|
## 主な機能
|
|
72
72
|
|
|
73
|
-
-
|
|
74
|
-
-
|
|
73
|
+
- **設計上、ヘッドレス**: CI/CDパイプライン、自動化されたワークフロー、およびプログラムによる実行向けに設計されています。
|
|
74
|
+
- **最適なデフォルト設定**: ハードウェアとデータセットに基づいて、最適なハイパーパラメータを自動的に設定します。
|
|
75
75
|
- **複数回の学習によるSLAO**: 長時間の学習中に発生する破滅的な忘却を防ぐための高度な学習戦略。
|
|
76
|
-
- **Windows
|
|
77
|
-
- **シームレスなエクスポート**: ワンクリックでGGUF形式にエクスポートし、Ollama
|
|
76
|
+
- **Windowsへの完全なサポート**: Windows環境で動作するようにテストおよび最適化されており、一般的なPyTorch/CUDAの問題を回避します。
|
|
77
|
+
- **シームレスなエクスポート**: ワンクリックでGGUF形式にエクスポートし、Ollamaに自動登録します。
|
|
78
78
|
- **モジュール式のアーキテクチャ**: 必要な依存関係のみをインストールできます（例：`[unsloth]`、`[ui]`、`[export]`）。
|
|
79
79
|
|
|
80
80
|
## インストール
|
|
@@ -90,47 +90,46 @@ pip install backpropagate[full] # Everything
|
|
|
90
90
|
| 追加機能 | 説明 | 依存関係 |
|
|
91
91
|
|-------|-------------|--------------|
|
|
92
92
|
| `unsloth` | 学習速度が2倍、VRAM使用量が50%削減 | unsloth |
|
|
93
|
-
| `ui` | Reflex (Radix UI)
|
|
93
|
+
| `ui` | Reflex (Radix UI)のWebインターフェース | reflex>=0.9.2, fastapi>=0.115 |
|
|
94
94
|
| `validation` | Pydanticによる設定検証 | pydantic, pydantic-settings |
|
|
95
|
-
| `export` | Ollama
|
|
96
|
-
| `monitoring` | WandB + システム監視（v1.1.0
|
|
97
|
-
| `observability` | OpenTelemetryによるトレース | opentelemetry-api, opentelemetry-sdk |
|
|
95
|
+
| `export` | Ollama用のGGUFエクスポート | llama-cpp-python |
|
|
96
|
+
| `monitoring` | WandB + システム監視（v1.1.0でトレーナーに自動的に組み込み） | wandb, psutil |
|
|
98
97
|
| `logging` | 構造化されたロギング | structlog |
|
|
99
98
|
| `security` | JWT認証 + トークン生成 | PyJWT, cryptography |
|
|
100
99
|
| `production` | unsloth + ui + 検証 + ロギング + セキュリティ | （バンドル） |
|
|
101
100
|
|
|
102
|
-
|
|
101
|
+
**要件:** Python 3.10以上、CUDA対応GPU（8GB以上のVRAM）、PyTorch 2.0以上
|
|
103
102
|
|
|
104
103
|
### プラットフォームの前提条件
|
|
105
104
|
|
|
106
|
-
Backpropagate
|
|
105
|
+
Backpropagateは、実行時の問題を解決します（マルチプロセッシング、RTX 40/50でのxformers、Windowsでのデータローダー）。ただし、インストール時のプラットフォームの問題は解決しません。それらの問題は事前に解決してください。
|
|
107
106
|
|
|
108
|
-
- **CUDAツールキットのバージョン。** PyTorchはCUDA
|
|
109
|
-
- **Windows。** `[export]
|
|
110
|
-
- **macOS。** GPU
|
|
111
|
-
- **Linux。** ほとんどのディストリビューションで問題なく動作します。PyPI
|
|
107
|
+
- **CUDA ツールキットのバージョン。** PyTorch は CUDA に合わせてリリースされます。誤った wheel を選択すると、CPU のみで動作する torch がインストールされてしまいます。お使いのドライバに合った正確な `pip install torch ...` コマンドについては、<https://pytorch.org/get-started/locally/> の選択ツールをご利用ください。`nvidia-smi` コマンドを実行して、ドライバまたは CUDA のバージョンを確認してください。
|
|
108
|
+
- **Windows。** `[export]` オプションを使用する場合（`llama-cpp-python` はソースコードからビルドされます）、Visual Studio Build Tools (C++) と CMake が必要です。`bitsandbytes` wheel は、Windows ネイティブで利用できるようになりました（>= 0.43）。古いドキュメントで `bitsandbytes-windows` が言及されている場合は、最新の情報ではありません。
|
|
109
|
+
- **macOS。** GPU を使用した学習は**サポートされていません**。CUDA は利用できません。エクスポートされた GGUF モデルを Ollama を介して *推論* 実行するには、Backpropagate をインストールできますが、`trainer.train()` を実行すると `DEP_GPU_NOT_AVAILABLE` エラーが発生します。学習には CUDA 対応の環境を使用してください。
|
|
110
|
+
- **Linux。** ほとんどのディストリビューションで問題なく動作します。PyPI からのバイナリリリースを使用している場合は、Linux のビルドでは CPU のみで動作する torch が使用されていることに注意してください（GitHub のリリースアセットの 2GB 制限を超えるため）。最初に、pytorch.org から対応する CUDA wheel をインストールしてください。
|
|
112
111
|
|
|
113
|
-
詳細なインストールに関するトラブルシューティングについては、[トラブルシューティングガイド](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/)を参照してください。
|
|
112
|
+
詳細なインストールに関するトラブルシューティングについては、[トラブルシューティングガイド](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/) を参照してください。
|
|
114
113
|
|
|
115
114
|
## 設定
|
|
116
115
|
|
|
117
|
-
すべての設定は、`BACKPROPAGATE_
|
|
116
|
+
すべての設定は、`BACKPROPAGATE_` というプレフィックスが付いた環境変数を使用して上書きできます（例：`BACKPROPAGATE_LOG_LEVEL=debug`）。プロジェクトのルートディレクトリにある `.env` ファイルは、`[validation]` オプションがインストールされている場合に自動的に読み込まれます。
|
|
118
117
|
|
|
119
|
-
|
|
118
|
+
一般的な設定項目（詳細については、[環境変数リファレンス](https://mcp-tool-shop-org.github.io/backpropagate/handbook/env-vars/) を参照してください）。
|
|
120
119
|
|
|
121
120
|
| 変数 | デフォルト値 | 備考 |
|
|
122
121
|
|----------|---------|-------|
|
|
123
122
|
| `BACKPROPAGATE_LOG_LEVEL` | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
|
|
124
|
-
| `BACKPROPAGATE_LOG_JSON` |
|
|
123
|
+
| `BACKPROPAGATE_LOG_JSON` | auto | JSON ログを強制 (`true`) するか、コンソールログ (`false`) を使用するか |
|
|
125
124
|
| `BACKPROPAGATE_LOG_FILE` | 未設定 | ログを保存するパス |
|
|
126
|
-
| `BACKPROPAGATE_DEFER_FEATURE_DETECTION` | 未設定 | 起動時のオプション依存関係の検出をスキップし、CLIの起動を高速化 |
|
|
127
|
-
| `BACKPROPAGATE_SECURITY__REQUIRE_AUTH_FOR_SHARE` | `true` | `true
|
|
128
|
-
| `BACKPROPAGATE_UI__OUTPUT_DIR` | `~/.backpropagate/ui-outputs` | すべてのUIファイルシステムの書き込みのサンドボックスベース。許可リストで検証済み |
|
|
125
|
+
| `BACKPROPAGATE_DEFER_FEATURE_DETECTION` | 未設定 | 起動時のオプション依存関係の検出をスキップし、CLI の起動を高速化 |
|
|
126
|
+
| `BACKPROPAGATE_SECURITY__REQUIRE_AUTH_FOR_SHARE` | `true` | `true` の場合、`--auth` オプションなしでの `backprop ui --share` を拒否 |
|
|
127
|
+
| `BACKPROPAGATE_UI__OUTPUT_DIR` | `~/.backpropagate/ui-outputs` | すべての UI ファイルシステムの書き込みのサンドボックスベース。許可リストで検証済み |
|
|
129
128
|
| `BACKPROPAGATE_MODEL__NAME` | `Qwen/Qwen2.5-7B-Instruct` | デフォルトモデル |
|
|
130
129
|
| `BACKPROPAGATE_TRAINING__LEARNING_RATE` | `2e-4` | 学習率 |
|
|
131
|
-
| `BACKPROPAGATE_LORA__R` | `16` | LoRAのランク |
|
|
130
|
+
| `BACKPROPAGATE_LORA__R` | `16` | LoRA のランク |
|
|
132
131
|
|
|
133
|
-
|
|
132
|
+
ネストされたキーでは、区切り文字として二重アンダースコアを使用します（Pydantic の `env_nested_delimiter` 規則）。
|
|
134
133
|
|
|
135
134
|
## 使い方
|
|
136
135
|
|
|
@@ -145,9 +144,9 @@ trainer.save("./my-model")
|
|
|
145
144
|
trainer.export("gguf", quantization="q4_k_m")
|
|
146
145
|
```
|
|
147
146
|
|
|
148
|
-
`Qwen/Qwen2.5-7B-Instruct
|
|
147
|
+
`Qwen/Qwen2.5-7B-Instruct` がデフォルトです。`Trainer()` を呼び出す際にモデル引数を指定しない場合、この値が適用されます（`config.py` の `ModelConfig.name` を参照）。以前の例では、事前量子化された `unsloth/Qwen2.5-7B-Instruct-bnb-4bit` が使用されていましたが、より安定性の高い公式の Qwen モデルをデフォルトに変更しました（[CHANGELOG v1.1.0](CHANGELOG.md#110---2026-05-21)）。どちらのモデルでも動作します。
|
|
149
148
|
|
|
150
|
-
### マルチランSLAO学習
|
|
149
|
+
### マルチラン SLAO 学習
|
|
151
150
|
|
|
152
151
|
```python
|
|
153
152
|
from backpropagate import Trainer
|
|
@@ -163,9 +162,9 @@ result = trainer.multi_run(
|
|
|
163
162
|
)
|
|
164
163
|
```
|
|
165
164
|
|
|
166
|
-
SLAO
|
|
165
|
+
SLAO (Single LoRA Continual Learning via Asymmetric Merging) は、[Merge before Forget](https://arxiv.org/abs/2512.23017) という論文を実装しています。QR 分解による直交 A 行列の初期化、非対称な A/B 行列の処理、および時間依存の `λ(i) = 1/√i` スケーリングが含まれます。CLI フラグは `--samples` で、対応するフィールドは `samples_per_run` です。
|
|
167
166
|
|
|
168
|
-
### Ollamaへのエクスポート
|
|
167
|
+
### Ollama へのエクスポート
|
|
169
168
|
|
|
170
169
|
```python
|
|
171
170
|
# Export to GGUF
|
|
@@ -191,11 +190,11 @@ backprop resume <run-id> # v1.1.0: resume a crashed multi
|
|
|
191
190
|
backprop push ./output/lora --repo me/my-model # v1.1.0: push adapter to HF Hub
|
|
192
191
|
```
|
|
193
192
|
|
|
194
|
-
すべてのサブコマンドとフラグについては、[CLIリファレンス](https://mcp-tool-shop-org.github.io/backpropagate/handbook/cli-reference/)を参照するか、`backprop <サブコマンド> --help
|
|
193
|
+
すべてのサブコマンドとフラグについては、[CLI リファレンス](https://mcp-tool-shop-org.github.io/backpropagate/handbook/cli-reference/) を参照するか、`backprop <サブコマンド> --help` を実行してください。
|
|
195
194
|
|
|
196
|
-
###
|
|
195
|
+
### チェックポイントからの再開 (v1.1.0)
|
|
197
196
|
|
|
198
|
-
5
|
|
197
|
+
4 回の実行でクラッシュした 5 回のマルチランが、現在では復旧可能です。すべてのマルチランセッションでは、`run_id` が `run_history.json` とオンディスクのチェックポイントマニフェストの両方に書き込まれるため、中断した場所から再開するには、次のコマンドを実行します。
|
|
199
198
|
|
|
200
199
|
```bash
|
|
201
200
|
backprop resume <run-id> # picks up the in-progress session
|
|
@@ -203,13 +202,13 @@ backprop multi-run --data ... --resume <run-id> # explicit form
|
|
|
203
202
|
backprop train --data ... --resume <run-id> # single-run resume (continues run_id)
|
|
204
203
|
```
|
|
205
204
|
|
|
206
|
-
`backprop multi-run
|
|
205
|
+
`backprop multi-run` のデフォルト動作（`--resume` オプションなし）では、同じ出力ディレクトリで実行中のジョブを自動的に検出し、それを継続します。クリーンなセッションを開始するには、`resume_from="off"`（Python API）を指定するか、`--resume` オプションを省略して、新しい出力ディレクトリで実行してください。
|
|
207
206
|
|
|
208
|
-
|
|
207
|
+
マルチラン再開時には、その `run_id` に対応する最新のチェックポイントがモデルにロードされ、チェックポイントの隣にある `slao/` ディレクトリから SLAO のマージ状態が復元され、実行ループが `last_completed_run + 1` から継続されます。履歴エントリの `status` が `running` に戻るため、`backprop list-runs --status running` コマンドで実行中のセッションが表示されます。
|
|
209
208
|
|
|
210
|
-
###
|
|
209
|
+
### 実験の追跡機能（v1.1.0）
|
|
211
210
|
|
|
212
|
-
`Trainer
|
|
211
|
+
`Trainer` は、インストールされている実験追跡ツール (`wandb`, `tensorboard`, `mlflow`) を自動的に検出し、それらを基盤となる `transformers.TrainingArguments` に統合します。デフォルトでは `report_to="auto"` が設定されており、インポート可能なものがすべて利用されます。
|
|
213
212
|
|
|
214
213
|
```bash
|
|
215
214
|
pip install backpropagate[monitoring] # installs wandb + psutil
|
|
@@ -217,11 +216,11 @@ wandb login # one-time
|
|
|
217
216
|
backprop train --data my_data.jsonl # W&B run gets the same run_id prefix as the on-disk history
|
|
218
217
|
```
|
|
219
218
|
|
|
220
|
-
|
|
219
|
+
明示的に無効にするには、`Trainer(report_to=["wandb"])`、`Trainer(report_to=["tensorboard"])`、または `Trainer(report_to="none")` を使用します。MLflow を使用するには `pip install mlflow` を、TensorBoard を使用するには `pip install tensorboard` を実行してください。W&B の実行名は `backprop-<run_id_prefix>` なので、オペレーターは同じ識別子で W&B、ログ、および `run_history.json` を検索できます。
|
|
221
220
|
|
|
222
221
|
### トレーニング履歴
|
|
223
222
|
|
|
224
|
-
`backprop train
|
|
223
|
+
`backprop train` および `backprop multi-run` の実行ごとに、`<output>/run_history.json` に、実行 ID、モデル、データセット、ハイパーパラメータ、ステータス、最終的な損失、損失履歴、および（マルチランの場合）SLAO のマージのタイムラインが記録されます。最近の実行の一覧を表示するには、以下のコマンドを使用します。
|
|
225
224
|
|
|
226
225
|
```bash
|
|
227
226
|
backprop list-runs # most recent 20 runs, all statuses
|
|
@@ -230,40 +229,38 @@ backprop list-runs --json --limit 100 # machine-readable
|
|
|
230
229
|
backprop show-run abcd1234 # detail view (partial run_id ok)
|
|
231
230
|
```
|
|
232
231
|
|
|
233
|
-
|
|
232
|
+
実行履歴はプロセスを越えて保持されます。Web UI の「Runs」タブは、メモリ内のビューであり、オンディスクの履歴が `list-runs` / `show-run` / `resume` のための信頼できる情報源です。
|
|
234
233
|
|
|
235
234
|
### Web UI
|
|
236
235
|
|
|
237
|
-
ローカルでReflexインターフェースを起動します。
|
|
236
|
+
ローカルで Reflex インターフェースを起動します。
|
|
238
237
|
|
|
239
238
|
```bash
|
|
240
239
|
backprop ui --port 7862
|
|
241
240
|
```
|
|
242
241
|
|
|
243
|
-
|
|
242
|
+
パブリックインターネット経由でアクセスできるようにするには、`--share` オプションを `--auth` オプションと組み合わせて使用する必要があります。
|
|
244
243
|
|
|
245
244
|
```bash
|
|
246
245
|
backprop ui --share --auth alice:hunter2
|
|
247
246
|
```
|
|
248
247
|
|
|
249
|
-
`backprop ui --share
|
|
248
|
+
`backprop ui --share` コマンドを `--auth` オプションなしで実行すると、エラーコード `1` が発生し、構造化されたエラーメッセージ `[RUNTIME_UI_AUTH_NOT_ENFORCED]` が表示されます。これは、`--share` オプションが公開URLを生成し、認証なしで利用可能にすると、インターネット上の誰でもトレーニングパイプラインを操作できてしまうためです。この動作を回避するオプションはありません。認証情報を設定したくない場合は、SSHのポートフォワード機能を使用してください。具体的には、`ssh -L 7860:localhost:7860 <ホスト>` コマンドを実行し、その後、`http://localhost:7860` をローカルで開きます。詳細なセキュリティに関する情報は、[handbook/security.md](site/src/content/docs/handbook/security.md) を参照してください。
|
|
250
249
|
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
UIからのファイルシステムへの書き込みは、単一のディレクトリにサンドボックス化されています。
|
|
250
|
+
UI からのファイルシステムへの書き込みは、単一のディレクトリにサンドボックス化されています。
|
|
254
251
|
|
|
255
252
|
- デフォルト: `~/.backpropagate/ui-outputs`
|
|
256
253
|
- 上書き: `BACKPROPAGATE_UI__OUTPUT_DIR=/path/you/own`
|
|
257
|
-
-
|
|
254
|
+
- 上書きは、許可リストで検証されます。システムパスや認証情報パス（`/etc`, `/var`, `~/.ssh`, `~/.aws`, `C:\Windows\System32` など）は、`[UI_OUTPUT_DIR_FORBIDDEN]` というエラーで拒否されます。
|
|
258
255
|
|
|
259
|
-
## Windowsサポート
|
|
256
|
+
## Windows サポート
|
|
260
257
|
|
|
261
|
-
Backpropagateは、Windows
|
|
258
|
+
Backpropagate は、Windows での動作を前提として設計されています。
|
|
262
259
|
|
|
263
260
|
- マルチプロセッシングのクラッシュを回避するための事前トークン化
|
|
264
|
-
- RTX 40/50
|
|
261
|
+
- RTX 40/50 シリーズ向け xformers の自動無効化
|
|
265
262
|
- 安全なデータローダー設定
|
|
266
|
-
- RTX 5080 (16GB VRAM)
|
|
263
|
+
- RTX 5080 (16GB VRAM) での動作確認済み
|
|
267
264
|
|
|
268
265
|
## モデルプリセット
|
|
269
266
|
|
|
@@ -299,52 +296,52 @@ backpropagate/
|
|
|
299
296
|
│ ├── chrome.py # Header / LeftNav / SideRail / Footer
|
|
300
297
|
│ ├── pages/ # Train / Multi-Run / Export / Dataset
|
|
301
298
|
│ └── components/ # Bp* primitives (status pill, sparkline, event log…)
|
|
302
|
-
|
|
303
|
-
├── ui_gradio_legacy.py # DEPRECATED — preserved as v1.0 reference; removed in v1.2
|
|
304
|
-
└── theme_gradio_legacy.py # DEPRECATED — same
|
|
299
|
+
└── ui_security.py # Rate limiting, CSRF, file validation (framework-agnostic)
|
|
305
300
|
```
|
|
306
301
|
|
|
302
|
+
v1.0 の Gradio 実装 (`ui_gradio_legacy.py` + `theme_gradio_legacy.py`) は、v1.1.x まで参照として保持され、v1.2.0 で削除されました。
|
|
303
|
+
|
|
307
304
|
## トラブルシューティング
|
|
308
305
|
|
|
309
|
-
|
|
306
|
+
よく発生する初期エラーの簡単な一覧です。詳細な逆引き索引は、[トラブルシューティングハンドブックのページ](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/) にあります。以下に示すすべてのコードは、[エラーコード](https://mcp-tool-shop-org.github.io/backpropagate/handbook/error-codes/) に詳しく説明されています。
|
|
310
307
|
|
|
311
|
-
| 症状 | コード |
|
|
308
|
+
| 症状 | コード | 対処法 |
|
|
312
309
|
|---------|------|-----|
|
|
313
|
-
|
|
|
314
|
-
| HF Hub
|
|
310
|
+
| GPUメモリ不足によるトレーニング中断 | `RUNTIME_GPU_OOM` | OOM自動復旧 (B-002) が、バッチサイズを最大3回まで自動的に半分にします。無効にするには、`Trainer(oom_recovery=False)` を指定します。バッチサイズを強制的に小さくするには、`--batch-size 1` を指定します。 |
|
|
311
|
+
| HF Hub から 401 エラー / "モデルが見つかりません" というエラー | `DEP_MODEL_LOAD_FAILED` | `huggingface-cli login` を実行し、再度試してください。入力ミスがある場合は、<https://huggingface.co/models> から正確な ID をコピーしてください。 |
|
|
315
312
|
| モデル名の入力ミス | `INPUT_VALIDATION_FAILED` または `DEP_MODEL_LOAD_FAILED` | <https://huggingface.co/models> での `org/name` の識別子を確認してください。 |
|
|
316
|
-
| `register_with_ollama`
|
|
317
|
-
|
|
|
318
|
-
| GPU
|
|
313
|
+
| `register_with_ollama` への接続拒否 | `DEP_OLLAMA_REGISTRATION_FAILED` | デーモンを起動します: `ollama serve`。 <https://ollama.com> からインストールしてください。再試行可能です。 |
|
|
314
|
+
| チェックポイント保存中にディスク容量不足 | `STATE_CHECKPOINT_INVALID` | クラッシュ時に、`.partial` というディレクトリが作成されますが、削除しても問題ありません。以前の正常なチェックポイントは保持されています。 |
|
|
315
|
+
| GPUの過熱によるトレーニングの一時停止/中断 | `RUNTIME_GPU_TEMPERATURE_CRITICAL` | B-003: NVMLの温度閾値を超えるとモニタが一時停止し、GPUが冷却されると自動的に再開されます。エアフローを改善するか、GPUへの負荷を軽減してください。 |
|
|
319
316
|
| `backprop ui --share` が拒否される | `INPUT_AUTH_REQUIRED` | `--auth user:password` を指定するか、`BACKPROPAGATE_SECURITY__REQUIRE_AUTH_FOR_SHARE=false` を設定して、認証を無効にします（警告が表示されます）。 |
|
|
320
|
-
|
|
|
321
|
-
| GGUF
|
|
317
|
+
| 複数回の実行における "validation overlap" (検証データの重複) | `CONFIG_INVALID` (Stage A backend B-001) | `--samples` の値を、トレーニングプールサイズよりも小さくするか、データセットを増やすか、検証を無効にしてください。 |
|
|
318
|
+
| GGUF エクスポートが初回試行で失敗 | `RUNTIME_GGUF_EXPORT_FAILED` | `pip install backpropagate[export]` を実行してください。Windows の場合は、Visual C++ Build Tools + CMake も必要です。 |
|
|
322
319
|
|
|
323
320
|
## バグの報告
|
|
324
321
|
|
|
325
|
-
|
|
322
|
+
エラーが発生した場合、Backpropagate は起動時に `run_started run_id=<uuid>` という行を出力し、同じ ID をチェックポイントのマニフェスト、SLAOのマージ履歴、および構造化されたログ行に関連付けます。バグ報告には、`run_id` を必ず含めてください。これにより、開発者が、その特定の実行に関するすべてのログ行、すべてのチェックポイント、およびすべてのマージを関連付けることができます。
|
|
326
323
|
|
|
327
324
|
良いバグレポートには、以下の情報が含まれている必要があります。
|
|
328
325
|
|
|
329
|
-
1. **`run_id`** — 起動時に表示されるUUID
|
|
326
|
+
1. **`run_id`** — 起動時に表示される UUID (また、`TrainingRun.run_id` および `RunResult.run_id` でも利用可能です)。
|
|
330
327
|
2. **エラーコード** — `stderr` に表示される `[CODE_NAME]: message` の行を検索してください。詳細については、[エラーコード](https://mcp-tool-shop-org.github.io/backpropagate/handbook/error-codes/) を参照してください。
|
|
331
|
-
3.
|
|
332
|
-
4. **Python / PyTorchのバージョン、GPU
|
|
328
|
+
3. **コマンドライン (一部情報を削除したもの)。** 詳細表示モードでない場合、`stderr` は自動的に情報が削除されます (Bearerトークン、`sk-*`、`hf_*`、AWSキー、`password=`/`token=`/`api_key=` のペアは削除されます)。貼り付けても安全です。完全なトレースバックを表示するには、`--verbose` オプションで再実行しますが、投稿する前に内容を確認してください。
|
|
329
|
+
4. **Python / PyTorch のバージョン、GPU のモデル、OS。** `backprop info` コマンドで、これらすべてを表示できます。
|
|
333
330
|
|
|
334
331
|
## プライバシー
|
|
335
332
|
|
|
336
|
-
トレーニングはすべて、ローカルのGPU
|
|
333
|
+
トレーニングはすべて、ローカルの GPU 上で行われます。Backpropagate は、HuggingFace からモデルをダウンロードするために必要なネットワークリクエストを除き、他のネットワークリクエストは行いません。テレメトリーやクラウドへの依存はありません。
|
|
337
334
|
|
|
338
335
|
## スコアカード
|
|
339
336
|
|
|
340
337
|
| カテゴリ | スコア | 備考 |
|
|
341
338
|
|----------|-------|-------|
|
|
342
|
-
| A. セキュリティ | 6/8 | SECURITY.md、信頼できるモデル、秘密情報/テレメトリーなし、safe_path()。MCP
|
|
343
|
-
| B. エラー処理 | 5/7 | 構造化された例外情報（`code`/`message`/`hint`/`cause`/`retryable`）は、ERROR_CODES レジストリを通じて提供されます。CLIの終了コードは0/1/2/3です。`--verbose`オプションなしでは、生のスタックトレースは表示されません。`run_id
|
|
339
|
+
| A. セキュリティ | 6/8 | SECURITY.md、信頼できるモデル、秘密情報/テレメトリーなし、safe_path()。MCP の項目はスキップされます。 |
|
|
340
|
+
| B. エラー処理 | 5/7 | 構造化された例外情報（`code`/`message`/`hint`/`cause`/`retryable`）は、ERROR_CODES レジストリを通じて提供されます。CLIの終了コードは0/1/2/3です。`--verbose`オプションなしでは、生のスタックトレースは表示されません。`run_id`による関連付け、内容が一部隠蔽された標準エラー出力、`--share`と`--auth`の組み合わせによる制限。MCP、デスクトップ版、Visual Studio Codeは対象外です。 |
|
|
344
341
|
| C. オペレーター向けドキュメント | 4/7 | README、CHANGELOG、LICENSE、`--help`。ロギング、MCP、複雑な機能は対象外。 |
|
|
345
|
-
| D. リリース時の品質管理 | 6/9 | `verify.sh
|
|
342
|
+
| D. リリース時の品質管理 | 6/9 | `verify.sh`、バージョン=タグ、CI環境での5つのスキャナー、dependabot、`python_requires`、クリーンなビルド。 |
|
|
346
343
|
| E. アイデンティティ | 4/4 | ロゴ、翻訳、ランディングページ、メタデータ。 |
|
|
347
|
-
| **Total** | **25/31** | 14項目は理由によりスキップされました。`shipcheck audit`は100%合格。監査日: 2026年5月21日（B行は、ステージBとステージAのCLI
|
|
344
|
+
| **Total** | **25/31** | 14項目は理由によりスキップされました。`shipcheck audit`は100%合格。監査日: 2026年5月21日（B行は、ステージBとステージAのCLI終了コードの作業後に再評価）。 |
|
|
348
345
|
|
|
349
346
|
設計の経緯と、各項目が何に対応しているかについては、[ROADMAP.md](ROADMAP.md)を参照してください。v1.1.0では、Week 1～4のすべての項目がリリースされます。
|
|
350
347
|
|
package/README.md
CHANGED
|
@@ -94,7 +94,6 @@ pip install backpropagate[full] # Everything
|
|
|
94
94
|
| `validation` | Pydantic config validation | pydantic, pydantic-settings |
|
|
95
95
|
| `export` | GGUF export for Ollama | llama-cpp-python |
|
|
96
96
|
| `monitoring` | WandB + system monitoring (auto-wired into trainer in v1.1.0) | wandb, psutil |
|
|
97
|
-
| `observability` | OpenTelemetry tracing | opentelemetry-api, opentelemetry-sdk |
|
|
98
97
|
| `logging` | Structured logging | structlog |
|
|
99
98
|
| `security` | JWT auth + token generation | PyJWT, cryptography |
|
|
100
99
|
| `production` | unsloth + ui + validation + logging + security | (bundle) |
|
|
@@ -145,7 +144,7 @@ trainer.save("./my-model")
|
|
|
145
144
|
trainer.export("gguf", quantization="q4_k_m")
|
|
146
145
|
```
|
|
147
146
|
|
|
148
|
-
`Qwen/Qwen2.5-7B-Instruct` is the canonical default — the value `Trainer()` resolves when called with no model argument (see [`config.py`](backpropagate/config.py) `ModelConfig.name`). Older examples pinned the pre-quantized `unsloth/Qwen2.5-7B-Instruct-bnb-4bit`; we switched the default to the official Qwen weights for better reliability ([CHANGELOG
|
|
147
|
+
`Qwen/Qwen2.5-7B-Instruct` is the canonical default — the value `Trainer()` resolves when called with no model argument (see [`config.py`](backpropagate/config.py) `ModelConfig.name`). Older examples pinned the pre-quantized `unsloth/Qwen2.5-7B-Instruct-bnb-4bit`; we switched the default to the official Qwen weights for better reliability ([CHANGELOG v1.1.0](CHANGELOG.md#110---2026-05-21)). Either model works.
|
|
149
148
|
|
|
150
149
|
### Multi-Run SLAO Training
|
|
151
150
|
|
|
@@ -246,9 +245,7 @@ To expose a public-internet URL, you must pair `--share` with `--auth`:
|
|
|
246
245
|
backprop ui --share --auth alice:hunter2
|
|
247
246
|
```
|
|
248
247
|
|
|
249
|
-
`backprop ui --share` without `--auth` exits with code `1` and the structured error `[
|
|
250
|
-
|
|
251
|
-
To explicitly opt out (e.g. an internal dev environment), set the env var `BACKPROPAGATE_SECURITY__REQUIRE_AUTH_FOR_SHARE=false`. A loud warning will print on every launch — and there's a 5-second grace period before the unauth'd UI binds, so you can `Ctrl-C` if it looks wrong.
|
|
248
|
+
`backprop ui --share` without `--auth` exits with code `1` and the structured error `[RUNTIME_UI_AUTH_NOT_ENFORCED]`. The rationale: `--share` publishes a public URL that anyone on the internet can hit, and without auth that means anyone can drive your training pipeline. There is no opt-out — if you don't want to set credentials, use SSH port-forwarding instead: `ssh -L 7860:localhost:7860 <host>` then open `http://localhost:7860` locally. See [handbook/security.md](site/src/content/docs/handbook/security.md) for the full threat model.
|
|
252
249
|
|
|
253
250
|
Filesystem writes from the UI are sandboxed to a single directory:
|
|
254
251
|
|
|
@@ -299,11 +296,11 @@ backpropagate/
|
|
|
299
296
|
│ ├── chrome.py # Header / LeftNav / SideRail / Footer
|
|
300
297
|
│ ├── pages/ # Train / Multi-Run / Export / Dataset
|
|
301
298
|
│ └── components/ # Bp* primitives (status pill, sparkline, event log…)
|
|
302
|
-
|
|
303
|
-
├── ui_gradio_legacy.py # DEPRECATED — preserved as v1.0 reference; removed in v1.2
|
|
304
|
-
└── theme_gradio_legacy.py # DEPRECATED — same
|
|
299
|
+
└── ui_security.py # Rate limiting, CSRF, file validation (framework-agnostic)
|
|
305
300
|
```
|
|
306
301
|
|
|
302
|
+
The v1.0 Gradio implementation (`ui_gradio_legacy.py` + `theme_gradio_legacy.py`) was preserved through v1.1.x as reference and removed in v1.2.0.
|
|
303
|
+
|
|
307
304
|
## Troubleshooting
|
|
308
305
|
|
|
309
306
|
A short index of the most common first-run failures. The full reverse index lives at [the troubleshooting handbook page](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/); every code below is documented at [error codes](https://mcp-tool-shop-org.github.io/backpropagate/handbook/error-codes/).
|
package/README.pt-BR.md
CHANGED
|
@@ -94,7 +94,6 @@ pip install backpropagate[full] # Everything
|
|
|
94
94
|
| `validation` | Validação de configuração Pydantic | pydantic, pydantic-settings |
|
|
95
95
|
| `export` | Exportação GGUF para Ollama | llama-cpp-python |
|
|
96
96
|
| `monitoring` | WandB + monitoramento do sistema (integrado automaticamente ao treinador na versão 1.1.0) | wandb, psutil |
|
|
97
|
-
| `observability` | Rastreamento OpenTelemetry | opentelemetry-api, opentelemetry-sdk |
|
|
98
97
|
| `logging` | Registro estruturado | structlog |
|
|
99
98
|
| `security` | Autenticação JWT + geração de tokens | PyJWT, cryptography |
|
|
100
99
|
| `production` | unsloth + ui + validação + registro + segurança | (pacote) |
|
|
@@ -145,7 +144,7 @@ trainer.save("./my-model")
|
|
|
145
144
|
trainer.export("gguf", quantization="q4_k_m")
|
|
146
145
|
```
|
|
147
146
|
|
|
148
|
-
`Qwen/Qwen2.5-7B-Instruct` é
|
|
147
|
+
`Qwen/Qwen2.5-7B-Instruct` é a opção padrão e canônica — o valor `Trainer()` é retornado quando chamado sem um argumento de modelo (veja [`config.py`](backpropagate/config.py) `ModelConfig.name`). Exemplos mais antigos utilizavam a versão pré-quantizada `unsloth/Qwen2.5-7B-Instruct-bnb-4bit`; mudamos a opção padrão para os pesos oficiais do Qwen para maior confiabilidade ([CHANGELOG v1.1.0](CHANGELOG.md#110---2026-05-21)). Qualquer um dos modelos funciona.
|
|
149
148
|
|
|
150
149
|
### Treinamento Multi-Run SLAO
|
|
151
150
|
|
|
@@ -246,9 +245,7 @@ Para expor um URL acessível pela internet, você deve combinar `--share` com `-
|
|
|
246
245
|
backprop ui --share --auth alice:hunter2
|
|
247
246
|
```
|
|
248
247
|
|
|
249
|
-
`backprop ui --share` sem `--auth` retorna
|
|
250
|
-
|
|
251
|
-
Para desativar explicitamente (por exemplo, em um ambiente de desenvolvimento interno), defina a variável de ambiente `BACKPROPAGATE_SECURITY__REQUIRE_AUTH_FOR_SHARE=false`. Um aviso será exibido a cada execução — e há um período de carência de 5 segundos antes que a interface não autenticada seja carregada, para que você possa usar `Ctrl-C` se algo parecer errado.
|
|
248
|
+
O comando `backprop ui --share` sem a opção `--auth` retorna o código de erro `1` e a mensagem de erro estruturada `[RUNTIME_UI_AUTH_NOT_ENFORCED]`. A razão para isso é que a opção `--share` publica um URL público que qualquer pessoa na internet pode acessar, e sem autenticação, isso significa que qualquer pessoa pode controlar o seu processo de treinamento. Não há como desativar essa proteção; se você não quiser definir credenciais, use o encaminhamento de porta SSH: `ssh -L 7860:localhost:7860 <host>` e, em seguida, abra `http://localhost:7860` localmente. Consulte o documento [handbook/security.md](site/src/content/docs/handbook/security.md) para obter informações detalhadas sobre o modelo de ameaças.
|
|
252
249
|
|
|
253
250
|
As operações de escrita no sistema de arquivos a partir da interface são restritas a um único diretório:
|
|
254
251
|
|
|
@@ -299,11 +296,11 @@ backpropagate/
|
|
|
299
296
|
│ ├── chrome.py # Header / LeftNav / SideRail / Footer
|
|
300
297
|
│ ├── pages/ # Train / Multi-Run / Export / Dataset
|
|
301
298
|
│ └── components/ # Bp* primitives (status pill, sparkline, event log…)
|
|
302
|
-
|
|
303
|
-
├── ui_gradio_legacy.py # DEPRECATED — preserved as v1.0 reference; removed in v1.2
|
|
304
|
-
└── theme_gradio_legacy.py # DEPRECATED — same
|
|
299
|
+
└── ui_security.py # Rate limiting, CSRF, file validation (framework-agnostic)
|
|
305
300
|
```
|
|
306
301
|
|
|
302
|
+
A implementação v1.0 do Gradio (`ui_gradio_legacy.py` + `theme_gradio_legacy.py`) foi mantida nas versões v1.1.x como referência e removida na v1.2.0.
|
|
303
|
+
|
|
307
304
|
## Solução de problemas
|
|
308
305
|
|
|
309
306
|
Um índice resumido dos erros mais comuns no início da execução. O índice completo está disponível em [esta página do manual de solução de problemas](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/); cada código abaixo está documentado em [códigos de erro](https://mcp-tool-shop-org.github.io/backpropagate/handbook/error-codes/).
|
package/README.zh.md
CHANGED
|
@@ -94,7 +94,6 @@ pip install backpropagate[full] # Everything
|
|
|
94
94
|
| `validation` | Pydantic 配置验证 | pydantic, pydantic-settings |
|
|
95
95
|
| `export` | 用于 Ollama 的 GGUF 导出 | llama-cpp-python |
|
|
96
96
|
| `monitoring` | WandB + 系统监控（在 v1.1.0 中自动集成到训练器中） | wandb, psutil |
|
|
97
|
-
| `observability` | OpenTelemetry 追踪 | opentelemetry-api, opentelemetry-sdk |
|
|
98
97
|
| `logging` | 结构化日志记录 | structlog |
|
|
99
98
|
| `security` | JWT 身份验证 + 令牌生成 | PyJWT, cryptography |
|
|
100
99
|
| `production` | unsloth + ui + validation + logging + security | (捆绑) |
|
|
@@ -145,7 +144,7 @@ trainer.save("./my-model")
|
|
|
145
144
|
trainer.export("gguf", quantization="q4_k_m")
|
|
146
145
|
```
|
|
147
146
|
|
|
148
|
-
`Qwen/Qwen2.5-7B-Instruct`
|
|
147
|
+
`Qwen/Qwen2.5-7B-Instruct` 是默认的、标准的配置。当 `Trainer()` 函数在没有指定模型参数的情况下被调用时，该值会被解析（参见 `config.py` 文件的 `ModelConfig.name`）。 较早的示例使用了预量化的 `unsloth/Qwen2.5-7B-Instruct-bnb-4bit` 模型；我们已将默认配置更改为官方的 Qwen 模型权重，以提高可靠性（[CHANGELOG v1.1.0](CHANGELOG.md#110---2026-05-21)）。 两种模型都可以使用。
|
|
149
148
|
|
|
150
149
|
### 多轮 SLAO 训练
|
|
151
150
|
|
|
@@ -246,9 +245,7 @@ backprop ui --port 7862
|
|
|
246
245
|
backprop ui --share --auth alice:hunter2
|
|
247
246
|
```
|
|
248
247
|
|
|
249
|
-
`backprop ui --share` 命令，如果未指定 `--auth` 参数，将以错误代码 `1` 退出，并显示结构化错误信息 `[
|
|
250
|
-
|
|
251
|
-
为了明确禁用身份验证（例如，在内部开发环境中），请设置环境变量 `BACKPROPAGATE_SECURITY__REQUIRE_AUTH_FOR_SHARE=false`。每次启动时，系统会发出明显的警告。此外，在未授权的界面加载之前，会有一个 5 秒的缓冲期，如果界面显示不正确，您可以按 `Ctrl-C` 停止。
|
|
248
|
+
`backprop ui --share` 命令，如果未指定 `--auth` 参数，将以错误代码 `1` 退出，并显示结构化错误信息 `[RUNTIME_UI_AUTH_NOT_ENFORCED]`。 原因是：`--share` 会发布一个公开的 URL，任何人都可以访问。 如果没有身份验证，这意味着任何人都可以控制您的训练流水线。 如果您不想设置凭据，请使用 SSH 端口转发：`ssh -L 7860:localhost:7860 <host>`，然后在本地打开 `http://localhost:7860`。 请参阅 [handbook/security.md](site/src/content/docs/handbook/security.md) 以获取完整的安全风险评估。
|
|
252
249
|
|
|
253
250
|
用户界面中的文件写入操作会被限制在一个单独的目录中，以提高安全性。
|
|
254
251
|
|
|
@@ -299,11 +296,11 @@ backpropagate/
|
|
|
299
296
|
│ ├── chrome.py # Header / LeftNav / SideRail / Footer
|
|
300
297
|
│ ├── pages/ # Train / Multi-Run / Export / Dataset
|
|
301
298
|
│ └── components/ # Bp* primitives (status pill, sparkline, event log…)
|
|
302
|
-
|
|
303
|
-
├── ui_gradio_legacy.py # DEPRECATED — preserved as v1.0 reference; removed in v1.2
|
|
304
|
-
└── theme_gradio_legacy.py # DEPRECATED — same
|
|
299
|
+
└── ui_security.py # Rate limiting, CSRF, file validation (framework-agnostic)
|
|
305
300
|
```
|
|
306
301
|
|
|
302
|
+
v1.0 的 Gradio 实现（`ui_gradio_legacy.py` + `theme_gradio_legacy.py`）在 v1.1.x 版本中被保留，仅作为参考，并在 v1.2.0 版本中被移除。
|
|
303
|
+
|
|
307
304
|
## 故障排除
|
|
308
305
|
|
|
309
306
|
常见首次运行失败的简要索引。完整的反向索引位于[故障排除手册页面](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/)；以下每个代码都记录在[错误代码](https://mcp-tool-shop-org.github.io/backpropagate/handbook/error-codes/)中。
|
package/bin/backpropagate.js
CHANGED
|
@@ -19,7 +19,7 @@ const os = require("os");
|
|
|
19
19
|
// ---------------------------------------------------------------------------
|
|
20
20
|
|
|
21
21
|
const TOOL = "backpropagate";
|
|
22
|
-
const VERSION = "1.
|
|
22
|
+
const VERSION = "1.2.0";
|
|
23
23
|
|
|
24
24
|
if (process.platform === "linux") {
|
|
25
25
|
// XDG-compliant install root
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mcptoolshop/backpropagate",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "Headless LLM fine-tuning CLI with smart defaults — train, export, serve. Reflex web UI, HF Hub push, resume-from-checkpoint, run history, model cards, multi-run SLAO.",
|
|
3
|
+
"version": "1.2.0",
|
|
4
|
+
"description": "Headless LLM fine-tuning CLI with smart defaults — train, export, serve. Reflex web UI (auth-gated), HF Hub push, resume-from-checkpoint, run history, model cards, multi-run SLAO. v1.2.0: auth-bypass closed + truth-in-advertising sweep.",
|
|
5
5
|
"type": "commonjs",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"engines": { "node": ">=20" },
|