# 处理器

多模态模型需要一个能够处理结合多种模态的输入的预处理器。根据输入模态的不同，处理器需要将文本转换为张量数组，将图像转换为像素值，并将音频转换为具有正确采样率的张量数组。

例如，[PaliGemma](./model_doc/paligemma) 是一个视觉-语言模型，它使用 [SigLIP](./model_doc/siglip) 图像处理器和 [Llama](./model_doc/llama) 分词器。[ProcessorMixin](/docs/transformers/v5.23.0/zh/main_classes/processors#transformers.ProcessorMixin) 类将这两种预处理器类型封装在一起，为多模态模型提供一个统一且单一的处理器类。

调用 [from_pretrained()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2Processor.from_pretrained) 来加载处理器。将输入类型传递给处理器，以生成预期的模型输入、输入 id 和像素值。

```py
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
```

本指南介绍了处理器类以及如何对多模态输入进行预处理。

## 处理器类

All processors inherit from the [ProcessorMixin](/docs/transformers/v5.23.0/zh/main_classes/processors#transformers.ProcessorMixin) class which provides methods like [from_pretrained()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2Processor.from_pretrained), [save_pretrained()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2Processor.save_pretrained), and [push_to_hub()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) for loading, saving, and sharing processors to the Hub.

加载处理器有两种方式：使用 [AutoProcessor](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoProcessor) 或使用特定于模型的处理器类。

[AutoClass](./model_doc/auto) API 提供了一个简单的接口，用于加载处理器，而无需直接指定其所属的具体模型类。

使用 [from_pretrained()](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoProcessor.from_pretrained) 加载处理器。

```py
from transformers import AutoProcessor

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

Processor 也与特定的预训练多模态模型类相关联。您可以使用 [from_pretrained()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2Processor.from_pretrained) 直接从模型类加载 processor。

```py
from transformers import WhisperProcessor

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

您也可以分别加载这两种预处理器类型：[WhisperTokenizerFast](/docs/transformers/v5.23.0/zh/model_doc/whisper#transformers.WhisperTokenizer) 和 [WhisperFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/whisper#transformers.WhisperFeatureExtractor)。

```py
from transformers import WhisperTokenizerFast, WhisperFeatureExtractor, WhisperProcessor

tokenizer = WhisperTokenizerFast.from_pretrained("openai/whisper-tiny")
feature_extractor = WhisperFeatureExtractor.from_pretrained("openai/whisper-tiny")
processor = WhisperProcessor(feature_extractor=feature_extractor, tokenizer=tokenizer)
```

## 保存和加载处理器

[save_pretrained()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2Processor.save_pretrained) 会将处理器的配置写入单个 `processor_config.json` 文件。分词器和聊天模板则保存在各自独立的文件中。

```py
from transformers import AutoProcessor

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

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

除分词器外，每个子处理器都嵌套在 `processor_config.json` 中，以其属性名称作为键，例如 `image_processor`、`video_processor` 或 `feature_extractor`。属于处理器本身的设置，如 `image_token`，则位于顶层。以下示例已作简化。

```json
{
  "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>"
}
```

其他文件会单独保存。

- 分词器会写入其常规文件，例如 `tokenizer.json` 和 `tokenizer_config.json`。如果处理器包含第二个分词器，它会被保存在一个以其属性命名的子文件夹中，例如 `decoder_tokenizer/`。
- 聊天模板会保存到 `chat_template.jinja` 中。如果某个 processor 包含多个聊天模板，`default` 模板会放在 `chat_template.jinja` 中，其余模板则放在 `chat_templates/` 文件夹中。

使用 [from_pretrained()](/docs/transformers/v5.23.0/zh/model_doc/wav2vec2#transformers.Wav2Vec2Processor.from_pretrained) 加载处理器时，每个子处理器会先在 `processor_config.json` 中查找其嵌套键。如果该键不存在，则会回退到独立文件。图像处理器和特征提取器读取 `preprocessor_config.json`，而视频处理器则读取 `video_preprocessor_config.json`，然后读取 `preprocessor_config.json`。将每个子处理器存储在各自独立文件中的旧检查点仍可通过此方式加载。

> [!NOTE]
> 嵌套配置优先于独立文件。如果检查点同时包含两者，编辑 `preprocessor_config.json` 或 `video_preprocessor_config.json` 将不生效。请改为编辑 `processor_config.json` 中的嵌套条目。

## 预处理

Processors 将多模态输入预处理为 Transformers 所期望的格式。处理器可以处理多种输入模态的组合，例如文本与音频，或文本与图像。

自动语音识别（ASR）任务需要一个能够处理文本和音频输入的处理器。加载数据集并查看 `audio` 和 `text` 列（可以删除其他不需要的列）。

```py
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'
```

请记住重新采样采样率，以匹配预训练模型所需的采样率。

```py
from datasets import Audio

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

加载一个处理器，并将音频 `array` 和 `text` 列传入其中。

```py
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
```

使用 `prepare_dataset` 函数对数据集进行预处理。处理器会为 `audio` 列返回 `input_features`，并为文本列返回 `labels`。

```py
prepare_dataset(dataset[0])
```

