Processadores

Modelos multimodais exigem um pré-processador capaz de lidar com entradas que combinam mais de uma modalidade. Dependendo da modalidade de entrada, um processador precisa converter texto em um array de tensores, imagens em valores de pixels e áudio em um array de tensores com a taxa de amostragem correta.

Por exemplo, o PaliGemma é um modelo de visão-linguagem que utiliza o processador de imagens SigLIP e o tokenizador Llama. A classe ProcessorMixin encapsula ambos esses tipos de pré-processador, fornecendo uma única classe de processador unificada para um modelo multimodal.

Chame from_pretrained() para carregar um processador. Passe o tipo de entrada ao processador para gerar as entradas de modelo esperadas, os ids de entrada e os valores de pixel.

from transformers import AutoProcessor, PaliGemmaForConditionalGeneration
from PIL import Image
import requests

processor = AutoProcessor.from_pretrained("google/paligemma-3b-pt-224")

prompt = "answer en Where is the cat standing?"
url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
image = Image.open(requests.get(url, stream=True).raw)

inputs = processor(text=prompt, images=image, return_tensors="pt")
inputs

Este guia descreve a classe de processador e como pré-processar entradas multimodais.

Classes de processador

Todos os processadores herdam da classe ProcessorMixin, que fornece métodos como from_pretrained(), save_pretrained() e push_to_hub() para carregar, salvar e compartilhar processadores no Hub.

Existem duas formas de carregar um processador, com um AutoProcessor e com uma classe de processador específica do modelo.

AutoProcessor

processador específico do modelo

Salvar e carregar um processador

save_pretrained() grava a configuração do processor em um único arquivo processor_config.json. O tokenizer e o chat template são salvos em seus próprios arquivos.

from transformers import AutoProcessor

processor = AutoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf")
processor.save_pretrained("./llava-onevision")

llava-onevision/
├── chat_template.jinja
├── processor_config.json
├── tokenizer.json
└── tokenizer_config.json

Cada sub-processador, exceto o tokenizer, está aninhado dentro de processor_config.json sob o nome de seu atributo, como image_processor, video_processor ou feature_extractor. As configurações que pertencem ao próprio processador, como image_token, ficam no nível superior. O exemplo abaixo está abreviado.

{
  "image_processor": {
    "image_processor_type": "LlavaOnevisionImageProcessor",
    "do_resize": true,
    "size": {"height": 384, "width": 384},
    "image_mean": [0.5, 0.5, 0.5]
  },
  "image_token": "<image>",
  "processor_class": "LlavaOnevisionProcessor",
  "video_processor": {
    "video_processor_type": "LlavaOnevisionVideoProcessor",
    "do_resize": true,
    "size": {"height": 384, "width": 384},
    "image_mean": [0.5, 0.5, 0.5]
  },
  "video_token": "<video>"
}

Os outros arquivos são salvos separadamente.

O tokenizer grava seus arquivos habituais, como tokenizer.json e tokenizer_config.json. Se um processador tiver um segundo tokenizer, ele é salvo em uma subpasta com o nome do seu atributo, como decoder_tokenizer/.
O modelo de chat é salvo em chat_template.jinja. Se um processador tiver vários modelos de chat, o modelo default fica em chat_template.jinja e os demais ficam em uma pasta chat_templates/.

Ao carregar um processador com from_pretrained(), cada sub-processador procura primeiro sua chave aninhada em processor_config.json. Se a chave não estiver presente, ele recorre a um arquivo independente. Processadores de imagem e extratores de recursos leem preprocessor_config.json, e processadores de vídeo leem video_preprocessor_config.json e, em seguida, preprocessor_config.json. Checkpoints mais antigos que armazenam cada sub-processador em seu próprio arquivo ainda são carregados dessa forma.

Uma configuração aninhada tem prioridade sobre um arquivo independente. Se um checkpoint tiver ambos, editar preprocessor_config.json ou video_preprocessor_config.json não terá efeito. Edite a entrada aninhada em processor_config.json em vez disso.

Pré-processar

Processadores pré-processam entradas multimodais para o formato esperado do Transformers. Existem algumas combinações de modalidades de entrada que um processador pode tratar, como texto e áudio ou texto e imagem.

Tarefas de reconhecimento automático de fala (ASR) exigem um processador que possa lidar com entradas de texto e áudio. Carregue um conjunto de dados e examine as colunas audio e text (você pode remover as outras colunas que não são necessárias).

from datasets import load_dataset

dataset = load_dataset("keithito/lj_speech", split="train")
dataset = dataset.map(remove_columns=["file", "id", "normalized_text"])
dataset[0]["audio"]
{'array': array([-7.3242188e-04, -7.6293945e-04, -6.4086914e-04, ...,
         7.3242188e-04,  2.1362305e-04,  6.1035156e-05], dtype=float32),
 'path': '/root/.cache/huggingface/datasets/downloads/extracted/917ece08c95cf0c4115e45294e3cd0dee724a1165b7fc11798369308a465bd26/LJSpeech-1.1/wavs/LJ001-0001.wav',
 'sampling_rate': 22050}

dataset[0]["text"]
'Printing, in the only sense with which we are at present concerned, differs from most if not from all the arts and crafts represented in the Exhibition'

Lembre-se de reamostrar a taxa de amostragem para corresponder à taxa de amostragem exigida pelos modelos pré-treinados.

from datasets import Audio

dataset = dataset.cast_column("audio", Audio(sampling_rate=16000))

Carregue um processador e passe as colunas array e text para ele.

from transformers import AutoProcessor

processor = AutoProcessor.from_pretrained("openai/whisper-tiny")

def prepare_dataset(example):
    audio = example["audio"]
    example.update(processor(audio=audio["array"], text=example["text"], sampling_rate=16000))
    return example

Aplique a função prepare_dataset para pré-processar o conjunto de dados. O processador retorna input_features para a coluna audio e labels para a coluna de texto.

prepare_dataset(dataset[0])

Update on GitHub