Transformerspipeline推理实战从文本生成到音频、视觉任务的完整使用指南【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers本文基于 transformers 仓库的 Pipeline 教程docs/source/it/pipeline_tutorial.md系统讲解pipeline这一高层推理抽象如何以最少的代码调用 Model Hub 上的预训练模型完成文本生成、音频情绪分类、图像分类等任务如何指定特定的模型与 tokenizer以及关键参数的含义与默认值。读完后你可以不深入了解底层模型代码直接用三五行 Python 代码跑通从文本、音频到图像的多模态推理并理解 pipeline 工厂函数在底层是如何解析任务、加载组件的。pipeline 是什么预处理 模型 后处理的封装pipeline是 transformers 提供的推理工厂函数给定一个任务名它会自动加载该任务的默认模型和对应的 tokenizer或图像/音频处理器把「预处理 → 前向推理 → 后处理」整条链路封装成一个可直接调用的对象。也就是说即使你不熟悉某一模态音频、视觉的模型结构也能用统一接口完成推理。从源码结构看pipeline()的定义位于 src/transformers/pipelines/init.py#L671其 docstring 明确说明了一条 pipeline 由三部分构成一个或多个预处理组件tokenizer、image_processor、feature_extractor 或 processor一个负责预测的模型可选的后处理步骤也可由 processor 处理。每个任务都有对应的专用 pipeline 类全部注册在SUPPORTED_TASKS字典中src/transformers/pipelines/init.py#L141-L294当前版本内置支持的任务包括任务字符串返回的 pipeline 类当前默认模型audio-classificationAudioClassificationPipelinesuperb/wav2vec2-base-superb-ksautomatic-speech-recognitionAutomaticSpeechRecognitionPipelinefacebook/wav2vec2-base-960hdepth-estimationDepthEstimationPipelineIntel/dpt-largedocument-question-answeringDocumentQuestionAnsweringPipelineimpira/layoutlm-document-qafeature-extractionFeatureExtractionPipelinedistilbert/distilbert-base-casedfill-maskFillMaskPipelinedistilbert/distilroberta-baseimage-classificationImageClassificationPipelinegoogle/vit-base-patch16-224image-feature-extractionImageFeatureExtractionPipelinegoogle/vit-base-patch16-224image-segmentationImageSegmentationPipelinefacebook/detr-resnet-50-panopticimage-text-to-textImageTextToTextPipelineQwen/Qwen3-VL-2B-Instructkeypoint-matching/mask-generationKeypointMatchingPipeline/MaskGenerationPipelinemagic-leap-community/superglue_outdoor/facebook/sam-vit-hugeobject-detectionObjectDetectionPipelinefacebook/detr-resnet-50table-question-answeringTableQuestionAnsweringPipelinegoogle/tapas-base-finetuned-wtqtext-classification别名sentiment-analysisTextClassificationPipelinedistilbert/distilbert-base-uncased-finetuned-sst-2-englishtext-generationTextGenerationPipelineHuggingFaceTB/SmolLM3-3Btext-to-audio别名text-to-speechTextToAudioPipelinesuno/bark-smalltoken-classification别名nerTokenClassificationPipelinedbmdz/bert-large-cased-finetuned-conll03-englishvideo-classificationVideoClassificationPipelineMCG-NJU/videomae-base-finetuned-kineticszero-shot-classification/zero-shot-image-classification/zero-shot-audio-classification/zero-shot-object-detection对应的 ZeroShot 系列 pipeline如 zero_shot_classification.pyfacebook/bart-large-mnli等任务别名在 src/transformers/pipelines/init.py#L136-L140 的TASK_ALIASES中定义sentiment-analysis等价于text-classificationner等价于token-classificationtext-to-speech等价于text-to-audio。所有 pipeline 类的公共基础设施数据格式、__call__流程、组件加载位于 src/transformers/pipelines/base.py。基本用法创建 pipeline 并做推理每个任务虽然都有专属 pipeline 类但更常见的做法是直接使用这个通用抽象——你只需指定任务名pipeline会自动加载该任务的默认模型和 tokenizer。创建 pipeline 并指定要推理的任务 from transformers import pipeline generator pipeline(tasktext-generation)不指定model时源码会走到 src/transformers/pipelines/init.py#L982-L989 的分支通过get_default_model_and_revision取任务的默认模型当前text-generation的默认模型是HuggingFaceTB/SmolLM3-3B并打印一条警告提示「在生产环境中使用 pipeline 而不指定模型名和 revision 并不推荐」——因此正式使用时建议显式指定模型。将输入文本交给 pipeline generator( ... Three Rings for the Elven-kings under the sky, Seven for the Dwarf-lords in their halls of stone ... ) # doctest: SKIP [{generated_text: Three Rings for the Elven-kings under the sky, Seven for the Dwarf-lords in their halls of stone, Seven for the Iron-priests at the door to the east, and thirteen for the Lord Kings at the end of the mountain}]如果有多个输入把它们放进一个列表即可pipeline 会对列表中的每条输入分别推理 generator( ... [ ... Three Rings for the Elven-kings under the sky, Seven for the Dwarf-lords in their halls of stone, ... Nine for Mortal Men, doomed to die, One for the Dark Lord on his dark throne, ... ] ... ) # doctest: SKIP传递额外参数任何与任务相关的额外参数都可以直接写进 pipeline 的调用里。以text-generation为例底层调用的是模型的~generation.GenerationMixin.generate方法其中的采样参数会透传下去。例如想一次生成多条输出就传num_return_sequences generator( ... Three Rings for the Elven-kings under the sky, Seven for the Dwarf-lords in their halls of stone, ... num_return_sequences2, ... ) # doctest: SKIP选择特定的模型和 tokenizerpipeline接受 Model Hub 上的任意模型。Hub 上带有按任务过滤的 tag选定模型后推荐用对应的AutoModelFor*类和 [AutoTokenizer] 加载再把实例传给 pipeline。以 causal language modeling 为例加载 [AutoModelForCausalLM] from transformers import AutoTokenizer, AutoModelForCausalLM tokenizer AutoTokenizer.from_pretrained(distilbert/distilgpt2) model AutoModelForCausalLM.from_pretrained(distilbert/distilgpt2)创建 pipeline 时传入已加载的 model 和 tokenizer from transformers import pipeline generator pipeline(tasktext-generation, modelmodel, tokenizertokenizer)再次推理此时生成结果就来自 distilgpt2 而不是任务默认模型 generator( ... Three Rings for the Elven-kings under the sky, Seven for the Dwarf-lords in their halls of stone ... ) # doctest: SKIP [{generated_text: Three Rings for the Elven-kings under the sky, Seven for the Dwarf-lords in their halls of stone, Seven for the Dragon-lords (for them to rule in a world ruled by their rulers, and all who live within the realm}]从源码看当model是一个字符串时pipeline()会先加载config.jsonL888-L901拿到 commit hash再依据任务的pt字段中声明的 Auto 类如text-generation对应AutoModelForCausalLM调用load_model完成实例化L1034-L1043tokenizer、image_processor、feature_extractor 等组件则按「显式传入 → 按 model 名推断 → 按 config 名推断」的顺序解析L1056-L1104。因此显式传入的 tokenizer 会覆盖自动推断结果这正是上面示例中指定 tokenizer 生效的原因。关键参数详解结合 pipeline 函数签名L671-L690 与 docstring常用参数及默认值如下参数默认值说明taskNone任务字符串决定返回哪个 pipeline 类若省略而提供了字符串形式的model会尝试从 Hub 的pipeline_tag自动推断见 get_taskL306-L320离线模式下无法自动推断modelNone模型标识符字符串或 [PreTrainedModel] 实例不传则使用任务默认模型并发出警告configNone模型配置标识符或 [PreTrainedConfig] 实例可单独于 model 指定tokenizerNonetokenizer 标识符或实例不传时按 model → config → 任务默认顺序推断feature_extractor/image_processor/video_processor/processorNone面向音频、图像、视频及多模态模型的预处理组件多模态模型通常还需要 tokenizer 配合revisionmain模型版本可以是分支名、tag 或 commit iduse_fastTrue尽可能使用 Fast tokenizer[PreTrainedTokenizerFast]tokenNone访问私有/受限仓库的 tokenTrue表示使用hf auth login生成的 tokendeviceNone指定设备如cpu、cuda:1、mps或 GPU 序号不设置时自动放到第一个可用加速器CUDA、MPS、XPU 等都没有才回退 CPU。不能与device_map同时使用device_mapNone会原样透传给model_kwargs在安装了 accelerate 时可用device_mapauto自动分片大模型。源码中同时传device与device_map会告警且device会覆盖device_mapL1000-L1004dtypeauto模型加载精度透传给from_pretrainedauto表示按保存时的 dtype 加载也可显式传torch.float16、torch.bfloat16等。旧参数torch_dtype已废弃L1008-L1011trust_remote_codeNone是否允许执行 Hub 仓库中的自定义 modeling/tokenization/pipeline 代码仅在确认信任该仓库时设为Truemodel_kwargs{}额外透传给模型from_pretrained的字典参数pipeline_classNone直接指定 pipeline 类可覆盖任务映射结果**kwargs—透传给具体 pipeline 类构造函数的其他参数此外还有两点源码层面的细节值得注意task与model至少提供一个否则抛出RuntimeErrorL859-L864只传 tokenizer 或 feature_extractor 而不传 model 也会报错因为组件可能与默认模型不兼容L866-L877。音频 pipeline情绪识别示例pipeline的同一套接口同样适用于音频任务。以下示例对一段音频做情绪分类先用datasets加载一个语音样例得到音频文件路径 from datasets import load_dataset import torch torch.manual_seed(42) # doctest: IGNORE_RESULT ds load_dataset(hf-internal-testing/librispeech_asr_demo, clean, splitvalidation) audio_file ds[0][audio][path]从 Model Hub 按audio-classification任务挑选一个情绪识别模型并加载进 pipeline from transformers import pipeline audio_classifier pipeline( ... taskaudio-classification, modelehcalabres/wav2vec2-lg-xlsr-en-speech-emotion-recognition ... )将音频文件传入 pipeline 推理 preds audio_classifier(audio_file) preds [{score: round(pred[score], 4), label: pred[label]} for pred in preds] preds [{score: 0.1315, label: calm}, {score: 0.1307, label: neutral}, {score: 0.1274, label: sad}, {score: 0.1261, label: fearful}, {score: 0.1242, label: happy}]输出是一个按得分排序的(label, score)列表本例中「calm」得分最高。这里的音频输入由AudioClassificationPipeline内部的 feature extractor 完成波形预处理与文本任务相比你只是把输入从字符串换成了音频文件pipeline 调用方式完全一致。视觉 pipeline图像分类示例对图像做任务与文本、音频几乎相同指定image-classification任务然后直接把图片交给 pipeline——图片既可以是 URL也可以是你本机上的文件路径。例如对教程中那张猫的照片做分类 from transformers import pipeline vision_classifier pipeline(taskimage-classification) preds vision_classifier( ... imageshttps://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] preds [{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}]可以看到该图被识别为猞猁lynx等猫科物种。这里未指定模型pipeline按SUPPORTED_TASKS中image-classification的默认配置加载google/vit-base-patch16-224src/transformers/pipelines/init.py#L223-L228图像预处理由 ImageClassificationPipeline 配套的 image processor 完成。小结pipeline的价值在于用统一的「任务名 输入」接口屏蔽了 tokenizer、特征提取、设备放置等工程细节三行代码即可跑通文本生成text_generation.py、音频情绪分类audio_classification.py和图像分类image_classification.py三类任务需要自定义模型时用AutoModelFor*与AutoTokenizer显式加载并传入model/tokenizer即可需要控制精度、设备或分片时通过dtype、device、device_map、model_kwargs等参数完成。完整的任务清单以 SUPPORTED_TASKS 为准公共调用流程与数据格式可进一步参考 pipeline 基类。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考