alignment-handbook

一键复现主流 LLM 对齐实验，从 SFT 到 DPO 全流程开箱即用。

alignment-handbook 是一个用于对齐语言模型（LM）与人类及 AI 偏好的开源工具箱，由 Hugging Face 团队维护。它提供了一套稳健、可复现的“配方”（recipes），覆盖从监督微调（SFT）到偏好优化（如 DPO、KTO）的完整流程，帮助开发者高效地将基础模型训练成符合特定价值观或行为规范的助手。项目解决了 LLM 对齐过程中实验配置复杂、复现困难、工程门槛高的问题，通过模块化代码、清晰的命令行接口和详细的文档，让研究者与工程师能快速在单卡或分布式环境（如 DeepSpeed）下运行实验。其核心能力包括：支持多种主流模型架构（如 Llama、Mistral）、内置多种对齐算法、提供 DPO 训练脚本和 LoRA 微调支持，并附带大量社区贡献的配方与基准结果。

开源 free 开源模型

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 5681

维护状态活跃

是否开源是

定价模式 free

项目数据

分类开源模型

开发团队huggingface

所属国家

官网地址

GitHubhttps://github.com/huggingface/alignment-handbook

定价模式free

价格说明开源项目，Apache-2.0 许可证，可自由使用和部署，无付费版本。

访问状态

是否开源是

开源协议Apache-2.0

主要语言Python

技术栈/模型llm,rlhf,transformers

GitHub 星标★ 5681

30天Star增速

HF 下载量

上线时间2023-08-25 00:00:00

最近更新2026-09-22 00:00:00

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数3

使用教程

难度：进阶约 30 分钟部署方式：本地安装 6 步

环境要求

Python 3.11（README 用 uv 指定 --python 3.11 创建虚拟环境）
已安装 uv（需按 uv 官方安装指南安装）
带 CUDA 12.6 的 GPU 环境（PyTorch 通过 cu126 源安装）
git-lfs（用于向 Hugging Face Hub 推送模型）
可用的 Hugging Face 账号（需要 huggingface-cli login）

安装与启动步骤

1创建并激活虚拟环境

用 uv 创建名为 handbook 的 Python 3.11 虚拟环境，激活后升级 pip。未装 uv 需先按官方指南安装。
```
uv venv handbook --python 3.11 && source handbook/bin/activate && uv pip install --upgrade pip
```
2安装指定版本 PyTorch

从 PyTorch cu126 源安装 torch 2.6.0。版本必须精确以复现结果，换硬件请参考官方安装页。
```
uv pip install torch==2.6.0 --index-url https://download.pytorch.org/whl/cu126
```
3安装项目依赖

在仓库根目录安装 alignment-handbook 其余依赖，命令末尾的点表示从当前目录安装。
```
uv pip install .
```
4安装 Flash Attention 2

安装 flash-attn 2.7.4.post1，必须保留 --no-build-isolation 参数，否则编译会失败。
```
uv pip install "flash-attn==2.7.4.post1" --no-build-isolation
```
5登录 Hugging Face

执行后按提示粘贴 access token，用于下载数据集与上传模型到 Hugging Face Hub。
```
huggingface-cli login
```
6安装 Git LFS

安装 git-lfs 以便后续把训练好的模型推送到 Hugging Face Hub，需要 sudo 权限。
```
sudo apt-get install git-lfs
```

如何确认成功

上述命令均无报错执行完毕后，仓库根目录下的 scripts 和 recipes 目录即可查看，说明环境准备完成。

常见问题

Q：还没有安装 uv 怎么办？

A：按 README 给出的 UV 安装指南安装：https://docs.astral.sh/uv/getting-started/installation/ ，装好后再执行创建虚拟环境的命令。

Q：PyTorch 版本能换成别的吗？

A：README 强调精确版本对可复现性很重要，因此建议保持 torch==2.6.0；由于版本依赖硬件，也可参考 PyTorch 官方安装页面自行选择。

Q：flash-attn 安装失败是什么原因？

A：README 明确要求带 --no-build-isolation 参数安装，漏掉该参数容易在构建阶段报错，请按原命令重试。

Q：为什么要登录 Hugging Face？

A：登录后可拉取 Hub 上的数据集与模型，并在训练完成后用 git-lfs 将模型推送到 Hugging Face Hub。

注意事项

README 强调依赖版本精确（torch 2.6.0、flash-attn 2.7.4.post1）以保证可复现性，不要随意升级。
Flash Attention 2 对硬件和 CUDA 环境有要求，安装前确认 GPU 环境可用。
后续训练方法与配方请查阅仓库中的 scripts 和 recipes 目录，README 未在此处给出具体训练命令。
git-lfs 通过 apt 安装需要 sudo 权限，无权限时请联系管理员或改用其他安装方式。

核心亮点

模块化设计，SFT/DPO/KTO 等算法切换仅需修改配置，无需重写代码
基于 Hugging Face 生态，与 transformers、peft 深度集成，支持 LoRA 高效微调
提供多个已复现的基准配方（如 Zephyr、Tulu），可直接对比结果，节省调参时间

不足之处

文档对自定义数据格式和高级用法的说明不够详尽，新手需参考示例代码
部分算法（如 KTO）的稳定性和超参数敏感性仍需更多社区验证

适用场景

研究者快速验证新的偏好对齐算法效果
企业将开源基座模型微调为符合业务规范的客服或助手
高校实验室复现顶会论文中的对齐实验并作为基线

替代项目

TRL (Transformer Reinforcement Learning)、Axolotl、LLaMA-Factory

项目介绍

alignment-handbook 是模型训练领域的开源项目，由 huggingface 开发，2023 年首次发布。

在全站 13,090 个收录项目中，它的 GitHub 星标数（5,681）位列前 8%，在模型训练分类的 522 个项目里位列前 9%。

近 41 天，它的 GitHub 星标从 5,659 增加到 5,681，净增 22。

项目目前处于活跃维护状态，最近一次代码更新于 2026-09-22。Apache-2.0 许可证，可自由使用和部署，无付费版本。

它主要面向的使用场景是：研究者快速验证新的偏好对齐算法效果。同类可对比的替代方案包括 TRL (Transformer Reinforcement Learning)、Axolotl、LLaMA-Factory。

上一篇：chronos-forecasting

下一篇：xtuner