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

Model ini dipublikasikan di HF papers pada 2025-03-26 dan disumbangkan ke Hugging Face Transformers pada 2025-04-14.

Qwen2.5-Omni

Ikhtisar

Model Qwen2.5-Omni adalah model multimodal terpadu yang diusulkan dalam Qwen2.5-Omni Technical Report dari tim Qwen, Alibaba Group.

Abstrak dari laporan teknisnya adalah sebagai berikut:

Kami memperkenalkan Qwen2.5-Omni, model multimodal end-to-end yang dirancang untuk mempersepsikan berbagai modalitas, termasuk teks, gambar, audio, dan video, sambil secara bersamaan menghasilkan respons teks dan ucapan alami secara streaming. Untuk memungkinkan streaming informasi input multimodal, baik encoder audio maupun visual menggunakan pendekatan pemrosesan per blok. Strategi ini secara efektif memisahkan penanganan urutan panjang data multimodal, dengan mempercayakan tanggung jawab perseptual kepada encoder multimodal dan mempercayakan pemodelan urutan yang diperluas kepada large language model. Pembagian tugas seperti ini meningkatkan fusi berbagai modalitas melalui mekanisme perhatian bersama. Untuk menyinkronkan timestamp input video dengan audio, kami mengorganisasikan audio dan video secara berurutan dalam cara yang berselang-seling dan mengusulkan pendekatan position embedding baru, yang dinamakan TMRoPE (Time-aligned Multimodal RoPE). Untuk menghasilkan teks dan ucapan secara bersamaan sambil menghindari interferensi antara kedua modalitas, kami mengusulkan arsitektur Thinker-Talker. Dalam kerangka kerja ini, Thinker berfungsi sebagai large language model yang bertugas menghasilkan teks, sementara Talker adalah model autoregresif dual-track yang secara langsung memanfaatkan representasi tersembunyi dari Thinker untuk menghasilkan token audio sebagai output. Baik model Thinker maupun Talker dirancang untuk dilatih dan diinfer secara end-to-end. Untuk mendekode token audio secara streaming, kami memperkenalkan sliding-window DiT yang membatasi bidang reseptif, dengan tujuan mengurangi delay paket awal. Qwen2.5-Omni melampaui Qwen2-VL dan Qwen2-Audio yang berukuran serupa dalam kemampuan gambar dan audio. Selain itu, Qwen2.5-Omni mencapai kinerja state-of-the-art pada benchmark multimodal seperti Omni-Bench. Yang patut dicatat, Qwen2.5-Omni adalah model open-source pertama yang mencapai tingkat kinerja dalam mengikuti instruksi ucapan end-to-end yang sebanding dengan kemampuannya pada input teks, sebagaimana dibuktikan oleh benchmark seperti MMLU dan GSM8K. Untuk generasi ucapan, streaming Talker dari Qwen2.5-Omni melampaui sebagian besar alternatif streaming dan non-streaming yang ada saat ini dalam hal ketahanan dan kealamiahan.

Setel use_kernels=True di from_pretrained() untuk mengganti lapisan yang didukung dengan kernel yang dioptimalkan dari Hub. Lihat Memuat kernel untuk mempelajari lebih lanjut.

Catatan

Gunakan Qwen2_5OmniForConditionalGeneration untuk menghasilkan output audio dan teks. Untuk menghasilkan hanya satu jenis output, gunakan Qwen2_5OmniThinkerForConditionalGeneration untuk output teks saja dan Qwen2_5OmniTalkersForConditionalGeneration untuk output audio saja.
Jika terjadi error out-of-memory saat bekerja dengan input video, kurangi processor.max_pixels. Secara default, nilai maksimum diatur ke angka yang sangat besar dan visual beresolusi tinggi tidak akan di-resize, kecuali resolusinya melebihi processor.max_pixels.
Processor memiliki metode apply_chat_template() miliknya sendiri untuk mengonversi pesan chat menjadi input model.

Contoh penggunaan

Qwen2.5-Omni dapat ditemukan di Huggingface Hub.

Inferensi Media Tunggal

Model dapat menerima teks, gambar, audio, dan video sebagai input. Berikut adalah contoh kode untuk inferensi.

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)

Generasi hanya teks

Untuk menghasilkan hanya output teks dan menghemat komputasi dengan tidak memuat model generasi audio, kita dapat menggunakan model 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)

Inferensi Campuran Media Batch

Model dapat memproses input dalam bentuk batch yang terdiri dari campuran sampel berbagai jenis, seperti teks, gambar, audio, dan video, saat menggunakan model Qwen2_5OmniThinkerForConditionalGeneration. Berikut adalah contohnya.

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)

Batch generasi audio

Qwen2_5OmniForConditionalGeneration mendukung generasi output audio secara batch. Sebagai contoh, berikut adalah generasi batch untuk text-to-speech. Dengan batch yang berisi lebih dari satu sampel, audio yang dihasilkan dikembalikan sebagai daftar dengan satu waveform per sampel, di mana masing-masing sudah dipangkas sesuai panjangnya sendiri, sehingga sampel yang lebih pendek tidak di-pad dengan audio yang tidak relevan. Panggilan untuk satu sampel tetap mengembalikan satu tensor.

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")

Tips Penggunaan

Kompromi Resolusi Gambar

Model ini mendukung berbagai rentang resolusi input. Secara default, model menggunakan resolusi native untuk input, namun resolusi yang lebih tinggi dapat meningkatkan performa dengan biaya komputasi yang lebih besar. Pengguna dapat mengatur jumlah piksel minimum dan maksimum untuk mencapai konfigurasi optimal sesuai kebutuhan mereka.

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)

Prompt untuk keluaran audio

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.",
}

Gunakan keluaran audio atau tidak

Model ini mendukung output teks dan audio. Jika pengguna tidak memerlukan output audio, mereka dapat mengatur enable_audio_output pada fungsi from_pretrained. Opsi ini akan menghemat sekitar ~2GB memori GPU, tetapi opsi return_audio untuk fungsi generate hanya dapat diatur ke False.

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

Untuk mendapatkan pengalaman yang fleksibel, kami merekomendasikan agar pengguna mengatur enable_audio_output menjadi True saat menginisialisasi model melalui fungsi from_pretrained, lalu memutuskan apakah akan mengembalikan audio saat fungsi generate dipanggil. Ketika return_audio diatur ke False, model hanya akan mengembalikan keluaran teks agar respons teks lebih cepat.

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)

Ubah jenis suara audio keluaran

Qwen2.5-Omni mendukung kemampuan untuk mengubah suara audio keluaran. Pengguna dapat menggunakan parameter speaker dari fungsi generate untuk menentukan jenis suara. Checkpoint "Qwen/Qwen2.5-Omni-7B" mendukung dua jenis suara: Chelsie dan Ethan, di mana Chelsie adalah suara perempuan dan Ethan adalah suara laki-laki. Secara default, jika speaker tidak ditentukan, jenis suara default adalah Chelsie.

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

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

Flash-Attention 2 untuk mempercepat proses generasi

Pertama, pastikan untuk menginstal versi terbaru dari Flash Attention 2:

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

Selain itu, Anda harus memiliki perangkat keras yang kompatibel dengan FlashAttention 2. Baca lebih lanjut tentang hal ini di dokumentasi resmi flash attention repository. FlashAttention-2 hanya dapat digunakan ketika model dimuat dalam torch.float16 atau torch.bfloat16.

Untuk memuat dan menjalankan model menggunakan FlashAttention-2, tambahkan attn_implementation="flash_attention_2" saat memuat model:

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

Ikhtisar

Catatan

Contoh penggunaan

Inferensi Media Tunggal

Generasi hanya teks

Inferensi Campuran Media Batch

Batch generasi audio

Tips Penggunaan

Kompromi Resolusi Gambar

Prompt untuk keluaran audio

Gunakan keluaran audio atau tidak

Ubah jenis suara audio keluaran

Flash-Attention 2 untuk mempercepat proses generasi

Qwen2_5OmniConfig

kelas transformers.Qwen2_5OmniConfig

get_text_config

Qwen2_5OmniVisionEncoderConfig

kelas transformers.Qwen2_5OmniVisionEncoderConfig

Qwen2_5OmniTextConfig

kelas transformers.Qwen2_5OmniTextConfig

Qwen2_5OmniDiTConfig

kelas transformers.Qwen2_5OmniDiTConfig

Qwen2_5OmniBigVGANConfig

kelas transformers.Qwen2_5OmniBigVGANConfig

Qwen2_5OmniAudioEncoderConfig

kelas transformers.Qwen2_5OmniAudioEncoderConfig

Qwen2_5OmniProcessor

kelas transformers.Qwen2_5OmniProcessor

__call__

Qwen2_5OmniForConditionalGeneration

kelas transformers.Qwen2_5OmniForConditionalGeneration

forward

Qwen2_5OmniPreTrainedModelForConditionalGeneration

kelas transformers.Qwen2_5OmniPreTrainedModelForConditionalGeneration

get_chunked_index

get_rope_index

Qwen2_5OmniThinkerConfig

kelas transformers.Qwen2_5OmniThinkerConfig

Qwen2_5OmniThinkerModel

kelas transformers.Qwen2_5OmniThinkerModel

forward

Qwen2_5OmniThinkerForConditionalGeneration

kelas transformers.Qwen2_5OmniThinkerForConditionalGeneration

forward

get_audio_features

get_image_features

get_video_features

Qwen2_5OmniThinkerTextModel

kelas transformers.Qwen2_5OmniThinkerTextModel

forward

Qwen2_5OmniTalkerConfig

kelas transformers.Qwen2_5OmniTalkerConfig

Qwen2_5OmniTalkerForConditionalGeneration

kelas transformers.Qwen2_5OmniTalkerForConditionalGeneration

forward

Qwen2_5OmniTalkerModel

kelas transformers.Qwen2_5OmniTalkerModel

forward

Qwen2_5OmniToken2WavConfig

kelas transformers.Qwen2_5OmniToken2WavConfig

Qwen2_5OmniToken2WavModel

kelas transformers.Qwen2_5OmniToken2WavModel

forward

Qwen2_5OmniToken2WavDiTModel

kelas transformers.Qwen2_5OmniToken2WavDiTModel

Qwen2_5OmniToken2WavBigVGANModel

kelas transformers.Qwen2_5OmniToken2WavBigVGANModel

call