Transformers Processors 完全指南面向多模态输入的预处理处理器设计与实战【免费下载链接】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多模态模型视觉-语言、语音-文本、音视频模型等需要同时把不同模态的原始输入文本、图像、音频、视频统一转换成模型可消费的张量输入这正是ProcessorMixin与AutoProcessor这套处理器Processor体系所解决的问题。本文以 Processors 官方文档 为主体结合本仓库transformers源码深入讲解处理器的设计原理、加载方式、预处理流程与保存共享机制读完你既可以熟练为 PaliGemma、Whisper 等多模态模型编写预处理管线也能理解处理器内部一拆多合的组合式架构与占位符替换等底层实现。为什么多模态模型需要 Processor单模态预处理器只擅长一种输入分词器Tokenizer把文本变成 token 序列与input_ids图像处理器Image Processor把图片变成pixel_values特征提取器Feature Extractor把音频波形变成带有正确采样率的张量。而多模态模型的输入是混合形态的例如视觉-语言模型 PaliGemma使用 SigLIP 图像处理器 Llama 分词器语音识别模型 Whisper使用特征提取器处理 16kHz 音频 快速分词器处理文本转录视频-语言模型同时需要视频处理器与分词器。如果每次推理都要用户手动去分别调用 image processor 和 tokenizer再手工拼装字典既繁琐又易错。Processor处理器就是在这些底层预处理器之上再加一层薄封装把多个子预处理器聚合为一个统一类对外只暴露一个调用入口输入文字 图片就自动产出input_ids与pixel_values输入音频 文本就产出input_features与labels。处理器类体系一切从 ProcessorMixin 开始仓库中所有处理器都继承自ProcessorMixin该 mixin 与PushToHubMixin组合统一提供三大能力见源码 docstring 与各方法定义ProcessorMixin.from_pretrained从 Hub 模型仓库或本地目录加载处理器ProcessorMixin.save_pretrained把处理器及其全部子预处理器保存到本地目录push_to_hub把处理器一键推送/共享到 Hub。ProcessorMixin在内部维护一组子处理器属性动态挂载在实例上processing_utils.pytokenizer: Any # 文本分词器 feature_extractor: Any # 音频特征提取器旧称 image_processor: Any # 图像处理器 video_processor: Any # 视频处理器 chat_template: str | dict[str, str] | None注意__init__processing_utils.py会做严格的参数校验传入的关键字参数必须落在get_attributes()声明的子处理器名单内否则抛TypeError每个参数还会通过check_argument_for_proper_class校验类型比如把 feature extractor 误传给 tokenizer 槽位会被立刻拦截避免顺序传错这类低级错误。组合式设计的直观例证PaliGemmaProcessor的构造函数说明一个视觉-语言处理器通常由image_processor tokenizer组合而成并且可以扩展模型专属能力def __init__(self, image_processorNone, tokenizerNone, chat_templateNone, **kwargs): # 要求图像处理器携带 image_seq_length用于把图像展开成固定长度的视觉 token 序列 if not hasattr(image_processor, image_seq_length): raise ValueError(Image processor is missing an image_seq_length attribute.) ...类似地WhisperProcessor的组合更简单__init__(self, feature_extractor, tokenizer)。音频类处理器的实现也很直白——若同时给出audio与text则分别调用feature_extractor(audio, sampling_rate...)与tokenizer(text)并把 tokenizer 输出的input_ids重命名为labels合入结果processing_whisper.py。加载处理器AutoProcessor 与模型专属类两种路径加载处理器有两种等价方式对应ProcessorMixin.from_pretrained的两种调用入口。方式一AutoProcessor推荐无需关心具体类名AutoProcessor是 AutoClass 体系的一部分提供根据 checkpoint 自动推断处理器类型的免指定接口。它不能被直接__init__()实例化会抛OSError只能通过类方法from_pretrained使用from transformers import AutoProcessor processor AutoProcessor.from_pretrained(google/paligemma-3b-pt-224)从源码可以看到其解析流程processing_auto.pyAutoProcessor.from_pretrained会按优先级探测仓库根目录下的配置文件依次尝试preprocessor_config.json处理器配置→ image processor 配置 → video processor 配置 → feature extractor 配置从配置里的processor_class/auto_map字段解析出真正的处理器类再实例化。这也解释了为什么手动save_pretrained的目录也能被AutoProcessor无缝加载。方式二模型专属处理器类处理器通常与某个预训练模型类绑定因此也可直接从模型类身上加载from transformers import WhisperProcessor processor WhisperProcessor.from_pretrained(openai/whisper-tiny)这种方式的好处是显式、类型明确还能调用模型专属方法如WhisperProcessor.get_decoder_prompt_ids、get_prompt_ids。进阶手动拆装两个子预处理器from_pretrained本质上是在帮你分别加载子预处理器再组合。你完全可以自己复现这一过程先单独加载WhisperTokenizerFast与WhisperFeatureExtractor再手动实例化处理器from transformers import WhisperTokenizerFast, WhisperFeatureExtractor, WhisperProcessor tokenizer WhisperTokenizerFast.from_pretrained(openai/whisper-tiny) feature_extractor WhisperFeatureExtractor.from_pretrained(openai/whisper-tiny) processor WhisperProcessor(feature_extractorfeature_extractor, tokenizertokenizer)这一模式在给 checkpoint 更换/微调某个子预处理器例如替换 tokenizer 词汇时非常实用因为 ProcessorMixin 的构造器 支持位置参数只要保持子处理器顺序与声明的attributes一致即可组合任意配对。预处理把异构输入路由到正确的子预处理器调用处理器processor(text..., images..., audio..., ...)会返回一个标准的BatchFeature对象内部按return_tensors指定类型pt/tf/np张量化。处理器call的分发逻辑基类的__call__processing_utils.py实现了一条清晰的流水线prepare_inputs_layout做输入规范化——把文本包成 batch 列表、通过image_processor.fetch_images拉取并解码 URL 图片、自动抓取/重采样音频processing_utils.pyvalidate_inputs校验四种模态至少提供一种否则抛ValueErrorprocessing_utils.py_merge_kwargs把调用方 kwargs 与valid_processor_kwargs即 ProcessingKwargs TypedDict内含text_kwargs/images_kwargs/videos_kwargs/audio_kwargs分组默认值合并保证子处理器收到的是经过白名单校验的参数按需分发if images is not None and hasattr(self, image_processor)才调用图像处理器音频只在该实例存在_audio_processorfeature_extractor 或 audio_processor时才处理汇总data {**text_inputs, **processed_images, **processed_videos, **processed_audio}把文本输出与各模态输出合并为一个字典交给BatchFeature。关键点是模态可选processor 既能处理text image也能只处理text audio具体看这个多模态模型的子预处理器组合。实战用 Whisper 处理器准备 ASR 训练数据自动语音识别ASR需要处理器同时处理文本与音频。以keithito/lj_speech数据集为例先加载数据集并只保留audio与text两列可删除不需要的file、id、normalized_text列from datasets import load_dataset dataset load_dataset(keithito/lj_speech, splittrain) dataset dataset.map(remove_columns[file, id, normalized_text]) dataset[0][audio] {array: array([-7.3242188e-04, -7.6293945e-04, -6.4086914e-04, ..., 7.3242188e-04, 2.1362305e-04, 6.1035156e-05], dtypefloat32), path: /root/.cache/huggingface/datasets/downloads/extracted/917ece08c95cf0c4115e45294e3cd0dee724a1165b7fc11798369308a465bd26/LJSpeech-1.1/wavs/LJ001-0001.wav, sampling_rate: 22050} dataset[0][text] Printing, in the only sense with which we are at present concerned, differs from most if not from all the arts and crafts represented in the Exhibition务必重采样LJSpeech 原始采样率为 22050 Hz而 Whisper 预训练模型要求 16000 Hz采样率不匹配会直接破坏input_features的频谱计算因此先用datasets的Audio特性把audio列统一重采样from datasets import Audio dataset dataset.cast_column(audio, Audio(sampling_rate16000))然后加载处理器并编写prepare_dataset映射函数。处理器把音频array转成input_features把text转成labels一次调用即产出训练所需全部模型输入from transformers import AutoProcessor processor AutoProcessor.from_pretrained(openai/whisper-tiny) def prepare_dataset(example): audio example[audio] example.update(processor(audioaudio[array], textexample[text], sampling_rate16000)) return example prepare_dataset(dataset[0])需要强调传给处理器的sampling_rate16000必须与cast_column后的音频实际采样率一致这是音频类处理器能否正确计算梅尔频谱特征的前提。此模式可直接配合dataset.map(prepare_dataset)对全量数据做离线预处理供Seq2SeqTrainer/DataCollatorForSeq2Seq使用。视觉-语言示例PaliGemma 的图像 文本输入回到文档开头的 PaliGemma 例子处理器把提示文本 PIL 图像组合成模型需要的input_ids与pixel_valuesfrom transformers import AutoProcessor, PaliGemmaForConditionalGeneration from PIL import Image import requests processor AutoProcessor.from_pretrained(google/paligemma-3b-pt-224) prompt answer en Where is the cat standing? url https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg image Image.open(requests.get(url, streamTrue).raw) inputs processor(textprompt, imagesimage, return_tensorspt) inputs在 PaliGemmaProcessor.call的源码里还能看到视觉-语言处理器常见的几个细节支持suffix关键字构建前缀 后缀式的 VQA 样本后缀会自动追加 EOS token构造时强制开启return_token_type_idsTrue以便区分图像 token 与文本 token若结果里含token_type_ids会据此把非文本位置置为-100生成labels让推理与训练共用同一入口。多模态占位符Placeholder Token机制现代视觉-语言模型如 PaliGemma、LLaVA、Qwen-VL 系列的文本提示中常包含图片/视频/音频占位符如 PaliGemma 的{image}token。处理器需要把这些占位符原地展开成与多模态输入一一对应的完整 token 串。基类在__call__中通过get_text_with_replacementsprocessing_utils.py统一完成每个模态子处理器处理完后若处理器声明了image_token/video_token/audio_token属性就调用子类实现的replace_image_token/replace_video_token/replace_audio_tokenprocessing_utils.py基类默认NotImplementedError为每个图像/视频/音频生成替换字符串随后对文本按re.finditer扫描占位符用第 i 个图片占位符替换第 i 张图的替换串的顺序消费替换列表同时返回replacement_offsets每个占位符在原文与展开后文本中的(start, end)偏移用于后端如 vLLM 类推理引擎把多模态数据与文本 token 精确对齐。自定义多模态处理器的开发者只需在子类中定义好与文本中一致的image_token常量、重写对应的replace_image_token即可接入这套统一的占位符机制。保存、共享与 Chat Templatesave_pretrainedprocessing_utils.py会把一个组合处理器拆回多个标准文件落盘对每个子处理器调用其各自的save_pretrained分词器保存词汇文件并写入tokenizer_config.json等若模型有多个分词器如 encoder/decoder 双分词器额外的分词器会存进以属性名命名的子目录chat_templateJinja 模板单独存为chat_template.jinja多套模板则放入chat_templates/目录注意源码对模板名做了路径穿越防护见 CWE-22 检查processing_utils.py最后把所有非 tokenizer 子预处理器的配置汇总成一份统一的preprocessor_config.json即PROCESSOR_NAME其中的processor_class/auto_map字段正是AutoProcessor.from_pretrained反查处理器类型的依据。因此一个完整的处理器本地目录通常包含preprocessor_config.json、tokenizer_config.json、vocab.json、merges.txt、chat_template.jinja等文件保存后再用AutoProcessor.from_pretrained(./my_processor_dir)即可原样还原也支持push_to_hubTrue一键发布到 Hub 与他人共享。小结Processor 是transformers多模态生态的总装车间它以ProcessorMixin为基类将分词器、图像处理器、特征提取器等子预处理器组合成统一入口通过AutoProcessor.from_pretrained免指定加载、通过__call__按模态自动路由、通过占位符替换机制打通文本模板 ↔ 图像/音频张量的对齐并通过save_pretrained/push_to_hub实现配置的落盘与分享。掌握了这一套机制无论为 Whisper 准备 ASR 训练集、为 PaliGemma 构造 VQA 样本还是为新多模态模型编写自定义处理器都能做到一次预处理处处可复用。【免费下载链接】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），仅供参考