Transformers Feature Extractor 完全指南音频与视觉输入特征的前处理管线【免费下载链接】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 中Feature Extractor特征提取器承担着「把原始输入加工成模型可消费的输入特征」这一关键职责对音频文件完成 Log-Mel 频谱图等序列特征提取对图像完成裁剪、缩放与归一化并统一处理填充padding、注意力掩码以及到 NumPy / PyTorch / TensorFlow 张量的转换。本文以仓库中的 docs/source/ja/main_classes/feature_extractor.md 为骨架结合 feature_extraction_utils.py、feature_extraction_sequence_utils.py 与 image_utils.py 的源码实现完整讲解FeatureExtractionMixin、SequenceFeatureExtractor、BatchFeature与ImageFeatureExtractionMixin四大核心类使读者既能掌握开箱即用的调用方法也能理解底层张量转换与填充策略的实现原理。什么是 Feature Extractor按官方文档的定义feature extractor 负责为音频audio或视觉vision模型准备输入特征具体包括从序列中提取特征例如对音频文件做预处理生成 Log-Mel 频谱图Log-Mel Spectrogram特征从图像中提取特征例如对图像文件进行裁剪cropping等几何变换张量化与批处理完成 padding填充、normalization归一化以及到 NumPy、PyTorch、TensorFlow 张量的转换。从源码结构看该文档对应的四个类构成了整个特征提取体系的分层骨架类定义文件职责FeatureExtractionMixinfeature_extraction_utils.py提供from_pretrained/save_pretrained等保存加载基座SequenceFeatureExtractorfeature_extraction_sequence_utils.py面向语音识别等序列任务的通用提取器含pad核心方法BatchFeaturefeature_extraction_utils.py持有并转换pad/__call__输出的字典式容器ImageFeatureExtractionMixinimage_utils.py提供图像尺寸调整、裁剪、归一化等工具方法FeatureExtractionMixin特征提取器的保存与加载基座FeatureExtractionMixin是所有序列 / 音频特征提取器的公共基类定义在 feature_extraction_utils.py它继承自PushToHubMixin因此天然支持推送到 Hub。其构造函数会把kwargs中的键值对直接设置为对象属性并弹出processor_class避免污染序列化结果。from_pretrained从任意来源实例化类方法from_pretrained支持三种来源见 feature_extraction_utils.pyHub 上的模型 ID例如facebook/wav2vec2-base-960h会从 Hub 下载并缓存特征提取器配置本地目录包含save_pretrained保存出的配置文件的目录例如./test/saved_model/单个 JSON 文件例如./test/saved_model/preprocessor_config.json。关键参数来自 docstring 与源码签名参数默认值说明pretrained_model_name_or_path必填模型 ID、目录或 JSON 文件路径cache_dirNone自定义下载缓存目录force_downloadFalse是否强制重新下载并覆盖缓存local_files_onlyFalse是否只允许使用本地文件tokenNoneHub 访问令牌True时使用hf auth login产生的令牌revisionmain分支名 / 标签 / commit id也可传refs/pr/pr_number测试 PRreturn_unused_kwargsFalse为True时返回(feature_extractor, unused_kwargs)元组源码中的示例用法from transformers import Wav2Vec2FeatureExtractor # 1) 从 Hub 下载并缓存 feature_extractor Wav2Vec2FeatureExtractor.from_pretrained(facebook/wav2vec2-base-960h) # 2) 从本地目录加载 feature_extractor Wav2Vec2FeatureExtractor.from_pretrained(./test/saved_model/) # 3) 从单个 JSON 文件加载 feature_extractor Wav2Vec2FeatureExtractor.from_pretrained(./test/saved_model/preprocessor_config.json) # 4) kwargs 覆盖已加载属性未知键默认被忽略 feature_extractor Wav2Vec2FeatureExtractor.from_pretrained( facebook/wav2vec2-base-960h, return_attention_maskFalse, fooFalse ) assert feature_extractor.return_attention_mask is False # 5) return_unused_kwargsTrue 时回收未使用的键 feature_extractor, unused_kwargs Wav2Vec2FeatureExtractor.from_pretrained( facebook/wav2vec2-base-960h, return_attention_maskFalse, fooFalse, return_unused_kwargsTrue ) assert unused_kwargs {foo: False}从加载链路看get_feature_extractor_dictfeature_extraction_utils.pyfrom_pretrained会依次尝试解析processor_config.json新版嵌套格式与preprocessor_config.json旧版平铺格式并按「嵌套配置优先 → 旧版配置兜底」的顺序合并出特征提取器字典最终交给from_dict构造实例。这解释了为什么同一份代码能同时兼容新老格式的模型仓库。save_pretrained序列化到 JSONsave_pretrainedfeature_extraction_utils.py会把特征提取器序列化为preprocessor_config.json写入指定目录如果该目录不存在会自动创建。若push_to_hubTrue还会在保存后通过PushToHubMixin上传到 Hub。序列化时to_dict会剔除mel_filters、window等无法 JSON 化的中间数组见 feature_extraction_utils.py保证配置文件的纯净与可复现。SequenceFeatureExtractor语音特征提取的核心实现SequenceFeatureExtractor是面向语音识别speech recognition的通用特征提取类定义在 feature_extraction_sequence_utils.py。构造函数需要三个关键参数参数类型说明feature_sizeint提取特征的维度如 Mel 滤波器组数量sampling_rateint音频数字化采样率单位 Hzpadding_valuefloat填充位置使用的值此外它还会读取两个可配置项padding_side默认right决定左/右填充与return_attention_mask默认True。pad 方法与填充策略pad是整个类最核心的方法feature_extraction_sequence_utils.py既可以用于单样本预处理也可以直接作为 PyTorchDataLoader的collate_fn。其参数语义如下参数默认值说明processed_features必填单个BatchFeature/ dict或它们的列表 / 嵌套字典支持 numpy 数组与 PyTorch 张量paddingTrueTrue/longest填充到 batch 内最长序列max_length填充到max_lengthFalse/do_not_pad不填充max_lengthNone返回序列的最大长度与填充 / 截断配合truncationFalse是否将超过max_length的序列截断pad_to_multiple_ofNone把序列长度向上取整为该值的倍数return_attention_maskNone是否返回注意力掩码缺省时使用特征提取器自身默认值return_tensorsNonept返回 PyTorch 张量np返回 NumPy 数组实现上有几个值得注意的细节输入自动归一若传入的是 list[dict]pad会先转置成 dict[list] 以便批量处理随后把 Python 列表 / 张量统一转为 NumPy 数组见 feature_extraction_sequence_utils.py填充策略枚举PaddingStrategy定义在 utils/generic.py取值longest/max_length/do_not_padpad_to_multiple_of的硬件意义源码注释明确指出该参数对 NVIDIA compute capability ≥ 7.5Volta 起的 Tensor Cores以及受益于 128 倍数字列长度的 TPU 特别有用见 feature_extraction_sequence_utils.py填充实现_pad方法按padding_side在左或右侧调用np.pad填充padding_valuefeature_size 1时填充形状为((0, difference), (0, 0))以保留特征维度同时同步扩展attention_mask见 feature_extraction_sequence_utils.py截断前置先_truncate后_pad截断启用但未提供max_length时会直接抛出ValueError避免静默出错。BatchFeature字典式的张量容器BatchFeature是pad与各特征提取器__call__方法的统一返回值定义在 feature_extraction_utils.py。它继承自UserDict因此可以像普通 dict 一样使用键通常是input_values、attention_mask等。构造参数参数默认值说明dataNone__call__/pad返回的字典值为 list / 数组 / 张量tensor_typeNone初始化时是否立即将整数列表转换为 PyTorch / NumPy 张量skip_tensor_conversionNone需要跳过张量转换的键集合即使指定了tensor_type也不转换convert_to_tensors 与 to 方法convert_to_tensorsfeature_extraction_utils.py负责把内部内容批量转换为指定类型的张量TensorType枚举支持pt/np/mlx见 utils/generic.py。实现细节包括非类数组结构字符串、字典、字符串列表自动跳过转换转换失败时给出可操作的错误提示建议paddingTrue保证形状一致或return_tensorsNone返回 Python 对象针对overflowing_values键给出专门的报错信息便于定位填充溢出的问题。to方法feature_extraction_utils.py提供 PyTorch 设备的迁移能力只对浮点张量做 dtype 转换避免像 tokenizer 那样把LongTensor意外转成FloatTensor也支持non_blockingTrue的异步传输。ImageFeatureExtractionMixin图像特征处理工具箱ImageFeatureExtractionMixin定义在 image_utils.py提供图像特征准备的实用工具是视觉类特征提取器 / 图像处理器的公共能力集合。所有方法都通过_ensure_format_supported校验输入仅接受PIL.Image.Image、np.ndarray与torch.Tensor三种格式。常用工具方法一览方法作用to_pil_image转 PIL 图像浮点数组默认按×255缩放并转uint8必要时把通道维移回末尾image_utils.pyconvert_rgb将 PIL 图像转为 RGB 格式image_utils.pyrescale对 numpy 图像乘以缩放系数image_utils.pyto_numpy_array转 NumPy 数组默认把通道维放到最前channel_firstTrue并可选缩放到[0, 1]image_utils.pynormalize按逐通道mean/std归一化image_utils.pyresize调整尺寸支持default_to_square与max_sizeimage_utils.pycenter_crop中心裁剪到指定尺寸image_utils.pyflip_channel_order通道顺序翻转如 RGB ↔ BGRimage_utils.py配合使用示例from transformers.image_utils import ImageFeatureExtractionMixin mixin ImageFeatureExtractionMixin() image mixin.convert_rgb(pil_image) # 统一为 RGB array mixin.to_numpy_array(image) # (C, H, W)值域 [0, 1] array mixin.resize(array, (224, 224)) # 缩放到模型期望尺寸 array mixin.center_crop(array, (224, 224)) # 中心裁剪 array mixin.normalize(array, mean[0.5, 0.5, 0.5], std[0.5, 0.5, 0.5]) # 归一化面向现代生态从 Feature Extractor 到 Processor需要说明的是原文档 feature_extractor.md 描述的是较早的设计形态。在当前仓库中图像侧的能力已逐渐迁移到ImageProcessor见 image_processing_base.py 中的BatchFeature相关实现而语音识别等模态则由Processor如Wav2Vec2Processor统一编排 tokenizer 与 feature extractor。从get_feature_extractor_dict优先解析processor_config.json的加载逻辑feature_extraction_utils.py可以看出新老格式的兼容是当前仓库的默认行为旧代码中直接调用 feature extractor 的方式依然可用。理解本文的四大类是进一步掌握AutoFeatureExtractor与多模态Processor体系的基础。【免费下载链接】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），仅供参考