fairseq2：FAIR 序列建模工具包 2

文档：稳定版、夜间版 | 安装：Linux、macOS、Windows、源码安装 | 贡献：贡献指南

fairseq2 是一个序列建模工具包，使研究人员能够为内容生成任务训练自定义模型。

基于 fairseq2 的近期 FAIR 研究

• Omnilingual ASR：面向 1600 多种语言的开源多语言语音识别
• LLM 的离线与在线强化学习桥梁
• R.I.P.：通过“适者生存”提示提升模型性能
• 学习事实性推理
• 多样化的偏好优化
• 大型概念模型：基于句子表示空间的语言建模
• Seamless：多语言富有表现力的流式语音翻译

fairseq2 与原始 fairseq 有何不同？

fairseq2 是一个从零开始的项目，可以被视为对原始 fairseq 的重新启动，旨在提供一个干净、模块化的 API。值得注意的是，它在设计理念上与其前身有所不同：从单体框架转变为可扩展、侵入性更小的架构，使研究人员能够独立掌控自己的项目代码库。

由于 fairseq2 是一个全新的项目，而非对原始 fairseq 的增量更新，我们有意未将其命名为 fairseq 2，以体现其独特且独立的身份。

特性

• 第一方配方：用于语言模型的 指令微调 和 偏好优化
• 使用 DDP、FSDP 和张量并行的多 GPU、多节点 训练，支持 70B+ 参数规模的模型。
• 原生支持 vLLM，并内置采样和束搜索序列生成器。
• 可通过 setuptools 的 扩展机制 进行扩展。无需分叉或分支库即可轻松注册新模型、优化器、学习率调度器和训练单元。
• 现代 PyTorch 工具链。采用组合性（即 torch.compile）、PyTorch FSDP 等相关特性。
• 基于流式的高吞吐量 数据管道 API，使用 C++ 编写，支持语音及（即将支持）视频解码。
• 提供程序化 资产卡片，用于版本控制下访问模型、数据集和分词器。
• 基于内置 结构化 API 的灵活但确定性的配置。

入门

请访问我们的 文档网站 以了解更多关于 fairseq2 的信息。

在 Linux 上安装

系统依赖

fairseq2 依赖于 libsndfile，该库可在大多数 Linux 发行版中通过系统包管理器安装。对于基于 Ubuntu 的系统，请运行：

sudo apt install libsndfile1

同样地，在 Fedora 上，请运行：

sudo dnf install libsndfile

对于其他 Linux 发行版，请查阅其文档以了解如何安装软件包。

pip

要在 Linux x86-64 上安装 fairseq2，请运行：

pip install fairseq2

此命令将安装一个与 PyPI 上托管的 PyTorch 兼容的 fairseq2 版本。

目前，我们尚未提供适用于 ARM 架构系统（如 Raspberry Pi 或 NVIDIA Jetson）的预编译包。请参阅 源码安装，了解如何在这些系统上构建和安装 fairseq2。

变体

除了 PyPI 之外，fairseq2 还在 FAIR 的软件包仓库中提供了针对不同 PyTorch 和 CUDA 版本的预构建包。下表展示了支持的组合。

fairseq2	PyTorch	Python	变体*	架构
HEAD	2.9.1	>=3.10, <=3.12	cpu, cu126, cu128	x86_64
	2.8.0	>=3.10, <=3.12	cpu, cu126, cu128	x86_64
	2.7.1	>=3.10, <=3.12	cpu, cu126, cu128	x86_64
0.8	2.9.1	>=3.10, <=3.12	cpu, cu126, cu128	x86_64
	2.8.0	>=3.10, <=3.12	cpu, cu126, cu128	x86_64
	2.7.1	>=3.10, <=3.12	cpu, cu126, cu128	x86_64
0.7	2.9.0	>=3.10, <=3.12	cpu, cu126, cu128	x86_64
	2.8.0	>=3.10, <=3.12	cpu, cu126, cu128	x86_64
	2.7.1	>=3.10, <=3.12	cpu, cu126, cu128	x86_64
0.6	2.8.0	>=3.10, <=3.12	cpu, cu126, cu128	x86_64
	2.7.1	>=3.10, <=3.12	cpu, cu126, cu128	x86_64
	2.6.0	>=3.10, <=3.12	cpu, cu124	x86_64

* cuXYZ 指的是 CUDA XY.Z（例如，cu118 表示 CUDA 11.8）

要安装特定的组合，请先按照 pytorch.org 上的说明为所需的 PyTorch 版本进行安装，然后使用以下命令（以 PyTorch 2.9.1 和变体 cu126 为例）：

pip install fairseq2\
  --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/pt2.9.1/cu126

[!WARNING] fairseq2 依赖于 PyTorch 的 C++ API，而不同版本之间没有 API/ABI 兼容性。这意味着你必须安装与你的 PyTorch 版本完全匹配的 fairseq2 变体。否则，你可能会遇到进程立即崩溃或随机段错误等问题。出于同样的原因，如果你升级了 PyTorch 版本，你也必须同时升级 fairseq2 的安装。

夜间构建

对于 Linux 系统，我们还在 FAIR 的软件包仓库中提供了夜间构建版本。支持的变体与上述“变体”部分列出的相同。在安装好所需的 PyTorch 版本后，你可以使用以下命令来安装对应的夜间构建包（以 PyTorch 2.9.1 和变体 cu128 为例）：

pip install fairseq2\
  --pre --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/nightly/pt2.9.1/cu128

在 macOS 上安装

系统依赖

fairseq2 依赖于 libsndfile，可以通过 Homebrew 安装：

brew install libsndfile

pip

要在基于 ARM64（即 Apple Silicon）的 Mac 计算机上安装 fairseq2，请运行：

pip install fairseq2

该命令将安装一个与 PyPI 上托管的 PyTorch 兼容的 fairseq2 版本。

目前，我们尚未提供适用于 Intel 架构 Mac 计算机的预构建包。请参阅 从源代码安装，了解如何在 Intel 机器上构建和安装 fairseq2。

变体

除了 PyPI 之外，fairseq2 还在 FAIR 的软件包仓库中提供了针对不同 PyTorch 版本的预构建包。下表展示了支持的组合。

fairseq2	PyTorch	Python	架构
HEAD	2.9.1	>=3.10, <=3.12	arm64
0.8	2.9.1	>=3.10, <=3.12	arm64
0.7	2.9.0	>=3.10, <=3.12	arm64
0.6	2.8.0	>=3.10, <=3.12	arm64
	2.7.1	>=3.10, <=3.12	arm64

要安装特定的组合，请先按照 pytorch.org 上的说明为所需的 PyTorch 版本进行安装，然后使用以下命令（以 PyTorch 2.9.1 为例）：

pip install fairseq2\
  --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/pt2.9.1/cpu

[!WARNING] fairseq2 依赖于 PyTorch 的 C++ API，而不同版本之间没有 API/ABI 兼容性。这意味着您必须安装与您的 PyTorch 版本完全匹配的 fairseq2 变体。否则，您可能会遇到进程立即崩溃或无故段错误等问题。出于同样的原因，如果您升级了 PyTorch 版本，也必须同时升级 fairseq2 的安装。

夜间构建

对于 macOS，我们还在 FAIR 的软件包仓库中托管夜间构建版本。支持的变体与上述“变体”部分列出的相同。在安装好所需的 PyTorch 版本后，您可以使用以下命令来安装对应的夜间构建包（以 PyTorch 2.9.1 为例）：

pip install fairseq2\
  --pre --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/nightly/pt2.9.1/cpu

在 Windows 上安装

fairseq2 没有对 Windows 的原生支持，并且在可预见的未来也没有计划支持。不过，您可以通过 Windows Subsystem for Linux（即 WSL），并在 WSL 2 中获得完整的 CUDA 支持来使用 fairseq2。请按照在 Linux 上安装一节中的说明进行基于 WSL 的安装。

从源代码安装

请参阅 这里。

贡献

我们始终欢迎对 fairseq2 的贡献！请参考 贡献指南，了解如何格式化、测试和提交您的工作。

引用 fairseq2

如果您在研究中使用了 fairseq2 并希望引用它，请使用以下 BibTeX 条目。

@software{balioglu2023fairseq2,
  author = {Can Balioglu and Alexander Erben and Martin Gleize and Artyom Kozhevnikov and Ilia Kulikov and Julien Yao},
  title = {fairseq2},
  url = {http://github.com/facebookresearch/fairseq2},
  year = {2023},
}

许可证

本项目采用 MIT 许可证，详情请参见 LICENSE 文件。

fairseq2 快速上手指南

fairseq2 是 Meta FAIR 推出的新一代序列建模工具包，旨在为内容生成任务提供干净、模块化且可扩展的 API。它支持大规模模型训练（70B+）、多 GPU/多节点分布式训练，并原生集成 vLLM 等现代 PyTorch 特性。

环境准备

系统要求

• 操作系统：Linux (x86_64) 或 macOS (ARM64/Apple Silicon)
  • 注：目前官方未提供 ARM Linux (如 Raspberry Pi) 和 Intel Mac 的预编译包，需从源码安装。
• Python 版本：3.10 - 3.12
• PyTorch 版本：需与 fairseq2 变体严格匹配（见下文安装说明）

前置依赖

fairseq2 依赖 libsndfile 库进行音频处理，请先通过系统包管理器安装：

Ubuntu/Debian:

sudo apt install libsndfile1

Fedora/CentOS:

sudo dnf install libsndfile

macOS (使用 Homebrew):

brew install libsndfile

安装步骤

方式一：标准安装 (推荐)

适用于大多数用户，将安装与 PyPI 上最新稳定版 PyTorch 兼容的版本。

pip install fairseq2

方式二：指定 PyTorch/CUDA 版本安装

由于 fairseq2 依赖 PyTorch 的 C++ API，必须安装与您当前 PyTorch 版本完全匹配的 fairseq2 变体，否则会导致崩溃。

1. 首先前往 pytorch.org 安装指定版本的 PyTorch。
2. 根据下表选择对应的安装命令（以 PyTorch 2.9.1 + CUDA 12.6 为例）：

pip install fairseq2 \
  --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/pt2.9.1/cu126

注意：请将 URL 中的 pt2.9.1 和 cu126 替换为您实际使用的 PyTorch 版本和 CUDA 版本。

方式三：安装夜间构建版 (Nightly)

如需体验最新功能，可安装夜间构建版：

pip install fairseq2 \
  --pre --extra-index-url https://fair.pkg.atmeta.com/fairseq2/whl/nightly/pt2.9.1/cu128

基本使用

fairseq2 的核心优势在于其模块化的数据管道和训练器。以下是一个最简化的概念示例，展示如何加载资产卡片（Asset Card）并初始化数据管道。

提示：完整的工作流（如指令微调、偏好优化）请参考官方文档中的 端到端微调教程。

1. 验证安装与查看可用资产

在终端运行以下命令，检查安装是否成功并列出可用的模型和数据集卡片：

fseq2 asset list

2. Python 代码示例

以下代码演示了如何程序化地访问模型配置并构建一个基础的数据处理流程骨架：

from fairseq2.assets import default_asset_store
from fairseq2.data import DataPipelineBuilder

# 1. 获取默认资产存储
asset_store = default_asset_store()

# 2. 查找并加载特定的模型卡片 (例如：某个 LLM 或 ASR 模型)
# 替换 'your_model_name' 为实际存在的模型卡片名称
try:
    card = asset_store.retrieve_card("your_model_name")
    print(f"找到模型配置：{card.name}")
    # 这里可以进一步加载模型权重或分词器
except Exception as e:
    print(f"未找到指定模型或加载失败：{e}")

# 3. 构建一个简单的数据管道示例
# fairseq2 使用基于流的 C++ 数据管道以实现高吞吐量
pipeline = (
    DataPipelineBuilder([1, 2, 3, 4, 5])
    .map(lambda x: x * 2)
    .and_return(max_num_warnings=0)
)

# 遍历数据
for item in pipeline:
    print(f"处理数据：{item}")

关键特性速览

• 分布式训练：原生支持 DDP, FSDP 和张量并行，无需修改大量代码即可扩展至多节点。
• 扩展机制：通过 setuptools 入口点机制，您可以注册自定义模型、优化器或学习率调度器，而无需 fork 整个库。
• 配置管理：所有模型、数据集和分词器均通过版本控制的 "Asset Cards" 进行管理，确保实验的可复现性。