Qwen3-Omni

💜 Qwen Chat   |   🤗 Hugging Face   |   🤖 ModelScope   |   📑 Blog   |   📚 Cookbooks   |   📑 Paper  
🖥️ Hugging Face Demo   |    🖥️ ModelScope Demo   |   💬 WeChat (微信)   |   🫨 Discord   |   📑 API

我们发布了Qwen3-Omni，这是一系列原生端到端的多语言全模态基础模型。它能够处理文本、图像、音频和视频等多种输入，并以文本和自然语音的形式提供实时流式响应。点击下方视频了解更多详情 😃

英文版

中文版

新闻

• 2025年9月26日：⭐️⭐️⭐️ Qwen3-Omni荣登Hugging Face Trending榜单第一名！
• 2025年9月22日：🎉🎉🎉 我们已发布Qwen3-Omni。更多详情请查看我们的博客！

目录

• 概述
  • 简介
  • 模型架构
  • 使用场景手册
• 快速入门
  • 模型说明与下载
  • Transformers使用方法
  • vLLM使用方法
  • DashScope API使用方法
  • 使用技巧（建议阅读）
• 与Qwen3-Omni互动
  • 在线演示
  • 实时交互
  • 启动本地Web UI演示
• Docker
• 评估
  • Qwen3-Omni的性能
  • 评估设置
• 引用

概述

简介

Qwen3-Omni是原生端到端的多语言全模态基础模型。它可以处理文本、图像、音频和视频，并以文本和自然语音的形式提供实时流式响应。我们引入了多项架构升级，以提升性能和效率。其主要特点如下：

• 跨模态的最先进水平：早期的文本优先预训练和混合多模态训练提供了原生的多模态支持。在取得强大的音频及音视频效果的同时，单模态的文本和图像性能并未退化。在36项音视频基准测试中，有22项达到SOTA水平；在开源领域则有32项达到SOTA水平；ASR、音频理解以及语音对话的表现可与Gemini 2.5 Pro相媲美。

• 多语言支持：支持119种文本语言、19种语音输入语言和10种语音输出语言。

  • 语音输入：英语、汉语、韩语、日语、德语、俄语、意大利语、法语、西班牙语、葡萄牙语、马来语、荷兰语、印尼语、土耳其语、越南语、粤语、阿拉伯语、乌尔都语。
  • 语音输出：英语、汉语、法语、德语、俄语、意大利语、西班牙语、葡萄牙语、日语、韩语。

• 创新架构：基于MoE的Thinker–Talker设计，结合AuT预训练以获得强大的通用表征；同时采用多代码本设计，将延迟降至最低。

• 实时音视频交互：低延迟流式传输，具备自然的轮流发言机制，并能即时生成文本或语音回应。

• 灵活可控：通过系统提示词自定义行为，实现精细化控制和便捷适配。

• 详尽的音频字幕生成器：Qwen3-Omni-30B-A3B-Captioner现已开源——这是一款通用、高度细致且幻觉率极低的音频字幕生成模型，填补了开源社区中的一个重要空白。

模型架构

使用场景手册

Qwen3-Omni支持广泛的多模态应用场景，涵盖涉及音频、图像、视频以及视听模态的各种领域任务。以下是一些展示Qwen3-Omni使用场景的手册，其中包含了我们实际的执行记录。您可以先按照快速入门指南下载模型并安装必要的推理环境依赖，然后在本地运行和实验——尝试修改提示词或切换模型类型，尽情探索Qwen3-Omni的强大能力吧！

类别	笔记本	描述	打开
音频	语音识别	语音识别，支持多语言和长音频。
	语音翻译	语音到文本/语音到语音的翻译。
	音乐分析	对任何音乐进行详细分析与鉴赏，包括风格、流派、节奏等。
	声音分析	对各种音效及音频信号的描述与分析。
	音频字幕	音频字幕生成，对任意音频输入进行详细描述。
	混合音频分析	对混合音频内容的分析，例如语音、音乐和环境声音。
视觉	OCR	复杂图像的OCR识别。
	目标定位	目标检测与定位。
	图像问答	回答关于任意图像的任意问题。
	图像数学	解决图像中的复杂数学问题，突出“思考”模型的能力。
	视频描述	对视频内容的详细描述。
	视频导航	从第一人称运动视频中生成导航指令。
	视频场景转换	分析视频中的场景转换。
视听	视听问答	在视听场景中回答任意问题，展示模型对音频与视频之间时序对齐建模的能力。
	视听交互	使用视听输入与模型进行交互式沟通，包括通过音频指定任务。
	视听对话	使用视听输入与模型进行对话式交互，展示其在日常聊天和助理类行为方面的能力。
智能体	音频函数调用	利用音频输入执行函数调用，实现类似智能体的行为。
下游任务微调	Omni Captioner	介绍并演示Qwen3-Omni-30B-A3B-Captioner模型，该模型是在Qwen3-Omni-30B-A3B-Instruct基础上进行下游微调的版本，展示了Qwen3-Omni基础模型的强大泛化能力。

快速入门

在这里，我们提供了几种快速上手 Qwen3-Omni 的方法。如果您希望获得完整的 Qwen3-Omni 使用体验，可以使用 Hugging Face Transformers。然而，由于 Qwen3-Omni 采用了 MoE 架构，在 MoE 模型上使用 Hugging Face Transformers 进行推理时速度可能会非常慢。对于大规模调用或低延迟需求，我们强烈建议使用 vLLM 或通过 DashScope API 进行推理。此外，我们也强烈推荐使用我们提供的 Docker 镜像，其中包含了适用于 Hugging Face Transformers 和 vLLM 的完整运行环境。另外，我们的 cookbooks 提供了一些用例，展示了 Qwen3-Omni 的强大能力。欢迎进一步了解！

模型说明与下载

以下是所有 Qwen3-Omni 模型的说明，请根据您的需求选择并下载合适的模型。

在使用 Hugging Face Transformers 或 vLLM 加载模型时，模型权重会根据模型名称自动下载。然而，如果您的运行环境不适合在执行过程中下载权重，您可以参考以下命令，将模型权重手动下载到本地目录：

# 通过 ModelScope 下载（推荐中国大陆用户使用）
pip install -U modelscope
modelscope download --model Qwen/Qwen3-Omni-30B-A3B-Instruct --local_dir ./Qwen3-Omni-30B-A3B-Instruct
modelscope download --model Qwen/Qwen3-Omni-30B-A3B-Thinking --local_dir ./Qwen3-Omni-30B-A3B-Thinking
modelscope download --model Qwen/Qwen3-Omni-30B-A3B-Captioner --local_dir ./Qwen3-Omni-30B-A3B-Captioner

# 通过 Hugging Face 下载
pip install -U "huggingface_hub[cli]"
huggingface-cli download Qwen/Qwen3-Omni-30B-A3B-Instruct --local-dir ./Qwen3-Omni-30B-A3B-Instruct
huggingface-cli download Qwen/Qwen3-Omni-30B-A3B-Thinking --local-dir ./Qwen3-Omni-30B-A3B-Thinking
huggingface-cli download Qwen/Qwen3-Omni-30B-A3B-Captioner --local-dir ./Qwen3-Omni-30B-A3B-Captioner

Transformers 使用

安装

Qwen3-Omni 的 Hugging Face Transformers 代码已成功合并。我们强烈建议您 创建一个新的 Python 环境 或使用我们的 Docker，以避免环境运行时问题。

# 如果您已经安装了 transformers，请先卸载，或者创建一个新的 Python 环境
# pip uninstall transformers
pip install transformers==4.57.3
pip install accelerate

我们提供了一个工具包，可以帮助您更方便地处理各种类型的音频和视觉输入，提供类似 API 的使用体验。它支持 base64、URL 以及交错的音频、图像和视频输入。您可以通过以下命令安装，并确保系统已安装 ffmpeg：

pip install qwen-omni-utils -U

此外，我们建议在使用 Hugging Face Transformers 运行时启用 FlashAttention 2，以减少 GPU 内存占用。不过，如果您主要使用 vLLM 进行推理，则无需安装此库，因为 vLLM 默认已包含 FlashAttention 2。

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

同时，您的硬件需要兼容 FlashAttention 2。更多相关信息请参阅 FlashAttention 仓库 的官方文档。FlashAttention 2 只能在模型以 torch.float16 或 torch.bfloat16 加载时使用。

代码示例

以下是一个代码示例，展示如何使用 transformers 和 qwen_omni_utils 来操作 Qwen3-Omni：

import soundfile as sf

from transformers import Qwen3OmniMoeForConditionalGeneration, Qwen3OmniMoeProcessor
from qwen_omni_utils import process_mm_info

MODEL_PATH = "Qwen/Qwen3-Omni-30B-A3B-Instruct"
# MODEL_PATH = "Qwen/Qwen3-Omni-30B-A3B-Thinking"

model = Qwen3OmniMoeForConditionalGeneration.from_pretrained(
    MODEL_PATH,
    dtype="auto",
    device_map="auto",
    attn_implementation="flash_attention_2",
)

processor = Qwen3OmniMoeProcessor.from_pretrained(MODEL_PATH)

conversation = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-Omni/demo/cars.jpg"},
            {"type": "audio", "audio": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-Omni/demo/cough.wav"},
            {"type": "text", "text": "你能看到和听到什么？用一句话简短回答。"}
        ],
    },
]

# 设置是否在视频中使用音频
USE_AUDIO_IN_VIDEO = True

# 推理前的准备
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)

# 推理：生成输出文本和音频
text_ids, audio = model.generate(**inputs, 
                                 speaker="Ethan", 
                                 thinker_return_dict_in_generate=True,
                                 use_audio_in_video=USE_AUDIO_IN_VIDEO)

text = processor.batch_decode(text_ids.sequences[:, inputs["input_ids"].shape[1] :],
                              skip_special_tokens=True,
                              clean_up_tokenization_spaces=False)
print(text)
if audio is not None:
    sf.write(
        "output.wav",
        audio.reshape(-1).detach().cpu().numpy(),
        samplerate=24000,
    )

以下是一些更高级的使用示例。您可以展开下面的部分以了解更多信息。

from transformers import Qwen3OmniMoeForConditionalGeneration, Qwen3OmniMoeProcessor
from qwen_omni_utils import process_mm_info

MODEL_PATH = "Qwen/Qwen3-Omni-30B-A3B-Instruct"
# MODEL_PATH = "Qwen/Qwen3-Omni-30B-A3B-Thinking"

model = Qwen3OmniMoeForConditionalGeneration.from_pretrained(
    MODEL_PATH,
    dtype="auto",
    device_map="auto",
    attn_implementation="flash_attention_2",
)
model.disable_talker()

processor = Qwen3OmniMoeProcessor.from_pretrained(MODEL_PATH)

# 仅包含图像的对话
conversation1 = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-Omni/demo/cars.jpg"},
            {"type": "text", "text": "你在这个图片中看到了什么？用一句话回答。"},
        ]
    }
]

# 仅包含音频的对话
conversation2 = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-Omni/demo/cough.wav"},
            {"type": "text", "text": "你在这个音频中听到了什么？"},
        ]
    }
]

# 仅包含纯文本和系统提示的对话
conversation3 = [
    {
        "role": "system",
        "content": [
            {"type": "text", "text": "你是通义千问-全能模型。"}
        ],
    },
    {
        "role": "user",
        "content": "你是谁？"
    }
]

# 包含多种媒体的对话
conversation4 = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-Omni/demo/cars.jpg"},
            {"type": "audio", "audio": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-Omni/demo/cough.wav"},
            {"type": "text", "text": "你能看到什么，又能听到什么？用一句话回答。"}
        ],
    }
]

# 将消息组合起来以便批量处理
conversations = [conversation1, conversation2, conversation3, conversation4]

# 设置是否在视频中使用音频
USE_AUDIO_IN_VIDEO = True

# 准备批量推理
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)

# 批量推理不支持返回音频
text_ids, audio = model.generate(**inputs,
                                 return_audio=False,
                                 thinker_return_dict_in_generate=True,
                                 use_audio_in_video=USE_AUDIO_IN_VIDEO)

text = processor.batch_decode(text_ids.sequences[:, inputs["input_ids"].shape[1] :],
                              skip_special_tokens=True,
                              clean_up_tokenization_spaces=False)
print(text)

model = Qwen3OmniMoeForConditionalGeneration.from_pretrained(
    "Qwen/Qwen3-Omni-30B-A3B-Instruct",
    dtype="auto",
    device_map="auto",
    attn_implementation="flash_attention_2",
)
model.disable_talker()

model = Qwen3OmniMoeForConditionalGeneration.from_pretrained(
    "Qwen/Qwen3-Omni-30B-A3B-Instruct",
    dtype="auto",
    device_map="auto",
    attn_implementation="flash_attention_2",
)
...
text_ids, _ = model.generate(..., return_audio=False)```

</details>

<details>
<summary>更改输出音频的语音类型</summary>

Qwen3-Omni 支持更改输出音频的语音类型。检查点 `"Qwen/Qwen3-Omni-30B-A3B-Instruct"` 支持三种语音类型，具体如下：

| 语音类型 | 性别 | 描述 |
|------------|--------|-------------|
| Ethan      | 男性   | 一种明亮、积极向上且充满感染力的嗓音，给人温暖亲切的感觉。 |
| Chelsie    | 女性   | 一种如蜜糖般柔滑、带有温柔温暖与清澈明亮特质的嗓音。 |
| Aiden      | 男性   | 一种温暖、随和的美式男声，兼具温和与少年般的魅力。 |

用户可以通过 `generate` 函数的 `speaker` 参数来指定语音类型。默认情况下，如果未指定 `speaker`，则使用 `Ethan` 语音。

```python
text_ids, audio = model.generate(..., speaker="Ethan")

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

text_ids, audio = model.generate(..., speaker="Aiden")

此外，有关提示词设置、特定任务的使用方法以及资源需求等更多详细信息，请参阅 使用技巧 和 使用案例手册。

vLLM 使用

安装

我们强烈建议使用最新的 vLLM-Omni 来体验 Qwen3-Omni 系列模型。更多详情，请参阅 vLLM-Omni 官方的 离线推理文档 和 在线推理文档。

我们也推荐使用 vLLM 对 Qwen3-Omni 系列模型进行推理和部署。请注意，我们建议您 创建一个新的 Python 环境，或使用我们提供的 Docker，以避免运行时环境冲突和不兼容问题。

pip install vllm==0.13.0
# 如果在使用 VLLM_USE_PRECOMPILED=1 时遇到“未定义符号”错误，请使用 “pip install -e . -v” 从源码构建。

# 安装 Transformers 库
pip install transformers==4.57.3
pip install accelerate
pip install qwen-omni-utils -U
pip install -U flash-attn --no-build-isolation

推理

你可以使用以下代码进行 vLLM 推理。limit_mm_per_prompt 参数用于指定每条消息中每种模态数据的最大数量。由于 vLLM 需要预先分配 GPU 内存，较大的值会占用更多 GPU 内存；如果出现 OOM 问题，可以尝试减小该值。将 tensor_parallel_size 设置为大于 1 可以启用多 GPU 并行推理，从而提高并发性和吞吐量。此外，max_num_seqs 表示 vLLM 在每次推理步骤中并行处理的序列数量。该值越大，所需的 GPU 内存越多，但也能提升批量推理的速度。更多详细信息请参阅 vLLM 官方文档。以下是使用 vLLM 运行 Qwen3-Omni 的一个简单示例：

import os
import torch

from vllm import LLM, SamplingParams
from transformers import Qwen3OmniMoeProcessor
from qwen_omni_utils import process_mm_info

if __name__ == '__main__':
    MODEL_PATH = "Qwen/Qwen3-Omni-30B-A3B-Instruct"
    # MODEL_PATH = "Qwen/Qwen3-Omni-30B-A3B-Thinking"

    llm = LLM(
            model=MODEL_PATH, trust_remote_code=True, gpu_memory_utilization=0.95,
            tensor_parallel_size=torch.cuda.device_count(),
            limit_mm_per_prompt={'image': 3, 'video': 3, 'audio': 3},
            max_num_seqs=8,
            max_model_len=32768,
            seed=1234,
    )

    sampling_params = SamplingParams(
        temperature=0.6,
        top_p=0.95,
        top_k=20,
        max_tokens=16384,
    )

    processor = Qwen3OmniMoeProcessor.from_pretrained(MODEL_PATH)

    messages = [
        {
            "role": "user",
            "content": [
                {"type": "video", "video": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-Omni/demo/draw.mp4"}
            ], 
        }
    ]

    text = processor.apply_chat_template(
        messages,
        tokenize=False,
        add_generation_prompt=True,
    )
    audios, images, videos = process_mm_info(messages, use_audio_in_video=True)

    inputs = {
        'prompt': text,
        'multi_modal_data': {},
        "mm_processor_kwargs": {
            "use_audio_in_video": True,
        },
    }

    if images is not None:
        inputs['multi_modal_data']['image'] = images
    if videos is not None:
        inputs['multi_modal_data']['video'] = videos
    if audios is not None:
        inputs['multi_modal_data']['audio'] = audios

    outputs = llm.generate([inputs], sampling_params=sampling_params)

    print(outputs[0].outputs[0].text)

以下是一些更高级的使用示例。你可以展开下方的部分了解更多。

import os
import torch

from vllm import LLM, SamplingParams
from transformers import Qwen3OmniMoeProcessor
from qwen_omni_utils import process_mm_info

def build_input(processor, messages, use_audio_in_video):
    text = processor.apply_chat_template(
        messages,
        tokenize=False,
        add_generation_prompt=True,
    )
    audios, images, videos = process_mm_info(messages, use_audio_in_video=use_audio_in_video)

    inputs = {
        'prompt': text,
        'multi_modal_data': {},
        "mm_processor_kwargs": {
            "use_audio_in_video": use_audio_in_video,
        },
    }

    if images is not None:
        inputs['multi_modal_data']['image'] = images
    if videos is not None:
        inputs['multi_modal_data']['video'] = videos
    if audios is not None:
        inputs['multi_modal_data']['audio'] = audios
    
    return inputs

if __name__ == '__main__':
    MODEL_PATH = "Qwen/Qwen3-Omni-30B-A3B-Instruct"
    # MODEL_PATH = "Qwen/Qwen3-Omni-30B-A3B-Thinking"

    llm = LLM(
            model=MODEL_PATH, trust_remote_code=True, gpu_memory_utilization=0.95,
            tensor_parallel_size=torch.cuda.device_count(),
            limit_mm_per_prompt={'image': 3, 'video': 3, 'audio': 3},
            max_num_seqs=8,
            max_model_len=32768,
            seed=1234,
    )

    sampling_params = SamplingParams(
        temperature=0.6,
        top_p=0.95,
        top_k=20,
        max_tokens=16384,
    )

    processor = Qwen3OmniMoeProcessor.from_pretrained(MODEL_PATH)

    # 仅包含图片的对话
    conversation1 = [
        {
            "role": "user",
            "content": [
                {"type": "image", "image": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-Omni/demo/cars.jpg"},
                {"type": "text", "text": "你在这张图片中看到了什么？用一句话回答。"},
            ]
        }
    ]

    # 仅包含音频的对话
    conversation2 = [
        {
            "role": "user",
            "content": [
                {"type": "audio", "audio": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-Omni/demo/cough.wav"},
                {"type": "text", "text": "你在这段音频中听到了什么？"},
            ]
        }
    ]

    # 纯文本和系统提示的对话
    conversation3 = [
        {
            "role": "system",
            "content": [
                {"type": "text", "text": "你是 Qwen-Omni。"}
            ],
        },
        {
            "role": "user",
            "content": "你是谁？用一句话回答。"
        }
    ]

    # 混合媒体的对话
    conversation4 = [
        {
            "role": "user",
            "content": [
                {"type": "image", "image": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-Omni/demo/cars.jpg"},
                {"type": "audio", "audio": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-Omni/cookbook/asr_fr.wav"},
                {"type": "text", "text": "你看到了什么、听到了什么？用一句话回答。"}
            ],
        }
    ]
    
    USE_AUDIO_IN_VIDEO = True

    # 将所有对话合并以便批量处理
    conversations = [conversation1, conversation2, conversation3, conversation4]
    inputs = [build_input(processor, messages, USE_AUDIO_IN_VIDEO) for messages in conversations]

    outputs = llm.generate(inputs, sampling_params=sampling_params)

    result = [outputs[i].outputs[0].text for i in range(len(outputs))]
    print(result)

# Qwen3-Omni-30B-A3B-Instruct 单卡部署
vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --port 8901 --host 127.0.0.1 --dtype bfloat16 --max-model-len 32768 --allowed-local-media-path / -tp 1
# Qwen3-Omni-30B-A3B-Instruct 多卡部署（以4卡为例）
vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --port 8901 --host 127.0.0.1 --dtype bfloat16 --max-model-len 65536 --allowed-local-media-path / -tp 4
# Qwen/Qwen3-Omni-30B-A3B-Thinking 单卡部署
vllm serve Qwen/Qwen3-Omni-30B-A3B-Thinking --port 8901 --host 127.0.0.1 --dtype bfloat16 --max-model-len 32768 --allowed-local-media-path / -tp 1
# Qwen/Qwen3-Omni-30B-A3B-Thinking 多卡部署（以4卡为例）
vllm serve Qwen/Qwen3-Omni-30B-A3B-Thinking --port 8901 --host 127.0.0.1 --dtype bfloat16 --max-model-len 65536 --allowed-local-media-path / -tp 4

curl http://localhost:8901/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
    "messages": [
    {"role": "system", "content": "你是一位 helpful assistant。"},
    {"role": "user", "content": [
        {"type": "image_url", "image_url": {"url": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-Omni/demo/cars.jpg"}},
        {"type": "audio_url", "audio_url": {"url": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-Omni/demo/cough.wav"}},
        {"type": "text", "text": "你能看到和听到什么？请用一句话回答。"}
    ]}
    ]
    }'

此外，有关提示词设置、特定任务的使用方法以及资源需求等更多详细信息，请参阅使用技巧和使用案例手册。

DashScope API 使用

为了更深入地探索 Qwen3-Omni，我们建议您尝试使用我们的 DashScope API，以获得更快、更高效的体验。有关详细的 API 信息和文档，请参阅下表：

使用提示（建议阅读）

最低 GPU 显存要求

注：上表展示了使用 transformers 库和 BF16 精度进行推理时的理论最低显存需求，测试中采用了 attn_implementation="flash_attention_2"。Instruct 模型同时包含 thinker 和 talker 两个组件，而 Thinking 模型仅包含 thinker 部分。

音视频交互的提示词

在使用 Qwen3-Omni 进行音视频多模态交互时，输入为一段视频及其对应的音频（音频作为查询），我们建议采用 以下系统提示词。这种设置有助于模型保持较高的推理能力，同时更好地扮演智能助手等交互角色。此外，thinker 生成的文本将更具可读性，语气自然、对话感强，且避免了难以语音化的复杂格式，从而使 talker 的音频输出更加稳定流畅。您可以根据需要自定义系统提示词中的 user_system_prompt 字段，加入角色设定或其他特定于角色的描述。

user_system_prompt = "你是阿里巴巴通义千问打造的智能语音助手Qwen-Omni。"
message = {
    "role": "system",
    "content": [
          {"type": "text", "text": f"{user_system_prompt} 你是一位没有性别和年龄的虚拟语音助手。\n你正在与用户交流。\n在用户的消息中，“我/我的”指代用户，“你/你的”指代助手；而在你的回复中，则应以“你/你的”称呼用户，以“我/我的”称呼自己；切勿照搬用户的代词，始终转换视角。仅在直接引用时保留原有人称代词；若出现指代不明的情况，请提出简短的澄清问题。\n与用户互动时，请使用简短（不超过50字）、简洁、直白的语言，保持自然的语气。\n切勿使用正式用语、机械化的表达、项目符号或过于结构化的语言。\n你的输出必须仅包含希望用户听到的口语内容。\n不得包含任何关于动作、情感、声音或语音变化的描述。\n禁止使用星号、方括号、圆括号等符号来标注语气或动作。\n你必须回答用户的音频或文本问题，不得直接描述视频内容。\n除非用户另有要求，否则请严格使用与用户相同的语言进行交流。\n当你感到不确定时（例如看不清/听不清、不理解，或用户只是发表评论而非提问），请通过适当的问题引导用户继续对话。\n回复应简洁、口语化，如同面对面交谈一般。"}
    ]
}

Thinking 模型的最佳实践

Qwen3-Omni-30B-A3B-Thinking 模型主要用于理解和交互多模态输入，包括文本、音频、图像和视频。为了获得最佳性能，我们建议用户在每轮对话中，除了多模态输入外，还应附上明确的文本指令或任务描述。这有助于清晰传达意图，并显著提升模型的推理能力。例如：

messages = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": "/path/to/audio.wav"},
            {"type": "image", "image": "/path/to/image.png"},
            {"type": "video", "video": "/path/to/video.mp4"},
            {"type": "text", "text": "请综合分析这段音频、图片和视频。"},
        ], 
    }
]

视频中是否使用音频

在多模态交互中，用户提供的视频通常会伴随音频（如口头提问或视频中事件的声音）。这些信息有助于模型提供更好的交互体验。我们提供了以下选项，供用户决定是否使用视频中的音频。

# 数据预处理阶段
audios, images, videos = process_mm_info(messages, use_audio_in_video=True)

# 对于 Transformers
text = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
inputs = processor(text=text, audio=audios, images=images, videos=videos, return_tensors="pt", 
                   padding=True, use_audio_in_video=True)
text_ids, audio = model.generate(..., use_audio_in_video=True)

# 对于 vLLM
text = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
inputs = {
    'prompt': text,
    'multi_modal_data': {},
    "mm_processor_kwargs": {
        "use_audio_in_video": True,
    },
}

值得注意的是，在多轮对话过程中，use_audio_in_video 参数必须在上述步骤中保持一致；否则可能会导致意外结果。

与 Qwen3-Omni 的交互

在线演示

无需本地部署，您可以通过访问我们的 Hugging Face Spaces 和 ModelScope Studio 直接体验在线网页演示。其中包括 Qwen3-Omni-Realtime、Qwen3-Omni（Instruct 和 Thinking）以及 Qwen3-Omni-30B-A3B-Captioner 的快速实操体验。

实时交互

现在已支持与 Qwen3-Omni 的实时流式交互。请访问 Qwen Chat，并在聊天框中选择语音/视频通话选项即可体验。

启动本地 Web UI 演示

在这一部分，我们为用户提供构建基于 Web 的用户界面（UI）演示的说明。该 UI 演示允许用户通过 Web 浏览器与模型进行交互。请按照以下步骤开始 :)

安装

在开始之前，我们强烈建议您参考 vLLM 使用指南 中的 安装 部分来设置您的环境，这将使您能够无缝地使用 vLLM 和 Transformers 两种后端。然而，如果您仅打算使用 Transformers 后端（请注意，这会导致推理速度显著变慢），请遵循 Transformers 使用指南 中的安装说明。尽管如此，我们仍然强烈推荐使用我们的 Docker 镜像，以避免潜在的环境相关问题。此外，如果您是在本地运行，请确保您的系统已安装 ffmpeg，并安装以下依赖项：

pip install gradio==5.44.1 gradio_client==1.12.1 soundfile==0.13.1

运行演示

在安装完所需软件包后，您可以使用以下命令启动 Web 演示。这些命令将启动一个 Web 服务器，并为您提供一个链接，以便在浏览器中访问 UI。您可以通过运行 python web_demo.py --help 和 python web_demo_captioner.py --help 来了解更多的选项。

# 对于 Qwen3-Omni-30B-A3B-Instruct 模型，使用 vLLM 后端
python web_demo.py -c Qwen/Qwen3-Omni-30B-A3B-Instruct
# 对于 Qwen3-Omni-30B-A3B-Instruct 模型，使用 Transformers 后端
python web_demo.py -c Qwen/Qwen3-Omni-30B-A3B-Instruct --use-transformers --generate-audio
# 对于 Qwen3-Omni-30B-A3B-Instruct 模型，使用 Transformers 后端并支持 FlashAttention
python web_demo.py -c Qwen/Qwen3-Omni-30B-A3B-Instruct --use-transformers --generate-audio --flash-attn2

# 对于 Qwen3-Omni-30B-A3B-Thinking 模型，使用 vLLM 后端
python web_demo.py -c Qwen/Qwen3-Omni-30B-A3B-Thinking
# 对于 Qwen3-Omni-30B-A3B-Thinking 模型，使用 Transformers 后端
python web_demo.py -c Qwen/Qwen3-Omni-30B-A3B-Thinking --use-transformers
# 对于 Qwen3-Omni-30B-A3B-Thinking 模型，使用 Transformers 后端并支持 FlashAttention
python web_demo.py -c Qwen/Qwen3-Omni-30B-A3B-Thinking --use-transformers --flash-attn2

# 对于 Qwen3-Omni-30B-A3B-Captioner 模型，使用 vLLM 后端
python web_demo_captioner.py -c Qwen/Qwen3-Omni-30B-A3B-Captioner
# 对于 Qwen3-Omni-30B-A3B-Captioner 模型，使用 Transformers 后端
python web_demo_captioner.py -c Qwen/Qwen3-Omni-30B-A3B-Captioner --use-transformers
# 对于 Qwen3-Omni-30B-A3B-Captioner 模型，使用 Transformers 后端并支持 FlashAttention
python web_demo_captioner.py -c Qwen/Qwen3-Omni-30B-A3B-Captioner --use-transformers --flash-attn2

运行命令后，您将在终端中看到类似如下的链接：

正在本地运行：http://127.0.0.1:8901/

如果您是在本地运行，请复制此链接并粘贴到浏览器中以访问 Web UI。如果您是在服务器上或 Docker 容器中运行，请根据服务器的实际 IP 地址配置地址，或在必要时设置端口转发。有关如何从官方 Docker 容器将端口转发到宿主机的说明，请参阅 这里。

🐳 Docker

为了简化部署流程，我们提供了预装环境的 Docker 镜像：qwenllm/qwen3-omni。您只需安装驱动程序并下载模型文件即可启动演示。请参考 指南 安装 NVIDIA Container Toolkit，以确保您的 Docker 能够访问 GPU。对于在中国大陆可能难以访问 Docker Hub 的用户，可以使用镜像加速服务来拉取镜像。首先，运行以下命令来拉取并初始化容器：

LOCAL_WORKDIR=/path/to/your/workspace
HOST_PORT=8901
CONTAINER_PORT=80
docker run --gpus all --name qwen3-omni \
    -v /var/run/docker.sock:/var/run/docker.sock -p $HOST_PORT:$CONTAINER_PORT \
    --mount type=bind,source=$LOCAL_WORKDIR,target=/data/shared/Qwen3-Omni \
    --shm-size=4gb \
    -it qwenllm/qwen3-omni:3-cu124

执行该命令后，您将进入容器的 bash shell。您的本地模型和数据目录（请将 /path/to/your/workspace 替换为实际路径）会被挂载到容器内部的路径 /data/shared/Qwen3-Omni。宿主机的端口 8901 会映射到容器内的端口 80,这意味着您可以通过访问宿主机上的端口 8901 来访问容器内的服务。

请注意，容器内的服务必须使用 IP 0.0.0.0 启动，才能确保端口转发正常工作。例如：

# 在 Docker 容器内运行此命令
python web_demo.py -c Qwen/Qwen3-Omni-30B-A3B-Instruct --server-port 80 --server-name 0.0.0.0

有关更多启动 Web 演示的方式，请参阅 启动本地 Web UI 演示。如果您退出了容器，可以使用以下命令重新进入：

docker start qwen3-omni
docker exec -it qwen3-omni bash

或者，如果您想完全移除容器，请运行：

docker rm -f qwen3-omni

评估

Qwen3-Omni 的性能

Qwen3-Omni 在文本和视觉模态上保持了最先进的性能，且相对于同规模的单模态 Qwen 模型没有性能下降。在 36 个音频和视听基准测试中，它在 32 个任务上达到了开源领域的 SOTA，并在 22 个任务上刷新了 SOTA，表现优于 Gemini 2.5 Pro 和 GPT-4o 等强大的闭源系统。

评估设置

• 解码策略：对于Qwen3-Omni系列的所有评估基准，Instruct模型在生成过程中采用贪婪解码，不进行采样。对于Thinking模型，则应从检查点中的generation_config.json文件中获取解码参数。
• 基准特定格式化：大多数评估基准都自带ChatML格式，用于嵌入问题或提示。需要注意的是，在评估过程中，所有视频数据的帧率均设置为fps=2。
• 默认提示：对于某些基准中未包含提示的任务，我们使用以下提示设置：

• 系统提示：任何评估基准都不应设置系统提示。
• 输入序列：问题或提示应作为用户文本输入。除非基准另有规定，否则文本应位于多模态数据之后。例如：

messages = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": "/path/to/audio.wav"},
            {"type": "image", "image": "/path/to/image.png"},
            {"type": "video", "video": "/path/to/video.mp4"},
            {"type": "text", "text": "描述音频、图像和视频。"},
        ],
    },
]

引用

如果您在研究中发现我们的论文和代码有用，请考虑给个赞 :star: 和引用 :pencil: :)

@article{Qwen3-Omni,
  title={Qwen3-Omni技术报告},
  author={Jin Xu和Zhifang Guo和Hangrui Hu和Yunfei Chu和Xiong Wang和Jinzheng He和Yuxuan Wang和Xian Shi和Ting He和Xinfa Zhu和Yuanjun Lv和Yongqi Wang和Dake Guo和He Wang和Linhan Ma和Pei Zhang和Xinyu Zhang和Hongkun Hao和Zishan Guo和Baosong Yang和Bin Zhang和Ziyang Ma和Xipin Wei和Shuai Bai和Keqin Chen和Xuejing Liu和Peng Wang和Mingkun Yang和Dayiheng Liu和Xingzhang Ren和Bo Zheng和Rui Men和Fan Zhou和Bowen Yu和Jianxin Yang和Le Yu和Jingren Zhou和Junyang Lin},
  journal={arXiv预印本arXiv:2509.17765},
  year={2025}
}

Qwen3-Omni 快速上手指南

Qwen3-Omni 是通义千问团队推出的原生端到端多模态基础模型，支持文本、图像、音频和视频的混合输入，并能以文本或自然语音形式实时流式输出。本指南将帮助中国开发者快速完成环境搭建与基础调用。

环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu 20.04+) 或 macOS
• Python 版本: Python 3.10 或更高
• GPU: 推荐使用 NVIDIA GPU (显存建议 24GB+ 以运行较大参数版本)，需安装 CUDA 12.1+
• 内存: 建议 32GB+

前置依赖

确保已安装以下基础工具：

• git
• pip (建议升级至最新版)
• ffmpeg (用于处理音频/视频输入)

# 检查 Python 版本
python3 --version

# 安装 ffmpeg (Ubuntu/Debian)
sudo apt-get update && sudo apt-get install -y ffmpeg

# 安装 ffmpeg (macOS)
brew install ffmpeg

安装步骤

推荐使用国内镜像源加速依赖下载。

1. 克隆仓库

git clone https://github.com/QwenLM/Qwen3-Omni.git
cd Qwen3-Omni

2. 创建虚拟环境并安装依赖

# 创建虚拟环境
python3 -m venv qwen_omni_env
source qwen_omni_env/bin/activate

# 使用国内镜像源安装核心依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装 transformers 和 accelerate (如未包含在 requirements 中)
pip install transformers>=4.46.0 accelerate>=0.34.0 -i https://pypi.tuna.tsinghua.edu.cn/simple

# 如需高性能推理，可选安装 vLLM (注意版本兼容性)
pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 模型下载

您可以从 ModelScope (魔搭) 或 Hugging Face 下载模型。国内开发者强烈推荐通过 ModelScope 下载以获得更快速度。

方式 A: 使用 ModelScope 下载 (推荐)

# 安装 modelscope
pip install modelscope -i https://pypi.tuna.tsinghua.edu.cn/simple

# 使用 Python 脚本下载模型 (以 Qwen3-Omni-Instruct 为例)
python -c "from modelscope import snapshot_download; snapshot_download('Qwen/Qwen3-Omni-Instruct', cache_dir='./models')"

方式 B: 使用 Hugging Face CLI

# 需配置 HF_TOKEN
huggingface-cli download Qwen/Qwen3-Omni-Instruct --local-dir ./models

基本使用

以下示例展示如何使用 transformers 库进行最简单的多模态推理（图文问答）。

示例：图像理解与文本回复

import torch
from transformers import AutoProcessor, AutoModelForCausalLM
from PIL import Image

# 1. 加载模型和处理器
# 请将路径替换为您本地下载的模型路径，例如 './models/Qwen/Qwen3-Omni-Instruct'
model_path = "./models/Qwen3-Omni-Instruct" 

processor = AutoProcessor.from_pretrained(model_path, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
    model_path, 
    torch_dtype=torch.bfloat16, 
    device_map="auto",
    trust_remote_code=True
)

# 2. 准备输入
# 加载图片
image = Image.open("https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-Omni/demo_image.jpg").convert("RGB")
# 或者加载本地图片: Image.open("local_image.png").convert("RGB")

question = "这张图片里有什么？请详细描述。"

# 3. 构建消息
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": image},
            {"type": "text", "text": question}
        ]
    }
]

# 4. 预处理并生成
text_input = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
inputs = processor(text=text_input, images=[image], return_tensors="pt").to(model.device)

# 生成回复
generated_ids = model.generate(**inputs, max_new_tokens=512)
generated_ids_trimmed = [
    out_ids[len(in_ids):] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
]
output_text = processor.batch_decode(generated_ids_trimmed, skip_special_tokens=True)[0]

print(output_text)

示例：音频输入处理 (简要)

Qwen3-Omni 原生支持音频输入。只需将输入内容中的 image 替换为音频文件路径或音频数据即可，模型会自动识别模态。

# 伪代码示例：音频输入结构
messages = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": "path/to/audio.wav"}, # 支持 wav, mp3 等格式
            {"type": "text", "text": "这段音频里的人在说什么？"}
        ]
    }
]
# 后续处理流程与图像输入一致

提示: 更多复杂场景（如实时语音对话、视频分析、OCR 等）请参考官方仓库中的 cookbooks 目录，其中包含了详细的 Jupyter Notebook 示例。