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

Bu model, 2025-03-26 tarihinde HF papers'ta yayımlandı ve 2025-04-14 tarihinde Hugging Face Transformers'a katkıda bulunuldu.

Qwen2.5-Omni

Genel Bakış

Qwen2.5-Omni modeli, Alibaba Group bünyesindeki Qwen ekibinin Qwen2.5-Omni Technical Report raporunda önerilen, birleşik çoklu modallı bir modeldir.

Teknik rapordan alınan özet aşağıdaki gibidir:

Qwen2.5-Omni'yi sunuyoruz; metin, görsel, ses ve video gibi çeşitli modalitileri algılamak ve aynı anda metin ile doğal konuşma yanıtlarını akışkan (streaming) bir şekilde üretmek üzere tasarlanmış uçtan uca (end-to-end) bir multimodal modeldir. Multimodal bilgi girdilerinin akışkanlaştırılmasını (streaming) sağlamak için hem ses hem de görsel kodlayıcılar (encoder) blok bazlı bir işleme yaklaşımı kullanır. Bu strateji, multimodal verilerin uzun dizilerinin işlenmesini etkili bir şekilde ayrıştırarak algısal sorumlulukları multimodal kodlayıcıya (encoder) atar ve uzatılmış dizilerin modellemesini büyük bir dil modeline (LLM) emanet eder. Bu iş bölümü, farklı modalitelerin ortak dikkat (attention) mekanizması aracılığıyla birleştirilmesini (fusion) artırır. Video girdilerinin zaman damgalarını sesle senkronize etmek için, ses ve videoyu sıralı ve iç içe geçmiş (interleaved) bir şekilde düzenledik ve TMRoPE (Time-aligned Multimodal RoPE) adını verdiğimiz yeni bir konum gömme (position embedding) yaklaşımı önerdik. İki modalite arasındaki müdahaleyi önlerken metin ve konuşmayı eş zamanlı olarak üretmek için Thinker-Talker mimarisini öneriyoruz. Bu çerçevede Thinker, metin üretimiyle görevli bir büyük dil modeli (LLM) olarak çalışırken, Talker, Thinker'dan gelen gizli temsilleri (hidden representations) doğrudan kullanarak çıktı olarak ses token'ları üreten çift izlekli (dual-track) otoregresif bir modeldir. Hem Thinker hem de Talker modelleri, uçtan uca (end-to-end) bir şekilde eğitilmek ve çıkarım (inference) yapmak üzere tasarlanmıştır. Ses token'larını akışkan (streaming) bir şekilde çözmek (decode) için, ilk paket gecikmesini (initial package delay) azaltmayı hedefleyen, algı alanını (receptive field) kısıtlayan kayan pencere (sliding-window) DiT'yi tanıtıyoruz. Qwen2.5-Omni, hem görsel hem de ses yeteneklerinde benzer boyuttaki Qwen2-VL ve Qwen2-Audio modellerini geride bırakır. Ayrıca Qwen2.5-Omni, Omni-Bench gibi multimodal kıyaslamalarda (benchmark) en iyi performansı (state-of-the-art) elde eder. Önemle belirtmek gerekir ki, MMLU ve GSM8K gibi kıyaslamalarda (benchmark) kanıtlandığı üzere, Qwen2.5-Omni, metin girdileriyle olan yetenekleriyle karşılaştırılabilir düzeyde uçtan uca (end-to-end) ses talimatı izleme performansına ulaşan ilk açık kaynak modeldir. Konuşma üretimi açısından ise Qwen2.5-Omni'nin akışkan (streaming) Talker'ı, dayanıklılık ve doğallık açısından mevcut çoğu akışkan (streaming) ve akışkan olmayan (non-streaming) alternatifi geride bırakır.

from_pretrained() içinde use_kernels=True değerini ayarlayarak desteklenen katmanları Hub'daki optimize edilmiş çekirdeklerle değiştirin. Daha fazla bilgi için Çekirdekleri yükleme bölümüne bakın.

Notlar

Ses ve metin çıktısı üretmek için Qwen2_5OmniForConditionalGeneration sınıfını kullanın. Yalnızca tek bir çıktı türü üretmek için, yalnızca metin çıktısında Qwen2_5OmniThinkerForConditionalGeneration ve yalnızca ses çıktısında Qwen2_5OmniTalkersForConditionalGeneration sınıfını kullanın.
Video girişiyle çalışırken bellek dışı (out-of-memory) hataları oluşursa processor.max_pixels değerini azaltın. Varsayılan olarak maksimum değer çok yüksek bir değere ayarlanmıştır ve yüksek çözünürlüklü görseller, çözünürlük processor.max_pixels değerini aşılmadığı sürece yeniden boyutlandırılmaz.
İşleyicinin, sohbet mesajlarını model girdilerine dönüştürmek için kendi apply_chat_template() yöntemi vardır.

Kullanım örneği

Qwen2.5-Omni, Huggingface Hub'da bulunabilir.

Tekli Medya çıkarımı

Model, girdi olarak metin, görsel, ses ve video kabul edebilir. İşte çıkarım için örnek bir kod.

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)

Sadece metin üretimi

Sadece metin çıktısı üretmek ve ses üretim modelini yüklemeyerek hesaplama kaynağı tasarrufu sağlamak için Qwen2_5OmniThinkerForConditionalGeneration modelini kullanabiliriz.

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)

Toplu Karma Medya Çıkarımı

Qwen2_5OmniThinkerForConditionalGeneration modeli kullanıldığında, model; metin, görsel, ses ve video gibi çeşitli türlerden oluşan karışık örneklerden oluşan girdileri toplu (batch) olarak işleyebilir. Aşağıda bir örnek yer almaktadır.

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)

Ses üretimini toplu işleme

Qwen2_5OmniForConditionalGeneration, toplu (batched) ses çıktısı üretimini destekler. Örneğin, aşağıdaki metinden sese toplu üretim örneği gösterilmektedir. Birden fazla örnekten oluşan bir toplu işlemde, üretilen ses, her örnek için kendi uzunluğuna göre kırpılmış tek bir dalga formu içeren bir liste olarak döndürülür; böylece daha kısa örnekler gereksiz sesle doldurulmaz. Tek örnekli bir çağrı ise hâlâ tek bir tensör döndürür.

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

Kullanım İpuçları

Görüntü Çözünürlüğü ödünleşimi

Model, geniş bir çözünürlük aralığında girdileri destekler. Varsayılan olarak girdi için yerel çözünürlüğü kullanır, ancak daha yüksek çözünürlükler, daha fazla hesaplama maliyeti karşılığında performansı artırabilir. Kullanıcılar, ihtiyaçlarına uygun en iyi yapılandırmayı elde etmek için minimum ve maksimum piksel sayısını ayarlayabilir.

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)

Ses çıktısı için istem

Kullanıcıların sesli çıktıya ihtiyacı varsa, sistem istemi “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.” olarak ayarlanmalıdır; aksi takdirde sesli çıktı beklenildiği gibi çalışmayabilir.

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

Ses çıktısı kullanılır mı

Model hem metin hem de ses çıktılarını destekler; kullanıcılar ses çıktısına ihtiyaç duymuyorsa, from_pretrained fonksiyonunda enable_audio_output parametresini ayarlayabilir. Bu seçenek yaklaşık ~2GB GPU belleği tasarrufu sağlar ancak generate fonksiyonu için return_audio seçeneği yalnızca False olarak ayarlanabilir.

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

Esnek bir deneyim elde etmek için, kullanıcıların from_pretrained fonksiyonu üzerinden model başlatılırken enable_audio_output değerini True olarak ayarlamalarını ve ardından generate fonksiyonu çağrıldığında ses döndürülüp döndürülmeyeceğine karar vermelerini öneririz. return_audio değeri False olarak ayarlandığında, model daha hızlı metin yanıtları almak için yalnızca metin çıktıları döndürür.

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)

Çıktı sesinin ses türünü değiştirin

Qwen2.5-Omni, çıktı sesinin ses tipini değiştirme özelliğini destekler. Kullanıcılar, generate fonksiyonunun speaker parametresini kullanarak ses tipini belirleyebilir. "Qwen/Qwen2.5-Omni-7B" kontrol noktası iki ses tipini destekler: Chelsie ve Ethan; burada Chelsie kadın, Ethan ise erkek sesidir. Varsayılan olarak, speaker belirtilmediğinde varsayılan ses tipi Chelsie'dir.

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

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

Üretim hızını artırmak için Flash-Attention 2

Öncelikle, Flash Attention 2'nin en son sürümünün yüklendiğinden emin olun:

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

Ayrıca, FlashAttention 2 ile uyumlu donanıma sahip olmanız gerekir. Bu konuda daha fazla bilgiyi flash attention deposunun resmi dokümantasyonunda bulabilirsiniz. FlashAttention-2 yalnızca bir model torch.float16 veya torch.bfloat16 olarak yüklendiğinde kullanılabilir.

FlashAttention-2 kullanarak bir model yüklemek ve çalıştırmak için, modeli yüklerken attn_implementation="flash_attention_2" parametresini ekleyin:

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

Genel Bakış

Notlar

Kullanım örneği

Tekli Medya çıkarımı

Sadece metin üretimi

Toplu Karma Medya Çıkarımı

Ses üretimini toplu işleme

Kullanım İpuçları

Görüntü Çözünürlüğü ödünleşimi

Ses çıktısı için istem

Ses çıktısı kullanılır mı

Çıktı sesinin ses türünü değiştirin

Üretim hızını artırmak için Flash-Attention 2

Qwen2_5OmniConfig

sınıf transformers.Qwen2_5OmniConfig

get_text_config

Qwen2_5OmniVisionEncoderConfig

sınıf transformers.Qwen2_5OmniVisionEncoderConfig

Qwen2_5OmniTextConfig

sınıf transformers.Qwen2_5OmniTextConfig

Qwen2_5OmniDiTConfig

sınıf transformers.Qwen2_5OmniDiTConfig

Qwen2_5OmniBigVGANConfig

sınıf transformers.Qwen2_5OmniBigVGANConfig

Qwen2_5OmniAudioEncoderConfig

sınıf transformers.Qwen2_5OmniAudioEncoderConfig

Qwen2_5OmniProcessor

sınıf transformers.Qwen2_5OmniProcessor

__call__

Qwen2_5OmniForConditionalGeneration

sınıf transformers.Qwen2_5OmniForConditionalGeneration

forward

Qwen2_5OmniPreTrainedModelForConditionalGeneration

sınıf transformers.Qwen2_5OmniPreTrainedModelForConditionalGeneration

get_chunked_index

get_rope_index

Qwen2_5OmniThinkerConfig

sınıf transformers.Qwen2_5OmniThinkerConfig

Qwen2_5OmniThinkerModel

sınıf transformers.Qwen2_5OmniThinkerModel

forward

Qwen2_5OmniThinkerForConditionalGeneration

sınıf transformers.Qwen2_5OmniThinkerForConditionalGeneration

forward

get_audio_features

get_image_features

get_video_features

Qwen2_5OmniThinkerTextModel

sınıf transformers.Qwen2_5OmniThinkerTextModel

forward

Qwen2_5OmniTalkerConfig

sınıf transformers.Qwen2_5OmniTalkerConfig

Qwen2_5OmniTalkerForConditionalGeneration

sınıf transformers.Qwen2_5OmniTalkerForConditionalGeneration

forward

Qwen2_5OmniTalkerModel

sınıf transformers.Qwen2_5OmniTalkerModel

forward

Qwen2_5OmniToken2WavConfig

sınıf transformers.Qwen2_5OmniToken2WavConfig

Qwen2_5OmniToken2WavModel

sınıf transformers.Qwen2_5OmniToken2WavModel

forward

Qwen2_5OmniToken2WavDiTModel

sınıf transformers.Qwen2_5OmniToken2WavDiTModel

Qwen2_5OmniToken2WavBigVGANModel

sınıf transformers.Qwen2_5OmniToken2WavBigVGANModel

call