alignment-handbook : des recettes reproductibles pour aligner un LLM sur des préférences

Le vide que le dépôt cherche à combler

Le README part d'un constat daté : l'écosystème open source s'est surtout concentré sur le supervised fine-tuning, c'est-à-dire apprendre à un modèle à suivre des instructions. Les papiers InstructGPT et Llama2 montrent que l'on gagne en utilité et en sécurité en ajoutant une étape de préférences humaines ou synthétiques. Or les ressources publiques expliquant comment entraîner ces modèles, quelles données collecter et quelles métriques suivre sont rares. C'est le public visé : une équipe qui a déjà un modèle de base et qui veut savoir quoi faire ensuite, pas un cours d'introduction au fine-tuning. Le dépôt se présente comme un ensemble de recettes, pas comme une bibliothèque. Cette distinction compte : vous n'y trouverez pas d'API à importer, mais des scripts à lancer et des fichiers de configuration à copier.

Ce que contiennent réellement scripts/ et recipes/

L'architecture est volontairement plate. Le dossier scripts/ contient quatre étapes d'entraînement : pré-entraînement continu, SFT pour le chat, alignement par DPO, et ORPO qui combine SFT et préférences en une seule passe. Chaque script accepte deux modes : entraînement distribué des poids complets via DeepSpeed ZeRO-3, ou LoRA/QLoRA pour un fine-tuning paramétrique efficace. Le dossier recipes/ contient des fichiers YAML, un par run d'entraînement, avec tous les paramètres associés. Une recette gpt2-nl illustre l'adaptation à une autre langue ou à un domaine : pré-entraînement continu, puis SFT, puis DPO. Le README mentionne aussi un volet reward modeling et rejection sampling dans la liste des techniques couvertes. Le point important : la recette est l'unité de reproductibilité. Si vous modifiez un YAML, vous vous écartez du résultat publié, et le dépôt ne propose pas de mécanisme de validation qui vous le signalera.

Mise en route : les commandes que donne le README

L'installation passe par uv. Le README donne cette séquence : uv venv handbook --python 3.11 && source handbook/bin/activate && uv pip install --upgrade pip, puis uv pip install torch==2.6.0 --index-url https://download.pytorch.org/whl/cu126. La note est explicite : la version précise compte pour la reproductibilité, et comme elle dépend du matériel, le README renvoie à la page d'installation PyTorch. Ensuite uv pip install . pour le reste des dépendances, puis uv pip install "flash-attn==2.7.4.post1" --no-build-isolation. Il faut encore huggingface-cli login, et git-lfs via sudo apt-get install git-lfs pour pousser les modèles sur le Hub. Rien d'exotique, mais cette chaîne suppose un GPU CUDA 12.6 et une compilation de Flash Attention. Sur un environnement sans GPU NVIDIA récent, l'étape flash-attn est le premier point de friction, et le README ne propose pas de variante CPU.

Le piège de la reproductibilité affichée

Le dépôt promet des recettes robustes et reproductibles. C'est vrai au sens où les YAML sont versionnés et où les versions de PyTorch et de Flash Attention sont épinglées. C'est fragile au sens où la reproductibilité dépend d'un triplet : version de la bibliothèque transformers, matériel, et données. Le README ne détaille pas de mécanisme de vérification des sorties, et les releases récentes ne sont pas listées dans les métadonnées fournies. Autrement dit, si vous lancez une recette Zephyr sur un cluster différent de celui utilisé à l'origine, rien ne garantit que vous obtiendrez les mêmes métriques. Le dépôt fournit le point de départ, pas la preuve d'équivalence. Pour un usage en production, cela signifie que vous devez instrumenter vous-même la comparaison, par exemple en évaluant votre modèle final sur un jeu de test fixe et en le comparant au modèle publié sur le Hub.

ORPO, DPO, ou les deux : un choix qui n'est pas neutre

Le dépôt couvre DPO et ORPO côte à côte, et propose aussi une recette de comparaison DPO vs KTO vs IPO. C'est utile, mais cela laisse l'utilisateur arbitrer seul. ORPO fusionne SFT et alignement en une étape, ce qui réduit le nombre de runs et la gestion de deux jeux de données. DPO suppose un modèle SFT déjà entraîné et un jeu de préférences séparé. Le README ne tranche pas et ne donne pas de critère de sélection au-delà de la description des techniques. C'est un manque réel : un lecteur qui débute avec un modèle brut doit deviner s'il part sur ORPO directement ou s'il suit le pipeline en deux temps. La recette pref_align_scan existe précisément pour éclairer ce choix, mais elle n'est pas mise en avant dans le parcours de démarrage recommandé, qui pointe d'abord vers la reproduction de Zephyr-7b-beta.

Ce que le dépôt n'est pas

alignment-handbook n'est pas un framework d'entraînement. Il ne remplace ni un Trainer générique, ni une bibliothèque de gestion d'expériences. Il n'embarque pas de suivi de métriques, pas de registre de modèles, pas d'orchestration de pipeline. Si votre besoin est de définir votre propre boucle d'entraînement avec un contrôle fin sur la fonction de perte, vous serez mieux servi par les composants sous-jacents (transformers, TRL, DeepSpeed) que vous assemblez vous-même. Le dépôt est également centré sur des modèles de type Llama, Mistral, Gemma et SmolLM. Le README ne revendique pas de support pour des architectures non causales ou multimodales. Si votre modèle sort de ce périmètre, les recettes ne s'appliquent pas telles quelles, et vous devrez adapter les scripts, ce qui annule l'avantage de reproductibilité.

Alternative : TRL seul, ou un pipeline maison

L'alternative la plus directe est d'utiliser TRL, la bibliothèque d'entraînement de Hugging Face, sans passer par les recettes du handbook. La différence n'est pas dans les algorithmes, DPO et ORPO sont disponibles des deux côtés. Elle est dans le contrat : TRL vous donne des classes et des arguments à configurer ; le handbook vous donne un YAML complet et un script qui a servi à produire un modèle publié. Avec TRL seul, vous gardez la main sur chaque hyperparamètre et vous n'êtes pas contraint par la version de PyTorch épinglée. Avec le handbook, vous héritez d'une configuration qui a fonctionné, au prix d'une flexibilité moindre et d'une dépendance à la pile exacte décrite. Le choix dépend de ce que vous cherchez : un point de départ vérifié, ou un contrôle total. Les deux ne sont pas compatibles sur le même projet.

Coût de maintenance et licence

Le dépôt est sous Apache-2.0, ce qui autorise l'usage commercial et la modification, avec obligation de conserver les mentions de licence et d'état des modifications. Le README ne fournit pas de politique de support ni de calendrier de versions, et les métadonnées ne listent aucune release. La maintenance se lit donc dans les commits et les recettes ajoutées au fil du temps : SmolLM3 en juillet 2025, SmolLM2 en novembre 2024, StarChat2 en mars 2024. Le rythme est irrégulier, ce qui est normal pour un dépôt de recettes. Concrètement, votre coût de mise à jour vient moins du code que des dépendances épinglées : torch==2.6.0 et flash-attn==2.7.4.post1 devront être réévalués à chaque changement de matériel ou de version CUDA. Pour un projet qui doit tourner plusieurs années, prévoyez de figer vous-même les versions dans votre propre environnement plutôt que de suivre le dépôt.

Conclusion éditoriale

À adopter si vous voulez reproduire une recette publiée (Zephyr, SmolLM, StarChat2) ou repartir d'un pipeline SFT puis DPO déjà câblé, en acceptant la dépendance à une pile matérielle et logicielle précise. À éviter si vous cherchez une bibliothèque d'abstraction pour votre propre boucle d'entraînement, ou si vous ne pouvez pas faire tourner DeepSpeed ZeRO-3 ou Flash Attention 2. Avant de vous engager, vérifiez trois choses dans le dépôt : que le fichier YAML de la recette visée correspond bien à votre modèle de base, que la version de PyTorch imposée est installable sur votre GPU, et que le format de votre jeu de données suit les instructions de scripts/README.md.

Sources officielles

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