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

Mô hình này được công bố trên HF papers vào ngày 2025-03-26 và được đóng góp cho Hugging Face Transformers vào ngày 2025-04-14.

Qwen2.5-Omni

Tổng quan

Mô hình Qwen2.5-Omni là một mô hình đa phương thức thống nhất được đề xuất trong Qwen2.5-Omni Technical Report từ nhóm Qwen, Alibaba Group.

Tóm tắt từ báo cáo kỹ thuật như sau:

Chúng tôi giới thiệu Qwen2.5-Omni, một mô hình đa phương thức end-to-end được thiết kế để nhận thức các phương thức đa dạng, bao gồm văn bản, hình ảnh, âm thanh và video, đồng thời tạo ra các phản hồi văn bản và giọng nói tự nhiên theo cách streaming. Để cho phép streaming các đầu vào thông tin đa phương thức, cả bộ mã hóa âm thanh và bộ mã hóa thị giác đều sử dụng phương pháp xử lý theo khối (block-wise). Chiến lược này tách rời hiệu quả việc xử lý các chuỗi dài dữ liệu đa phương thức, giao trách nhiệm nhận thức cho bộ mã hóa đa phương thức và giao việc mô hình hóa các chuỗi mở rộng cho một mô hình ngôn ngữ lớn. Sự phân công lao động như vậy tăng cường sự kết hợp của các phương thức khác nhau thông qua cơ chế chú ý (attention) được chia sẻ. Để đồng bộ hóa các mốc thời gian của đầu vào video với âm thanh, chúng tôi sắp xếp âm thanh và video theo trình tự một cách xen kẽ và đề xuất một phương pháp nhúng vị trí (position embedding) mới, có tên là TMRoPE (Time-aligned Multimodal RoPE). Để đồng thời tạo ra văn bản và giọng nói mà tránh sự can thiệp giữa hai phương thức, chúng tôi đề xuất kiến trúc Thinker-Talker. Trong khung làm việc này, Thinker hoạt động như một mô hình ngôn ngữ lớn có nhiệm vụ tạo văn bản, trong khi Talker là một mô hình tự hồi quy (autoregressive) hai đường ray (dual-track) trực tiếp sử dụng các biểu diễn ẩn (hidden representations) từ Thinker để tạo ra các token âm thanh làm đầu ra. Cả hai mô hình Thinker và Talker đều được thiết kế để huấn luyện và suy luận theo cách end-to-end. Để giải mã các token âm thanh theo cách streaming, chúng tôi giới thiệu một DiT có cửa sổ trượt (sliding-window) nhằm hạn chế trường nhận (receptive field), với mục tiêu giảm độ trễ của gói dữ liệu ban đầu. Qwen2.5-Omni vượt trội hơn Qwen2-VL và Qwen2-Audio có kích thước tương đương về cả khả năng hình ảnh và âm thanh. Hơn nữa, Qwen2.5-Omni đạt hiệu suất tiên tiến (state-of-the-art) trên các bộ chuẩn (benchmark) đa phương thức như Omni-Bench. Đáng chú ý, Qwen2.5-Omni là mô hình mã nguồn mở đầu tiên đạt được mức hiệu suất trong việc tuân theo chỉ thị giọng nói end-to-end tương đương với khả năng của nó với các đầu vào văn bản, như được chứng minh bởi các bộ chuẩn như MMLU và GSM8K. Về tạo giọng nói, Talker streaming của Qwen2.5-Omni vượt trội hơn hầu hết các phương án streaming và non-streaming hiện có về độ bền (robustness) và tính tự nhiên.

Đặt use_kernels=True trong from_pretrained() để thay thế các lớp được hỗ trợ bằng các kernel tối ưu từ Hub. Xem Tải kernel để biết thêm.

Ghi chú

Sử dụng Qwen2_5OmniForConditionalGeneration để tạo ra đầu ra âm thanh và văn bản. Để chỉ tạo ra một loại đầu ra, hãy dùng Qwen2_5OmniThinkerForConditionalGeneration cho đầu ra chỉ văn bản và Qwen2_5OmniTalkersForConditionalGeneration cho đầu ra chỉ âm thanh.
Trong trường hợp xảy ra lỗi hết bộ nhớ khi làm việc với đầu vào video, hãy giảm processor.max_pixels. Mặc định, giá trị tối đa được đặt ở mức rất lớn và các hình ảnh độ phân giải cao sẽ không được thay đổi kích thước, trừ khi độ phân giải vượt quá processor.max_pixels.
Bộ xử lý có phương thức apply_chat_template() riêng để chuyển đổi các tin nhắn chat thành đầu vào cho mô hình.

Ví dụ sử dụng

Qwen2.5-Omni có thể được tìm thấy trên Huggingface Hub.

Suy luận phương tiện đơn

Mô hình có thể nhận văn bản, hình ảnh, âm thanh và video làm đầu vào. Dưới đây là một mã ví dụ cho suy luận.

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)

Tạo chỉ văn bản

Để chỉ tạo ra đầu ra dạng văn bản và tiết kiệm tài nguyên tính toán bằng cách không nạp mô hình tạo âm thanh, chúng ta có thể sử dụng mô hình 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)

Suy luận phương tiện hỗn hợp theo lô

Mô hình có thể xử lý các lô đầu vào bao gồm các mẫu hỗn hợp của nhiều loại khác nhau như văn bản, hình ảnh, âm thanh và video khi sử dụng mô hình Qwen2_5OmniThinkerForConditionalGeneration. Dưới đây là một ví dụ.

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)

Tạo âm thanh theo lô

Qwen2_5OmniForConditionalGeneration hỗ trợ tạo đầu ra âm thanh theo lô. Ví dụ, dưới đây là tạo âm thanh từ văn bản theo lô. Với một lô gồm nhiều hơn một mẫu, âm thanh được tạo sẽ được trả về dưới dạng danh sách với một dạng sóng cho mỗi mẫu, mỗi dạng sóng đã được cắt gọn theo độ dài riêng của nó, do đó các mẫu ngắn hơn sẽ không bị đệm bằng âm thanh giả. Một cuộc gọi chỉ với một mẫu vẫn trả về một tensor duy nhất.

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

Mẹo sử dụng

Sự đánh đổi về Độ phân giải ảnh

Mô hình hỗ trợ một phạm vi rộng các đầu vào độ phân giải. Mặc định, nó sử dụng độ phân giải gốc cho đầu vào, nhưng các độ phân giải cao hơn có thể cải thiện hiệu suất với chi phí là nhiều phép tính hơn. Người dùng có thể đặt số lượng pixel tối thiểu và tối thiểu để đạt được cấu hình tối ưu cho nhu cầu của mình.

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 cho đầu ra âm thanh

Nếu người dùng cần đầu ra âm thanh, prompt hệ thống phải được đặt là “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.”, nếu không đầu ra âm thanh có thể không hoạt động như mong đợi.

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

Sử dụng đầu ra âm thanh hay không

Mô hình hỗ trợ cả đầu ra văn bản và âm thanh. Nếu người dùng không cần đầu ra âm thanh, họ có thể đặt enable_audio_output trong hàm from_pretrained. Tùy chọn này sẽ tiết kiệm khoảng ~2GB bộ nhớ GPU, nhưng tùy chọn return_audio của hàm generate sẽ chỉ cho phép đặt ở False.

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

Để có trải nghiệm linh hoạt, chúng tôi khuyến nghị người dùng đặt enable_audio_output thành True khi khởi tạo mô hình thông qua hàm from_pretrained, sau đó quyết định có trả về âm thanh hay không khi gọi hàm generate. Khi return_audio được đặt thành False, mô hình sẽ chỉ trả về đầu ra dạng văn bản để nhận phản hồi văn bản nhanh hơn.

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)

Thay đổi kiểu giọng của âm thanh đầu ra

Qwen2.5-Omni hỗ trợ khả năng thay đổi giọng nói của âm thanh đầu ra. Người dùng có thể sử dụng tham số speaker của hàm generate để chỉ định loại giọng nói. Checkpoint "Qwen/Qwen2.5-Omni-7B" hỗ trợ hai loại giọng nói: Chelsie và Ethan, trong đó Chelsie là giọng nữ và Ethan là giọng nam. Mặc định, nếu không chỉ định speaker, loại giọng nói mặc định sẽ là Chelsie.

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

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

Flash-Attention 2 để tăng tốc độ tạo

Đầu tiên, hãy đảm bảo cài đặt phiên bản mới nhất của Flash Attention 2:

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

Ngoài ra, bạn cần có phần cứng tương thích với FlashAttention 2. Đọc thêm về điều này trong tài liệu chính thức của flash attention repository. FlashAttention-2 chỉ có thể được sử dụng khi mô hình được nạp ở torch.float16 hoặc torch.bfloat16.

Để tải và chạy một mô hình bằng FlashAttention-2, hãy thêm attn_implementation="flash_attention_2" khi tải mô hình:

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

Tổng quan

Ghi chú

Ví dụ sử dụng

Suy luận phương tiện đơn

Tạo chỉ văn bản

Suy luận phương tiện hỗn hợp theo lô

Tạo âm thanh theo lô

Mẹo sử dụng

Sự đánh đổi về Độ phân giải ảnh

Prompt cho đầu ra âm thanh

Sử dụng đầu ra âm thanh hay không

Thay đổi kiểu giọng của âm thanh đầu ra

Flash-Attention 2 để tăng tốc độ tạo

Qwen2_5OmniConfig

lớp transformers.Qwen2_5OmniConfig

get_text_config

Qwen2_5OmniVisionEncoderConfig

lớp transformers.Qwen2_5OmniVisionEncoderConfig

Qwen2_5OmniTextConfig

lớp transformers.Qwen2_5OmniTextConfig

Qwen2_5OmniDiTConfig

lớp transformers.Qwen2_5OmniDiTConfig

Qwen2_5OmniBigVGANConfig

lớp transformers.Qwen2_5OmniBigVGANConfig

Qwen2_5OmniAudioEncoderConfig

lớp transformers.Qwen2_5OmniAudioEncoderConfig

Qwen2_5OmniProcessor

lớp transformers.Qwen2_5OmniProcessor

__call__

Qwen2_5OmniForConditionalGeneration

lớp transformers.Qwen2_5OmniForConditionalGeneration

forward

Qwen2_5OmniPreTrainedModelForConditionalGeneration

lớp transformers.Qwen2_5OmniPreTrainedModelForConditionalGeneration

get_chunked_index

get_rope_index

Qwen2_5OmniThinkerConfig

lớp transformers.Qwen2_5OmniThinkerConfig

Qwen2_5OmniThinkerModel

lớp transformers.Qwen2_5OmniThinkerModel

forward

Qwen2_5OmniThinkerForConditionalGeneration

lớp transformers.Qwen2_5OmniThinkerForConditionalGeneration

forward

get_audio_features

get_image_features

get_video_features

Qwen2_5OmniThinkerTextModel

lớp transformers.Qwen2_5OmniThinkerTextModel

forward

Qwen2_5OmniTalkerConfig

lớp transformers.Qwen2_5OmniTalkerConfig

Qwen2_5OmniTalkerForConditionalGeneration

lớp transformers.Qwen2_5OmniTalkerForConditionalGeneration

forward

Qwen2_5OmniTalkerModel

lớp transformers.Qwen2_5OmniTalkerModel

forward

Qwen2_5OmniToken2WavConfig

lớp transformers.Qwen2_5OmniToken2WavConfig

Qwen2_5OmniToken2WavModel

lớp transformers.Qwen2_5OmniToken2WavModel

forward

Qwen2_5OmniToken2WavDiTModel

lớp transformers.Qwen2_5OmniToken2WavDiTModel

Qwen2_5OmniToken2WavBigVGANModel

lớp transformers.Qwen2_5OmniToken2WavBigVGANModel

call