Transformers 任务全景指南：用 pipeline 三行代码打通音频、视觉、NLP 与多模态任务

本文以官方文档 docs/source/ar/task_summary.md 为主线，系统梳理 Hugging Face Transformers 库覆盖的音频、计算机视觉、自然语言处理与多模态四大类任务，并逐一给出可运行的 pipeline 代码示例；同时结合 src/transformers/pipelines 目录下的源码实现，讲清每个任务在库内部如何被注册、如何被分派到具体的 Pipeline 类、以及预处理/推理/后处理三阶段是如何组织的。读完后，你可以按任务类型快速选型模型，并在仓库源码层面理解每一行 pipeline 代码背后发生了什么。

任务体系：一次注册，三行代码即可调用

Transformers 不仅提供 Transformer 类模型，还包括非 Transformer 架构（例如用于计算机视觉的现代卷积神经网络 CNN）。官方文档以"三行代码解决一个任务"为演示标准：

>>> from transformers import pipeline
>>> classifier = pipeline(task="sentiment-analysis")
>>> classifier("Hugging Face is the best thing since sliced bread!")
[{'score': 0.9991, 'label': 'POSITIVE'}]

这套"一行工厂函数覆盖所有任务"的体验，来自一个集中式的任务注册表。在 src/transformers/pipelines/init.py 中，TASK_ALIASES 将用户习惯的短名映射到正式任务名：

TASK_ALIASES = {
    "sentiment-analysis": "text-classification",
    "ner": "token-classification",
    "text-to-speech": "text-to-audio",
}

紧随其后的 SUPPORTED_TASKS 字典（src/transformers/pipelines/init.py）为每个任务登记了三样东西：Pipeline 实现类（impl）、可接受的 Auto 模型类（pt）、以及未指定模型时的默认模型及锁定版本（default）。pipeline() 工厂函数（src/transformers/pipelines/init.py）接收 task、model、config、tokenizer、feature_extractor、image_processor、processor、device、device_map、dtype、trust_remote_code、model_kwargs 等参数，内部依次完成：校验任务名（check_task）→ 按默认配置加载模型 → 按需自动补齐 tokenizer / 特征提取器 / 图像处理器等组件。

每个具体任务对应一个位于 src/transformers/pipelines/ 下的模块，例如 audio_classification.py、automatic_speech_recognition.py、image_classification.py、object_detection.py、image_segmentation.py、depth_estimation.py、text_generation.py、fill_mask.py、document_question_answering.py 等。它们的共同骨架由基类 Pipeline 定义（src/transformers/pipelines/base.py），其执行流程被固定为四步：

1. _sanitize_parameters（base.py#L1134）：规范化用户传入的运行参数；
2. preprocess（base.py#L1147）：把原始输入（URL、文件路径、PIL 图像、音频波形等）编码为模型张量；
3. _forward（base.py#L1155）：执行模型推理；
4. postprocess（base.py#L1168）：把 logits 转成人类可读的标签、分数、边界框等结果。

这个统一契约保证了无论任务多么异构，pipeline(task=...) 的调用方式和返回格式始终一致。下文按官方文档的四大章节逐一展开。

音频任务

音频与其他模态的差异在于：音频是连续信号。与可以把句子自然切分为词的文字不同，原始声波无法整齐地离散化，因此通常以固定间隔对信号采样——采样率越高，重构出的声音越接近原始信号。

传统方法会先做特征工程（梅尔频谱等）；现在的通行做法是把原始波形直接喂给特征编码器（Feature Encoder），让模型端到端地学习最有用的表示。这在库中的体现就是音频 Pipeline 都自动加载一个 feature_extractor（如 Wav2Vec2FeatureExtractor）而非 tokenizer。

音频分类

音频分类（Audio Classification）将一段音频归入预定义类别，涵盖以下典型应用（引自原文档）：

• 声音场景分类：给音频打场景标签（"办公室"、"海滩"、"操场"）；
• 声音事件检测：标注事件（"汽车喇叭"、"鲸鱼叫声"、"玻璃破碎"）；
• 多标签标注：一段含多种声音的音频（鸟鸣、会议说话人识别）；
• 音乐分类：按流派打标签（"金属"、"嘻哈"、"乡村"）。

>>> from transformers import pipeline

>>> classifier = pipeline(task="audio-classification", model="superb/hubert-base-superb-er")
>>> preds = classifier("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac")
>>> preds = [{"score": round(pred["score"], 4), "label": pred["label"]} for pred in preds]
>>> preds
[{'score': 0.4532, 'label': 'hap'},
 {'score': 0.3622, 'label': 'sad'},
 {'score': 0.0943, 'label': 'neu'},
 {'score': 0.0903, 'label': 'ang'}]

如果省略 model，注册表会回退到默认模型 superb/wav2vec2-base-superb-ks（见 SUPPORTED_TASKS），并打印一条默认模型警告。

源码层面，AudioClassificationPipeline 有几个值得注意的实现细节：

• 输入形态：preprocess 同时接受本地文件路径、http(s):// URL、bytes 或 np.ndarray。对文件/字节输入，会调用 ffmpeg 子进程解码并重采样到 feature_extractor.sampling_rate（ffmpeg_read）——所以处理音频文件前系统需要安装 ffmpeg；若传入的 dict 自带不同的采样率，则通过 torchaudio 的 F.resample 完成重采样（audio_classification.py#L213-L228）。
• top_k 行为：构造函数中若未显式指定 top_k，默认为 5（audio_classification.py#L99-L107）；top_k=None 或超过类别总数时返回全部标签。
• 后处理：postprocess 默认对 logits 施加 softmax，也可指定 function_to_apply 为 "sigmoid" 或 "none"（audio_classification.py#L246-L259），返回 label/score 字典列表，与上文示例输出结构一致。

自动语音识别（ASR）

ASR 把语音转写成文本。由于语音是人类最自然的交流方式，它是音频领域最主流的任务：智能音箱、手机、车载助手背后的"播放音乐、设置提醒、查询天气"能力都依赖 ASR。

Transformer 时代 ASR 的一大突破是对低资源语言的处理：在大规模无标注语音上预训练后，仅用约 1 小时的已标注低资源语言数据微调，即可达到优于以 100 倍标注数据训练的传统 ASR 系统的质量（原文档表述）。

>>> from transformers import pipeline

>>> transcriber = pipeline(task="automatic-speech-recognition", model="openai/whisper-small")
>>> transcriber("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac")
{'text': ' I have a dream that one day this nation will rise up and live out the true meaning of its creed.'}

AutomaticSpeechRecognitionPipeline 继承自 ChunkPipeline，有两个源码级要点：

• 默认生成参数：除非模型的 generation_config.json 另行声明，流水线默认使用 max_new_tokens=256、num_beams=5（沿用 Whisper 官方实现，见 automatic_speech_recognition.py#L193-L197）。
• 长音频分块：chunk_iter（automatic_speech_recognition.py#L95-L118）把超长波形按 chunk_len 与左右重叠量（stride）切块，逐块编码推理后，用 _find_longest_common_sequence 依据相邻块之间的最长公共序列拼接结果，从而避免重复文本。

计算机视觉任务

文档指出，计算机视觉最早的成功之一是 CNN 识别邮政编码图片：图像由像素组成、每个像素是数值，因此图像天然是像素值矩阵。库中解决视觉问题有两条路线：

1. 卷积路线：自底向上学习层级化特征——从低级边缘逐步到高级抽象对象；
2. Transformer 路线：把图像切块（patch），让模型学习各块之间的关联。与 CNN 的自底向上相反，这类似先看一幅模糊的整体，再逐渐聚焦细节。

图像分类

图像分类（Image Classification）为整张图打一个预定义类别标签，应用包括：医疗影像筛查、卫星图监测毁林与森林火灾、农作物与土地利用监测、物种丰度监测与濒危物种追踪。

>>> from transformers import pipeline

>>> classifier = pipeline(task="image-classification")
>>> preds = classifier(
...     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
... )
>>> preds = [{"score": round(pred["score"], 4), "label": pred["label"]} for pred in preds]
>>> print(*preds, sep="\n")
{'score': 0.4335, 'label': 'lynx, catamount'}
{'score': 0.0348, 'label': 'cougar, puma, catamount, mountain lion, painter, panther, Felis concolor'}
{'score': 0.0324, 'label': 'snow leopard, ounce, Panthera uncia'}
{'score': 0.0239, 'label': 'Egyptian cat'}
{'score': 0.0229, 'label': 'tiger cat'}

不指定模型时，该任务默认加载 google/vit-base-patch16-224（SUPPORTED_TASKS 注册项）——即一条 ViT 路线的代表。ImageClassificationPipeline 接受 http 链接、本地路径或 PIL 图像（单张或批量），其 function_to_apply 参数取 "default"/"sigmoid"/"softmax"/"none"："default" 会在单标签模型上应用 sigmoid、多标签模型上应用 softmax；top_k 默认返回 5 个候选，与示例输出吻合。

目标检测

目标检测（Object Detection）不仅给出类别，还给出每个物体在图中的位置（边界框 bounding box），典型应用：自动驾驶感知（车辆、行人、交通标志）、遥感（灾害监测、城市规划、天气预报）、工业缺陷检测（裂缝、结构损伤、制造缺陷）。

>>> from transformers import pipeline

>>> detector = pipeline(task="object-detection")
>>> preds = detector(
...     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
... )
>>> preds = [{"score": round(pred["score"], 4), "label": pred["label"], "box": pred["box"]} for pred in preds]
>>> preds
[{'score': 0.9865,
  'label': 'cat',
  'box': {'xmin': 178, 'ymin': 154, 'xmax': 882, 'ymax': 598}}]

该任务的默认模型是 facebook/detr-resnet-50（DETR，Transformer 检测路线的代表）。ObjectDetectionPipeline 的 preprocess 会记录原始图像的 target_size，postprocess 中用 threshold（默认 0.5）过滤低置信度检测，并把归一化坐标还原为原图尺寸下的 xmin/ymin/xmax/ymax 整数框——这就是示例中 box 字典的由来。此外它兼容 LayoutLM 类的"OCR + token 分类"模型：若检测到 tokenizer 存在，则走"识别出文字框、再对词做分类"的分支（object_detection.py#L135-L145）。

图像分割

图像分割（Image Segmentation）是像素级任务：为每个像素分配类别。与用边界框的整体判定相比，它精度更高。文档区分了三种类型：

• 实例分割（Instance Segmentation）：除物体类别外，还为每个独立实例编号（"狗-1"、"狗-2"）；
• 全景分割（Panoptic Segmentation）：语义分割 + 实例分割的混合，每个像素同时获得语义类别和实例标识；
• （语义分割：所有同类物体共享一个掩码，是上述两者的基础。）

应用场景：自动驾驶构建像素级世界地图以安全绕行行人与车辆；医学影像中定位异常细胞与器官特征；电商中的虚拟试衣、以及通过手机摄像头把物体叠加到现实场景的 AR 体验。

>>> from transformers import pipeline

>>> segmenter = pipeline(task="image-segmentation")
>>> preds = segmenter(
...     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
... )
>>> preds = [{"score": round(pred["score"], 4), "label": pred["label"]} for pred in preds]
>>> print(*preds, sep="\n")
{'score': 0.9879, 'label': 'LABEL_184'}
{'score': 0.9973, 'label': 'snow'}
{'score': 0.9972, 'label': 'cat'}

源码注册显示，image-segmentation 同时接受 AutoModelForImageSegmentation 与 AutoModelForSemanticSegmentation 两类模型，默认模型为 facebook/detr-resnet-50-panoptic（SUPPORTED_TASKS 注册项）——默认即全景分割模型，与示例输出中"雪地 + 猫"的多区域掩码一致。

深度估计

深度估计（Depth Estimation）预测图像中每个像素到相机的距离，是场景理解与重建的关键：自动驾驶需要知道行人、路牌、他车有多远以避免碰撞；深度信息还能由二维图像构建三维表征，用于生物结构或建筑的高保真三维重建。文档归纳了两类方法：

• 立体视觉（Stereo）：用同一场景两张视角略有差异的图像比较估计深度；
• 单目视觉（Monocular）：仅凭单张图像估计深度。

>>> from transformers import pipeline

>>> depth_estimator = pipeline(task="depth-estimation")
>>> preds = depth_estimator(
...     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
... )

该任务默认模型是 Intel/dpt-large（DPT 单目深度模型，SUPPORTED_TASKS 注册项），实现位于 src/transformers/pipelines/depth_estimation.py。

自然语言处理（NLP）任务

NLP 是其中最常见的一类任务，因为文本本身就是人类自然的沟通媒介。模型要理解文本，先要把文本数字化：把字符串切分为词或子词单元（token），再把 token 映射为数字。这样一段文本就是一个数字序列，可以直接送入模型完成各类 NLP 任务。这一"切词 → 数字化"的过程在库中由 tokenizer / feature extractor / image processor 等预处理组件承担（详见 docs/source/ar/preprocessing.md 与 docs/source/ar/tokenizer_summary.md）。

文本分类

文本分类（Text Classification）把一段文本（句子、段落或整篇文档）归入预定义类别，典型应用：

• 情感分析（Sentiment Analysis）：按"积极/消极"等标准分类，支撑政治、金融、营销等决策；
• 内容分类（Content Classification）：按主题归类（"天气"、"体育"、"金融"），用于新闻与信息流组织过滤。

>>> from transformers import pipeline

>>> classifier = pipeline(task="sentiment-analysis")
>>> preds = classifier("Hugging Face is the best thing since sliced bread!")
>>> preds = [{"score": round(pred["score"], 4), "label": pred["label"]} for pred in preds]
>>> preds
[{'score': 0.9991, 'label': 'POSITIVE'}]

这里 sentiment-analysis 只是 text-classification 的别名（见 TASK_ALIASES），默认模型为 distilbert/distilbert-base-uncased-finetuned-sst-2-english（SUPPORTED_TASKS 注册项）。

token 分类

任何 NLP 任务都会先把文本切分为词或子词 token（术语见 docs/source/ar/glossary.md）。token 分类（Token Classification）为每个 token 从预定义类别中分配一个标签，常见两种形态：

• 命名实体识别（NER）：按组织、人物、地点、日期等实体类别标注 token，在生物信息学场景中常用于基因、蛋白、药物名分类；
• 词性标注（POS）：按名词、动词、形容词等句法角色标注，可帮助机器翻译区分同一词形的不同句法用法。

>>> from transformers import pipeline

>>> classifier = pipeline(task="ner")
>>> preds = classifier("Hugging Face is a French company based in New York City.")
>>> preds = [
...     {
...         "entity": pred["entity"],
...         "score": round(pred["score"], 4),
...         "index": pred["index"],
...         "word": pred["word"],
...         "start": pred["start"],
...         "end": pred["end"],
...     }
...     for pred in preds
... ]
>>> print(*preds, sep="\n")
{'entity': 'I-ORG', 'score': 0.9968, 'index': 1, 'word': 'Hu', 'start': 0, 'end': 2}
{'entity': 'I-ORG', 'score': 0.9293, 'index': 2, 'word': '##gging', 'start': 2, 'end': 7}
{'entity': 'I-ORG', 'score': 0.9763, 'index': 3, 'word': 'Face', 'start': 8, 'end': 12}
{'entity': 'I-MISC', 'score': 0.9983, 'index': 6, 'word': 'French', 'start': 18, 'end': 24}
{'entity': 'I-LOC', 'score': 0.999, 'index': 10, 'word': 'New', 'start': 42, 'end': 45}
{'entity': 'I-LOC', 'score': 0.9987, 'index': 11, 'word': 'York', 'start': 46, 'end': 50}
{'entity': 'I-LOC', 'score': 0.9992, 'index': 12, 'word': 'City', 'start': 51, 'end': 55}

注意输出里的 ##gging：子词切分把 "Hugging" 拆成 "Hu" 与 "##gging"（前缀标记表示该片段是上一 token 的延续），I-ORG 的 BIO 标签则说明这些 token 共同构成一个组织实体。默认模型为 dbmdz/bert-large-cased-finetuned-conll03-english（SUPPORTED_TASKS 注册项），实现位于 src/transformers/pipelines/token_classification.py。

问答

问答（Question Answering）也是 token 级任务，根据问题给出答案。答案可能依赖给定上下文（封闭域），也可能不需要上下文（开放域）。它出现在向虚拟助手提问（"这家餐厅开门了吗"）、客服与技术支持、以及帮助搜索引擎检索相关信息的场景中。两类常见形态：

• 抽取式（Extractive）：给定问题与上下文，答案是模型从上下文中抽取出来的一段文本；
• 生成式/抽象式（Abstractive）：给定问题与上下文，答案是基于上下文生成的。

抽取式（question-answering）与生成式（结合 text-generation）分别对应不同的 Auto 模型类，注册表中分别由 AutoModelForQuestionAnswering 与生成类模型承接（SUPPORTED_TASKS）。

摘要

摘要（Summarization）从长文本生成保留主要语义的短版本，是典型的序列到序列（seq2seq）任务：输入长序列，输出更短的文本序列。法律、金融、专利、学术论文等长文档都可以借此快速传达要点。与问答类似，摘要也分两类：

• 抽取式：挑选并抽取原文中最重要的句子；
• 抽象式：基于原文生成可能包含新词的摘要。

此类任务由 seq2seq 架构（如 T5、BART 等）承接，在库中对应 AutoModelForSeq2SeqLM 一类的模型入口（见 src/transformers/pipelines/init.py#L96-L124 中导入的 Auto 类清单）。

翻译

翻译把一种语言的文本序列转换为另一种语言的文本序列，既帮助不同背景的人交流、扩大内容受众，也可作为语言学习工具。与摘要一样，翻译属于 seq2seq 任务：模型接收输入序列、生成目标序列。早期翻译模型多为单语对单语，而近年的趋势是多语言模型，可在一对模型中覆盖大量语言对。

语言建模

语言建模（Language Modeling）预测文本序列中的下一个 token。它之所以重要，是因为预训练好的语言模型可以进一步微调到几乎任何下游任务；而大语言模型（LLM）展现出的零样本/少样本学习能力，使其甚至能完成从未被显式训练过的任务。语言模型也能生成流畅可信的文本，但需要留意：生成内容不一定总是准确的。两类范式：

• 因果式（Causal）：预测下一个 token，未来的 token 对被遮蔽（不可见）：

>>> from transformers import pipeline

>>> prompt = "Hugging Face is a community-based open-source platform for machine learning."
>>> generator = pipeline(task="text-generation")
>>> generator(prompt)  # doctest: +SKIP

• 掩蔽式（Masked）：预测序列中被隐藏的某个 token，同时可完整访问其余 token：

>>> text = "Hugging Face is a community-based open-source <mask> for machine learning."
>>> fill_mask = pipeline(task="fill-mask")
>>> preds = fill_mask(text, top_k=1)
>>> preds = [
...     {
...         "score": round(pred["score"], 4),
...         "token": pred["token"],
...         "token_str": pred["token_str"],
...         "sequence": pred["sequence"],
...     }
...     for pred in preds
... ]
>>> preds
[{'score': 0.2236,
  'token': 1761,
  'token_str': ' platform',
  'sequence': 'Hugging Face is a community-based open-source platform for machine learning.'}]

源码注册表显示，text-generation 走 AutoModelForCausalLM、默认模型为 HuggingFaceTB/SmolLM3-3B；fill-mask 走 AutoModelForMaskedLM、默认模型为 distilbert/distilroberta-base（SUPPORTED_TASKS 注册项）。这印证了文档中"因果式/掩蔽式"两类范式与具体模型族的对应关系。

多模态任务

多模态（Multimodal）任务要求模型联合处理多种数据模态（文本、图像、音频、视频）来解决一个问题。典型例子是图像描述（Image Captioning）：输入一张图，输出描述该图（或其某些特征）的文本。

虽然多模态模型面对的数据形态各异，但预处理步骤会把所有模态统一转换为嵌入向量（Embeddings）——携带数据语义信息的数值向量。以图像描述为例，模型学习的正是"图像嵌入"与"文本嵌入"之间的对应关系。这一点在源码中同样可见：多模态 Pipeline 往往通过 _load_processor = True 自动加载 AutoProcessor，由处理器协同处理文本与图像输入（如 src/transformers/pipelines/image_text_to_text.py）。

文档问答

文档问答（Document Question Answering）针对文档图像回答自然语言问题。与输入纯文本的 token 级问答不同，它接收"文档图片 + 问题"并返回答案，可用于解释格式化文档并抽取关键信息。下面的例子从一张收据图片中直接问出总额：

>>> from transformers import pipeline
>>> from PIL import Image
>>> import requests

>>> url = "https://huggingface.co/datasets/hf-internal-testing/example-documents/resolve/main/jpeg_images/2.jpg"
>>> image = Image.open(requests.get(url, stream=True).raw)

>>> doc_question_answerer = pipeline("document-question-answering", model="magorshunov/layoutlm-invoices")
>>> preds = doc_question_answerer(
...     question="ما هو المبلغ الإجمالي؟",
...     image=image,
... )
>>> preds
[{'score': 0.8531, 'answer': '17,000', 'start': 4, 'end': 4}]

该任务的默认模型是 impira/layoutlm-document-qa（SUPPORTED_TASKS 注册项），实现位于 src/transformers/pipelines/document_question_answering.py。

任务、默认模型与扩展方式速查

综合源码注册表 src/transformers/pipelines/init.py，本篇覆盖的任务与其默认模型可整理如下（默认模型 列摘自 SUPPORTED_TASKS["default"]，实际加载的是其中锁定的 revision）：

任务名（task 字符串）	别名	默认模型	实现模块
audio-classification	—	superb/wav2vec2-base-superb-ks	audio_classification.py
automatic-speech-recognition	—	facebook/wav2vec2-base-960h	automatic_speech_recognition.py
image-classification	—	google/vit-base-patch16-224	image_classification.py
object-detection	—	facebook/detr-resnet-50	object_detection.py
image-segmentation	—	facebook/detr-resnet-50-panoptic	image_segmentation.py
depth-estimation	—	Intel/dpt-large	depth_estimation.py
text-classification	sentiment-analysis	distilbert/distilbert-base-uncased-finetuned-sst-2-english	text_classification.py
token-classification	ner	dbmdz/bert-large-cased-finetuned-conll03-english	token_classification.py
fill-mask	—	distilbert/distilroberta-base	fill_mask.py
text-generation	—	HuggingFaceTB/SmolLM3-3B	text_generation.py
document-question-answering	—	impira/layoutlm-document-qa	document_question_answering.py
text-to-audio	text-to-speech	suno/bark-small	text_to_audio.py

注册表之外，库还支持零样本分类（zero-shot-classification / zero-shot-image-classification / zero-shot-audio-classification）、表格问答（table-question-answering）、掩码生成（mask-generation）、关键点匹配（keypoint-matching）、视频分类（video-classification）等任务，均按同一 preprocess → _forward → postprocess 契约组织。

从源码结构看，任务扩展是开放的：check_task（src/transformers/pipelines/init.py#L323-L359）只依赖 PIPELINE_REGISTRY；模型配置中的 custom_pipelines 字段还能注册自定义 Pipeline（src/transformers/pipelines/init.py#L936-L972），配合 trust_remote_code 从 Hub 动态加载。此外，pipeline() 的完整参数（revision、use_fast、device、device_map、dtype、token、model_kwargs 等）与"只传 model 时自动推断任务"的行为（get_task，src/transformers/pipelines/init.py#L306-L320）可在 docs/source/ar/pipeline_tutorial.md 中进一步学习。

小结

本文沿官方文档的四大任务版图——音频（分类、ASR）、视觉（分类、检测、分割、深度估计）、NLP（文本分类、token 分类、问答、摘要、翻译、语言建模）、多模态（文档问答）——给出了一致的 pipeline 用法范式：pipeline(task=..., model=...) 加上一次函数调用即可得到结构化预测。而源码层面的注册表 SUPPORTED_TASKS、任务别名、以及 Pipeline 基类的四段式执行流程，解释了这种"统一接口覆盖异构任务"的设计如何在 src/transformers/pipelines 中落地。掌握了任务名、默认模型与三阶段执行结构这三点，你就可以在仓库中精确定位任意任务从入口函数到具体 Pipeline 实现的全部链路。