alignment-handbook を読む: SFT と選好学習を YAML レシピで再現するための判断材料

alignment-handbook が埋めようとしている穴は何か

SFT で指示に従うモデルを作るところまでは、公開データセットとモデルが揃っていて参入しやすい。README はこの状況を「mostly focused on teaching language models to follow instructions through supervised fine-tuning (SFT)」と表現している。一方で、InstructGPT や Llama2 の論文が示したように、人間または AI の選好を加えると有用性と安全性の面で改善が見込めるが、その学習手順やデータの集め方、評価指標を公開した資料は少ない。alignment-handbook はこの差分を、パイプライン全体を覆う学習レシピ集として埋めようとしている。対象読者は、既にモデルの学習を回した経験があり、SFT の次の段階として選好学習を自前のデータで試したいエンジニアである。チュートリアルというより、再現用の設定ファイル群とその実行スクリプトの集合体に近い。

scripts と recipes の二層構造

リポジトリは意図的に単純な構成を取っている。scripts/ には学習と評価のコードが置かれ、継続事前学習、チャット向け SFT、DPO による選好学習、ORPO による SFT と選好学習の統合という 4 段階が含まれる。各スクリプトは DeepSpeed ZeRO-3 による全重みの分散学習と、LoRA/QLoRA によるパラメータ効率の良いファインチューニングの両方に対応すると README は説明している。recipes/ 側は Zephyr 7B のようなモデルを再現するための YAML ファイルで、1 回の学習実行に対応するパラメータがそこに集約されている。gpt2-nl というレシピも用意されており、別言語や別ドメインへの適応、つまり継続事前学習の後に SFT と DPO を重ねる流れを小さなモデルで確認できる。学習コードと設定を分離したことで、同じスクリプトを使い回しながらレシピだけ差し替える運用が成立する。

環境構築でつまずきやすい箇所

インストール手順は uv を前提にしている。仮想環境を作り、PyTorch をバージョン固定で入れ、残りの依存をインストールする流れだ。README は「the precise version is important for reproducibility」と明記しており、torch==2.6.0 と flash-attn==2.7.4.post1 という具体的なバージョンが示されている。ここは再現性のための設計判断だが、同時に導入時の最大の障壁でもある。flash-attn は --no-build-isolation 付きでインストールする指示になっており、これはビルド時に既存の torch を参照させる必要があるためだ。CUDA のバージョンが README の想定とずれていると、このビルドが通らない可能性がある。手順には huggingface-cli login と git-lfs の導入も含まれる。学習済みモデルを Hugging Face Hub に push する前提の構成だからで、ローカル完結で使いたい場合でもこの認証ステップを省けるかは README からは読み取れない。

DPO と ORPO をどう選ぶか

リポジトリが扱う手法は複数ある。報酬モデリング、棄却サンプリング、DPO、そして ORPO である。README は DPO を PPO の代替として位置づけ、ORPO については SFT と DPO を 1 段階に統合する手法と説明している。実務的な違いは段階数にある。DPO は SFT 済みモデルを出発点にするため、SFT と選好学習を別々に回す必要があり、その分だけ中間モデルの管理と計算資源が増える。ORPO はそれを 1 回の学習に畳む。ただし README は ORPO の適用条件や、DPO と比べた品質差についての数値的な説明を与えていない。どちらを選ぶべきかは、手元のデータ量と、SFT 段階のモデルを別用途にも使い回したいかで決めるしかない。判断材料としては、recipes/ に両方のレシピが存在するので、同じデータで両方を流して比較するのが最短になる。

レシピの再現性はモデルとデータに依存する

recipes/ の YAML は、Zephyr 7B や SmolLM 系など特定のモデルとデータセットの組み合わせを再現するために書かれている。README のニュース欄には SmolLM3-3B のポストトレーニングレシピ、SmolLM2-Instruct のファインチューニングレシピ、Zephyr 141B や StarChat2 15B のレシピなどが列挙されている。これは裏を返せば、自分のモデルやデータセットにそのまま適用できるわけではないということだ。README 自身も、自前のデータセットでチャットモデルを学習したい場合は scripts/README.md のデータセット整形手順に従うよう案内している。つまりレシピは出発点であり、データ形式を合わせる作業は利用者側に残る。ここを軽視すると、YAML を書き換えただけで動くと考えて時間を失う。

向かないケースと代替手段

このリポジトリは学習パイプラインの再現に重点を置いており、推論やサービング、評価の自動化までは面倒を見ない。手軽に少量のデータでモデルを適応させたいだけなら、Transformers の Trainer と PEFT を直接使うほうが構成は小さい。alignment-handbook を挟むと、DeepSpeed の設定、分散学習の起動、バージョン固定の依存という追加の管理対象が生じる。逆に、TRL を単体で使うアプローチとの違いは明確だ。TRL は DPO や ORPO のトレーナー実装を提供するライブラリであり、学習の実行そのものを担う。alignment-handbook はその上に、どのモデルをどのデータでどのハイパーパラメータで学習するかを YAML として固定し、再現手順として配布する役割を担う。自分で設定を設計したいなら TRL を直接叩けばよく、既知の構成を忠実に再現したいなら handbook のレシピを使う、という住み分けになる。

ライセンスと保守の見通し

ライセンスは Apache-2.0 で、商用利用を含む広い利用が許される条項を持つ。ただしこれはリポジトリのコードに対するもので、レシピが参照するモデルやデータセットのライセンスは別に確認する必要がある。Zephyr や SmolLM の重み、No Robots などのデータセットにはそれぞれ条件があり、学習済みモデルの配布や商用利用の可否はそちらに従う。法的な判断はここでは扱わない。保守面では、README のニュース欄が 2023 年 11 月から 2025 年 7 月まで継続的に更新されており、新しいモデル系列ごとにレシピが追加されている。一方でリリースタグは取得できておらず、バージョン番号による固定ができるかは不明である。依存を torch==2.6.0 のように固定している以上、上流の更新に追随するコストは利用者側が負うことになる。

編集部の結論

自分で SFT や DPO の学習パイプラインを組み、DeepSpeed ZeRO-3 と Flash Attention 2 が動く GPU 環境を持っているチームには向いている。逆に、少量のデータで手軽にファインチューニングしたいだけの用途や、CPU しかない環境には重すぎる。導入前に確認すべきは、recipes/ 配下の YAML が想定するモデルとデータセットの組み合わせが自分の対象と一致するか、そして README が指定する torch==2.6.0 と flash-attn==2.7.4.post1 を自分の CUDA 環境でビルドできるかである。ここが合わなければ、レシピを流用するより scripts/ 以下の学習スクリプトだけを取り出して自前の設定を書くほうが早い。

公式情報源

1. huggingface/alignment-handbook on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README