Unsloth LoRA トレーニング
ローカルGPU上でUnslothを使用してチャット形式のデータセットに対してLoRAをトレーニングし、結果をGGUFとしてエクスポートします。データセットはユーザーが用意するものです（生成は問題固有です）。このスキルはtrain.jsonlとval.jsonlから開始します。モデルのサービングは別のステップです。このスキルが生成する実行フォルダ（GGUFとrun.json）は、ollama-modelなどのサービングスキルが受け取るものです。
すべてのスクリプトは、Bashツールを使用してランチャーを通じて実行します：${CLAUDE_SKILL_DIR}/scripts/run <script.py> [args]。このスキルはそのコマンドのみを許可しており、自動モードで実行されます。別の方法でスクリプトを呼び出すと拒否されます。ユーザーからの新しいメッセージの後にランチャーコマンドが拒否された場合は、このスキルを再度呼び出してください。ランチャーは、check_data.pyを任意のPython 3で実行し、preflight.py、train.py、export_gguf.pyをUnsloth環境のPythonで、--out/--runフォルダの親フォルダで実行します（Unslothはカレントディレクトリにunsloth_compiled_cache/フォルダを書き込みます）。すべてのパスは絶対パスで指定してください。コマンドはワーキングディレクトリを共有しません。
開始前に確認すること
- データセットフォルダと、後でモデルを比較するために使用する評価セット：トレーニングの一部であってはなりません。ない場合は、トレーニング前にサンプルを保留することを提案してください。
- ベースモデル：Unsloth 4ビット名（例：
unsloth/Qwen2.5-Coder-3B-Instruct-bnb-4bit）。複数のベースモデルがある場合は、それぞれに1つの実行フォルダがあり、各ステップを順次実行します（references/base-models.md）。 - マシン：トレーニングにはCUDA GPUとUnsloth環境のPythonが必要です。
UNSLOTH_PYTHONが設定されておらず、~/.config/llm-finetune/unsloth-pythonが存在しない場合は、ユーザーにそのPythonのパスを尋ね、そのパスをファイルの最初の行として書き込みます（ユーザーの了解を得て）。ランチャーはそこから読み取ります。 - 実行フォルダ：実行フォルダを配置する場所で、gitチェックアウトの外側にあります。以下では
<runs>がその絶対パスです。
手順
1. データのチェック
${CLAUDE_SKILL_DIR}/scripts/run check_data.py <data> --eval <eval.jsonl>
okを表示する必要があります。壊れた行、アシスタントの回答で終わらない会話、トレーニングに含まれるバリデーションまたは評価プロンプト（同じまたは異なる回答の場合）があると失敗します。モデルがそれらを見ているため、再現率を測定することになります。修正方法は、バリデーションまたは評価からそれらを取り除くこと（またはデータの分割方法を修正すること）であり、チェックを通過させるためにトレーニングを変更してはいけません。また、システムメッセージの使用方法（なし、1つの共有、または混合）も報告します（references/chat-formats.mdを参照）。
2. マシンのプリフライト
${CLAUDE_SKILL_DIR}/scripts/run preflight.py --params-b <パラメータ数（十億単位）> --out <runs>/<run>
空きGPUメモリは総メモリよりも重要です：ゲーム、GPUアクセラレーションを使用するブラウザ、ローカルサーバーがまだ保持しているモデル（ollama ps、ollama stop <model>でアンロード）は、空きメモリを少なくします。プリフライトが他のGPUユーザーをリストした場合は、ユーザーに伝えて決定を委ね、プロセスを強制終了しないでください。--params-bを使用すると、必要なメモリを推定します（3Bモデルは4ビットでシーケンス長1024、バッチサイズ4で6.6 GiB、7Bモデルは8.1 GiB）し、空きメモリが不足している場合は、代わりに使用する--batch-size/--grad-accumのペアを出力します。これは2回の実行からの推定です。他のサイズやシーケンス長の場合は--need-gibを渡し、スモークランが報告するピークメモリを監視してください。
インポートに失敗した場合、環境が壊れています。何かを再インストールする前にreferences/troubleshooting.mdを参照してください。
3. スモークラン
${CLAUDE_SKILL_DIR}/scripts/run train.py --model <base> --data <data> --out <runs>/<run>-smoke --max-steps 2
出力を読み、終了コードだけを確認しないでください：
- 最初の例がどのようにレンダリングされるか：上部のシステム行は、モデルが学習することを期待するものです。
- 損失を受け取るトークン：質問ではなく、回答のみ。
- トークン長：トランケーション警告は、
--max-seq-lengthを上げるか、例を削除する必要があることを意味します。 - サーバーが送信する必要のあるシステムターンとそれに関する警告。思考テンプレート（Qwen3、Qwen3.5）は、トレーニングされたすべての回答の前に空の
thinking responseブロックを配置します：アプリが回答にそれを受け取り、削除する必要があることをユーザーに伝えてください。
4. フルラン
${CLAUDE_SKILL_DIR}/scripts/run train.py --model <base> --data <data> --out <runs>/<run>
しばらく実行されます（3Bモデルで数千サンプルで数分、7Bモデルではそれ以上）。Bashツールのバックグラウンドオプションを使用して開始し、セッションを開いたままにしないでください（ツールは出力をファイルに保持し、それがログです。コマンドに>、;、&&を追加しないでください。事前承認はランチャーコマンドをそのままカバーします）。${CLAUDE_SKILL_DIR}/scripts/run train_status.py <runs>/<run>で確認します：ステップ、損失、最小検証損失のステップと残り時間（最新のチェックポイントの時点）。クラッシュ後は--resumeを使用してください。トレーニング損失と検証損失、およびピークGPUメモリを報告します。検証損失がトレーニング損失よりもはるかに高い場合は、過学習を意味します：エポック数を減らすか、データを増やしてください。
5. エクスポート
${CLAUDE_SKILL_DIR}/scripts/run export_gguf.py --run <runs>/<run>
3Bモデルで数分、7Bモデルでは10分以上かかります（マージ、変換、量子化）。これはBashツールがフォアグラウンドコマンドを実行できる時間よりも長いため、トレーニングと同様にバックグラウンドで開始し、完了を待ってください。GGUFを<run>/gguf/に書き込み、サイズとチェックサムをrun.jsonに記録します。マージされた16ビットモデル（数GB。--keep-mergedで保持し、その場合GGUFは<run>/gguf_gguf/に残ります）と、UnslothがGGUFの横に書き込むModelfileを削除します。そのModelfileはデフォルトのテンプレートを使用しており、トレーニングで使用したレイアウトではないため、Unslothのヒントに従ってollama createしないでください。エクスポート毎にllama.cppのコンバータに関する[CRITICAL]警告が表示されることを想定してください。その意味をユーザーに説明し（references/troubleshooting.md）、エクスポートを停止しないでください。実行フォルダはこれでサービングの準備ができました：ollama-modelスキルを続行するか、run.jsonのchatセクションをモデルをサービスするものに渡してください（references/run-json.md）。
6. クリーンアップ（事前に確認）
モデルがエクスポートされ評価されたら、再開やセットアップの確認にのみ必要なものを削除することを提案します：<run>/checkpoints/（--resume用、7Bモデルで数GB）と<run>-smokeフォルダ。それぞれの容量を伝え、ユーザーが同意したものだけを削除してください。adapter/とrun.jsonは保持します。これらは小さく、新しいエクスポートとリリースノートに必要です。
ルール
- 評価結果を良く見せるためにデータセットを変更したり、トレーニングデータで評価したりしないでください。
- 確認なしにUnsloth環境にパッケージをインストールまたはアップグレードしないでください。そのtorch/CUDAの組み合わせは脆弱です。
- 実行フォルダやチェックポイントを削除する前に確認してください。