Transformers documentation

Procesadores multimodales

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Procesadores multimodales

Un procesador combina un tokenizador con uno o varios procesadores de modalidades, como un procesador de imágenes, un procesador de video o un extractor de características. Expone un único método __call__ que enruta cada entrada al componente adecuado y fusiona las salidas en un único diccionario.

Algunos modelos multimodales intercalan texto con imágenes, vídeos o audio. Para estos modelos, ProcessorMixin puede reemplazar los tokens de marcador de posición como <image>, <video> y <audio> con el patrón de tokens esperado por el modelo.

Agregar un nuevo procesador

Defina una clase de procesador creando src/transformers/models/<model>/processing_<my_model_name>.py y subclase ProcessorMixin. Asegúrese de definir un objeto TypedDict con valores predeterminados y asignarlo como cls.valid_processor_kwargs

from ...processing_utils import ProcessorMixin

class MyModelProcessor(ProcessorMixin):

    def __init__(self, image_processor, tokenizer, chat_template=None, **kwargs):
        self.image_token = tokenizer.image_token
        self.image_token_id = tokenizer.image_token_id
        super().__init__(
            image_processor=image_processor,
            tokenizer=tokenizer,
            chat_template=chat_template,
            **kwargs,
        )

Implementa replace_<modality>_token si es necesario. Recibe el diccionario de salida completo del subprocesador y el índice de la entrada actual, y devuelve la cadena de reemplazo expandida para esa entrada. La cadena de reemplazo es lo que el modelo espera en la secuencia de entrada.

Si el modelo no utiliza repetición de marcadores en absoluto (no se define image_token), no es necesario sobrescribir este método. Deja self.image_token sin establecer y la clase base omitirá la sustitución por completo.

def replace_image_token(self, image_inputs: dict, image_idx: int) -> str:
    num_crops = image_inputs["num_crops"][image_idx]
    return f"{self.boi_token}{self.image_token * self.num_image_tokens * num_crops}{self.eoi_token}"

Opcionalmente, sobrescriba los métodos prepare_inputs_layout y validate_inputs. Si el modelo requiere una estructura de entrada específica antes de que comience el procesamiento, como reordenar las imágenes en una lista anidada, o una validación específica del modelo además de las comprobaciones comunes.

def prepare_inputs_layout(self, images=None, text=None, videos=None, audio=None, **kwargs):
    # Call `super()` to apply common preparation steps first 
    images, text, videos, audio = super().prepare_inputs_layout(images, text, videos, audio)
    if images is not None:
        images = make_nested_list_of_images(images)
    return images, text, videos, audio

def validate_inputs(self, images=None, text=None, videos=None, audio=None, **kwargs):
    super().validate_inputs(images=images, text=text, **kwargs)
    if text is not None and images is not None:
        n_tokens = [s.count(self.image_token) for s in text]
        n_images = [len(img_list) for img_list in images]
        if n_tokens != n_images:
            raise ValueError(
                f"Number of {self.image_token} tokens in text {n_tokens} does not match "
                f"number of images {n_images}."
            )

Consulte Gemma4Processor y Qwen2VLProcessor como referencia.

Agregar argumentos personalizados

Hay tres formas de agregar argumentos personalizados a un procesador:

Dónde agregarUsoValor predeterminadoConfigurable en tiempo de ejecuciónEjemplo
__init__Ajustes guardados en la configuración (propiedades del modelo)Normalmente tiene un valor predeterminadoNoimage_seq_length en Gemma3Processor
__call__Entradas conocidas solo en tiempo de ejecuciónSin valor predeterminado o NoneSíimages, labels, suffix, etc.
Clase MyModelProcessingKwargs personalizadaConfiguraciones que se pueden configurar en tiempo de ejecuciónEstablecer como atributo de la clase procesadoraSíuse_image_id en MiniCPMV4_7Processor

Los argumentos de tiempo de ejecución que pueden tener un valor predeterminado deben agregarse a un MyModelProcessingKwargs personalizado y se pasarán como parte de **kwargs a __call__. Los valores predeterminados para estos valores se pueden establecer como atributos de la clase del procesador. Los valores predeterminados para los procesadores específicos de la modalidad, por ejemplo, el tokenizador o el procesador de imágenes, se pueden definir de la misma manera. Esto generalmente no es necesario, ya que los procesadores específicos de la modalidad ya tienen valores predeterminados definidos en sus respectivas clases. Utilice esta opción solo si el procesador debe sobrescribir una configuración de un procesador específico de la modalidad. Por supuesto, los argumentos pasados en tiempo de ejecución a __call__ siempre tienen mayor prioridad que cualquier valor predeterminado.

from ...processing_utils import ProcessingKwargs, ProcessorMixin, Unpack

class MyModelProcessorKwargs(ProcessingKwargs, total=False):
    """
    use_image_id (`bool`, defaults to `False`):
        Whether to prepend an image-id tag (``<image_id>N</image_id>``) before
        each image placeholder.
    """
    use_image_id: bool


class MyModelProcessor(ProcessorMixin):
    valid_processor_kwargs = MyModelProcessorKwargs
    use_image_id = False

    text_kwargs = {"padding": True}   # default passed to tokenizer

    def __init__(self, image_processor=None, tokenizer=None, chat_template=None, image_seq_length: int = 256, **kwargs):
        super().__init__(image_processor, tokenizer, chat_template=chat_template, **kwargs)
        self.image_seq_length = image_seq_length

    @auto_docstring
    def __call__(
        self,
        images: ImageInput | None = None,
        text: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None,
        suffix: str | None = None,
        **kwargs: Unpack[MyModelProcessorKwargs],
    ):
        images, text, videos, audio = self.prepare_inputs_layout(images=images, text=text, **kwargs)
        self.validate_inputs(images=images, text=text, **kwargs)

        merged_kwargs = self._merge_kwargs(tokenizer_init_kwargs=self.tokenizer.init_kwargs, **kwargs)

        merged_kwargs["use_image_id"] # is `False` as default from class attribute is added by _merge_kwargs
        merged_kwargs["text_kwargs"]["padding"] # is `True`

Pruebas

Todos los procesadores multimodales deben tener una clase de prueba que herede de ProcessorTesterMixin. Este mixin proporciona una suite estándar que cubre la tokenización, el procesamiento de imágenes, el batching y la codificación de ida y vuelta.

# tests/models/my_model_name/test_processor_<my_model_name>.py

from transformers.testing_utils import require_vision
from transformers.utils import is_vision_available
from ...test_processing_common import ProcessorTesterMixin

if is_vision_available():
    from transformers import MyModelProcessor

@require_vision
class MyModelProcessorTest(ProcessorTesterMixin, unittest.TestCase):
    processor_class = MyModelProcessor

    def get_processor(self):
        return MyModelProcessor.from_pretrained("hf-internal-testing/my-model-test")
Update on GitHub