soup

Soup — 1つのコマンドで行うLLMのファインチューニング

Soupを使えば、単一のYAML設定ファイルで、ファインチューニングをsoup init→soup trainとして実行できます。タスクの選択、量子化、バッチサイズ、GPU／バックエンドの検出はすべて自動で処理されます。目玉機能であるレイヤーストリーミング（stream_layers: true）は、凍結されたベースモデルをVRAMに置かず、デコーダーレイヤーを一度に1つずつストリーミングします。そのため、8Bモデルを4 GBのノートPC向けGPUでファインチューニングできます。通常の常駐実行とビット単位で一致することも測定済みです。

このスキルを使う場面

• Transformers／PEFT／TRLのトレーニングスクリプトを手作業で作る代わりに、新しいファインチューニングの実行を準備する（soup init、soup train）
• トレーニング手法（SFT、DPO／GRPO／ORPO／SimPO／KTO／IPO／BCO）や、GPUの制約に合わせた省メモリ方式（QLoRA、DoRA、LoRA+、rsLoRA、レイヤーストリーミング）を選ぶ
• GPUの実行時間を使う前にトレーニングのコスト／メモリを見積もる（soup cost、soup profile）、または実行前に手法の推奨を得る（soup advise）
• 既存のAxolotl／LLaMA-Factory／Unsloth設定をSoupに移行する
• トレーニング済みのアダプターをサービング、マージ、プッシュする（soup serve、soup merge、soup push）、またはデータ品質／評価ツールを実行する（soup data ...、soup ship）

このスキルを使わない場面

• 主な関心事がRay／DeepSpeedクラスター／マルチノード規模のトレーニングインフラである場合 → deepspeedまたはopenrlhf-trainingを直接使用してください。SoupはDeepSpeed／FSDPを起動フラグとしてラップするものであり、これらの代替ではありません
• トレーニングを伴わず、マージ済みモデルを純粋に推論サービングする場合 → 通常の推論ランタイム向けスキルが適しています
• ユーザーがSoup／PEFT／TRLをまったく使わない場合（例：プロンプトエンジニアリングのみ） → すぐにsoup trainへ進むのではなく、soup advise独自の判定に回してください（トレーニングではなくPROMPT_ENGと判定されることもあります）

手順

ステップ1：適切なプロファイルをインストールする

bash pip install soup-cli # 軽量なCLIのみ：init/advise/data/profile/cost pip install "soup-cli[train]" # + 実際のトレーニング用torch/transformers/peft/trl

ステップ2：GPUの実行時間を使う前に手法を決める

bash soup advise <data.jsonl> --goal "..." # PROMPT_ENG / RAG / SFT / DPO / GRPO の判定 soup autopilot --model --data d.jsonl --goal "" # 設定不要：タスク／量子化／LR／エポックを選択

最初からsoup trainを実行しないでください。誤った手法（例：データが選好ペアなのにSFTを使う）を選ぶと、実行全体が無駄になるため、advise／autopilotが用意されています。

ステップ3：設定をひな形から作成して編集する

bash soup init --template chat # またはcode/audio/... — docs/models.mdを参照 soup fetch # すぐに使えるサンプル設定を取得

メモリに制約のあるハードウェアでは、レイヤーストリーミングを明示的に有効にしてください。

yaml training: stream_layers: true # ベースモデルをVRAM外にストリーミングし、アダプターのみをトレーニング quantization: 4bit # NF4 batch_size: 4 stream_source: auto # RAMに収まる場合はRAM、そうでなければNVMeディスク

レイヤーストリーミングはベータ版で、SFTとDPO／ORPO／SimPO／KTOに対応しています。GRPO／PPOには対応していません（生成トークンごとにすべてのレイヤーを再読み込みするため、ストリーミングの償却効果が失われます）。

ステップ4：GPUを使う前に見積もる

bash soup profile --config soup.yaml --gpu a100 soup cost --config soup.yaml --gpu H100

ステップ5：トレーニング後、公開前に検証する

bash soup train --config soup.yaml soup train --config soup.yaml --gate evals/gate.yaml # 評価によるゲート付き soup ship --config soup.yaml # 実行可否を判定

ステップ6：結果をサービング、マージ、またはプッシュする

bash soup infer --model ./output --input p.jsonl soup chat --model ./output soup merge --adapter ./output soup push --model ./output --repo user/name soup serve --model ./output

ステップ 7：読み取り専用の環境チェックにラッパーを使用する

bash bash .agent-skills/soup/scripts/soup.sh doctor bash .agent-skills/soup/scripts/soup.sh advise <data.jsonl> --goal "..." bash .agent-skills/soup/scripts/soup.sh profile <config.yaml>

doctor は環境（Python のバージョン、soup のインストール状況、[train] の追加機能、CUDA/MPS の利用可否）を確認するだけで、パッケージのインストールやトレーニングの開始は行いません。

ベストプラクティス

1. soup train の前に soup advise／soup autopilot を実行する — タスクファミリー（SFT と選好損失のどちらか）を誤って選んだ場合、先に実行しないとトレーニングを最後まで実行してから判明します。
2. GPU をレンタルする前に soup cost／soup profile を実行する — 実行後に OOM や予想外の 40 ドルの費用に気づくよりも安く済みます。
3. レイヤーストリーミングはオプションで選ぶトレードオフであり、デフォルトではありません — メモリ使用量を減らす代わりに、レイヤースタックの読み取りが増えます（DPO では SFT の約 1.52 倍の頻度で読み取ります）。有効にする前に、手法がサポート対象リスト（SFT/DPO/ORPO/SimPO/KTO）に含まれていることを確認してください。
4. リリース前にゲートを設ける — 損失曲線を目視で確認するよりも、--gate evals/gate.yaml と soup ship を使用してください。
5. 重い依存関係は遅延読み込みのままにする — Soup を実行するスクリプトのモジュール最上位で torch／transformers／peft／trl のインポートを提案しないでください。プロジェクト自体がこれらを遅延インポートするため、軽量な CLI の起動が速く保たれます。
6. 設定は手作業で移植せず、移行する — soup migrate --from axolotl|llamafactory|unsloth は、手動での設定変換によるエラーを避けるために用意されています。

参考資料

• references/commands.md — ワークフローの段階ごとに整理された厳選コマンドリファレンス
• scripts/soup.sh — 読み取り専用の doctor と、薄い advise／profile／cost ラッパー
• Soup GitHub リポジトリ
• Soup のドキュメント索引
• プロジェクト標準：.agent-skills/skill-standardization/SKILL.md

例

例 1：手法を選び、4 GB のノート PC GPU でファインチューニングする

bash soup advise data.jsonl --goal "モデルに厳密な出力スキーマに従わせる" soup init --template chat

soup.yaml: stream_layers: true、quantization: 4bit を設定

soup profile --config soup.yaml soup train --config soup.yaml

例 2：トレーニング方法を推奨する前に環境を確認する

bash bash .agent-skills/soup/scripts/soup.sh doctor