Hugging Face Transformers：统一文本、视觉、音频与多模态模型的模型定义框架

Hugging Face Transformers 是一个面向文本、计算机视觉、音频、视频和多模态模型的“模型定义框架”，同时支持推理与训练。它的核心思路不是把每种模型封装成互不相干的工具，而是把模型定义集中到一处，让同一份定义在训练框架、推理引擎和相关建模库之间保持一致。对于开发者来说，这意味着学会一套 API，就能接入大量预训练模型。

项目定位：让模型定义成为生态共同语言

根据项目 README，Transformers 的定位是“state-of-the-art pretrained models for inference and training”。它把模型定义集中管理，并使其在生态中被一致认可。项目自述为“pivot across frameworks”：如果一个模型定义被 Transformers 支持，那么它就能与多数训练框架（如 Axolotl、Unsloth、DeepSpeed、FSDP、PyTorch-Lightning 等）、推理引擎（如 vLLM、SGLang、TGI 等）以及相邻建模库（如 llama.cpp、mlx 等）配合使用，这些工具会复用 Transformers 中的模型定义。

项目同时表示，会帮助支持新的前沿模型，并让其模型定义保持简单、可定制和高效，以降低使用门槛。

覆盖的任务与模型类型

README 显示，Transformers 覆盖文本、计算机视觉、音频、视频和多模态任务。Hugging Face Hub 上有超过 100 万个 Transformers 模型检查点可供使用。项目列举了各模态下的示例模型，用于说明适用范围：

• 音频：CLAP 用于音频分类；Parakeet、Whisper、GLM-ASR、Moonshine-Streaming 用于自动语音识别；Wav2Vec2 用于关键词检测；Moshi 用于语音到语音生成；MusicGen 用于文本到音频；CSM 用于文本到语音。
• 计算机视觉：SAM 用于自动掩码生成；DepthPro 用于深度估计；DINO v2 用于图像分类；SuperPoint 用于关键点检测；SuperGlue 用于关键点匹配；RT-DETRv2 用于目标检测；VitPose 用于姿态估计；OneFormer 用于通用分割；VideoMAE 用于视频分类。
• 多模态：Voxtral、Audio Flamingo 用于音频或文本到文本；LayoutLMv3 用于文档问答；Qwen-VL 用于图像或文本到文本；BLIP-2 用于图像描述；GOT-OCR2 用于基于 OCR 的文档理解；TAPAS 用于表格问答；Emu3 用于统一多模态理解与生成；Llava-OneVision 用于视觉到文本；Llava 用于视觉问答；Kosmos-2 用于视觉指代表达式分割。
• 自然语言处理：ModernBERT 用于掩码词补全；Gemma 用于命名实体识别；Mixtral 用于问答；BART 用于摘要；T5 用于翻译；Llama 用于文本生成；Qwen 用于文本分类。

使用方式：Pipeline API 与命令行

Transformers 提供了面向推理的高层类 Pipeline，支持文本、音频、视觉和多模态任务。它会处理输入预处理并返回相应输出。以文本生成为例，实例化 pipeline 并指定模型后，模型会被下载并缓存，之后可以复用；再把提示文本传入即可。聊天场景的使用模式相同，区别是需要构造用户与系统之间的聊天历史作为输入。

README 还提到，只要 transformers serve 正在运行，也可以直接从命令行与模型聊天。项目展示了自动语音识别、图像分类和视觉问答等不同模态的 Pipeline 示例，说明同一高层接口可以覆盖多种任务。

技术特点与框架选择

项目强调几个实际特点：

• 统一 API：用户面向的抽象较少，README 称只需学习三个类，即可用统一 API 使用所有预训练模型。
• 降低计算成本：通过共享已训练模型而不是从头训练，可以减少计算时间和生产成本；项目提到有数百种模型架构和超过 100 万个预训练检查点，覆盖各模态。
• 跨框架移动：可以在 PyTorch、JAX、TF2.0 之间移动同一个模型，并按训练、评估和生产的不同阶段选择合适框架。
• 可定制：项目为每种架构提供示例，以复现原论文结果；模型内部尽可能一致地暴露；模型文件可以脱离库独立使用，便于快速实验。

运行环境与安装

根据 README，Transformers 需要 Python 3.11+ 和 PyTorch 2.6+。官方建议使用 venv 或 uv 创建并激活虚拟环境，然后在虚拟环境中安装 Transformers。如果希望获取库的最新改动或参与贡献，也可以从源码安装；但 README 提醒最新版本可能不稳定，遇到错误可以提交 issue。

不适合什么场景

项目明确说明了两类不适用情况。第一，它不是神经网络模块化工具箱；模型文件中的代码有意不做额外抽象重构，以便研究者快速迭代各个模型，而不必深入额外的抽象或文件。第二，训练 API 针对 Transformers 提供的 PyTorch 模型进行了优化；对于通用机器学习循环，应使用 Accelerate 等其他库。

适用人群与社区

Transformers 面向研究者、工程师和开发者，尤其是希望以较低门槛使用前沿预训练模型、在多种模态间复用统一 API、或围绕 Hugging Face Hub 构建项目的人。项目还维护了一个 awesome-transformers 页面，列出 100 个使用 Transformers 构建的社区项目，并欢迎通过 PR 补充。

项目指标说明

该项目在 GitHub 上获得约 168,992 个 Star、35,219 个 Fork，主要语言为 Python，许可证为 Apache-2.0。Hugging Face Likes 和 Downloads 在本次资料中不适用，因此不将其与 GitHub Star 混为一谈。上述数字仅反映对应平台上的社区关注度，不代表官方排名或认证。

项目主页

GitHub 项目主页：https://github.com/huggingface/transformers

项目地址：transformers