如何使用 Hugging Face Transformers：2026 完整指南
2026-06-09 · jilo.ai SEO
学习如何在2026年使用 Hugging Face Transformers：涵盖管道、分词器、微调、部署、评估与实用工作流。
# 如何使用 Hugging Face Transformers：2026 完整指南
Hugging Face Transformers 是现代人工智能开发中最重要的开源库之一。如果你想使用预训练语言模型、构建文本分类器、总结文档、翻译文本、运行问答系统、在自己的数据集上微调模型，或快速原型化生成式 AI 功能，Transformers 通常是最实用的起点之一。
本文会从基础到实战系统讲解如何使用 Hugging Face Transformers。内容包括安装、核心概念、pipeline 管道、tokenizer 分词器、模型加载、数据集、训练、评估、推理、优化和部署。它面向开发者、数据科学家、技术创业者、产品构建者，以及希望真正理解模型工作流的进阶 AI 用户。
读完之后，你不只会知道如何运行一个模型，还会理解各个部分如何配合：为什么 tokenizer 很重要，模型 checkpoint 如何加载，什么时候使用 pipeline，什么时候编写自定义代码，如何安全微调，以及如何在 2026 年为真实应用选择合适模型。
## 什么是 Hugging Face Transformers？
Hugging Face Transformers 是一个 Python 库，为使用 transformer 架构的机器学习模型提供统一接口。它支持许多模型家族和任务，包括文本分类、文本生成、摘要、翻译、词元分类、问答、图像分类、语音识别、多模态模型等。
这个库与 Hugging Face Hub 紧密关联。Hub 是模型 checkpoint、数据集、演示和配置文件的集中仓库。当你加载一个情感分析模型或文本生成模型时，Transformers 可以自动下载相关文件，缓存在本地，并提供一致的 Python API。
它的核心价值是标准化。你不需要为每种模型架构学习完全不同的加载方式，很多时候可以使用同一套流程：
1. 选择一个预训练模型 checkpoint。
2. 加载 tokenizer 或 processor。
3. 加载模型。
4. 准备输入。
5. 执行推理或训练。
6. 解码或后处理输出。
这种统一流程让 Transformers 既适合实验，也适合构建生产系统。
## 为什么 2026 年仍然值得学习 Transformers？
到 2026 年，AI 开发已经不再只属于大型研究实验室。开发者会经常组合托管 API、开源模型、本地推理、检索系统、自动化工具和应用框架。Hugging Face Transformers 仍然非常有价值，因为它让你直接控制模型和数据。
托管工具在需要快速落地和托管基础设施时非常方便。例如，[Poe](/zh/tools/poe) 适合探索不同聊天机器人，[DeepSeek](/zh/tools/deepseek) 提供易访问的 AI 模型体验，[Writer](/zh/tools/writer-ai) 更关注企业写作工作流。但当你需要检查模型输入、微调行为、控制推理成本、本地运行模型，或构建自定义机器学习管道时，Transformers 提供的是更底层、更可控的基础。
它也能很好地融入开发工具链。你可以用 [Cursor](/zh/tools/cursor) 编写和重构模型代码，用 [v0](/zh/tools/v0) 原型化界面，用 [Zapier](/zh/tools/zapier) 将模型输出连接到业务流程。Transformers 并不是这些工具的替代品，而是可以在它们背后提供自定义 AI 行为的模型层。
## Transformers 总览
| 领域 | Transformers 提供什么 | 为什么重要 |
|---|---|---|
| 预训练模型 | 统一加载大量 checkpoint | 不必从零训练模型 |
| Tokenizer | 将文本快速转换为模型输入 | 推理和训练的基础 |
| Pipeline | 高层任务 API | 用很少代码快速原型化 |
| Trainer API | 训练和微调工具 | 简化常见训练循环 |
| 模型类 | 架构相关类和自动加载类 | 支持自定义推理和高级控制 |
| Hub 集成 | 下载、缓存和分享模型 | 提升可复现性和分发效率 |
| 多模态支持 | 文本、图像、音频和视觉语言任务 | 适合现代 AI 应用 |
| 优化支持 | 量化、设备映射和加速选项 | 更高效运行大模型 |
## 必须理解的核心概念
在写代码之前，先理解几个会反复出现的对象。
### 模型 Checkpoint
模型 checkpoint 是保存好的模型权重和配置文件。它通常代表一个已经预训练或针对特定任务微调过的模型。
例如，一个 checkpoint 可能是：
- 用于文本生成的通用语言模型。
- 针对情感分类微调过的 BERT 类模型。
- 用于摘要的 T5 类模型。
- 用于命名实体识别的词元分类模型。
- 用于图像分类的视觉 transformer。
当你通过 Transformers 加载 checkpoint 时，库会读取模型配置，并在你使用合适的 Auto 类时自动构建匹配架构。
### Tokenizer 分词器
机器学习模型不能像人一样直接读取文本。它们读取数字。Tokenizer 会把原始文本转换成 token ID、attention mask，有时还会生成其他输入。
例如：
```text
Transformers are useful.
```
可能会被转换成一串整数 ID。具体 ID 取决于 checkpoint 使用的 tokenizer。因此，几乎总是应该加载与模型 checkpoint 配套的 tokenizer。
Tokenizer 负责：
- 将文本拆分为 token 或子词。
- 将 token 映射为整数 ID。
- 添加特殊 token。
- 对 batch 进行 padding。
- 截断过长输入。
- 创建 attention mask。
初学者常犯的错误是把模型和不匹配的 tokenizer 混用。这可能导致结果很差或运行时报错。
### 模型
模型就是神经网络本身。在 Transformers 中，你可以通过任务专用类或 Auto 类加载模型。
常见 Auto 类包括：
| 类 | 典型用途 |
|---|---|
| `AutoModel` | 加载没有任务头的基础模型 |
| `AutoModelForSequenceClassification` | 情感分析、主题分类、意图识别 |
| `AutoModelForTokenClassification` | 命名实体识别、词元标注 |
| `AutoModelForQuestionAnswering` | 抽取式问答 |
| `AutoModelForCausalLM` | 自回归文本生成 |
| `AutoModelForSeq2SeqLM` | 翻译、摘要、序列到序列生成 |
| `AutoTokenizer` | 自动加载匹配 tokenizer |
| `AutoProcessor` | 加载多模态模型 processor |
Auto 类通常是最好的起点，因为它们能从 checkpoint 配置推断正确架构。
### Pipeline 管道
Pipeline 是常见任务的高层封装。它把 tokenization、模型推理和输出格式化组合成一个简单函数。
例如，情感分析 pipeline 可以接受一个字符串并返回标签和分数。你不需要手动 tokenize 输入或解码输出。
Pipeline 非常适合：
- 学习库的基本用法。
- 快速原型化。
- 用很少代码运行常见任务。
- 在写自定义逻辑前测试模型是否有用。
但在以下场景中不太理想：
- 需要极致性能优化。
- 需要复杂 batching 逻辑。
- 需要自定义 loss。
- 需要自定义后处理。
- 需要细粒度控制生成参数。
### Datasets 数据集
Hugging Face 还提供 Datasets 库，通常和 Transformers 一起使用。它可以加载、处理、切分、map、缓存和流式读取数据集。对于微调任务，Datasets 与 tokenizer 和 Trainer API 配合很好，能节省大量时间。
### Trainer
Trainer API 为许多监督学习任务提供便利训练循环。它处理 batching、优化、日志、评估、checkpoint 保存、梯度累积、混合精度和分布式训练选项。
你当然可以写自定义 PyTorch 训练循环，有时也应该这样做。但对于很多标准微调任务，Trainer 是非常务实的选择。
## 安装与环境设置
最简单的安装方式是 pip。
```bash
pip install transformers
```
很多真实项目还需要配套库：
```bash
pip install transformers datasets evaluate accelerate torch
```
根据任务不同，你可能还需要安装用于 tokenization、量化、音频、图像处理或特定硬件加速的库。
### 推荐项目结构
清晰的项目结构能避免实验代码混乱。
```text
my-transformers-project/
data/
notebooks/
src/
inference.py
train.py
evaluate.py
models/
requirements.txt
README.md
```
小型原型可以使用 notebook。面向生产的工作流应把代码放在脚本或模块中，把 notebook 当作探索工具。
### CPU 与 GPU
Transformers 可以在 CPU 上运行，但许多模型没有加速会很慢。小模型或简单分类任务在 CPU 上可以接受。大语言模型、文本生成、微调和批处理通常更适合 GPU。
在 PyTorch 中可以这样检查 GPU：
```python
import torch
print(torch.cuda.is_available())
```
如果返回 `True`，就可以把模型和 tensor 移到 CUDA。Transformers pipeline 也支持设备设置。
## 第一个 Pipeline：情感分析
使用 Transformers 最简单的方式是 pipeline。
```python
from transformers import pipeline
classifier = pipeline("sentiment-analysis")
result = classifier("Hugging Face Transformers makes model prototyping surprisingly approachable.")
print(result)
```
典型输出是包含标签和分数的字典列表。
```python
[{'label': 'POSITIVE', 'score': 0.999}]
```
实际输出取决于库版本和默认模型。生产代码中应该显式指定模型，而不是依赖默认值。
```python
from transformers import pipeline
classifier = pipeline(
"sentiment-analysis",
model="distilbert-base-uncased-finetuned-sst-2-english"
)
texts = [
"The setup was smooth and the model worked immediately.",
"The output was confusing and not useful for our task."
]
print(classifier(texts))
```
### 为什么要显式指定模型名
显式指定模型名可以提升可复现性。如果未来库版本改变默认模型，项目行为可能意外变化。明确 checkpoint 也能让团队成员更容易理解系统依赖。
## 常见 Pipeline 任务
Transformers 支持许多 pipeline 任务。具体任务集合会演进，但以下是常见类型。
| 任务 | Pipeline 名称 | 输入 | 输出 | 常见用途 |
|---|---|---|---|---|
| 情感分析 | `sentiment-analysis` | 文本 | 标签和分数 | 评论、工单、反馈分流 |
| 文本分类 | `text-classification` | 文本 | 类别标签 | 意图识别、路由、审核辅助 |
| 词元分类 | `token-classification` | 文本 | 实体片段 | 命名实体识别、信息抽取 |
| 问答 | `question-answering` | 问题和上下文 | 答案片段 | 文档搜索、FAQ 抽取 |
| 摘要 | `summarization` | 长文本 | 短文本 | 报告、文章、转录稿 |
| 翻译 | `translation` | 文本 | 翻译文本 | 多语言内容流程 |
| 文本生成 | `text-generation` | 提示词 | 生成续写 | 草稿、聊天原型、创意生成 |
| 填空 | `fill-mask` | 带 mask 的文本 | token 预测 | 语言模型演示 |
| 图像分类 | `image-classification` | 图像 | 标签和分数 | 视觉分类 |
| 语音识别 | `automatic-speech-recognition` | 音频 | 转录文本 | 会议纪要、媒体索引 |
Pipeline 特别适合快速比较任务，然后再决定是否投入微调。
## 分步教程：使用 Pipeline 做文本分类
下面构建一个用于客户消息分类的简单流程。
### 第 1 步：安装依赖
```bash
pip install transformers torch
```
### 第 2 步：创建分类器
```python
from transformers import pipeline
classifier = pipeline(
"zero-shot-classification",
model="facebook/bart-large-mnli"
)
```
零样本分类允许你在推理时提供候选标签。当你还没有标注数据时，这非常有用。
### 第 3 步：定义标签
```python
labels = ["billing", "technical support", "sales", "cancellation"]
```
### 第 4 步：分类消息
```python
message = "I was charged twice this month and need help fixing my invoice."
result = classifier(message, candidate_labels=labels)
print(result)
```
### 第 5 步：谨慎解释结果
零样本标签不是绝对真相。模型会基于学到的语言理解对候选标签排序。用于生产决策前，应使用真实样本测试并定义置信度阈值。
### 什么时候用零样本分类
| 适合零样本 | 更适合微调 |
|---|---|
| 需要快速原型 | 已有标注样本 |
| 标签经常变化 | 标签稳定且高频 |
| 准确性要求中等 | 准确性要求严格 |
| 正在探索分类体系 | 需要可预测生产行为 |
| 暂时不能训练 | 可以系统评估和再训练 |
## 分步教程：命名实体识别
命名实体识别，即 NER，用来识别文本中的人物、组织、地点、日期和产品名等实体。
### 第 1 步：加载词元分类 Pipeline
```python
from transformers import pipeline
ner = pipeline(
"token-classification",
model="dslim/bert-base-NER",
aggregation_strategy="simple"
)
```
`aggregation_strategy` 会把子词 token 合并成更可读的实体片段。
### 第 2 步：运行实体抽取
```python
text = "Sarah Chen visited Berlin to meet engineers from Acme Robotics."
entities = ner(text)
for entity in entities:
print(entity)
```
### 第 3 步：在应用中使用实体
实体抽取可以用于：
- 标记支持工单。
- 填充 CRM 字段。
- 检测被提到的产品。
- 构建搜索过滤器。
- 在审核后辅助脱敏敏感文本。
NER 系统需要谨慎评估，因为不同领域的实体定义不同。通用 NER 模型可能无法识别你的产品名、内部代码、法律术语或医学术语。
## 分步教程：问答
抽取式问答会在给定上下文中寻找答案片段。
```python
from transformers import pipeline
qa = pipeline("question-answering")
context = "Transformers provides pipelines, tokenizers, model classes, and training utilities for machine learning workflows."
question = "What does Transformers provide?"
answer = qa(question=question, context=context)
print(answer)
```
这种 QA 不会凭空发明答案，而是从上下文中抽取。因此它适合受约束应用，但也意味着答案必须存在于文本里。
### 抽取式 QA 与生成式 QA
| 维度 | 抽取式 QA | 生成式 QA |
|---|---|---|
| 输出 | 源文本中的片段 | 新生成答案 |
| 优势 | 基于给定上下文 | 灵活、对话感强 |
| 风险 | 答案隐含时可能失败 | 约束不足时可能幻觉 |
| 模型类型 | 常见为 encoder 模型 | 常见为 decoder 或 encoder-decoder |
| 最适合 | 文档查找、合规敏感回答 | 助手、解释、综合回答 |
## 分步教程：摘要
摘要是 Transformers 最常见的实际用途之一。
```python
from transformers import pipeline
summarizer = pipeline(
"summarization",
model="facebook/bart-large-cnn"
)
article = """
Hugging Face Transformers is a Python library for working with pretrained models.
It supports many tasks, including classification, summarization, translation, and generation.
Developers use it to prototype AI features, fine-tune models, and run inference in custom applications.
"""
summary = summarizer(article, max_length=60, min_length=20, do_sample=False)
print(summary)
```
### 实用摘要技巧
摘要质量取决于输入长度、模型训练数据、解码设置和领域匹配。新闻摘要模型未必适合支持工单或法律合同。对于长文档，通常需要分块。
简单分块策略：
1. 将文档拆成多个部分。
2. 分别总结每个部分。
3. 合并各部分摘要。
4. 如有需要，再总结合并后的摘要。
5. 保留对原文来源的引用以便核查。
不要在没有审核的情况下把生成摘要当作法律、医疗或财务可靠结论。模型可能遗漏重要细节，也可能过度强调次要信息。
## 分步教程：文本生成
文本生成使用语言模型继续或回应提示词。
```python
from transformers import pipeline
generator = pipeline(
"text-generation",
model="gpt2"
)
prompt = "In practical machine learning projects, evaluation matters because"
outputs = generator(
prompt,
max_new_tokens=60,
do_sample=True,
temperature=0.7,
top_p=0.9
)
print(outputs[0]["generated_text"])
```
### 理解生成参数
| 参数 | 作用 | 实用建议 |
|---|---|---|
| `max_new_tokens` | 限制生成长度 | 控制成本和延迟 |
| `do_sample` | 启用概率采样 | 用于创意或多样输出 |
| `temperature` | 控制随机性 | 越低越聚焦，越高越多样 |
| `top_p` | nucleus sampling 阈值 | 常用于避免低概率噪声 |
| `top_k` | 限制下一 token 候选 | 可让输出更受约束 |
| `repetition_penalty` | 抑制重复 | 模型循环时有用 |
| `num_beams` | 使用 beam search | 适合翻译或摘要，不一定适合创意文本 |
对于确定性工作流，可以在合适情况下设置 `do_sample=False`。对于创意草稿，使用采样并结合领域样本调参。
## 直接使用 Tokenizer
Pipeline 会隐藏 tokenization，这很方便。但你最终会需要直接使用 tokenizer。
```python
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("distilbert-base-uncased")
encoded = tokenizer(
"Transformers converts text into token IDs.",
padding=True,
truncation=True,
return_tensors="pt"
)
print(encoded)
```
结果通常包括：
- `input_ids`：token ID。
- `attention_mask`：哪些 token 是真实内容，哪些是 padding。
- 有时包括 `token_type_ids`：成对输入的 segment ID，取决于模型架构。
### Padding 与 Truncation
模型通常要求 batch 具有一致 tensor 形状。Padding 会给较短样本添加额外 token，使其与较长样本长度一致。Truncation 会截断超过模型最大长度的样本。
```python
batch = tokenizer(
["Short text.", "This is a slightly longer piece of text."],
padding=True,
truncation=True,
max_length=128,
return_tensors="pt"
)
```
一定要理解截断。如果重要信息出现在最大长度之后，模型根本看不到它。
## 直接加载模型
直接加载模型比 pipeline 提供更多控制。
```python
import torch
from transformers import AutoTokenizer, AutoModelForSequenceClassification
checkpoint = "distilbert-base-uncased-finetuned-sst-2-english"
tokenizer = AutoTokenizer.from_pretrained(checkpoint)
model = AutoModelForSequenceClassification.from_pretrained(checkpoint)
inputs = tokenizer(
"The documentation is clear and practical.",
return_tensors="pt"
)
with torch.no_grad():
outputs = model(**inputs)
logits = outputs.logits
predicted_class_id = logits.argmax().item()
print(model.config.id2label[predicted_class_id])
```
这种方式能访问 logits、标签、可选 hidden states 以及其他模型特定输出。它更适合需要自定义 batching、指标或业务逻辑的生产代码。
## Pipeline 与直接模型调用对比
| 选择 | 最适合 | 优势 | 代价 |
|---|---|---|---|
| Pipeline | 原型和常见任务 | 快速、简洁、处理预处理和后处理 | 灵活性较低 |
| 直接模型调用 | 自定义应用 | 完全控制输入、输出、batching 和设备 | 代码更多 |
| Trainer API | 标准微调 | 处理大量训练工作流 | 不如自定义循环灵活 |
| 自定义 PyTorch 循环 | 研究或特殊训练 | 最大控制力 | 维护成本更高，错误空间更大 |
实用模式是：先用 pipeline 验证想法，任务清晰后转向直接模型调用，只有当评估显示需要时才微调或优化。
## 如何选择合适模型
模型选择是 Transformers 项目中最重要的决策之一。更大并不一定更好。最佳模型取决于任务、延迟、成本、语言、领域、硬件、许可证和评估结果。
### 模型选择标准
| 标准 | 应该问的问题 |
|---|---|
| 任务匹配 | 这个模型是否为你的任务设计或微调？ |
| 语言覆盖 | 是否支持用户实际使用的语言？ |
| 上下文长度 | 是否能处理输入长度而不丢失关键信息？ |
| 延迟 | 是否足够快以满足用户体验？ |
| 硬件 | 能否在你的 CPU、GPU 或加速器上运行？ |
| 许可证 | 是否允许用于你的目标场景？ |
| 质量 | 在你自己的评估样本上表现如何？ |
| 维护性 | 是否有文档，社区是否仍在使用？ |
### 小模型与大模型
| 模型大小 | 优势 | 弱点 | 适用场景 |
|---|---|---|---|
| 小模型 | 快、便宜、易部署 | 推理和生成能力较弱 | 分类、抽取、边缘推理 |
| 中等模型 | 质量更好且仍可管理 | 通常需要 GPU 才足够快 | 摘要、领域分类器、内部工具 |
| 大模型 | 生成和推理更强 | 成本高、速度慢、托管难 | 复杂助手、综合分析、高级生成 |
对于许多业务任务，一个较小的微调模型可能在成本、速度和稳定性上优于更大的通用模型。务必用自己的样本评估。
## 使用 Transformers 微调模型
微调会把预训练模型适配到你的数据集。你不是从零训练，而是从已经学到语言模式的模型开始，再针对你的任务更新参数。
微调适合：
- 有标注样本。
- prompting 或零样本分类不够稳定。
- 需要比大型托管模型更低的延迟。
- 领域词汇特殊。
- 需要窄任务上的可预测输出。
微调不是魔法。糟糕标签、不一致定义、数据泄漏和薄弱评估，都可能产生在 notebook 中看似不错、生产中失败的模型。
## 分步教程：微调文本分类器
下面展示监督分类微调工作流的结构。你可以把它改成自己的数据集。
### 第 1 步：安装库
```bash
pip install transformers datasets evaluate accelerate torch
```
### 第 2 步：加载数据集
```python
from datasets import load_dataset
dataset = load_dataset("imdb")
```
IMDb 数据集常用于情感分类示例。你自己的项目可能从 CSV、JSON、Parquet 或内部系统加载数据。
```python
from datasets import load_dataset
data_files = {
"train": "data/train.csv",
"validation": "data/validation.csv"
}
dataset = load_dataset("csv", data_files=data_files)
```
典型 CSV 可能包含 `text` 和 `label` 列。
### 第 3 步：加载 Tokenizer
```python
from transformers import AutoTokenizer
checkpoint = "distilbert-base-uncased"
tokenizer = AutoTokenizer.from_pretrained(checkpoint)
```
### 第 4 步：Tokenize 数据集
```python
def tokenize_function(examples):
return tokenizer(
examples["text"],
padding="max_length",
truncation=True,
max_length=256
)
tokenized_dataset = dataset.map(tokenize_function, batched=True)
```
为了提升效率，可以使用 data collator 做动态 padding，而不是把所有样本 padding 到固定最大长度。
### 第 5 步：准备标签
标签应是数字 ID。如果原始数据使用 `positive` 和 `negative` 这样的字符串，应一致映射。
```python
label2id = {"negative": 0, "positive": 1}
id2label = {0: "negative", 1: "positive"}
```
### 第 6 步：加载模型
```python
from transformers import AutoModelForSequenceClassification
model = AutoModelForSequenceClassification.from_pretrained(
checkpoint,
num_labels=2,
id2label=id2label,
label2id=label2id
)
```
### 第 7 步：定义指标
```python
import evaluate
import numpy as np
accuracy = evaluate.load("accuracy")
def compute_metrics(eval_pred):
logits, labels = eval_pred
predictions = np.argmax(logits, axis=-1)
return accuracy.compute(predictions=predictions, references=labels)
```
Accuracy 容易理解，但对类别不均衡数据可能不够。可以考虑 precision、recall、F1、混淆矩阵和人工错误分析。
### 第 8 步：配置训练
```python
from transformers import TrainingArguments
training_args = TrainingArguments(
output_dir="models/sentiment-classifier",
eval_strategy="epoch",
save_strategy="epoch",
learning_rate=2e-5,
per_device_train_batch_size=16,
per_device_eval_batch_size=16,
num_train_epochs=3,
weight_decay=0.01,
load_best_model_at_end=True
)
```
参数名可能随版本演进。如果出现参数错误，请检查已安装的 Transformers 版本。
### 第 9 步：训练
```python
from transformers import Trainer, DataCollatorWithPadding
data_collator = DataCollatorWithPadding(tokenizer=tokenizer)
trainer = Trainer(
model=model,
args=training_args,
train_dataset=tokenized_dataset["train"],
eval_dataset=tokenized_dataset["test"],
tokenizer=tokenizer,
data_collator=data_collator,
compute_metrics=compute_metrics
)
trainer.train()
```
### 第 10 步：保存并加载微调模型
```python
trainer.save_model("models/sentiment-classifier-final")
tokenizer.save_pretrained("models/sentiment-classifier-final")
```
之后这样加载：
```python
from transformers import pipeline
classifier = pipeline(
"text-classification",
model="models/sentiment-classifier-final",
tokenizer="models/sentiment-classifier-final"
)
```
## 微调检查清单
| 步骤 | 检查什么 | 为什么重要 |
|---|---|---|
| 标签定义 | 标签是否清晰一致 | 模糊标签会训练出模糊行为 |
| 训练验证切分 | 样本是否没有跨集合泄漏 | 泄漏会造成误导性评估 |
| Token 长度 | 重要文本是否未被截断 | 截断可能隐藏信号 |
| 基线 | 是否与简单基线比较 | 防止过度工程化 |
| 指标 | 指标是否适合业务问题 | Accuracy 可能误导 |
| 错误分析 | 是否人工查看错误预测 | 揭示数据和分类体系问题 |
| 版本管理 | 是否保存模型、tokenizer、代码和数据版本 | 支持复现 |
## 使用你自己的数据集
数据集通常比模型选择更重要。干净、有代表性的数据能让一个普通模型变得有用。噪声数据会让强模型也不可靠。
### 推荐数据格式
分类任务：
```csv
text,label
The invoice is incorrect,billing
The app crashes when I log in,technical_support
I want to upgrade my subscription,sales
```
摘要任务：
```csv
document,summary
Long document text here,Human-written summary here
```
问答任务通常需要 context、question 和 answer span。指令微调可能需要 instruction、input 和 output 字段。
### 数据质量问题
训练前请确认：
- 标签是否一致？
- 样本是否匹配真实用户输入？
- 训练和验证之间是否有重复？
- 敏感字段是否被删除或妥善处理？
- 少数类别是否足够用于评估？
- 这个任务是否真的能从输入文本中学到？
模型无法可靠推断输入中不存在或标签不一致的信息。
## 评估：如何判断模型是否有效
评估应在部署前设计好。不要只依赖微调结束时打印的训练指标。
### 评估方法
| 方法 | 能说明什么 | 局限 |
|---|---|---|
| Accuracy | 整体正确率 | 不适合类别不均衡 |
| Precision | 正预测中有多少是正确的 | 不显示漏掉的正例 |
| Recall | 找到了多少真实正例 | 不单独显示误报 |
| F1 | 平衡 precision 和 recall | 可能隐藏类别问题 |
| 混淆矩阵 | 哪些标签容易混淆 | 需要解释 |
| 人工审核 | 真实质量和可用性 | 更慢且主观 |
| 延迟测试 | 预期负载下速度 | 依赖环境 |
| 回归集 | 更新是否破坏已知案例 | 需要维护 |
### 构建小型评估集
即使是小型人工审核评估集，也比猜测好。应包含常见样本、边界案例、对抗性表达、短输入、长输入、多语言样本以及应被拒绝或标记的样本。
对于生成模型，应评估事实性、格式、安全性、完整性和有用性。自动指标有帮助，但人工审核通常不可少。
## 推理性能与优化
模型有效之后，下一个挑战是高效运行。
### 实用性能杠杆
| 杠杆 | 效果 | 备注 |
|---|---|---|
| 更小模型 | 降低延迟和内存 | 可能降低质量 |
| Batching | 提高吞吐 | 可能增加单请求延迟 |
| GPU 推理 | 多数工作负载更快 | 需要兼容环境 |
| 量化 | 降低内存 | 可能影响质量 |
| 最大 token 限制 | 控制生成时间 | 对可预测成本很重要 |
| 缓存 | 避免重复计算 | 适合重复输入 |
| 蒸馏 | 小模型模仿大模型 | 需要额外训练流程 |
### 推理时使用 `torch.no_grad()`
不训练时应关闭梯度跟踪。
```python
with torch.no_grad():
outputs = model(**inputs)
```
这样能减少内存使用并提高推理效率。
### 批量处理输入
不要每条文本单独调用模型，可以批量处理。
```python
texts = ["First text", "Second text", "Third text"]
inputs = tokenizer(texts, padding=True, truncation=True, return_tensors="pt")
with torch.no_grad():
outputs = model(**inputs)
```
Batch size 应根据硬件和延迟目标调优。
## 部署选项
部署 Transformers 模型有多种方式。
| 部署方式 | 最适合 | 代价 |
|---|---|---|
| 本地脚本 | 批处理任务、内部自动化 | 简单但不是服务 |
| Web API | 应用集成 | 需要可靠性和监控 |
| Serverless 函数 | 偶发轻量推理 | 冷启动和模型大小可能麻烦 |
| 专用 GPU 服务 | 低延迟或高吞吐推理 | 运维工作更多 |
| 边缘或端侧 | 隐私和离线使用 | 需要小型优化模型 |
| 托管推理平台 | 快速部署 | 基础设施控制较少 |
典型 Web API 会把 tokenization 和模型推理封装在 endpoint 后面。严肃使用时，应添加请求校验、输入长度限制、日志、超时、模型版本和监控。
## 围绕 Transformers 构建应用
Transformers 很少独立构成完整产品。它通常处在更大的工作流中。
例如：
- 支持工单分流系统可以分类来信，并通过 [Zapier](/zh/tools/zapier) 发送到正确队列。
- 编码助手流程可以在你构建和测试推理服务时使用 [Cursor](/zh/tools/cursor)。
- 原型界面可以用 [v0](/zh/tools/v0) 生成或草拟，再连接到 Transformers 后端。
- 内容工作流可以把自定义摘要器与 [Writer](/zh/tools/writer-ai) 等写作平台比较。
- 创意产品可能把文本模型与 [Canva](/zh/tools/canva)、[Midjourney](/zh/tools/midjourney)、[Luma AI](/zh/tools/luma-ai) 或 [Pika](/zh/tools/pika) 等视觉工具结合，具体取决于媒体格式。
- 强品牌项目可以使用 [Looka](/zh/tools/looka) 探索品牌识别，同时由 Transformers 在后台处理分类或文案分析。
实用结论很简单：当你需要模型层控制时使用 Transformers。当某个专用工具能更快解决产品、设计、自动化或工作流问题时，就使用专用工具。
## Hugging Face Transformers 与相邻 AI 工具对比
| 工具 | 定价层级 | 主要优势 | 与 Transformers 的关系 |
|---|---|---|---|
| Hugging Face Transformers | 开源库 | 自定义模型推理和微调 | 核心模型开发层 |
| [Cursor](/zh/tools/cursor) | Freemium，当前价格请查看官网 | AI 辅助编程 | 帮助编写、调试和重构 Transformers 代码 |
| [DeepSeek](/zh/tools/deepseek) | Free，当前价格请查看官网 | AI 模型访问和聊天体验 | 适合模型交互，不专注本地自定义管道 |
| [Poe](/zh/tools/poe) | Freemium，当前价格请查看官网 | 访问多个 AI 机器人 | 适合探索和比较，不是微调库 |
| [Writer](/zh/tools/writer-ai) | Paid，当前价格请查看官网 | 企业写作和品牌内容控制 | 产品化写作流程，而不是底层模型代码 |
| [Zapier](/zh/tools/zapier) | Freemium，当前价格请查看官网 | 工作流自动化 | 可将 Transformers 服务输出路由到业务应用 |
| [v0](/zh/tools/v0) | Freemium，当前价格请查看官网 | Web 应用 UI 生成 | 可帮助原型化模型工具前端 |
| [Canva](/zh/tools/canva) | Freemium，当前价格请查看官网 | 设计和内容创作 | 在营销和内容流程中补充文本模型 |
| [Midjourney](/zh/tools/midjourney) | Paid，当前价格请查看官网 | 图像生成 | 相邻创意工具，不是 Transformers 训练流程 |
| [Looka](/zh/tools/looka) | Paid，当前价格请查看官网 | Logo 和品牌识别生成 | 用于品牌，不用于模型工程 |
## 常见项目模式
### 模式 1：分类服务
使用微调过的序列分类模型为输入打标签。适合工单路由、内容分类、意图识别和审核辅助。
架构：
1. 用户或系统提交文本。
2. API 校验长度和格式。
3. Tokenizer 准备输入。
4. 模型预测标签概率。
5. 业务逻辑应用阈值。
6. 结果被存储、展示或路由。
### 模式 2：检索加生成
Transformers 可以成为检索增强生成系统的一部分。在这种模式中，搜索层找到相关文档，生成模型基于上下文写出答案。
重要防护：
- 保留检索来源以便检查。
- 准确性重要时，将答案限制在检索上下文中。
- 上下文不足时添加拒答行为。
- 使用真实用户问题评估。
### 模式 3：批量摘要
批量摘要应异步处理文档，而不是阻塞用户请求。
流程：
1. 收集文档。
2. 将长文档拆成块。
3. 总结每个块。
4. 合并摘要。
5. 将输出与来源引用一起存储。
6. 必要时发送给人工审核。
### 模式 4：实体抽取管道
NER 和词元分类可以把非结构化文本转换成结构化字段。
用途包括：
- 从销售备注中抽取公司名。
- 在评论中识别产品提及。
- 在物流消息中检测日期和地点。
- 通过标记敏感术语辅助合规审核。
## 常见错误排查
### 模型和 Tokenizer 不匹配
症状：结果很差、shape 错误、特殊 token 异常或警告。
修复：除非有明确原因并了解兼容限制，否则从同一 checkpoint 加载 tokenizer 和模型。
### 输入过长
症状：截断警告或输出缺少信息。
修复：设置 `max_length`，使用分块，选择更长上下文模型，或重新设计任务。
### 内存不足
症状：CUDA out-of-memory 或进程崩溃。
修复：减小 batch size，使用更小模型，适当启用混合精度，尝试量化，缩短输入，或训练时使用梯度累积。
### 推理太慢
症状：请求耗时过长。
修复：批量处理输入，使用 GPU，减少生成 token 限制，选择更小模型，缓存重复结果，或使用优化推理运行时。
### 微调效果差
症状：验证指标差或生产样本失败。
修复：检查标签，查看训练验证切分，检查截断，评估类别不均衡，与基线比较，并人工分析错误。
## 生产使用最佳实践
### 固定版本
使用 `requirements.txt` 或 lockfile。模型行为可能依赖库版本、tokenizer 版本和配置文件。
```text
transformers
datasets
evaluate
accelerate
torch
```
严格生产系统应在测试后固定精确版本。
### 记录模型版本
记录 checkpoint 名称、本地模型路径、tokenizer 版本、代码版本和配置。如果未来输出变化，你需要知道什么发生了变化。
### 校验输入
限制文本长度、文件大小、语言和请求频率。不要让任意大小输入未经检查直接进入模型。
### 高风险工作流加入人工审核
法律、医疗、金融、招聘、教育、安全和合规相关工作流中，模型输出应被适当审核和治理。Transformers 很强大，但模型输出不能替代专业责任。
### 监控漂移
用户行为、语言、产品和政策都会变化。去年工单训练的分类器可能随着新问题出现而退化。保持评估集更新，并定期查看错误。
### 尊重许可证和隐私
商业使用前检查模型许可证。除非有许可、控制措施和明确保留策略，否则不要用敏感数据训练。
## 下一步值得学习的高级主题
掌握基础后，以下主题会显著提升实战能力。
### 参数高效微调
参数高效方法只更新较少参数，而不是整个模型。它们能降低计算和存储需求，尤其适合较大模型。
### 量化
量化会降低模型权重精度以节省内存，有时还能提升推理速度。必须认真测试质量，因为量化可能影响输出。
### Accelerate
Accelerate 库帮助你用更少样板代码在不同硬件环境中运行训练和推理。当你从单机迁移到更复杂环境时，它很有用。
### 自定义 Data Collator
Data collator 控制样本如何组成 batch。对于特殊输入格式、动态 padding 或特殊标签，自定义 collator 很有用。
### 自定义训练循环
Trainer 很方便，但当你需要特殊 loss、多任务训练、强化学习流程或细粒度优化控制时，自定义循环更合适。
## 实用学习路径
如果你刚开始学习 Transformers，可以按这个顺序：
1. 运行三个 pipeline：情感分析、摘要和文本生成。
2. 直接加载 tokenizer，检查 `input_ids` 和 `attention_mask`。
3. 直接加载模型，并用 `torch.no_grad()` 运行推理。
4. 在已知数据集上微调小型分类器。
5. 把已知数据集替换成自己的小数据集。
6. 构建评估集和混淆矩阵。
7. 将推理封装成简单 API。
8. 在正确性可接受后再优化延迟和内存。
9. 添加监控、版本管理和输入校验。
10. 用真实使用数据重新评估模型选择。
这条路径能避免你在理解基础前直接陷入大模型复杂性。
## 实用示例：支持工单分类器
假设你想把支持工单分类为 billing、login、bug report、feature request 和 cancellation。
### 原型阶段
从零样本分类开始。使用已移除敏感数据的真实工单样本。检查候选标签是否合理。
```python
from transformers import pipeline
classifier = pipeline("zero-shot-classification", model="facebook/bart-large-mnli")
labels = ["billing", "login", "bug report", "feature request", "cancellation"]
result = classifier(
"I cannot access my account after resetting my password.",
candidate_labels=labels
)
print(result)
```
### 数据集阶段
导出历史工单并一致标注。删除重复，脱敏敏感字段，切分 train、validation 和 test。
### 微调阶段
微调序列分类模型。先用较小模型建立基线。跟踪每个类别的指标，而不只是总体 accuracy。
### 部署阶段
把模型部署在内部 API 后面。使用置信度阈值。低置信度预测发送给人工分流。记录预测，并之后与最终人工标签比较。
### 迭代阶段
每月或在工作流明显变化后查看错误。添加新样本，调整标签定义，并在评估显示确有提升时重新训练。
## 安全、隐私与治理
Transformers 项目可能处理敏感文本、图像或音频。应把模型管道视为数据系统的一部分，而不是孤立实验。
关键实践：
- 最小化数据收集。
- 尽量移除密钥和个人数据。
- 限制训练数据和模型输出访问。
- 审查模型和数据集许可证。
- 为生产决策保留审计记录。
- 高影响结果使用人工审核。
- 在相关场景中测试不同用户群体上的偏差或不一致行为。
不要假设开源 checkpoint 自动适合所有商业用途。阅读 model card、许可证、预期用途和限制。
## FAQ
### Hugging Face Transformers 是免费的吗？
Transformers 库是开源的。但实际成本取决于硬件、托管、存储、数据准备，以及你围绕它使用的付费服务。商业部署前应检查模型许可证和服务价格。
### 使用 Transformers 必须有 GPU 吗？
不必须。许多小模型可以在 CPU 上运行，尤其适合学习和小型分类任务。大型模型、文本生成、微调和高吞吐推理通常更需要 GPU。
### 应该使用 pipeline 还是直接加载模型？
原型和常见任务使用 pipeline。需要控制 batching、设备、logits、自定义后处理、训练或生产行为时，直接加载 tokenizer 和模型。
### 小数据集可以微调模型吗？
有时可以。小数据集适合窄而一致的任务，但过拟合和误导性评估风险更高。应从基线开始，使用验证集，人工检查错误，不要假设训练指标代表真实质量。
### 如何选择最佳模型？
根据任务匹配、语言支持、上下文长度、延迟、硬件、许可证和你自己评估样本上的表现选择。不要只看流行度或模型大小。
### Transformers 可以用于图像和音频吗？
可以。Transformers 通过合适的模型和 processor 支持许多视觉、音频和多模态工作流。文本是最常见入口，但这个库不只限于 NLP。
### Transformers 与 Poe 或 DeepSeek 这样的聊天工具有什么不同？
Transformers 是开发者库，用于加载、运行、微调和部署模型。[Poe](/zh/tools/poe) 和 [DeepSeek](/zh/tools/deepseek) 等工具提供面向用户的 AI 体验。它们很有用，但不能替代直接用 Transformers 构建时获得的控制力。
### 学完基础后应该学什么？
继续学习评估、数据集设计、高效推理、量化、参数高效微调、部署模式和监控。这些能力在真实项目中通常比记住大量模型名称更重要。