Transformers documentation

Мультимодальные шаблоны чата

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Мультимодальные шаблоны чата

Мультимодальные чат-модели принимают на вход изображения, аудио или видео в дополнение к тексту. Ключ content в мультимодальной истории чата представляет собой список, содержащий элементы разных типов. Это отличается от текстовых чат-моделей, у которых ключ content содержит одну строку.

Так же как класс Tokenizer обрабатывает шаблоны чата и токенизацию для текстовых моделей, класс Processor выполняет предобработку, токенизацию и работу с шаблонами чата для мультимодальных моделей. Их методы apply_chat_template() практически идентичны.

В этом руководстве показано, как вести диалог с мультимодальными моделями с помощью высокоуровневого ImageTextToTextPipeline и на более низком уровне с использованием методов apply_chat_template() и generate().

ImageTextToTextPipeline

ImageTextToTextPipeline — это высокоуровневый класс для генерации изображений и текста с «режимом чата». Режим чата активируется, если обнаружена модель для диалогов, а чат-промпт корректно отформатирован.

Добавьте блоки с изображениями и текстом в ключ content в истории чата.

messages = [
    {
        "role": "system",
        "content": [{"type": "text", "text": "You are a friendly chatbot who always responds in the style of a pirate"}],
    },
    {
      "role": "user",
      "content": [
            {"type": "image", "url": "http://images.cocodataset.org/val2017/000000039769.jpg"},
            {"type": "text", "text": "What are these?"},
        ],
    },
]

Создайте ImageTextToTextPipeline и передайте в него чат. Для больших моделей установка device_map=“auto” помогает загрузить модель быстрее и автоматически размещает её на самом быстром доступном устройстве. Установка типа данных в auto также помогает экономить память и повышать скорость.

import torch
from transformers import pipeline

pipe = pipeline("image-text-to-text", model="Qwen/Qwen2.5-VL-3B-Instruct", device_map="auto", dtype="auto")
out = pipe(text=messages, max_new_tokens=128)
print(out[0]['generated_text'][-1]['content'])
Ahoy, me hearty! These be two feline friends, likely some tabby cats, taking a siesta on a cozy pink blanket. They're resting near remote controls, perhaps after watching some TV or just enjoying some quiet time together. Cats sure know how to find comfort and relaxation, don't they?

Помимо постепенного перехода от пиратского жаргона к современному американскому английскому (в конце концов, это всего лишь модель на 3B параметров), всё верно!

Использование apply_chat_template

Как и в случае с моделями, работающими только с текстом, для подготовки сообщений чата для мультимодальных моделей используйте метод apply_chat_template(). Этот метод выполняет токенизацию и форматирование сообщений чата, включая изображения и другие типы медиа. Полученные входные данные передаются в модель для генерации.

from transformers import AutoProcessor, AutoModelForImageTextToText

model = AutoModelForImageTextToText.from_pretrained("Qwen/Qwen2.5-VL-3B-Instruct", device_map="auto", torch_dtype="auto")
processor = AutoProcessor.from_pretrained("Qwen/Qwen2.5-VL-3B-Instruct")

messages = [
    {
      "role": "system",
      "content": [{"type": "text", "text": "You are a friendly chatbot who always responds in the style of a pirate"}],
    },
    {
      "role": "user",
      "content": [
            {"type": "image", "url": "http://images.cocodataset.org/val2017/000000039769.jpg"},
            {"type": "text", "text": "What are these?"},
        ],
    },
]

Передайте messages в apply_chat_template() для токенизации входного содержимого. В отличие от текстовых моделей, вывод apply_chat_template содержит ключ pixel_values с предобработанными данными изображения, помимо токенизированного текста.

processed_chat = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt")
print(list(processed_chat.keys()))
['input_ids', 'attention_mask', 'pixel_values', 'image_grid_thw']

Передайте эти входные данные в generate().

out = model.generate(**processed_chat.to(model.device), max_new_tokens=128)
print(processor.decode(out[0]))

Декодированный вывод содержит весь диалог до текущего момента, включая сообщение пользователя и плейсхолдерные токены, содержащие информацию об изображении. Перед отображением вывода пользователю может потребоваться удалить предыдущий диалог из вывода.

Видеовходы

Некоторые модели компьютерного зрения также поддерживают видео как входные данные. Формат сообщений очень похож на формат для изображений, описанный в предыдущем разделе.

  • Значение "type" должно быть "video", чтобы указать, что содержимое представляет собой видео.
  • Для видео это может быть ссылка на видео ("url") или путь к файлу ("path"). Видео декодируются с помощью torchcodec. Если torchcodec недоступен, а вы используете более старую версию torchvision, декодирование выполняется средствами torchvision.
  • Помимо загрузки видео по URL или пути к файлу, вы также можете передать декодированные данные видео напрямую. Это полезно, если вы уже предварительно обработали или декодировали кадры видео в другом месте в памяти. Вам не нужно сохранять данные в файлы или хранить их по URL.

PyAV и Decord доступны, но только если вы декодируете видео самостоятельно и явно указываете бэкенд с помощью load_video(backend=...).

from transformers import AutoProcessor, LlavaOnevisionForConditionalGeneration

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

messages = [
    {
      "role": "system",
      "content": [{"type": "text", "text": "You are a friendly chatbot who always responds in the style of a pirate"}],
    },
    {
      "role": "user",
      "content": [
            {"type": "video", "url": "https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/720/Big_Buck_Bunny_720_10s_10MB.mp4"},
            {"type": "text", "text": "What do you see in this video?"},
        ],
    },
]

Пример: Передача декодированных объектов видео

import numpy as np

video_object1 = np.random.randint(0, 255, size=(16, 224, 224, 3), dtype=np.uint8),

messages = [
    {
        "role": "system",
        "content": [{"type": "text", "text": "You are a friendly chatbot who always responds in the style of a pirate"}],
    },
    {
        "role": "user",
        "content": [
            {"type": "video", "video": video_object1},
            {"type": "text", "text": "What do you see in this video?"}
        ],
    },
]

Вы также можете использовать существующую функцию ("load_video()") для загрузки видео, отредактировать его в памяти и передать в сообщениях.


# Make sure a video backend library (torchcodec, pyav, or decord) is available.
from transformers.video_utils import load_video

# load a video file in memory for testing
video_object2, _ = load_video(
    "https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/720/Big_Buck_Bunny_720_10s_10MB.mp4"
)

messages = [
    {
        "role": "system",
        "content": [{"type": "text", "text": "You are a friendly chatbot who always responds in the style of a pirate"}],
    },
    {
        "role": "user",
        "content": [
            {"type": "video", "video": video_object2},
            {"type": "text", "text": "What do you see in this video?"}
        ],
    },
]

Передайте messages в apply_chat_template(), чтобы токенизировать входные данные. В apply_chat_template() есть несколько дополнительных параметров, управляющих процессом выборки.

фиксированное количество кадров
fps
список кадров изображения

Параметр num_frames определяет, сколько кадров равномерно извлечь из видео. У каждой контрольной точки есть максимальное количество кадров, с которым она была предобучена, и превышение этого значения может значительно снизить качество генерации. Важно выбрать количество кадров, которое соответствует как возможностям модели, так и ресурсам вашего оборудования. Если num_frames не указан, загружается всё видео без выборки кадров.

processed_chat = processor.apply_chat_template(
    messages,
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
    num_frames=32,
)
print(processed_chat.keys())

Эти входные данные теперь готовы к использованию в generate().

Update on GitHub