Hugging Face's logo

Transformers documentation

Procesadores

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Procesadores

Procesadores multimodales

Cualquier modelo multimodal requerirá un objeto para codificar o decodificar los datos que agrupan varias modalidades (entre texto, visión y audio). Esto se gestiona mediante objetos llamados procesadores, que agrupan dos o más objetos de procesamiento, como tokenizadores (para la modalidad de texto), procesadores de imágenes (para visión) y extractores de características (para audio).

Esos procesadores heredan de la siguiente clase base que implementa la funcionalidad de guardado y carga:

clase transformers.ProcessorMixin

< >

( *args**kwargs )

Esta es una clase mixin que se utiliza para proporcionar funcionalidad de guardado/carga para todas las clases de procesador.

__call__

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )

Parámetros

  • images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], opcional) — Imagen a preprocesar. Espera una imagen única o un lote de imágenes con valores de píxeles que van de 0 a 255. Si se pasan imágenes con valores de píxeles entre 0 y 1, establezca do_rescale=False.
  • text (Union[str, list[str], list[list[str]]], opcional) — La secuencia o lote de secuencias que se codificarán. Cada secuencia puede ser una cadena de caracteres o una lista de cadenas de caracteres (cadenas pre-tokenizadas). Si se pasa una entrada pre-tokenizada, establezca is_split_into_words=True para evitar ambigüedad con las entradas por lotes.
  • videos (Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], list[list[PIL.Image.Image]], list[list[numpy.ndarray]], list[list[torch.Tensor]], ~video_utils.URL, list[~video_utils.URL], list[list[~video_utils.URL]], ~video_utils.Path, list[~video_utils.Path], list[list[~video_utils.Path]]], opcional) — Vídeo a preprocesar. Espera un único vídeo o un lote de vídeos con valores de píxeles que van de 0 a 255. Si se pasan vídeos con valores de píxeles entre 0 y 1, establece do_rescale=False.
  • audio (Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]], opcional) — El audio o lote de audios que se va a preparar. Cada audio puede ser un array de NumPy o un tensor de PyTorch. En el caso de un array de NumPy/tensor de PyTorch, cada audio debe tener la forma (C, T), donde C es el número de canales y T es la longitud de la muestra del audio.
  • return_tensors (str o TensorType, opcional) — Si se establece, devolverá tensores de un marco de trabajo específico. Los valores aceptables son:
    • 'pt': Devuelve objetos torch.Tensor de PyTorch.
    • 'np': Devuelve objetos np.ndarray de NumPy.
  • **kwargs (ProcessingKwargs, opcional) — Opciones de procesamiento adicionales para cada modalidad (texto, imágenes, videos, audio). Los parámetros específicos del modelo se enumeran arriba; consulte la clase TypedDict para obtener la lista completa de argumentos admitidos.

prepare_inputs_layout

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )

Normaliza y preobtiene las entradas antes de procesarlas. Envuelve el texto en una lista para los procesadores multimodales, obtiene imágenes y audio remotos si se proporcionan URLs y garantiza que el audio se agrupe correctamente. Devuelve la tupla normalizada (images, text, videos, audio).

validate_inputs

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )

Valida que se proporcione al menos una entrada y que no se utilicen argumentos de palabra clave obsoletos. De lo contrario, lanza ValueError.

Sobrescríbalo cuando el procesador necesite una validación adicional de los argumentos de entrada.

get_text_with_replacements

< >

( text: listimages_replacements: list = []videos_replacements: list = []audio_replacements: list = [] ) → tuple[list[str], list[dict[str, Any]]]

Parámetros

  • text (list[str]) — Lote de cadenas de texto sin procesar, cada una de las cuales puede contener tokens de marcador de posición multimodales. Tenga en cuenta que se modificará in situ y se devolverá.
  • images_replacements (list[str], opcional, valor predeterminado []) — Cadenas de reemplazo expandidas para cada imagen, en el orden en que aparecen en el lote. Generadas por self._process_images.
  • videos_replacements (list[str], opcional, valor predeterminado []) — Cadenas de reemplazo expandidas para cada video. Generadas por self._process_videos.
  • audio_replacements (list[str], opcional, valor predeterminado []) — Cadenas de reemplazo expandidas para cada entrada de audio. Generadas por self._process_audio.

Devuelve

tuple[list[str], list[dict[str, Any]]]

Una tupla de:

  • El lote de text modificado con todos los tokens de marcador de posición expandidos.
  • batch_replacement_offsets: una entrada por elemento del lote, cada una siendo una lista de diccionarios con las claves:
  • “type” (str): nombre de la modalidad — “image”, “video” o “audio”
  • “span” (tuple[int, int]): desplazamientos de caracteres originales (start, end) del token de marcador
  • “new_span” (tuple[int, int]): desplazamientos (start, end) del marcador de posición en la cadena expandida
  • “text” (str): la cadena de token de marcador de posición original que se coincidió
  • “replacement” (str): la cadena con la que se reemplazó

Reemplaza los tokens de marcador de posición multimodales en un lote de cadenas de texto con sus representaciones expandidas y devuelve los textos modificados junto con los metadatos de desplazamiento.

Este método es el paso central de preprocesamiento del lado del texto para entradas multimodales. Recorre cada texto del lote en busca de tokens especiales (imagen, video, audio) y los reemplaza en orden con las cadenas de reemplazo precalculadas generadas por self.replace_image_token / self.replace_video_token / self.replace_audio_token. Los reemplazos se consumen secuencialmente de la lista de cada modalidad, por lo que la i-ésima aparición de, por ejemplo, self.image_token se reemplaza por images_replacements[i].

Para añadir un nuevo procesador multimodal con tokens de marcador de posición, debe definir un self.image_token correcto, que es el mismo token que se incrusta en el texto de entrada y que también se utiliza como marcador de posición y se repite muchas veces. A continuación, debe sobrescribir self.replace_image_token para devolver la cadena de reemplazo correcta para una imagen dada en el índice i. Lo mismo aplica para todas las demás modalidades admitidas.

create_mm_token_type_ids

< >

( input_ids: list ) → list[list[int]]

Parámetros

  • input_ids (list[list[int]]) — Lote de secuencias de ID de tokens. Puede estar sin relleno (longitud variable), por lo que se espera una lista de listas de Python en lugar de un tensor o un array de forma uniforme.

Devuelve

list[list[int]]

Una lista con la misma estructura que input_ids, donde cada entero es el ID de tipo de modalidad para el token correspondiente.

Construye los IDs de tipo de modalidad por token para un lote de secuencias de token_id.

A cada posición se le asigna un entero que indica a qué modalidad pertenece: 0 para texto regular, 1 para tokens de imagen, 2 para tokens de video y 3 para tokens de audio. La pertenencia se determina comparando con self.image_token_ids, self.video_token_ids y self.audio_token_ids.

apply_chat_template

< >

( conversation: list[dict[str, str]] | list[list[dict[str, str]]]chat_template: str | None = Nonetools: list[dict] | None = Nonedocuments: list[dict[str, str]] | None = Noneadd_generation_prompt: bool = Falsecontinue_final_message: bool | str = Falsereturn_assistant_tokens_mask: bool = Falsetokenize: bool = Falsereturn_tensors: str | transformers.utils.generic.TensorType | None = 'auto'return_dict: bool = Falseload_audio_from_video: bool = Falseprocessor_kwargs: dict | None = None**kwargs )

Parámetros

  • conversation (Union[list[Dict, [str, str]], list[list[dict[str, str]]]]) — La conversación a formatear.
  • chat_template (Optional[str], opcional) — La plantilla Jinja que se utilizará para formatear la conversación. Si no se proporciona, se utiliza la plantilla de chat del tokenizador.

De manera similar al método apply_chat_template en los tokenizadores, este método aplica una plantilla Jinja a las conversaciones de entrada para convertirlas en una única cadena tokenizable.

Se espera que la entrada esté en el siguiente formato, donde el contenido de cada mensaje es una lista que consiste en texto y, opcionalmente, entradas de imagen o video. También se puede proporcionar una imagen, un video, una URL o una ruta local, que se utilizará para formar pixel_values cuando return_dict=True. Si no se proporciona, se obtendrá solo el texto formateado, opcionalmente el texto tokenizado.

conversation = [ { “role”: “user”, “content”: [ {“type”: “image”, “url”: “https://www.ilankelman.org/stopsigns/australia.jpg”}, {“type”: “text”, “text”: “Please describe this image in detail.”}, ], }, ]

Procesamiento de kwargs

Los métodos __call__ de Processor aceptan argumentos por nombre organizados por modalidad. Las siguientes clases TypedDict definen los argumentos por nombre disponibles para cada modalidad. Los procesadores específicos de un modelo pueden subclasear estas para añadir o sobrescribir campos.

clase transformers.ProcessingKwargs

< >

( )

Clase base para la transmisión de kwargs a los procesadores. Si un modelo tiene kwargs específicos que no están presentes en la clase base o valores predeterminados para claves existentes, debe tener su propia clase ModelProcessorKwargs que herede de ProcessingKwargs para proporcionar: 1) Claves adicionales con tipo que este modelo requiere para procesar las entradas. 2) Valores predeterminados para las claves existentes bajo un atributo _defaults. Las nuevas claves deben definirse de la siguiente manera para garantizar que la anotación de tipos se realice correctamente.

# adding a new image kwarg for this model
class ModelImagesKwargs(ImagesKwargs, total=False):
    new_image_kwarg: Optional[bool]

class ModelProcessorKwargs(ProcessingKwargs, total=False):
    images_kwargs: ModelImagesKwargs
    _defaults = {
        "images_kwargs: {
            "new_image_kwarg": False,
        }
        "text_kwargs": {
            "padding": "max_length",
        },
    }

Para la compatibilidad con Python 3.8, al heredar de esta clase y sobrescribir uno de los kwargs,

debe actualizar manualmente el diccionario annotations. Esto se puede hacer de la siguiente manera:

class CustomProcessorKwargs(ProcessingKwargs, total=False):
    images_kwargs: CustomImagesKwargs

CustomProcessorKwargs.__annotations__["images_kwargs"] = CustomImagesKwargs  # python 3.8 compatibility

clase transformers.TextKwargs

< >

( )

Parámetros

  • add_special_tokens (bool, opcional) — Indica si se deben o no añadir tokens especiales al codificar las secuencias.
  • padding (bool, str o PaddingStrategy, opcional) — Activa y controla el relleno.
  • truncation (bool, str o TruncationStrategy, opcional) — Activa y controla la truncación.
  • max_length (int, opcional) — Controla la longitud máxima que debe usar uno de los parámetros de truncado/relleno.
  • stride (int, opcional) — Si se establece, los tokens desbordados contendrán algunos tokens del final de la secuencia truncada.
  • is_split_into_words (bool, opcional) — Indica si la entrada ya está pre-tokenizada.
  • pad_to_multiple_of (int, opcional) — Si se establece, se rellenará la secuencia hasta un múltiplo del valor proporcionado.
  • return_token_type_ids (bool, opcional) — Si se deben devolver los IDs de tipo de token.
  • return_attention_mask (bool, opcional) — Si se debe devolver la máscara de atención.
  • return_overflowing_tokens (bool, opcional) — Si se deben devolver o no las secuencias de tokens que exceden el límite.
  • return_special_tokens_mask (bool, opcional) — Si se debe o no devolver información de la máscara de tokens especiales.
  • return_offsets_mapping (bool, opcional) — Indica si se deben devolver (char_start, char_end) para cada token.
  • return_length (bool, opcional) — Indica si se deben devolver las longitudes de las entradas codificadas.
  • verbose (bool, opcional) — Si se imprime más información y advertencias.
  • padding_side (str, opcional) — El lado en el que se aplicará el relleno.
  • return_mm_token_type_ids (bool, opcional) — Si se deben devolver los ids de tipo de token multimodal que indican las posiciones de los tokens de marcador de posición de mm.
  • return_text_replacement_offsets (bool, opcional) — Si se deben devolver los desplazamientos de caracteres para cada marcador de posición mm y su reemplazo.
  • return_tensors (str o TensorType, opcional) — Si se establece, devolverá tensores de un marco de trabajo específico. Los valores aceptables son:
    • 'pt': Devuelve objetos torch.Tensor de PyTorch.
    • 'np': Devuelve objetos np.ndarray de NumPy.

Argumentos de palabra clave para el procesamiento de texto. Para una documentación extendida, consulte los métodos y las docstrings asociadas de tokenization_utils_base.

clase transformers.ImagesKwargs

< >

( )

Parámetros

  • do_convert_rgb (bool) — Si se debe convertir la imagen al formato RGB.
  • do_resize (bool, opcional) — Si se debe redimensionar la imagen.
  • size (dict[str, int], opcional) — Redimensiona usando uno de los diccionarios de tamaño admitidos. Los límites de área en píxeles usan {"min_pixels": int, "max_pixels": int}.
  • default_to_square (bool, opcional, valor predeterminado self.default_to_square) — Si se debe usar un cuadrado por defecto al redimensionar, cuando size es un int.
  • crop_size (dict[str, int], opcional) — Tamaño de salida deseado al aplicar un recorte centrado.
  • resample (PILImageResampling, opcional) — Filtro de remuestreo que se utilizará si se cambia el tamaño de la imagen.
  • do_rescale (bool, opcional) — Si se debe reescalar la imagen según el factor de escala especificado rescale_factor.
  • rescale_factor (int o float, opcional) — Factor de escala a utilizar si se reescala la imagen.
  • do_normalize (bool, opcional) — Si se debe normalizar la imagen.
  • image_mean (float o list[float] or tuple[float, float, float], opcional) — Media a utilizar si se normaliza la imagen.
  • image_std (float o list[float] or tuple[float, float, float], opcional) — Desviación estándar a utilizar si se normaliza la imagen.
  • do_pad (bool, opcional) — Si se deben rellenar las imágenes del lote.
  • pad_size (dict[str, int], opcional) — El tamaño {"height": int, "width" int} al que se rellenan las imágenes.
  • do_center_crop (bool, opcional) — Si se debe recortar la imagen centrada.
  • data_format (ChannelDimension o str, opcional) — El formato de la dimensión de canal para la imagen de salida.
  • input_data_format (ChannelDimension o str, opcional) — El formato de la dimensión de canal para la imagen de entrada.
  • device (Union[str, torch.Tensor], opcional) — El dispositivo a utilizar para el procesamiento (p. ej., “cpu”, “cuda”), solo relevante para el backend de torchvision.
  • return_tensors (str o TensorType, opcional) — Si se establece, devolverá tensores de un marco de trabajo específico. Los valores aceptables son:
    • 'pt': Devuelve objetos torch.Tensor de PyTorch.
    • 'np': Devuelve objetos np.ndarray de NumPy.
  • disable_grouping (bool, opcional) — Si se agrupan las imágenes por formas al procesarlas o no; solo es relevante para el backend de torchvision.
  • image_seq_length (int, opcional) — El número de tokens de imagen que se usarán para cada imagen en la entrada. Se añadió por compatibilidad con versiones anteriores, pero en futuros modelos debería establecerse como un atributo del procesador.

Argumentos de palabra clave para el procesamiento de imágenes. Para una documentación extendida, consulte los métodos y docstrings de la clase ImageProcessor correspondiente.

clase transformers.VideosKwargs

< >

( )

Parámetros

  • do_convert_rgb (bool) — Si se debe convertir el vídeo al formato RGB.
  • do_resize (bool) — Si se debe redimensionar el video.
  • size (dict[str, int], opcional) — Redimensiona el lado más corto de la entrada a size["shortest_edge"].
  • default_to_square (bool, opcional, valor predeterminado self.default_to_square) — Si se debe usar un cuadrado por defecto al redimensionar, cuando size es un int.
  • resample (PILImageResampling, opcional) — Filtro de remuestreo que se utilizará si se cambia el tamaño del video.
  • do_rescale (bool, opcional) — Si se debe reescalar el video según el factor de escala especificado rescale_factor.
  • rescale_factor (int o float, opcional) — Factor de escala a utilizar si se reescala el video.
  • do_normalize (bool, opcional) — Si se debe normalizar el video.
  • image_mean (float o list[float] or tuple[float, float, float], opcional) — Media a utilizar si se normaliza el video.
  • image_std (float o list[float] or tuple[float, float, float], opcional) — Desviación estándar a utilizar si se normaliza el video.
  • do_center_crop (bool, opcional) — Si se debe recortar el video desde el centro.
  • do_pad (bool, opcional) — Si se deben rellenar las imágenes del lote.
  • do_sample_frames (bool, opcional) — Si se deben muestrear fotogramas del video antes de procesarlo o si se debe procesar el video completo.
  • video_metadata (Union[VideoMetadata, dict], opcional) — Metadatos del video que contienen información sobre la duración total, los fps y el número total de fotogramas.
  • num_frames (int, opcional) — Número máximo de fotogramas a muestrear cuando do_sample_frames=True.
  • fps (int o float, opcional) — Marcos objetivo a muestrear por segundo cuando do_sample_frames=True.
  • crop_size (dict[str, int], opcional) — Tamaño de salida deseado al aplicar un recorte centrado.
  • data_format (ChannelDimension o str, opcional) — El formato de la dimensión de canal para el video de salida.
  • input_data_format (ChannelDimension o str, opcional) — El formato de la dimensión de canal para el video de entrada.
  • device (Union[str, torch.Tensor], opcional) — El dispositivo a utilizar para el procesamiento (p. ej., “cpu”, “cuda”), solo relevante para el procesamiento de imágenes rápido.
  • return_metadata (bool, opcional) — Si se debe o no devolver los metadatos del video.
  • return_tensors (str o TensorType, opcional) — Si se establece, devolverá tensores de un marco de trabajo específico. Los valores aceptables son:
    • 'pt': Devuelve objetos torch.Tensor de PyTorch.
    • 'np': Devuelve objetos np.ndarray de NumPy.

Argumentos de palabra clave para el procesamiento de video.

clase transformers.AudioKwargs

< >

( )

Parámetros

  • sampling_rate (int, opcional) — La tasa de muestreo a la que se muestreó la entrada raw_speech.
  • raw_speech (np.ndarray, list[float], list[np.ndarray], list[list[float]]) — La secuencia o lote de secuencias que se van a rellenar. Cada secuencia puede ser un array de numpy, una lista de valores float, una lista de arrays de numpy o una lista de listas de valores float. Debe ser audio de canal mono, no estéreo, es decir, un solo float por paso de tiempo.
  • padding (bool, str o PaddingStrategy, opcional) — Seleccione una estrategia para rellenar las secuencias devueltas (según el lado de relleno y el índice de relleno del modelo) entre las siguientes opciones:
    • True o 'longest': Rellena hasta la secuencia más larga del lote (o no aplica relleno si solo se proporciona una secuencia).
    • 'max_length': Rellena hasta una longitud máxima especificada con el argumento max_length o hasta la longitud de entrada máxima aceptable para el modelo si no se proporciona dicho argumento.
    • False o 'do_not_pad'
  • max_length (int, opcional) — Longitud máxima de la lista devuelta y, opcionalmente, longitud de relleno (véase arriba).
  • truncation (bool, opcional) — Activa la truncación para recortar las secuencias de entrada más largas que max_length a max_length.
  • pad_to_multiple_of (int, opcional) — Si se establece, se rellenará la secuencia hasta un múltiplo del valor proporcionado.
  • return_attention_mask (bool, opcional) — Si call() debe devolver attention_mask o no.
  • device (str o torch.device, opcional) — El dispositivo en el que se calculan las características de audio (p. ej., “cpu”, “cuda”), solo relevante para los extractores de características que las calculan con torch.
  • return_tensors (str o TensorType, opcional) — Si se establece, devolverá tensores de un marco de trabajo específico. Los valores aceptables son:
    • 'pt': Devuelve objetos torch.Tensor de PyTorch.
    • 'np': Devuelve objetos np.ndarray de NumPy.
  • load_audio_backend (str, opcional) — Backend utilizado por load_audio() para decodificar/re-muestrear el audio referenciado por URL/ruta en apply_chat_template. Uno de "auto", "torchcodec", "librosa", "torchaudio".

Argumentos de palabra clave para el procesamiento de audio.

Update on GitHub

←Pipelines Exportadores→