Hugging Face's logo

Transformers documentation

Processadores

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

Processadores

Processadores multi-modais

Qualquer modelo multi-modal exigirá um objeto para codificar ou decodificar os dados que agrupam várias modalidades (entre texto, visão e áudio). Isso é tratado por objetos chamados de processadores, que reúnem dois ou mais objetos de processamento, como tokenizers (para a modalidade de texto), image processors (para visão) e feature extractors (para áudio).

Esses processadores herdam da seguinte classe base, que implementa a funcionalidade de salvamento e carregamento:

classe transformers.ProcessorMixin

< >

( *args**kwargs )

Este é um mixin usado para fornecer a funcionalidade de salvamento/carregamento para todas as classes de processador.

__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) — Imagem a ser pré-processada. Espera uma única imagem ou um lote de imagens com valores de pixel variando de 0 a 255. Se passar imagens com valores de pixel entre 0 e 1, defina do_rescale=False.
  • text (Union[str, list[str], list[list[str]]], opcional) — A sequência ou lote de sequências a ser codificada. Cada sequência pode ser uma string ou uma lista de strings (string pré-tokenizada). Se você passar uma entrada pré-tokenizada, defina is_split_into_words=True para evitar ambiguidade com entradas em lote.
  • 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 ser pré-processado. Espera um único vídeo ou um lote de vídeos com valores de pixel variando de 0 a 255. Se passar vídeos com valores de pixel entre 0 e 1, defina do_rescale=False.
  • audio (Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]], opcional) — O áudio ou lote de áudios a ser preparado. Cada áudio pode ser um array NumPy ou um tensor PyTorch. No caso de um array NumPy/tensor PyTorch, cada áudio deve ter a forma (C, T), onde C é o número de canais e T é o comprimento de amostras do áudio.
  • return_tensors (str ou TensorType, opcional) — Se definido, retornará tensors de um framework específico. Os valores aceitos são:
    • 'pt': Retorna objetos torch.Tensor do PyTorch.
    • 'np': Retorna objetos np.ndarray do NumPy.
  • **kwargs (ProcessingKwargs, opcional) — Opções de processamento adicionais para cada modalidade (texto, imagens, vídeos, áudio). Os parâmetros específicos do modelo estão listados acima; consulte a classe TypedDict para a lista completa de argumentos suportados.

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 e faz o pré-busca dos dados de entrada antes do processamento. Envolve o texto em uma lista para processadores multimodais, busca imagens e áudio remotos se URLs forem fornecidas e garante que o áudio seja agrupado corretamente. Retorna a 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'> )

Valide que pelo menos uma entrada seja fornecida e que nenhum argumento de palavra-chave obsoleto seja utilizado. Caso contrário, levanta ValueError.

Substitua quando o processador precisar de validação adicional nos 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 strings de texto bruto, cada uma potencialmente contendo tokens placeholder multimodais. Observe que será modificado in-place e retornado.
  • images_replacements (list[str], opcional, padrão []) — Strings de substituição expandidas para cada imagem, na ordem em que aparecem no lote. Geradas por self._process_images.
  • videos_replacements (list[str], opcional, padrão []) — Strings de substituição expandidas para cada vídeo. Geradas por self._process_videos.
  • audio_replacements (list[str], opcional, padrão []) — Strings de substituição expandidas para cada entrada de áudio. Geradas por self._process_audio.

Retorna

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

Uma tupla de:

  • O lote de text modificado com todos os tokens de espaço reservado expandidos.
  • batch_replacement_offsets: uma entrada por item do lote, cada uma sendo uma lista de dicionários com as chaves:
  • “type” (str): nome da modalidade — “image”, “video” ou “audio”
  • “span” (tuple[int, int]): deslocamentos de caracteres originais (start, end) do token placeholder
  • “new_span” (tuple[int, int]): (start, end) deslocamentos do placeholder na string expandida
  • “text” (str): a string do token placeholder original que foi correspondida
  • “replacement” (str): a string pela qual foi substituído

Substitua os tokens de espaço reservado multimodais em um lote de strings de texto pelas suas representações expandidas e retorne os textos modificados junto com os metadados de deslocamento.

Este método é a etapa central de pré-processamento do lado do texto para entradas multimodais. Ele varre cada texto do lote em busca de tokens especiais (imagem, vídeo, áudio) e os substitui, em ordem, pelas strings de substituição pré-computadas geradas por self.replace_image_token / self.replace_video_token / self.replace_audio_token. As substituições são consumidas sequencialmente da lista de cada modalidade, de modo que a i-ésima ocorrência de, por exemplo, self.image_token é substituída por images_replacements[i].

Para adicionar um novo processador multimodal com tokens de espaço reservado, você precisa definir um self.image_token correto, que é o mesmo token incorporado no texto de entrada e também usado como espaço reservado e repetido muitas vezes. Em seguida, você precisa sobrescrever self.replace_image_token para retornar a string de substituição correta para uma imagem dada no índice i. O mesmo vale para todas as outras modalidades suportadas.

create_mm_token_type_ids

< >

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

Parâmetros

  • input_ids (list[list[int]]) — Lote de sequências de IDs de tokens. Pode estar sem padding (comprimento variável), portanto, é esperado uma lista simples de listas em Python, em vez de um tensor ou um array com forma uniforme.

Retorna

list[list[int]]

Uma lista com a mesma estrutura de input_ids, em que cada inteiro é o ID do tipo de modalidade para o token correspondente.

Construa IDs de tipo de modalidade por token para um lote de sequências de token_id.

Cada posição recebe um inteiro indicando a qual modalidade pertence: 0 para texto regular, 1 para tokens de imagem, 2 para tokens de vídeo e 3 para tokens de áudio. A associação é determinada pela comparação com self.image_token_ids, self.video_token_ids e 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]]]]) — A conversa a ser formatada.
  • chat_template (Optional[str], opcional) — O modelo Jinja a ser usado para formatar a conversa. Se não for fornecido, o modelo de chat do tokenizer será utilizado.

Assim como o método apply_chat_template em tokenizadores, este método aplica um modelo Jinja às conversas de entrada para convertê-las em uma única string tokenizável.

A entrada é esperada no seguinte formato, em que o conteúdo de cada mensagem é uma lista consistindo de texto e, opcionalmente, entradas de imagem ou vídeo. Também é possível fornecer uma imagem, vídeo, URL ou caminho local, que será usado para formar pixel_values quando return_dict=True. Se não for fornecido, será obtido apenas o texto formatado, opcionalmente o 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.”}, ], }, ]

Processamento de kwargs

Os métodos __call__ do Processor aceitam argumentos por palavra-chave organizados por modalidade. As classes TypedDict a seguir definem os argumentos por palavra-chave disponíveis para cada modalidade. Processadores específicos de modelo podem subclássar essas classes para adicionar ou substituir campos.

classe transformers.ProcessingKwargs

< >

( )

Classe base para a passagem de kwargs para processadores. Caso um modelo tenha kwargs específicos que não estejam presentes na classe base ou valores padrão para chaves existentes, ele deve ter sua própria classe ModelProcessorKwargs que herda de ProcessingKwargs para fornecer: 1) Chaves tipadas adicionais que esse modelo requer para processar as entradas. 2) Valores padrão para chaves existentes sob um atributo _defaults. Novas chaves devem ser definidas da seguinte forma para garantir que a dica de tipo seja feita corretamente.

# 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 compatibilidade com o Python 3.8, ao herdar desta classe e sobrescrever um dos kwargs,

você precisa atualizar manualmente o dicionário annotations. Isso pode ser feito da seguinte forma:

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

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

classe transformers.TextKwargs

< >

( )

Parâmetros

  • add_special_tokens (bool, opcional) — Indica se os tokens especiais devem ser adicionados ao codificar as sequências.
  • padding (bool, str ou PaddingStrategy, opcional) — Ativa e controla o padding.
  • truncation (bool, str ou TruncationStrategy, opcional) — Ativa e controla a truncagem.
  • max_length (int, opcional) — Controla o comprimento máximo a ser usado por um dos parâmetros de truncamento/preenchimento.
  • stride (int, opcional) — Se definido, os tokens em excesso conterão alguns tokens do final da sequência truncada.
  • is_split_into_words (bool, opcional) — Indica se a entrada já está pré-tokenizada.
  • pad_to_multiple_of (int, opcional) — Se definido, a sequência será preenchida até um múltiplo do valor fornecido.
  • return_token_type_ids (bool, opcional) — Se deve retornar os IDs de tipo de token.
  • return_attention_mask (bool, opcional) — Se deve retornar a máscara de atenção.
  • return_overflowing_tokens (bool, opcional) — Se deve ou não retornar sequências de tokens que excedem o limite.
  • return_special_tokens_mask (bool, opcional) — Se deve ou não retornar informações da máscara de tokens especiais.
  • return_offsets_mapping (bool, opcional) — Se deve ou não retornar (char_start, char_end) para cada token.
  • return_length (bool, opcional) — Indica se as comprimentos das entradas codificadas devem ser retornados.
  • verbose (bool, opcional) — Se deve ou não exibir mais informações e avisos.
  • padding_side (str, opcional) — O lado em que o preenchimento será aplicado.
  • return_mm_token_type_ids (bool, opcional) — Se deve retornar os ids de tipo de token multimodal que indicam as posições dos tokens placeholder de mm.
  • return_text_replacement_offsets (bool, opcional) — Se deve retornar os deslocamentos de caracteres para cada placeholder de mm e sua substituição.
  • return_tensors (str ou TensorType, opcional) — Se definido, retornará tensors de um framework específico. Os valores aceitos são:
    • 'pt': Retorna objetos torch.Tensor do PyTorch.
    • 'np': Retorna objetos np.ndarray do NumPy.

Argumentos de palavra-chave para o processamento de texto. Para a documentação estendida, consulte os métodos e docstrings associados em tokenization_utils_base.

classe transformers.ImagesKwargs

< >

( )

Parâmetros

  • do_convert_rgb (bool) — Se a imagem deve ser convertida para o formato RGB.
  • do_resize (bool, opcional) — Se deve redimensionar a imagem.
  • size (dict[str, int], opcional) — Redimensiona usando um dos dicionários de tamanho suportados. Os limites de área em pixels usam {"min_pixels": int, "max_pixels": int}.
  • default_to_square (bool, opcional, padrão self.default_to_square) — Se deve usar um quadrado por padrão ao redimensionar, caso o tamanho seja um inteiro.
  • crop_size (dict[str, int], opcional) — Tamanho de saída desejado ao aplicar recorte central.
  • resample (PILImageResampling, opcional) — Filtro de reamostragem a ser usado ao redimensionar a imagem.
  • do_rescale (bool, opcional) — Se deve redimensionar a imagem pelo fator de escala especificado rescale_factor.
  • rescale_factor (int ou float, opcional) — Fator de escala a ser usado ao reescalar a imagem.
  • do_normalize (bool, opcional) — Indica se a imagem deve ser normalizada.
  • image_mean (float ou list[float] or tuple[float, float, float], opcional) — Média a ser usada ao normalizar a imagem.
  • image_std (float ou list[float] or tuple[float, float, float], opcional) — Desvio padrão a ser usado ao normalizar a imagem.
  • do_pad (bool, opcional) — Indica se as imagens do lote devem ser preenchidas (padding).
  • pad_size (dict[str, int], opcional) — O tamanho {"height": int, "width" int} para o qual as imagens devem ser preenchidas.
  • do_center_crop (bool, opcional) — Se deve recortar a imagem pelo centro.
  • data_format (ChannelDimension ou str, opcional) — O formato da dimensão de canal para a imagem de saída.
  • input_data_format (ChannelDimension ou str, opcional) — O formato da dimensão de canal para a imagem de entrada.
  • device (Union[str, torch.Tensor], opcional) — O dispositivo a ser usado para o processamento (por exemplo, “cpu”, “cuda”), relevante apenas para o backend torchvision.
  • return_tensors (str ou TensorType, opcional) — Se definido, retornará tensors de um framework específico. Os valores aceitos são:
    • 'pt': Retorna objetos torch.Tensor do PyTorch.
    • 'np': Retorna objetos np.ndarray do NumPy.
  • disable_grouping (bool, opcional) — Se as imagens devem ser agrupadas por formas durante o processamento ou não; relevante apenas para o backend torchvision.
  • image_seq_length (int, opcional) — O número de tokens de imagem a serem usados para cada imagem na entrada. Adicionado para compatibilidade reversa, mas isso deve ser definido como um atributo do processador em modelos futuros.

Argumentos de palavra-chave para processamento de imagem. Para documentação estendida, consulte os métodos e docstrings da classe ImageProcessor apropriada.

classe transformers.VideosKwargs

< >

( )

Parâmetros

  • do_convert_rgb (bool) — Se deve converter o vídeo para o formato RGB.
  • do_resize (bool) — Indica se o vídeo deve ser redimensionado.
  • size (dict[str, int], opcional) — Redimensiona o lado mais curto da entrada para size["shortest_edge"].
  • default_to_square (bool, opcional, padrão self.default_to_square) — Se deve usar um quadrado por padrão ao redimensionar, caso o tamanho seja um inteiro.
  • resample (PILImageResampling, opcional) — Filtro de redimensionamento a ser usado ao redimensionar o vídeo.
  • do_rescale (bool, opcional) — Se deve redimensionar o vídeo pelo fator de escala especificado rescale_factor.
  • rescale_factor (int ou float, opcional) — Fator de escala a ser usado ao reescalar o vídeo.
  • do_normalize (bool, opcional) — Indica se o vídeo deve ser normalizado.
  • image_mean (float ou list[float] or tuple[float, float, float], opcional) — Média a ser usada ao normalizar o vídeo.
  • image_std (float ou list[float] or tuple[float, float, float], opcional) — Desvio padrão a ser usado ao normalizar o vídeo.
  • do_center_crop (bool, opcional) — Se deve aplicar recorte centralizado ao vídeo.
  • do_pad (bool, opcional) — Indica se as imagens do lote devem ser preenchidas (padding).
  • do_sample_frames (bool, opcional) — Se deve amostrar quadros do vídeo antes do processamento ou processar o vídeo inteiro.
  • video_metadata (Union[VideoMetadata, dict], opcional) — Metadados do vídeo contendo informações sobre a duração total, o fps e o número total de quadros.
  • num_frames (int, opcional) — Número máximo de quadros a amostrar quando do_sample_frames=True.
  • fps (int ou float, opcional) — Quantidade de quadros a amostrar por segundo quando do_sample_frames=True.
  • crop_size (dict[str, int], opcional) — Tamanho de saída desejado ao aplicar recorte central.
  • data_format (ChannelDimension ou str, opcional) — O formato da dimensão de canal para o vídeo de saída.
  • input_data_format (ChannelDimension ou str, opcional) — O formato da dimensão de canal para o vídeo de entrada.
  • device (Union[str, torch.Tensor], opcional) — O dispositivo a ser usado para o processamento (por exemplo, “cpu”, “cuda”), relevante apenas para o processamento rápido de imagens.
  • return_metadata (bool, opcional) — Se deve retornar os metadados do vídeo ou não.
  • return_tensors (str ou TensorType, opcional) — Se definido, retornará tensors de um framework específico. Os valores aceitos são:
    • 'pt': Retorna objetos torch.Tensor do PyTorch.
    • 'np': Retorna objetos np.ndarray do NumPy.

Argumentos de palavra-chave para processamento de vídeo.

classe transformers.AudioKwargs

< >

( )

Parâmetros

  • sampling_rate (int, opcional) — A taxa de amostragem na qual a entrada raw_speech foi amostrada.
  • raw_speech (np.ndarray, list[float], list[np.ndarray], list[list[float]]) — A sequência ou lote de sequências a serem preenchidas. Cada sequência pode ser um array numpy, uma lista de valores float, uma lista de arrays numpy ou uma lista de listas de valores float. Deve ser áudio mono, não estéreo, ou seja, um único float por timestep.
  • padding (bool, str ou PaddingStrategy, opcional) — Selecione uma estratégia para aplicar padding às sequências retornadas (de acordo com o lado de padding e o índice de padding do modelo) entre:
    • True ou 'longest': Preenche até a sequência mais longa do lote (ou não aplica preenchimento se apenas uma sequência for fornecida).
    • 'max_length': Preenche até o comprimento máximo especificado com o argumento max_length ou até o comprimento máximo aceitável de entrada para o modelo, caso esse argumento não seja fornecido.
    • False ou 'do_not_pad'
  • max_length (int, opcional) — Comprimento máximo da lista retornada e, opcionalmente, o comprimento do padding (veja acima).
  • truncation (bool, opcional) — Ativa a truncagem para cortar sequências de entrada com comprimento maior que max_length para max_length.
  • pad_to_multiple_of (int, opcional) — Se definido, a sequência será preenchida até um múltiplo do valor fornecido.
  • return_attention_mask (bool, opcional) — Se call() deve retornar attention_mask ou não.
  • device (str ou torch.device, opcional) — O dispositivo em que as características de áudio serão calculadas (por exemplo, “cpu”, “cuda”), relevante apenas para extratores de características que as calculam com torch.
  • return_tensors (str ou TensorType, opcional) — Se definido, retornará tensors de um framework específico. Os valores aceitos são:
    • 'pt': Retorna objetos torch.Tensor do PyTorch.
    • 'np': Retorna objetos np.ndarray do NumPy.
  • load_audio_backend (str, opcional) — Backend usado por load_audio() para decodificar/reamostrar áudio referenciado por URL/caminho em apply_chat_template. Um dos valores "auto", "torchcodec", "librosa", "torchaudio".

Argumentos de palavra-chave para processamento de áudio.

Update on GitHub

←Pipelines Exportadores→