8. 開発者向けリファレンス：自動テストとコードマップ¶
演習をするだけでコードを変更しない読者は、この章を飛ばしてかまいません。データ処理、学習コード、またはチュートリアル自体を変更したい場合は、まずここを読んでください。このプロジェクトでは自動テストによって、「ドキュメントに書かれていること」と「コードが実際に行うこと」を結びつけています。
8.1 自動テスト¶
データ処理や学習のコードを変更したら、CPU 環境で回帰テストを実行します。この環境には PyTorch、TRL、PEFT が含まれており、ランダムに初期化した小さなモデルで学習の仕組みを検証するためのものです。第 2 章のデータ演習では飛ばしてかまいません。
python3.11 -m venv .venv-cpu
source .venv-cpu/bin/activate
python -m pip install -r requirements-cpu.txt
python -m pytest -q
テストには tests/ を含む完全なプロジェクトソースが必要です。第 3 章の簡略化した GPU アップロード用バンドルには開発者向けテストは含まれていません。完全なプロジェクトでは .venv-train でテストを実行することもできます。小さなモデルのテストでは、重みをダウンロードする必要はありません。
| レイヤー | テスト/コマンド | 何を証明するか |
|---|---|---|
| データ | test_data.py、test_prepare.py、test_bundle.py、test_notebook.py |
単一ファイルの読み込み、ドラフトのゲート、グループと未来のラウンドの隔離、空でないターゲット、スナップショットの互換性 |
| テンプレート | test_render.py、lab.audit |
ターゲットの範囲、トークン境界、EOS、オーバーフロー、実際の collator のパディング |
| 小さなモデルでの学習 | test_training.py、test_notebook.py |
CLI の学習コンポーネントとノートブックの実際のコードで、LoRA の更新、保存、再読み込み、マージができる |
| 評価 | test_eval.py |
ペアリング、欠けたスコア、引き分け、会話単位でクラスタリングした統計 |
| ドキュメントとコード | test_tutorial.py、test_book.py |
チュートリアルのコマンドが実際の CLI に受け付けられる。デプロイの例と付録がソースと一致する。ページとダウンロード用バンドルが機能する |
| API の例 | test_tutorial.py |
本書の呼び出し例を直接実行し、モデル名、アドレス、パラメータ、マルチターンの履歴の受け渡しを確認する |
| ダウンロード | test_download.py |
すべてのダウンロード元が同じリビジョンを使う。欠けた/破損した重みは拒否される |
| GPU モデル | 第 4 章と第 5 章のコマンド | 実際の QLoRA の学習/再開、アダプターとマージ済みの出力 |
| vLLM の統合 | /health、/v1/models、第 5 章の Python の例、vllm bench serve |
実際のサービスを呼び出せる。シングルターン/マルチターン/ストリーミングの呼び出しと同時実行の負荷テストが完了する |
API の例のテストは一時的なローカル HTTP サーバーを使うため、vLLM による推論の証拠にはなりません。GPU とサービスのチェックはそれぞれの環境で実行し、実行していない項目は todo でチェックを付けないままにします。
次の受け入れの証拠を保管してください：生データ/展開後のデータとレビュー記録、トークンのレポートとテストの出力、モデルの SHA・依存関係・ドライバー・学習設定、チェックポイント・アダプター・再開ステップ、A/B/C の生の出力とスコア、マージの manifest・推論環境のバージョン・API のレスポンス。
8.2 コードの読み方マップと設計の根拠¶
メインパスについては、まずノートブックを読み、補助モジュールは役割に応じて参照してください。
| チュートリアル内の位置 | 対応するコード | 目的 |
|---|---|---|
| 2.8 節、第 3 章 | download.py、download-lock.json | 固定したリビジョンをダウンロードし、完全性をチェックする |
| 第 2 章 | dataset.json、data.py、prepare.py、common.py | ファクトと会話を検証し、プロンプトを組み立て、トークナイズ済みのサンプルを生成する |
| 第 2 章、第 6 章 | audit.py | 実際の collator の教師範囲とパディングを確認する |
| 第 4 章 | 01_gpu_train.en.ipynb | 1 エポックの学習、loss 曲線、成果物のチェック、再読み込み後の回答、マージ |
| 4.6 節、第 6 章、付録 | train.py、training.py | コマンドラインでの学習、正式なパラメータ比較、チェックポイントからの再開 |
| 第 6 章 | infer.py、evaluate.py | A/B/C の推論、ブラインドレビューの統計、候補の凍結 |
| 第 5 章 | merge.py、ノートブックの最後の 2 節 | 単体でのエクスポート、vLLM のデプロイとアダプターのマウント、API 呼び出し、負荷テスト |
ノートブックは学習の詳細を示し、CLI は繰り返しの実験と再開のために残しています。それぞれのエントリーポイントには対応する章があります。API の例は HTTP または OpenAI SDK を直接呼び出し、負荷テストには vLLM に組み込みの vllm bench serve を使うので、独自のクライアントは保守していません。
| 判断 | 理由と出典 |
|---|---|
| テキスト専用の 4B に固定 | 同じベースモデルで実験を比較する。Qwen モデルカード |
| 明示的な completion mask | 教師範囲を検査できる。TRL 0.24 |
| NF4+LoRA | 1 枚の GPU で少数のパラメータを学習する。PEFT の量子化 |
| 推論環境を分離 | 依存関係が互いに上書きされるのを避ける。vLLM の GPU インストール |
| ファクトと表現を分けて学習 | このプロジェクトの実験設計。改善は比較によって検証する |
ファクトカードには科学的な出典へのリンクが記録されています。レビューでは、各主張、その適用条件、たとえの限界を 1 つずつ確認し、特にまだ pending と記されている出典に注意してください。Web ページにアクセスできるからといって、生成されたすべての会話を裏付けているとは限りません。