Qwen2.5-Omni - 端到端多模态模型

一、关于 Qwen2.5-Omni

Qwen2.5-Omni 是一个端到端的多模态模型，旨在感知包括文本、图像、音频和视频在内的多种模态，同时以流式方式生成文本和自然语音响应。

相关链接

• HuggingFace : https://huggingface.co/collections/Qwen/qwen25-omni-67de1e5f0f9464dc6314b36e
• Qwen chat : https://chat.qwen.ai/

核心特性

• 全能新颖的架构：我们提出了Thinker-Talker架构，这是一个端到端多模态模型，能够感知文本、图像、音频和视频等多种模态，同时以流式方式生成文本和自然语音响应。我们还提出了一种名为TMRoPE（时间对齐多模态RoPE）的新型位置嵌入方法，用于同步视频输入与音频的时间戳。
• 实时语音视频聊天：专为完全实时交互设计的架构，支持分块输入和即时输出。
• 自然且鲁棒的语音生成：超越了许多现有的流式和非流式方案，在语音生成方面展现出卓越的鲁棒性和自然度。
• 跨模态的强劲性能：在与同规模单模态模型的基准测试中，Qwen2.5-Omni在所有模态上都表现出色。其音频能力超越了同规模的Qwen2-Audio，并与Qwen2.5-VL-7B达到了相当的性能水平。
• 出色的端到端语音指令跟随：Qwen2.5-Omni在端到端语音指令跟随方面的表现与文本输入相当，MMLU和GSM8K等基准测试结果印证了这一点。

模型架构

二、快速入门

1、安装依赖

以下我们提供简单示例，展示如何通过🤗 Transformers使用Qwen2.5-Omni。

Qwen2.5-Omni的代码已集成至最新版Hugging Face transformers库，建议您通过以下命令从源码构建：

pip uninstall transformers
pip install git+https://github.com/huggingface/transformers@v4.51.3-Qwen2.5-Omni-preview
pip install accelerate

或者您可能会遇到以下错误：

KeyError: 'qwen2_5_omni'

我们提供了一套工具包，帮助您像调用API一样便捷地处理各类音视频输入，包括base64编码、URL链接以及交错的音频、图像和视频数据。您可以通过以下命令安装，并确保系统中已安装ffmpeg：

# It's highly recommended to use `[decord]` feature for faster video loading.
pip install qwen-omni-utils[decord] -U

如果你没有使用 Linux 系统，可能无法通过 PyPI 安装 decord。这种情况下，可以使用 pip install qwen-omni-utils -U 命令回退到 torchvision 进行视频处理。不过，你仍然可以从源码安装 decord 来确保加载视频时使用 decord。

2、🤗 Transformers 使用指南

以下代码片段展示了如何结合 transformers 和 qwen_omni_utils 使用聊天模型：

import soundfile as sf

from transformers import Qwen2_5OmniForConditionalGeneration, Qwen2_5OmniProcessor
from qwen_omni_utils import process_mm_info

# default: Load the model on the available device(s)
model = Qwen2_5OmniForConditionalGeneration.from_pretrained("Qwen/Qwen2.5-Omni-3B", torch_dtype="auto", device_map="auto")

# We recommend enabling flash_attention_2 for better acceleration and memory saving.
# model = Qwen2_5OmniForConditionalGeneration.from_pretrained(
#     "Qwen/Qwen2.5-Omni-3B",
#     torch_dtype="auto",
#     device_map="auto",
#     attn_implementation="flash_attention_2",
# )

processor = Qwen2_5OmniProcessor.from_pretrained("Qwen/Qwen2.5-Omni-3B")

conversation = [
    {
        "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": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen2.5-Omni/draw.mp4"},
        ],
    },
]

# set use audio in video
USE_AUDIO_IN_VIDEO = True

# Preparation for inference
text = processor.apply_chat_template(conversation, add_generation_prompt=True, tokenize=False)
audios, images, videos = process_mm_info(conversation, use_audio_in_video=USE_AUDIO_IN_VIDEO)
inputs = processor(text=text, audio=audios, images=images, videos=videos, return_tensors="pt", padding=True, use_audio_in_video=USE_AUDIO_IN_VIDEO)
inputs = inputs.to(model.device).to(model.dtype)

# Inference: Generation of the output text and audio
text_ids, audio = model.generate(**inputs, use_audio_in_video=USE_AUDIO_IN_VIDEO)

text = processor.batch_decode(text_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)
print(text)
sf.write(
    "output.wav",
    audio.reshape(-1).detach().cpu().numpy(),
    samplerate=24000,
)

3、最低GPU显存需求

注：上表展示了使用transformers进行推理时的理论最低显存需求，其中BF16测试时启用了attn_implementation="flash_attention_2"；但实际应用中，显存占用通常至少是理论值的1.2倍。更多信息请参阅此链接资源。

4、视频URL资源使用

视频URL的兼容性主要取决于第三方库版本，具体如下表所示。若需更改默认后端，可通过设置环境变量FORCE_QWENVL_VIDEO_READER=torchvision或FORCE_QWENVL_VIDEO_READER=decord实现。

5、批量推理

当设置 return_audio=False 时，该模型能够将文本、图像、音频和视频等多种类型的混合样本组合成批量输入。以下是一个示例。

# Sample messages for batch inference

# 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", "video": "/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", "audio": "/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": "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", "image": "/path/to/image.jpg"},
            {"type": "video", "video": "/path/to/video.mp4"},
            {"type": "audio", "audio": "/path/to/audio.wav"},
            {"type": "text", "text": "What are the elements can you see and hear in these medias?"},
        ],
    }
]

# Combine messages for batch processing
conversations = [conversation1, conversation2, conversation3, conversation4]

# set use audio in video
USE_AUDIO_IN_VIDEO = True

# Preparation for batch inference
text = processor.apply_chat_template(conversations, add_generation_prompt=True, tokenize=False)
audios, images, videos = process_mm_info(conversations, use_audio_in_video=USE_AUDIO_IN_VIDEO)

inputs = processor(text=text, audio=audios, images=images, videos=videos, return_tensors="pt", padding=True, use_audio_in_video=USE_AUDIO_IN_VIDEO)
inputs = inputs.to(model.device).to(model.dtype)

# Batch Inference
text_ids = model.generate(**inputs, use_audio_in_video=USE_AUDIO_IN_VIDEO, return_audio=False)
text = processor.batch_decode(text_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)
print(text)

三、使用技巧

1、音频输出提示

若用户需要音频输出，必须将系统提示设置为："你是由阿里巴巴集团Qwen团队开发的虚拟人类Qwen，能够感知听觉和视觉输入，并生成文本和语音。"否则音频输出可能无法正常工作。

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

2、在视频中使用音频

在多模态交互过程中，用户提供的视频通常包含音频（例如对视频内容的提问，或视频中某些事件产生的声音）。这些信息有助于模型提供更好的交互体验。因此我们为用户提供以下选项，来决定是否在视频中使用音频。

# first place, in data preprocessing
audios, images, videos = process_mm_info(conversations, use_audio_in_video=True)

# second place, in model processor
inputs = processor(text=text, audio=audios, images=images, videos=videos, return_tensors="pt", 
                   padding=True, use_audio_in_video=True)

#  third place, in model inference
text_ids, audio = model.generate(**inputs, use_audio_in_video=True)

值得注意的是，在多轮对话过程中，这些地方的use_audio_in_video参数必须设置为相同值，否则会出现意外结果。

3、是否启用音频输出

该模型同时支持文本和音频输出。如果用户不需要音频输出，可以在初始化模型后调用 model.disable_talker() 方法。此选项将节省约 ~2GB 的 GPU 显存，但会导致 generate 函数的 return_audio 参数只能设置为 False。

model = Qwen2_5OmniForConditionalGeneration.from_pretrained(
    "Qwen/Qwen2.5-Omni-3B",
    torch_dtype="auto",
    device_map="auto"
)
model.disable_talker()

为了获得更灵活的体验，我们建议用户可以在调用 generate 函数时自行决定是否返回音频。如果将 return_audio 参数设为 False，模型将仅返回文本输出，从而更快地获取文本响应。

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

4、更改输出音频的语音类型

Qwen2.5-Omni 支持修改输出音频的语音风格。"Qwen/Qwen2.5-Omni-3B" 模型检查点目前支持以下两种语音类型：

用户可通过 generate 函数的 speaker 参数指定语音类型。若未指定该参数，系统默认使用 Chelsie 语音类型。

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

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

5、使用 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-3B",
    device_map="auto",
    torch_dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
)

四、性能表现

我们对Qwen2.5-Omni进行了全面评估，结果显示其在所有模态上都展现出强劲性能，优于同规模单模态模型及Qwen2.5-VL-7B、Qwen2-Audio、Gemini-1.5-pro等闭源模型。

在多模态融合任务（如OmniBench）中，Qwen2.5-Omni实现了业界领先水平。

即使在单模态任务中，它也在语音识别（Common Voice）、翻译（CoVoST2）、音频理解（MMAU）、图像推理（MMMU/MMStar）、视频理解（MVBench）及语音生成（Seed-tts-eval与主观自然度评估）等领域表现卓越。

多模态转文本

音频转文本

图像转文本

视频（无音频）转文本

零样本语音生成

文本到文本性能对比

2025-05-06（二）