huggingface / transformers

huggingface/transformers

open_in_new前往仓库

Hugging Face Transformers 是一个用于文本、视觉、音频和多模态模型推理与训练的最先进预训练模型框架，提供统一的 API 和 Pipeline 接口，支持 PyTorch、TensorFlow 和 JAX。

项目概览

项目概述

Hugging Face Transformers 是一个用于最先进机器学习模型的模型定义框架，支持文本、计算机视觉、音频、视频和多模态模型，涵盖推理和训练。它集中了模型定义，使得模型定义在生态系统中得到一致认可，并作为跨框架的枢纽，兼容大多数训练框架（如 Axolotl、Unsloth、DeepSpeed、FSDP、PyTorch-Lightning）、推理引擎（如 vLLM、SGLang、TGI）以及相邻的建模库（如 llama.cpp、mlx）。该库提供超过 100 万个模型检查点，可通过 Hugging Face Hub 使用。

核心功能

  • 统一的模型 API：提供 Pipeline 高级推理接口，支持文本生成、自动语音识别、图像分类、视觉问答等多种任务。
  • 多模态支持：涵盖文本、视觉、音频、视频和多模态模型，支持推理和训练。
  • 跨框架兼容：模型可在 PyTorch、TensorFlow 和 JAX 之间轻松迁移。
  • 丰富的预训练模型：提供超过 100 万个模型检查点，涵盖多种架构和任务。
  • 易于定制：模型内部结构尽可能一致地暴露，支持自定义模型和配置。
  • 社区与生态：拥有庞大的社区和丰富的文档，支持多语言翻译。

适用与不适用场景

适用场景：

  • 使用预训练模型进行推理和微调。
  • 研究和实验最新的模型架构。
  • 快速原型开发和部署 NLP、视觉、音频等任务。
  • 需要跨框架（PyTorch、TensorFlow、JAX）的模型迁移。

不适用场景：

  • 作为神经网络构建模块的模块化工具箱（模型文件未进行额外抽象）。
  • 通用机器学习训练循环（建议使用 Accelerate 等库）。
  • 示例脚本可能无法直接适用于特定用例，需要自行调整。

技术架构与依赖

  • 编程语言：Python 3.10+。
  • 深度学习框架：PyTorch 2.5+（必需），可选 TensorFlow、JAX。
  • 依赖库：transformers[torch] 安装时包含 PyTorch 相关依赖。
  • 模型格式：支持 GGUF 格式加载（需 gguf>=0.10.0）。
  • 量化支持：通过 bitsandbytes 支持 8-bit 和 4-bit 量化。

安装与快速开始

安装：

# 使用 pip
pip install "transformers[torch]"

# 使用 uv
uv pip install "transformers[torch]"

快速开始：

from transformers import pipeline

# 文本生成
pipe = pipeline(task="text-generation", model="Qwen/Qwen2.5-1.5B")
pipe("the secret to baking a really good cake is ")

# 自动语音识别
pipe = pipeline(task="automatic-speech-recognition", model="openai/whisper-large-v3")
pipe("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac")

# 图像分类
pipe = pipeline(task="image-classification", model="facebook/dinov2-small-imagenet1k-1-layer")
pipe("https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png")

典型使用方法

  • 聊天对话：使用 pipeline 或 AutoModelForCausalLM 与模型进行多轮对话。
  • 微调模型：使用 Trainer API 或自定义训练循环进行微调。
  • 自定义模型：通过继承 PreTrainedModel 和 PreTrainedConfig 创建自定义模型，并注册到 AutoClass。
  • 量化推理：使用 BitsAndBytesConfig 加载 8-bit 或 4-bit 量化模型。
  • GGUF 加载：通过 gguf_file 参数加载 GGUF 格式模型。

配置与部署要点

  • 环境变量：可设置 HF_HUB_CACHE、HF_HOME 等控制缓存目录。
  • 离线模式：设置 HF_HUB_OFFLINE=1 可离线使用。
  • 设备映射：使用 device_map="auto" 自动分配设备。
  • 量化配置：通过 BitsAndBytesConfig 配置量化参数。
  • 模型缓存：模型下载后缓存于本地，可复用。

限制、风险与许可证

  • 许可证：Apache-2.0。
  • 安全风险：加载模型时可能执行远程代码，建议使用 trust_remote_code=True 时谨慎，并指定 revision 固定版本。
  • 性能限制：大型模型需要大量内存和计算资源，量化可能影响精度。
  • 示例脚本：可能不适用于所有场景，需要自行调整。

官方链接

信息来源和分析时间

  • 信息来源：GitHub 仓库 README、CONTRIBUTING.md、docs/README.md、docs/TRANSLATING.md 及部分文档。
  • 分析时间：2026-08-19（基于最新 release 日期）。