Hugging Face Transformers 视觉模型开发指南为图像与视频模型添加 Image/Video 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本文聚焦 Transformers 仓库中《Add vision processing components》官方文档所讲的开发主题为一个视觉图像或视频模型补齐预处理组件。你将掌握双后端图像处理器TorchvisionBackend/PilBackend的完整写法、BaseVideoProcessor视频处理器的默认值与帧采样机制、模型__init__.py的懒加载注册与Auto映射生成流程以及配套测试 mixin 的编写方式最终能够独立为一个新视觉模型交付可复用的预处理栈。前置条件先完成 modeling 与 config添加视觉处理组件不是孤立的一步。文档明确指出模型定义modeling与配置config部分应遵循 modular 指南先行完成视觉处理器是在 modular 流程之上追加的一层。也就是说标准工作流是按 modular 方式写好configuration_model_name.py与modeling_model_name.py或 modular 源文件若模型消费图像再创建图像处理器image processor若模型消费视频或采样视频帧再创建视频处理器video processor注册类、生成 Auto 映射、补测试。两类处理器分别位于 [AutoImageProcessor] 与 [AutoVideoProcessor] 入口点之后用户通过Auto*类按preprocessor_config.json/ 模型类型自动解析到具体实现。图像处理器双后端架构为什么需要两个类文档给出的核心约束是torchvision 后端是默认后端并支持 GPU 加速PIL 是 torchvision 不可用时的兜底fallback。两个图像处理器类共享同一套预处理逻辑但后端不同因此必须成对创建image_processing_model_name.py继承 [TorchvisionBackend]image_processing_pil_model_name.py继承 [PilBackend]类名以Pil结尾如MyModelImageProcessorPil。文档特别强调两个类的构造器签名和默认值必须完全一致。原因是 [AutoImageProcessor.from_pretrained] 在加载时选择后端同一份保存的配置saved config会落到不同的环境中如果两边签名或默认值不一致同一 checkpoint 在不同环境里行为就会漂移。这一点在源码中可以得到印证后端解析逻辑位于 image_processing_auto.py 的_resolve_backend当显式 backend 未指定时torchvision 可用则选torchvision否则回退pil随后_load_class_with_fallback还会在请求的后端不可用例如对应依赖缺失、类表现为DummyObject时按序尝试其余后端并打印 fallback 警告。此外use_fast参数已被弃用官方建议显式传backendtorchvision或backendpil。从仓库实际模型目录看这个双文件约定是普遍模式例如 llava_onevision 目录 下同时存在image_processing_llava_onevision.py与image_processing_pil_llava_onevision.py。torchvision 后端写法创建image_processing_model_name.py继承 [TorchvisionBackend]如果除标准 [ImagesKwargs] 外还需要自定义参数先定义一个 kwargs 类from ...image_processing_backends import TorchvisionBackend from ...image_utils import OPENAI_CLIP_MEAN, OPENAI_CLIP_STD, PILImageResampling from ...processing_utils import ImagesKwargs, Unpack from ...utils import auto_docstring class MyModelImageProcessorKwargs(ImagesKwargs, totalFalse): tile_size: int # any model-specific kwargs auto_docstring class MyModelImageProcessor(TorchvisionBackend): resample PILImageResampling.BICUBIC image_mean OPENAI_CLIP_MEAN image_std OPENAI_CLIP_STD size {shortest_edge: 224} do_resize True do_rescale True do_normalize True do_convert_rgb True def __init__(self, **kwargs: Unpack[MyModelImageProcessorKwargs]): super().__init__(**kwargs)文档建议参考 [LlavaOnevisionImageProcessor] 作为实现范本。对照其真实源码image_processing_llava_onevision.py可以补充理解几处细节类属性即默认值resample、image_mean、image_std、size、do_resize、do_rescale、do_normalize、do_convert_rgb等都是“默认预处理值”用户在实例化或调用时均可覆盖。model_input_namesLlavaOnevisionImageProcessor声明为[pixel_values, image_sizes, batch_num_images]即preprocess除了pixel_values外还会输出额外的模型输入键默认情况下处理器输出键是pixel_values。valid_kwargs显式指定为LlavaOnevisionImageProcessorKwargs用于运行时参数校验与自动生成文档字符串。kwargs 类承载自定义参数LlavaOnevisionImageProcessorKwargs里声明了image_grid_pinpoints: list[list[int]]这一高分辨率分辨率选择参数配合auto_docstring生成文档。从源码结构看TorchvisionBackend定义于 image_processing_backends.py本身实现了完整的预处理管线_preprocess按形状分组批量 resizegroup_images_by_shape、center crop、融合 rescale 与 normalizerescale_and_normalize其中用lru_cache缓存 mean/std 张量以融合缩放因子、以及do_pad时按最大尺寸 pad 并可返回 mask最终统一包装为BatchFeature(data{pixel_values: ...})。子类只需声明默认值管线逻辑全部继承。值得注意的是resize中对 LANCZOS 插值的处理torchvision 0.27 或非 CPU 设备时会自动降级为 BICUBIC 并告警image_processing_backends.py这也是 Auto 层存在DEFAULT_TO_PIL_BACKEND_IMAGE_PROCESSORS强制走 PIL 后端以保留 Lanczos 语义的动机之一。PIL 后端写法创建image_processing_pil_model_name.py继承 [PilBackend]。文档给出两条硬性规则kwargs 类要“复制”而不是“导入”PIL 文件中必须重新定义 kwargs 类# Adapted from ...注释标明来源因为 PIL 文件需要在未安装 torchvision 的环境中也能被导入跨文件 import 会引入不必要的依赖耦合加# Adapted from注释让两份代码保持同步这是仓库内两个 PIL 变体文件的标准约定。如果没有自定义参数直接使用 [ImagesKwargs]无需子类化from ...image_processing_backends import PilBackend from ...image_utils import OPENAI_CLIP_MEAN, OPENAI_CLIP_STD, PILImageResampling from ...processing_utils import ImagesKwargs, Unpack from ...utils import auto_docstring # Adapted from transformers.models.my_model.image_processing_my_model.MyModelImageProcessorKwargs class MyModelImageProcessorKwargs(ImagesKwargs, totalFalse): tile_size: int # any model-specific kwargs auto_docstring class MyModelImageProcessorPil(PilBackend): resample PILImageResampling.BICUBIC image_mean OPENAI_CLIP_MEAN image_std OPENAI_CLIP_STD size {shortest_edge: 224} do_resize True do_rescale True do_normalize True do_convert_rgb True def __init__(self, **kwargs: Unpack[MyModelImageProcessorKwargs]): super().__init__(**kwargs)参考实现为 [LlavaOnevisionImageProcessorPil]。从源码结构看PilBackendimage_processing_backends.py与 torchvision 后端逐一对应地实现了resize/rescale/normalize/center_crop/pad的 NumPy 版本_preprocess则是逐张串行处理无 GPU 批量路径。它还有一个to_dict重写保存配置时自动剥掉类名的Pil后缀image_processor_type确保两个后端保存出同一份处理器类型标识——这正是“同一 saved config 跨环境行为一致”机制落地的关键一环。后处理方法post-processing后处理方法直接加在处理器类上签名为“模型输出 该任务所需额外参数”class MyModelImageProcessor(TorchvisionBackend): ... def post_process_my_task(self, outputs, ...): ...后处理器返回两种形态之一简单对象列表list[str]或list[torch.Tensor]或复杂对象列表list[MyTaskPostProcessorOutput]或list[dict]。复杂输出类型定义在 image_processing_outputs.py继承自 [BatchFeature]class MyTaskPostProcessorOutput(BatchFeature): predictions: torch.Tensor scores: torch.Tensor视频处理器当模型消费视频或采样的视频帧时在模型目录创建video_processing_model_name.py。[BaseVideoProcessor]定义于 video_processing_utils.py继承自 [TorchvisionBackend]提供共享的视频解码、帧采样、resize、rescale、归一化、保存与加载行为。类属性即默认预处理值用户可在初始化或调用时覆盖文档建议尽量沿用 [VideosKwargs] 的命名size、crop_size、do_resize、do_sample_frames、num_frames、fps等。需要自定义参数时定义 kwargs 类设为valid_kwargs并用于__init__的类型标注同时服务运行时校验与自动文档字符串from ...processing_utils import Unpack, VideosKwargs from ...utils import auto_docstring from ...video_processing_utils import BaseVideoProcessor class MyModelVideoProcessorKwargs(VideosKwargs, totalFalse): min_frames: int max_frames: int auto_docstring class MyModelVideoProcessor(BaseVideoProcessor): size {shortest_edge: 224} crop_size {height: 224, width: 224} do_resize True do_center_crop True do_normalize True do_sample_frames True num_frames 16 model_input_names [pixel_values_videos] valid_kwargs MyModelVideoProcessorKwargs def __init__(self, **kwargs: Unpack[MyModelVideoProcessorKwargs]): super().__init__(**kwargs)何时覆写sample_frames文档的准则是只在基础均匀采样器表达不了的规则出现时才覆写[~BaseVideoProcessor.sample_frames]例如某些模型要求最少/最多帧数或按模型特定约束采样。对照源码可以看到默认实现的行为边界video_processing_utils.py默认按num_frames在[0, total_num_frames)内均匀取整点索引若传fps则结合metadata.fps换算帧数此时必须有VideoMetadata否则报错num_frames与fps互斥且num_frames total_num_frames时直接抛错。也就是说若你的模型要求“至少 16 帧、至多 128 帧”这类钳位语义就需要按文档示例min_frames/max_frameskwargs覆写sample_frames。参考实现为 [Qwen3VLVideoProcessor]。兼容 legacy 输入名覆写preprocess如果模型的forward期望的输入名不是默认的pixel_values_videos例如仍是pixel_values覆写preprocess在基类实现之后重命名键class MyModelVideoProcessor(BaseVideoProcessor): model_input_names [pixel_values] def preprocess(self, videos, **kwargs): batch super().preprocess(videos, **kwargs) batch[pixel_values] batch.pop(pixel_values_videos) return batch保存与加载视频处理器要与 checkpoint 一起保存在权重转换脚本conversion script中实例化处理器并调用 [~BaseVideoProcessor.save_pretrained]如果 [ProcessorMixin] 包装了视频处理器则改调 [~ProcessorMixin.save_pretrained]。文档特别警告不要手工创建或编辑预处理配置文件preprocessing config files一切以save_pretrained的自动输出为准。注册类与 Auto 映射模型包__init__.py把处理类从模型包的__init__.py暴露出来。文档要求遵循相邻模型的懒加载lazy import模式并按各后端所需的可选项依赖守卫导入。仓库中的标准形态见 llava_onevision/init.pyif TYPE_CHECKING: from .configuration_llava_onevision import * from .image_processing_llava_onevision import * from .image_processing_pil_llava_onevision import * from .modeling_llava_onevision import * from .processing_llava_onevision import * from .video_processing_llava_onevision import * else: import sys _file globals()[__file__] sys.modules[__name__] _LazyModule(__name__, _file, define_import_structure(_file), module_spec__spec__)_LazyModuledefine_import_structure使得torchvision或 Pillow 缺失时对应处理类会被替换为占位的DummyObject而导入本身不失败——Auto 层的 fallback 机制正是依赖这一行为。生成 Auto 映射把新类映射到模型配置后Auto*类才能加载它们。文档强调生成的 auto mapping 文件顶部带有“禁止手改”警告正确做法是添加或更新模型配置后运行脚本重新生成python utils/check_auto.py --fix_and_overwrite生成完成后在 auto_mappings.py 中验证模型类型出现在相应映射里IMAGE_PROCESSOR_MAPPING_NAMES供 [AutoImageProcessor] 使用VIDEO_PROCESSOR_MAPPING_NAMES供 [AutoVideoProcessor] 使用。以 llava_onevision 为例实际映射形态auto_mappings.py 与 第 1001 行(llava_onevision, {pil: LlavaOnevisionImageProcessorPil, torchvision: LlavaOnevisionImageProcessor}) (llava_onevision, LlavaOnevisionVideoProcessor)注意图像处理器映射是{backend: class}字典而非单值字符串——这就是双后端机制在 Auto 映射中的落点。测试每个视觉处理组件都要在模型测试目录加测试图像与视频处理器测试模式一致继承共享 mixin、在自动发现不足时显式指明 fast/slow 处理类、提供模型特定的 init kwargs、在模型使用非默认输出键时覆写输入名。图像处理器测试图像处理器测试通常位于tests/models/model_name/test_image_processing_model_name.py继承 [ImageProcessingTestMixin]。该 mixin 从IMAGE_PROCESSOR_MAPPING_NAMES发现处理器类模型特定默认值通过image_processor_dict属性提供只有需要可复用 dummy 输入或辅助方法聚焦测试时才添加 tester 对象from transformers.testing_utils import require_torch, require_vision from ...test_image_processing_common import ImageProcessingTestMixin require_torch require_vision class MyModelImageProcessingTest(ImageProcessingTestMixin, unittest.TestCase): property def image_processor_dict(self): return {size: {shortest_edge: 224}, do_resize: True}对 mixin 无法推断的行为自定义 resize 规则、模型特定 kwargs补充聚焦测试。后处理测试 mixin 位于 test_image_processing_common.py叠加在 [ImageProcessingTestMixin] 之上class MyModelImageProcessingTest(ImageProcessingTestMixin, MyTaskPostProcessTestMixin, unittest.TestCase):文档还说明测试会自动校验模型使用了正确的 mixin新任务对应的后处理 mixin 必须添加到tests/test_image_processing_common.py中。视频处理器测试视频处理器测试通常位于tests/models/model_name/test_video_processing_model_name.py继承 [VideoProcessingTestMixin]。设置fast_video_processing_class、定义video_processor_dict若模型使用pixel_values_videos之外的键则覆写input_namefrom transformers.testing_utils import require_torch, require_vision from transformers.utils import is_torchvision_available from ...test_video_processing_common import VideoProcessingTestMixin require_torch require_vision class MyModelVideoProcessingTest(VideoProcessingTestMixin, unittest.TestCase): fast_video_processing_class MyModelVideoProcessor if is_torchvision_available() else None input_name pixel_values_videos property def video_processor_dict(self): return {size: {shortest_edge: 224}, num_frames: 16}聚焦视频测试应覆盖帧采样、元数据处理metadata、解码后的视频输入、帧列表输入、输出形状如果处理器重命名了pixel_values_videos要断言返回的是重命名后的键。Processor 包装层的测试如果模型还有 [ProcessorMixin] 包装图像/视频处理器另加tests/models/model_name/test_processing_model_name.py继承 [ProcessorTesterMixin]设置processor_class对无法无参构造的组件覆写_setup_component()类方法用_setup_test_attributes()暴露公共处理器测试用到的占位 tokenfrom ...test_processing_common import ProcessorTesterMixin class MyModelProcessorTest(ProcessorTesterMixin, unittest.TestCase): processor_class MyModelProcessor classmethod def _setup_image_processor(cls): return cls._get_component_class_from_processor(image_processor)(size{shortest_edge: 224}) classmethod def _setup_video_processor(cls): return cls._get_component_class_from_processor(video_processor)(num_frames2) classmethod def _setup_test_attributes(cls, processor): cls.image_token getattr(processor, image_token, ) cls.video_token getattr(processor, video_token, )后续步骤与延伸阅读阅读 Auto-generating docstrings 指南用auto_docstring自动生成一致的文档字符串本文所有处理器示例均已使用阅读 Image processors 与 Video processors 指南了解面向用户user-facing的预处理行为语义。【免费下载链接】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），仅供参考 Hugging Face Transformers 视觉模型开发指南：为图像与视频模型添加 Image/Video Processor 组件
Hugging Face Transformers 视觉模型开发指南为图像与视频模型添加 Image/Video 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本文聚焦 Transformers 仓库中《Add vision processing components》官方文档所讲的开发主题为一个视觉图像或视频模型补齐预处理组件。你将掌握双后端图像处理器TorchvisionBackend/PilBackend的完整写法、BaseVideoProcessor视频处理器的默认值与帧采样机制、模型__init__.py的懒加载注册与Auto映射生成流程以及配套测试 mixin 的编写方式最终能够独立为一个新视觉模型交付可复用的预处理栈。前置条件先完成 modeling 与 config添加视觉处理组件不是孤立的一步。文档明确指出模型定义modeling与配置config部分应遵循 modular 指南先行完成视觉处理器是在 modular 流程之上追加的一层。也就是说标准工作流是按 modular 方式写好configuration_model_name.py与modeling_model_name.py或 modular 源文件若模型消费图像再创建图像处理器image processor若模型消费视频或采样视频帧再创建视频处理器video processor注册类、生成 Auto 映射、补测试。两类处理器分别位于 [AutoImageProcessor] 与 [AutoVideoProcessor] 入口点之后用户通过Auto*类按preprocessor_config.json/ 模型类型自动解析到具体实现。图像处理器双后端架构为什么需要两个类文档给出的核心约束是torchvision 后端是默认后端并支持 GPU 加速PIL 是 torchvision 不可用时的兜底fallback。两个图像处理器类共享同一套预处理逻辑但后端不同因此必须成对创建image_processing_model_name.py继承 [TorchvisionBackend]image_processing_pil_model_name.py继承 [PilBackend]类名以Pil结尾如MyModelImageProcessorPil。文档特别强调两个类的构造器签名和默认值必须完全一致。原因是 [AutoImageProcessor.from_pretrained] 在加载时选择后端同一份保存的配置saved config会落到不同的环境中如果两边签名或默认值不一致同一 checkpoint 在不同环境里行为就会漂移。这一点在源码中可以得到印证后端解析逻辑位于 image_processing_auto.py 的_resolve_backend当显式 backend 未指定时torchvision 可用则选torchvision否则回退pil随后_load_class_with_fallback还会在请求的后端不可用例如对应依赖缺失、类表现为DummyObject时按序尝试其余后端并打印 fallback 警告。此外use_fast参数已被弃用官方建议显式传backendtorchvision或backendpil。从仓库实际模型目录看这个双文件约定是普遍模式例如 llava_onevision 目录 下同时存在image_processing_llava_onevision.py与image_processing_pil_llava_onevision.py。torchvision 后端写法创建image_processing_model_name.py继承 [TorchvisionBackend]如果除标准 [ImagesKwargs] 外还需要自定义参数先定义一个 kwargs 类from ...image_processing_backends import TorchvisionBackend from ...image_utils import OPENAI_CLIP_MEAN, OPENAI_CLIP_STD, PILImageResampling from ...processing_utils import ImagesKwargs, Unpack from ...utils import auto_docstring class MyModelImageProcessorKwargs(ImagesKwargs, totalFalse): tile_size: int # any model-specific kwargs auto_docstring class MyModelImageProcessor(TorchvisionBackend): resample PILImageResampling.BICUBIC image_mean OPENAI_CLIP_MEAN image_std OPENAI_CLIP_STD size {shortest_edge: 224} do_resize True do_rescale True do_normalize True do_convert_rgb True def __init__(self, **kwargs: Unpack[MyModelImageProcessorKwargs]): super().__init__(**kwargs)文档建议参考 [LlavaOnevisionImageProcessor] 作为实现范本。对照其真实源码image_processing_llava_onevision.py可以补充理解几处细节类属性即默认值resample、image_mean、image_std、size、do_resize、do_rescale、do_normalize、do_convert_rgb等都是“默认预处理值”用户在实例化或调用时均可覆盖。model_input_namesLlavaOnevisionImageProcessor声明为[pixel_values, image_sizes, batch_num_images]即preprocess除了pixel_values外还会输出额外的模型输入键默认情况下处理器输出键是pixel_values。valid_kwargs显式指定为LlavaOnevisionImageProcessorKwargs用于运行时参数校验与自动生成文档字符串。kwargs 类承载自定义参数LlavaOnevisionImageProcessorKwargs里声明了image_grid_pinpoints: list[list[int]]这一高分辨率分辨率选择参数配合auto_docstring生成文档。从源码结构看TorchvisionBackend定义于 image_processing_backends.py本身实现了完整的预处理管线_preprocess按形状分组批量 resizegroup_images_by_shape、center crop、融合 rescale 与 normalizerescale_and_normalize其中用lru_cache缓存 mean/std 张量以融合缩放因子、以及do_pad时按最大尺寸 pad 并可返回 mask最终统一包装为BatchFeature(data{pixel_values: ...})。子类只需声明默认值管线逻辑全部继承。值得注意的是resize中对 LANCZOS 插值的处理torchvision 0.27 或非 CPU 设备时会自动降级为 BICUBIC 并告警image_processing_backends.py这也是 Auto 层存在DEFAULT_TO_PIL_BACKEND_IMAGE_PROCESSORS强制走 PIL 后端以保留 Lanczos 语义的动机之一。PIL 后端写法创建image_processing_pil_model_name.py继承 [PilBackend]。文档给出两条硬性规则kwargs 类要“复制”而不是“导入”PIL 文件中必须重新定义 kwargs 类# Adapted from ...注释标明来源因为 PIL 文件需要在未安装 torchvision 的环境中也能被导入跨文件 import 会引入不必要的依赖耦合加# Adapted from注释让两份代码保持同步这是仓库内两个 PIL 变体文件的标准约定。如果没有自定义参数直接使用 [ImagesKwargs]无需子类化from ...image_processing_backends import PilBackend from ...image_utils import OPENAI_CLIP_MEAN, OPENAI_CLIP_STD, PILImageResampling from ...processing_utils import ImagesKwargs, Unpack from ...utils import auto_docstring # Adapted from transformers.models.my_model.image_processing_my_model.MyModelImageProcessorKwargs class MyModelImageProcessorKwargs(ImagesKwargs, totalFalse): tile_size: int # any model-specific kwargs auto_docstring class MyModelImageProcessorPil(PilBackend): resample PILImageResampling.BICUBIC image_mean OPENAI_CLIP_MEAN image_std OPENAI_CLIP_STD size {shortest_edge: 224} do_resize True do_rescale True do_normalize True do_convert_rgb True def __init__(self, **kwargs: Unpack[MyModelImageProcessorKwargs]): super().__init__(**kwargs)参考实现为 [LlavaOnevisionImageProcessorPil]。从源码结构看PilBackendimage_processing_backends.py与 torchvision 后端逐一对应地实现了resize/rescale/normalize/center_crop/pad的 NumPy 版本_preprocess则是逐张串行处理无 GPU 批量路径。它还有一个to_dict重写保存配置时自动剥掉类名的Pil后缀image_processor_type确保两个后端保存出同一份处理器类型标识——这正是“同一 saved config 跨环境行为一致”机制落地的关键一环。后处理方法post-processing后处理方法直接加在处理器类上签名为“模型输出 该任务所需额外参数”class MyModelImageProcessor(TorchvisionBackend): ... def post_process_my_task(self, outputs, ...): ...后处理器返回两种形态之一简单对象列表list[str]或list[torch.Tensor]或复杂对象列表list[MyTaskPostProcessorOutput]或list[dict]。复杂输出类型定义在 image_processing_outputs.py继承自 [BatchFeature]class MyTaskPostProcessorOutput(BatchFeature): predictions: torch.Tensor scores: torch.Tensor视频处理器当模型消费视频或采样的视频帧时在模型目录创建video_processing_model_name.py。[BaseVideoProcessor]定义于 video_processing_utils.py继承自 [TorchvisionBackend]提供共享的视频解码、帧采样、resize、rescale、归一化、保存与加载行为。类属性即默认预处理值用户可在初始化或调用时覆盖文档建议尽量沿用 [VideosKwargs] 的命名size、crop_size、do_resize、do_sample_frames、num_frames、fps等。需要自定义参数时定义 kwargs 类设为valid_kwargs并用于__init__的类型标注同时服务运行时校验与自动文档字符串from ...processing_utils import Unpack, VideosKwargs from ...utils import auto_docstring from ...video_processing_utils import BaseVideoProcessor class MyModelVideoProcessorKwargs(VideosKwargs, totalFalse): min_frames: int max_frames: int auto_docstring class MyModelVideoProcessor(BaseVideoProcessor): size {shortest_edge: 224} crop_size {height: 224, width: 224} do_resize True do_center_crop True do_normalize True do_sample_frames True num_frames 16 model_input_names [pixel_values_videos] valid_kwargs MyModelVideoProcessorKwargs def __init__(self, **kwargs: Unpack[MyModelVideoProcessorKwargs]): super().__init__(**kwargs)何时覆写sample_frames文档的准则是只在基础均匀采样器表达不了的规则出现时才覆写[~BaseVideoProcessor.sample_frames]例如某些模型要求最少/最多帧数或按模型特定约束采样。对照源码可以看到默认实现的行为边界video_processing_utils.py默认按num_frames在[0, total_num_frames)内均匀取整点索引若传fps则结合metadata.fps换算帧数此时必须有VideoMetadata否则报错num_frames与fps互斥且num_frames total_num_frames时直接抛错。也就是说若你的模型要求“至少 16 帧、至多 128 帧”这类钳位语义就需要按文档示例min_frames/max_frameskwargs覆写sample_frames。参考实现为 [Qwen3VLVideoProcessor]。兼容 legacy 输入名覆写preprocess如果模型的forward期望的输入名不是默认的pixel_values_videos例如仍是pixel_values覆写preprocess在基类实现之后重命名键class MyModelVideoProcessor(BaseVideoProcessor): model_input_names [pixel_values] def preprocess(self, videos, **kwargs): batch super().preprocess(videos, **kwargs) batch[pixel_values] batch.pop(pixel_values_videos) return batch保存与加载视频处理器要与 checkpoint 一起保存在权重转换脚本conversion script中实例化处理器并调用 [~BaseVideoProcessor.save_pretrained]如果 [ProcessorMixin] 包装了视频处理器则改调 [~ProcessorMixin.save_pretrained]。文档特别警告不要手工创建或编辑预处理配置文件preprocessing config files一切以save_pretrained的自动输出为准。注册类与 Auto 映射模型包__init__.py把处理类从模型包的__init__.py暴露出来。文档要求遵循相邻模型的懒加载lazy import模式并按各后端所需的可选项依赖守卫导入。仓库中的标准形态见 llava_onevision/init.pyif TYPE_CHECKING: from .configuration_llava_onevision import * from .image_processing_llava_onevision import * from .image_processing_pil_llava_onevision import * from .modeling_llava_onevision import * from .processing_llava_onevision import * from .video_processing_llava_onevision import * else: import sys _file globals()[__file__] sys.modules[__name__] _LazyModule(__name__, _file, define_import_structure(_file), module_spec__spec__)_LazyModuledefine_import_structure使得torchvision或 Pillow 缺失时对应处理类会被替换为占位的DummyObject而导入本身不失败——Auto 层的 fallback 机制正是依赖这一行为。生成 Auto 映射把新类映射到模型配置后Auto*类才能加载它们。文档强调生成的 auto mapping 文件顶部带有“禁止手改”警告正确做法是添加或更新模型配置后运行脚本重新生成python utils/check_auto.py --fix_and_overwrite生成完成后在 auto_mappings.py 中验证模型类型出现在相应映射里IMAGE_PROCESSOR_MAPPING_NAMES供 [AutoImageProcessor] 使用VIDEO_PROCESSOR_MAPPING_NAMES供 [AutoVideoProcessor] 使用。以 llava_onevision 为例实际映射形态auto_mappings.py 与 第 1001 行(llava_onevision, {pil: LlavaOnevisionImageProcessorPil, torchvision: LlavaOnevisionImageProcessor}) (llava_onevision, LlavaOnevisionVideoProcessor)注意图像处理器映射是{backend: class}字典而非单值字符串——这就是双后端机制在 Auto 映射中的落点。测试每个视觉处理组件都要在模型测试目录加测试图像与视频处理器测试模式一致继承共享 mixin、在自动发现不足时显式指明 fast/slow 处理类、提供模型特定的 init kwargs、在模型使用非默认输出键时覆写输入名。图像处理器测试图像处理器测试通常位于tests/models/model_name/test_image_processing_model_name.py继承 [ImageProcessingTestMixin]。该 mixin 从IMAGE_PROCESSOR_MAPPING_NAMES发现处理器类模型特定默认值通过image_processor_dict属性提供只有需要可复用 dummy 输入或辅助方法聚焦测试时才添加 tester 对象from transformers.testing_utils import require_torch, require_vision from ...test_image_processing_common import ImageProcessingTestMixin require_torch require_vision class MyModelImageProcessingTest(ImageProcessingTestMixin, unittest.TestCase): property def image_processor_dict(self): return {size: {shortest_edge: 224}, do_resize: True}对 mixin 无法推断的行为自定义 resize 规则、模型特定 kwargs补充聚焦测试。后处理测试 mixin 位于 test_image_processing_common.py叠加在 [ImageProcessingTestMixin] 之上class MyModelImageProcessingTest(ImageProcessingTestMixin, MyTaskPostProcessTestMixin, unittest.TestCase):文档还说明测试会自动校验模型使用了正确的 mixin新任务对应的后处理 mixin 必须添加到tests/test_image_processing_common.py中。视频处理器测试视频处理器测试通常位于tests/models/model_name/test_video_processing_model_name.py继承 [VideoProcessingTestMixin]。设置fast_video_processing_class、定义video_processor_dict若模型使用pixel_values_videos之外的键则覆写input_namefrom transformers.testing_utils import require_torch, require_vision from transformers.utils import is_torchvision_available from ...test_video_processing_common import VideoProcessingTestMixin require_torch require_vision class MyModelVideoProcessingTest(VideoProcessingTestMixin, unittest.TestCase): fast_video_processing_class MyModelVideoProcessor if is_torchvision_available() else None input_name pixel_values_videos property def video_processor_dict(self): return {size: {shortest_edge: 224}, num_frames: 16}聚焦视频测试应覆盖帧采样、元数据处理metadata、解码后的视频输入、帧列表输入、输出形状如果处理器重命名了pixel_values_videos要断言返回的是重命名后的键。Processor 包装层的测试如果模型还有 [ProcessorMixin] 包装图像/视频处理器另加tests/models/model_name/test_processing_model_name.py继承 [ProcessorTesterMixin]设置processor_class对无法无参构造的组件覆写_setup_component()类方法用_setup_test_attributes()暴露公共处理器测试用到的占位 tokenfrom ...test_processing_common import ProcessorTesterMixin class MyModelProcessorTest(ProcessorTesterMixin, unittest.TestCase): processor_class MyModelProcessor classmethod def _setup_image_processor(cls): return cls._get_component_class_from_processor(image_processor)(size{shortest_edge: 224}) classmethod def _setup_video_processor(cls): return cls._get_component_class_from_processor(video_processor)(num_frames2) classmethod def _setup_test_attributes(cls, processor): cls.image_token getattr(processor, image_token, ) cls.video_token getattr(processor, video_token, )后续步骤与延伸阅读阅读 Auto-generating docstrings 指南用auto_docstring自动生成一致的文档字符串本文所有处理器示例均已使用阅读 Image processors 与 Video processors 指南了解面向用户user-facing的预处理行为语义。【免费下载链接】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），仅供参考