transformers

Transformers

概述

Hugging Face Transformers 库提供了对数千种预训练模型的访问，涵盖 NLP、计算机视觉、音频和多模态领域的各种任务。使用此技能加载模型、执行推理，并使用自定义数据进行微调。

安装

已针对 transformers 5.12.0（当前 PyPI 版本；2026 年 6 月）进行测试。需要 Python 3.10+；torch 附加组件目前需要 PyTorch 2.4+。

uv pip install "transformers[torch]==5.12.0" huggingface_hub==1.19.0 datasets==5.0.0 evaluate==0.4.6 accelerate==1.14.0

对于视觉任务，请添加：

uv pip install timm==1.0.27 pillow==12.2.0

对于音频任务，请添加：

uv pip install librosa==0.11.0 soundfile==0.14.0

这些固定版本用于确保示例可复现。进行探索性工作时，只有在检查 Transformers 和 Hub 的发行说明、确认 API 没有变更后，才放宽版本限制。

检查你的版本：

import transformers
print(transformers.__version__)

身份验证

Hugging Face Hub 上的许多模型都需要授权或设为私有。加载模型前请先进行身份验证。

**推荐：**使用 CLI 登录（令牌会保存在 ~/.cache/huggingface/token 中）：

hf auth login

Python：

from huggingface_hub import login
login()  # Interactive prompt; do not hardcode tokens in scripts

**服务端 / CI：**在环境中设置 HF_TOKEN（切勿将令牌提交到 git 或 Shell 配置文件中）：

export HF_TOKEN="..."  # Read token from a secret manager, not source code

在此处获取令牌：https://huggingface.co/settings/tokens

**安全：**切勿将令牌粘贴到笔记本、代码仓库或共享配置中。优先使用 hf auth login，而不要在 .bashrc 或 .zshrc 中导出令牌。

请使用满足需求的最小令牌权限范围：下载私有或受限模型时使用 read，仅在上传时使用 write。如果长时间运行的环境不应在每次 Hub 请求中都发送已存储的令牌，请设置 HF_HUB_DISABLE_IMPLICIT_TOKEN=1，并仅在需要身份验证时传递令牌。

Transformers v5

Transformers v5 仅支持 PyTorch（已移除 TensorFlow 和 JAX 后端）。从 v4 升级时，请参阅 v5 迁移指南。新项目应搭配使用 transformers 5.x 和 huggingface_hub 1.x。

**受限模型或自定义架构：**先在 Hub 上接受模型许可协议，然后仅当模型卡要求使用自定义代码，且你已审查过该代码时，才使用 trust_remote_code=True 加载模型。

**缓存位置：**设置 HF_HOME 以指定所有 Hugging Face 缓存的位置，或设置 HF_HUB_CACHE 以仅指定 Hub 文件的缓存位置。仅当所需的模型快照已缓存后，才使用 HF_HUB_OFFLINE=1。

快速入门

使用 Pipeline API，无需手动配置即可快速执行推理：

from transformers import pipeline

# Text generation (prefer max_new_tokens for causal LMs)
generator = pipeline("text-generation", model="Qwen/Qwen2.5-1.5B")
result = generator("The future of AI is", max_new_tokens=50)

# Text classification
classifier = pipeline("text-classification")
result = classifier("This movie was excellent!")

# Question answering
qa = pipeline("question-answering")
result = qa(question="What is AI?", context="AI is artificial intelligence...")

核心功能

1. 用于快速推理的 Pipelines

适用于多种任务的简单优化推理。支持文本生成、分类、NER、问答、摘要、翻译、图像分类、目标检测、音频分类等。

适用场景：快速原型开发、简单的推理任务、无需自定义预处理。

有关完整的任务范围和优化说明，请参阅 references/pipelines.md。

2. 模型加载与管理

加载预训练模型，并精细控制配置、设备放置和精度。

适用场景：自定义模型初始化、高级设备管理、模型检查。

有关加载模式和最佳实践，请参阅 references/models.md。

3. 文本生成

使用各种解码策略（贪心、集束搜索、采样）和控制参数（temperature、top-k、top-p）通过 LLM 生成文本。

适用场景：创意文本生成、代码生成、对话式 AI、文本补全。

有关生成策略和参数，请参阅 references/generation.md。

4. 训练与微调

使用 Trainer API 在自定义数据集上微调预训练模型，并支持自动混合精度、分布式训练和日志记录。

适用场景：针对特定任务调整模型、领域适配、提升模型性能。

有关训练工作流和最佳实践，请参阅 references/training.md。

5. 分词

将文本转换为模型输入所需的词元和词元 ID，并处理填充、截断和特殊词元。

使用场景：自定义预处理流水线、了解模型输入、批处理。

有关分词的详细信息，请参阅 references/tokenizers.md。

常见模式

模式 1：简单推理

对于简单任务，请使用流水线：

pipe = pipeline("task-name", model="model-id")
output = pipe(input_data)

模式 2：自定义模型用法

如需更精细的控制，请分别加载模型和分词器：

from transformers import AutoModelForCausalLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("model-id")
model = AutoModelForCausalLM.from_pretrained("model-id", device_map="auto")

inputs = tokenizer("text", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=100)
result = tokenizer.decode(outputs[0])

模式 3：微调

如需适配任务，请使用 Trainer：

from transformers import Trainer, TrainingArguments

training_args = TrainingArguments(
    output_dir="./results",
    num_train_epochs=3,
    per_device_train_batch_size=8,
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
)

trainer.train()

参考文档

有关特定组件的详细信息：

• 流水线：references/pipelines.md - 所有支持的任务和优化
• 模型：references/models.md - 加载、保存和配置
• 生成：references/generation.md - 文本生成策略和参数
• 训练：references/training.md - 使用 Trainer API 进行微调
• 分词器：references/tokenizers.md - 分词和预处理

Agent 操作流程

1. 检查环境。 确认 Python 环境和库版本（python -c "import pkg; print(pkg.__version__)"），并检查数据的形状、类型和缺失值。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问确认，而非猜测。
3. 先运行小规模版本。 先在样本或单个折上运行，并检查运行时间和内存。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 使用留出数据、固定随机种子和合适的指标；检查是否存在数据泄漏；报告不确定性（置信区间、不同随机种子的标准差）。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些内容仍不确定。

如果发生这种情况	请这样做
内存不足或执行非常缓慢	对数据进行子采样，使用分块或惰性计算，或缩小模型规模，并告知用户所做的更改。
当前安装版本中缺少这些说明里的函数、标志或端点	查阅已安装版本自带的文档（help()、--help、官方文档），调整用法并告知用户。切勿编造 API。
必需的输入、标识符或参数有歧义	询问用户，或在运行前明确说明假设。

诚信准则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请如实说明。
• 切勿报告本次会话中未计算的指标；应展示生成每个数字的代码路径。
• 此处的版本特定细节可能已经过时：请根据已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，必须事先征求同意。

相关技能

• axolotl：提供使用 Axolotl 微调大语言模型的指导，涵盖 YAML 训练配置、LoRA 和 QLoRA、偏好训练 w…
• unsloth：提供使用 Unsloth 微调大语言模型的指导。Unsloth 是一个用于通过 LoRA 和 QLoRA 加速训练、降低内存占用的库，基…
• huggingface-tokenizers：提供 HuggingFace Tokenizers 库（基于 Rust 核心，并提供 Python 和 Node.js 绑定），用于训练和使用 BPE、WordPiece 和 Unigram…