Transformers documentation

Qwen2.5-Omni

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Эта модель была опубликована в HF papers 26.03.2025 и добавлена в Hugging Face Transformers 14.04.2025.

Qwen2.5-Omni

Обзор

Модель Qwen2.5-Omni — это унифицированная мультимодальная модель, предложенная командой Qwen из Alibaba Group в Qwen2.5-Omni Technical Report.

Аннотация из технического отчёта приведена ниже:

Мы представляем Qwen2.5-Omni — мультимодальную модель, работающую end-to-end, которая воспринимает различные модальности, включая текст, изображения, аудио и видео, и одновременно генерирует текстовые и естественные речевые ответы в потоковом режиме. Для обеспечения потоковой обработки мультимодальных входных данных как аудио-, так и визуальные энкодеры используют подход поэлементной (block-wise) обработки. Эта стратегия эффективно разделяет обработку длинных последовательностей мультимодальных данных: задачи восприятия возлагаются на мультимодальный энкодер, а моделирование расширенных последовательностей — на большую языковую модель. Такое разделение труда улучшает слияние различных модальностей посредством общего механизма внимания. Для синхронизации временных меток видеовхода с аудио мы организовали аудио и видео последовательно, чередуя их, и предлагаем новый подход к позиционному эмбеддингу, названный TMRoPE (Time-aligned Multimodal RoPE). Чтобы одновременно генерировать текст и речь, избегая взаимного влияния этих двух модальностей, мы предлагаем архитектуру Thinker-Talker. В этой архитектуре Thinker выступает в роли большой языковой модели, отвечающей за генерацию текста, а Talker — это двухканальная авто регрессивная модель, которая напрямую использует скрытые представления от Thinker для генерации аудиотокенов на выходе. Обе модели, Thinker и Talker, спроектированы для обучения и инференса в end-to-end режиме. Для потоковой декодировки аудиотокенов мы вводим скользящее окно DiT, ограничивающее поле восприятия, с целью снижения начальной задержки пакета. Qwen2.5-Omni превосходит Qwen2-VL и Qwen2-Audio сопоставимого размера как по возможностям работы с изображениями, так и с аудио. Кроме того, Qwen2.5-Omni демонстрирует наилучшие результаты на мультимодальных бенчмарках, таких как Omni-Bench. Примечательно, что Qwen2.5-Omni — первая open-source модель, достигшая уровня производительности в end-to-end следовании речевым инструкциям, сопоставимого с её возможностями при текстовых входах, что подтверждается бенчмарками, такими как MMLU и GSM8K. Что касается генерации речи, потоковый Talker в Qwen2.5-Omni превосходит большинство существующих потоковых и непотоковых альтернатив по устойчивости и естественности.

Установите use_kernels=True в from_pretrained(), чтобы заменить поддерживаемые слои на оптимизированные ядра из Hub. Подробнее см. в разделе Загрузка ядер.

Примечания

Используйте Qwen2_5OmniForConditionalGeneration для генерации аудио- и текстового вывода. Чтобы генерировать только один тип вывода, используйте Qwen2_5OmniThinkerForConditionalGeneration для только текста и Qwen2_5OmniTalkersForConditionalGeneration для только аудио.
Если при работе с видеовходом возникают ошибки нехватки памяти, уменьшите processor.max_pixels. По умолчанию максимальное значение установлено на очень большое число, и изображения высокого разрешения не масштабируются, если их разрешение не превышает processor.max_pixels.
У процессора есть собственный метод apply_chat_template() для преобразования сообщений чата во входные данные модели.

Пример использования

Qwen2.5-Omni можно найти на Huggingface Hub.

Вывод для одиночных медиа

Модель может принимать на вход текст, изображения, аудио и видео. Ниже приведён пример кода для инференса.

import soundfile as sf

from transformers import Qwen2_5OmniForConditionalGeneration, Qwen2_5OmniProcessor


model = Qwen2_5OmniForConditionalGeneration.from_pretrained(
    "Qwen/Qwen2.5-Omni-7B",
    device_map="auto",
)
processor = Qwen2_5OmniProcessor.from_pretrained("Qwen/Qwen2.5-Omni-7B")

conversations = [
    {
        "role": "system",
        "content": [
            {"type": "text", "text": "You are Qwen, a virtual human developed by the Qwen Team, Alibaba Group, capable of perceiving auditory and visual inputs, as well as generating text and speech."}
        ],
    },
    {
        "role": "user",
        "content": [
            {"type": "video", "video": "/path/to/video.mp4"},
            {"type": "text", "text": "What can't you hear and see in this video?"},
        ],
    },
]

inputs = processor.apply_chat_template(
    conversations,
    load_audio_from_video=True,
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
    fps=1,

    # kwargs to be passed to `Qwen2-5-OmniProcessor`
    padding=True,
    use_audio_in_video=True,
).to(model.device)

# Generation params for audio or text can be different and have to be prefixed with `thinker_` or `talker_`
text_ids, audio = model.generate(**inputs, use_audio_in_video=True, thinker_do_sample=False, talker_do_sample=True)
text = processor.batch_decode(text_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)

sf.write(
    "output.wav",
    audio.reshape(-1).detach().cpu().numpy(),
    samplerate=24000,
)
print(text)

Генерация только текста

Чтобы генерировать только текстовый вывод и сэкономить вычислительные ресурсы, не загружая модель генерации аудио, можно использовать модель Qwen2_5OmniThinkerForConditionalGeneration.

from transformers import Qwen2_5OmniProcessor, Qwen2_5OmniThinkerForConditionalGeneration


model = Qwen2_5OmniThinkerForConditionalGeneration.from_pretrained(
    "Qwen/Qwen2.5-Omni-7B",
    device_map="auto",
)
processor = Qwen2_5OmniProcessor.from_pretrained("Qwen/Qwen2.5-Omni-7B")

conversations = [
    {
        "role": "system",
        "content": [
            {"type": "text", "text": "You are Qwen, a virtual human developed by the Qwen Team, Alibaba Group, capable of perceiving auditory and visual inputs, as well as generating text and speech."}
        ],
    },
    {
        "role": "user",
        "content": [
            {"type": "video", "video": "/path/to/video.mp4"},
            {"type": "text", "text": "What can't you hear and see in this video?"},
        ],
    },
]

inputs = processor.apply_chat_template(
    conversations,
    load_audio_from_video=True,
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
    fps=1,

    # kwargs to be passed to `Qwen2-5-OmniProcessor`
    padding=True,
    use_audio_in_video=True,
).to(model.device)


text_ids = model.generate(**inputs, use_audio_in_video=True)
text = processor.batch_decode(text_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)

print(text)

Пакетный вывод для смешанных мультимедийных данных

Модель Qwen2_5OmniThinkerForConditionalGeneration позволяет обрабатывать батчи, состоящие из смешанных образцов различных типов, таких как текст, изображения, аудио и видео. Ниже приведен пример.

from transformers import Qwen2_5OmniForConditionalGeneration, Qwen2_5OmniProcessor


model = Qwen2_5OmniForConditionalGeneration.from_pretrained(
    "Qwen/Qwen2.5-Omni-7B",
    device_map="auto"
)
processor = Qwen2_5OmniProcessor.from_pretrained("Qwen/Qwen2.5-Omni-7B")

# Conversation with video only
conversation1 = [
    {
        "role": "system",
        "content": [
            {"type": "text", "text": "You are Qwen, a virtual human developed by the Qwen Team, Alibaba Group, capable of perceiving auditory and visual inputs, as well as generating text and speech."}
        ],
    },
    {
        "role": "user",
        "content": [
            {"type": "video", "path": "/path/to/video.mp4"},
        ]
    }
]

# Conversation with audio only
conversation2 = [
    {
        "role": "system",
        "content": [
            {"type": "text", "text": "You are Qwen, a virtual human developed by the Qwen Team, Alibaba Group, capable of perceiving auditory and visual inputs, as well as generating text and speech."}
        ],
    },
    {
        "role": "user",
        "content": [
            {"type": "audio", "path": "/path/to/audio.wav"},
        ]
    }
]

# Conversation with pure text
conversation3 = [
    {
        "role": "system",
        "content": [
            {"type": "text", "text": "You are Qwen, a virtual human developed by the Qwen Team, Alibaba Group, capable of perceiving auditory and visual inputs, as well as generating text and speech."}
        ],
    },
    {
        "role": "user",
        "content": [{"type": "text", "text": "who are you?"}],
    }
]


# Conversation with mixed media
conversation4 = [
    {
        "role": "system",
        "content": [
            {"type": "text", "text": "You are Qwen, a virtual human developed by the Qwen Team, Alibaba Group, capable of perceiving auditory and visual inputs, as well as generating text and speech."}
        ],
    },
    {
        "role": "user",
        "content": [
            {"type": "image", "path": "/path/to/image.jpg"},
            {"type": "video", "path": "/path/to/video.mp4"},
            {"type": "audio", "path": "/path/to/audio.wav"},
            {"type": "text", "text": "What are the elements can you see and hear in these media?"},
        ],
    }
]

conversations = [conversation1, conversation2, conversation3, conversation4]

inputs = processor.apply_chat_template(
    conversations,
    load_audio_from_video=True,
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
    fps=1,

    # kwargs to be passed to `Qwen2-5-OmniProcessor`
    padding=True,
    use_audio_in_video=True,
).to(model.thinker.device)

text_ids = model.generate(**inputs, use_audio_in_video=True)
text = processor.batch_decode(text_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)

print(text)

Генерация аудио пакетами

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

import soundfile as sf
from transformers import AutoModelForTextToWaveform, AutoProcessor
import torch

model_id = "Qwen/Qwen2.5-Omni-7B"
model = AutoModelForTextToWaveform.from_pretrained(model_id, device_map="auto")
processor = AutoProcessor.from_pretrained(model_id)
sampling_rate = 24000  # output sampling rate
max_new_tokens = 200  # maximum number of tokens to generate

system_text = (
    "You are Qwen, a virtual human developed by the Qwen Team, Alibaba Group, capable of "
    "perceiving auditory and visual inputs, as well as generating text and speech."
)
texts = [
    "Hello, I'm Qwen. How can I help you today?",
    "The weather is nice today. Let's go for a walk.",
]
inputs = processor.apply_chat_template(
    [
        [
            {"role": "system", "content": [{"type": "text", "text": system_text}]},
            {
                "role": "user",
                "content": [
                    {
                        "type": "text",
                        "text": (
                            "Please read the following text aloud exactly as written, with no "
                            f"additional commentary:\n\n{text}"
                        ),
                    }
                ],
            },
        ]
        for text in texts
    ],
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
    return_tensors="pt",
    processor_kwargs={"padding": True},
).to(model.device, dtype=model.dtype)

gen_kwargs = {
    "talker_do_sample": True,
    "speaker": "Ethan",  # Ethan, Chelsie
    "talker_max_new_tokens": max_new_tokens,
}
_, pred_waveform = model.generate(**inputs, **gen_kwargs)

for sample_id, audio in enumerate(pred_waveform):
    sf.write(
        f"qwen2_5_omni_output_{sample_id}.wav",
        audio.detach().to(torch.float32).cpu().numpy(),
        sampling_rate,
    )
    print(f"Saved audio to qwen2_5_omni_output_{sample_id}.wav")

Советы по использованию

Компромисс с разрешением изображения

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

min_pixels = 128*28*28
max_pixels = 768*28*28
processor = AutoProcessor.from_pretrained("Qwen/Qwen2.5-Omni-7B", min_pixels=min_pixels, max_pixels=max_pixels)

Запрос для вывода аудио

If users need audio output, the system prompt must be set as “You are Qwen, a virtual human developed by the Qwen Team, Alibaba Group, capable of perceiving auditory and visual inputs, as well as generating text and speech.”, otherwise the audio output may not work as expected.

{
    "role": "system",
    "content": "You are Qwen, a virtual human developed by the Qwen Team, Alibaba Group, capable of perceiving auditory and visual inputs, as well as generating text and speech.",
}

Использовать аудиовыход или нет

Модель поддерживает как текстовый, так и аудиовыход. Если пользователям не нужен аудиовыход, они могут установить enable_audio_output в функции from_pretrained. Эта опция позволит сэкономить около ~2GB видеопамяти GPU, однако опция return_audio для функции generate будет доступна только со значением False.

model = Qwen2_5OmniForConditionalGeneration.from_pretrained(
    "Qwen/Qwen2.5-Omni-7B",
    device_map="auto",
    enable_audio_output=False,
)

Для обеспечения гибкого опыта работы мы рекомендуем пользователям устанавливать enable_audio_output в True при инициализации модели с помощью функции from_pretrained, а затем решать, возвращать ли аудио при вызове функции generate. Если return_audio установлено в False, модель будет возвращать только текстовые выходные данные, что позволяет получать текстовые ответы быстрее.

model = Qwen2_5OmniForConditionalGeneration.from_pretrained(
    "Qwen/Qwen2.5-Omni-7B",
    device_map="auto",
    enable_audio_output=True,
)
...
text_ids = model.generate(**inputs, return_audio=False)

Изменение типа голоса выходного аудио

Qwen2.5-Omni поддерживает возможность изменения голоса в выходном аудио. Пользователи могут использовать параметр speaker функции generate для указания типа голоса. Чекпоинт "Qwen/Qwen2.5-Omni-7B" поддерживает два типа голоса: Chelsie и Ethan, где Chelsie — женский голос, а Ethan — мужской. По умолчанию, если speaker не указан, используется тип голоса Chelsie.

text_ids, audio = model.generate(**inputs, speaker="Chelsie")

text_ids, audio = model.generate(**inputs, speaker="Ethan")

Flash-Attention 2 для ускорения генерации

Сначала убедитесь, что установлена последняя версия Flash Attention 2:

pip install -U flash-attn --no-build-isolation

Также у вас должно быть оборудование, совместимое с FlashAttention 2. Подробнее об этом можно прочитать в официальной документации репозитория flash attention. FlashAttention-2 можно использовать только тогда, когда модель загружена в формате torch.float16 или torch.bfloat16.

Чтобы загрузить и запустить модель с использованием FlashAttention-2, добавьте attn_implementation="flash_attention_2" при загрузке модели:

from transformers import Qwen2_5OmniForConditionalGeneration


model = Qwen2_5OmniForConditionalGeneration.from_pretrained(
    "Qwen/Qwen2.5-Omni-7B",
    device_map="auto",
    attn_implementation="flash_attention_2",
)

Transformers

Qwen2.5-Omni

Обзор

Примечания

Пример использования

Вывод для одиночных медиа

Генерация только текста

Пакетный вывод для смешанных мультимедийных данных

Генерация аудио пакетами

Советы по использованию

Компромисс с разрешением изображения

Запрос для вывода аудио

Использовать аудиовыход или нет

Изменение типа голоса выходного аудио

Flash-Attention 2 для ускорения генерации

Qwen2_5OmniConfig

класс transformers.Qwen2_5OmniConfig

get_text_config

Qwen2_5OmniVisionEncoderConfig

класс transformers.Qwen2_5OmniVisionEncoderConfig

Qwen2_5OmniTextConfig

класс transformers.Qwen2_5OmniTextConfig

Qwen2_5OmniDiTConfig

класс transformers.Qwen2_5OmniDiTConfig

Qwen2_5OmniBigVGANConfig

класс transformers.Qwen2_5OmniBigVGANConfig

Qwen2_5OmniAudioEncoderConfig

класс transformers.Qwen2_5OmniAudioEncoderConfig

Qwen2_5OmniProcessor

класс transformers.Qwen2_5OmniProcessor

__call__

Qwen2_5OmniForConditionalGeneration

класс transformers.Qwen2_5OmniForConditionalGeneration

forward

Qwen2_5OmniPreTrainedModelForConditionalGeneration

класс transformers.Qwen2_5OmniPreTrainedModelForConditionalGeneration

get_chunked_index

get_rope_index

Qwen2_5OmniThinkerConfig

класс transformers.Qwen2_5OmniThinkerConfig

Qwen2_5OmniThinkerModel

класс transformers.Qwen2_5OmniThinkerModel

forward

Qwen2_5OmniThinkerForConditionalGeneration

класс transformers.Qwen2_5OmniThinkerForConditionalGeneration

forward

get_audio_features

get_image_features

get_video_features

Qwen2_5OmniThinkerTextModel

класс transformers.Qwen2_5OmniThinkerTextModel

forward

Qwen2_5OmniTalkerConfig

класс transformers.Qwen2_5OmniTalkerConfig

Qwen2_5OmniTalkerForConditionalGeneration

класс transformers.Qwen2_5OmniTalkerForConditionalGeneration

forward

Qwen2_5OmniTalkerModel

класс transformers.Qwen2_5OmniTalkerModel

forward

Qwen2_5OmniToken2WavConfig

класс transformers.Qwen2_5OmniToken2WavConfig

Qwen2_5OmniToken2WavModel

класс transformers.Qwen2_5OmniToken2WavModel

forward

Qwen2_5OmniToken2WavDiTModel

класс transformers.Qwen2_5OmniToken2WavDiTModel

Qwen2_5OmniToken2WavBigVGANModel

класс transformers.Qwen2_5OmniToken2WavBigVGANModel

call