Skip to main content

Qwen-Omni-Realtime Python SDK

本文介绍 DashScope Python SDK 调用 Qwen-Omni 实时模型 时的关键接口与请求参数。

连接与鉴权参见 WebSocket 接入;事件字段与 JSON 示例参见客户端事件和服务端事件。

前提条件

SDK 版本需要不低于 2.0.1。请先阅读实时多模态交互流程。

快速开始

使用 qwen3.8-omni-flash-realtime 时,将会话构造参数 model 设为该模型名,默认音色为 Tina。Python SDK 会话配置和视频聚合参数示例见实时调用指南。 请访问GitHub下载示例代码。我们提供了三种调用方式的示例代码:
  1. 音频对话示例:麦克风采集实时音频输入,开启VAD 模式(自动检测语音起止),支持语音打断。
    enable_turn_detection参数需设为 True。
    推荐使用耳机播放音频,避免回声触发语音打断。
  2. 音视频对话示例:麦克风和摄像头采集实时音视频输入,开启VAD 模式(自动检测语音起止),支持语音打断。
    enable_turn_detection参数需设为 True。
    推荐使用耳机播放音频,避免回声触发语音打断。
  3. 本地调用:本地音频和图片作为输入,开启Manual 模式(手动控制发送节奏)。
    enable_turn_detection参数需设为 False。

请求参数

下述请求参数可以通过client.audio.realtime.connect方法进行设置。服务端事件不再通过回调下发,改为在接收线程中迭代会话的events()并按event["type"]分发处理(参见事件迭代)。

参数

类型

说明

model

str

Qwen-Omni系列模型名称。参见模型列表。

ws_url

str

完整WebSocket端点,未指定时按Client的workspace与region自动选择端点:

  • 新加坡地域:wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime

  • 北京地域:wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime

调用时请将{WorkspaceId}替换为真实的业务空间ID。

阿里云百炼为华北2(北京)、新加坡地域推出了业务空间专属域名,能够为推理请求提供卓越的性能和更高的稳定性,建议迁移至新域名:
  • 华北2(北京)地域:从 wss://dashscope.aliyuncs.com 迁移至 wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地域:从 wss://dashscope-intl.aliyuncs.com 迁移至 wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
其中 {WorkspaceId} 为您的业务空间 ID,可在阿里云百炼控制台的业务空间详情页面查看。Qwen3.8-Omni-Flash-Realtime 必须使用上述业务空间专属域名;旧型号可继续使用原域名。
下述请求参数可以通过update_session接口配置。
参数类型说明
output_modalitieslist[str]模型输出模态设置,支持设置['text'](仅输出文本)或['text', 'audio'](输出音频和文本)。
voicestr模型生成音频的音色,支持的音色参见音色列表。默认音色:
  • Qwen3.5-Omni-Realtime系列模型: "Tina"
  • qwen3-omni-flash-realtime-2025-09-15: "Cherry"
input_audio_configdict用户输入音频格式配置。通过 dict(含 type/sample_rate 键)同时设置格式(type:pcm/wav)和采样率(sample_rate:8000/16000/24000/48000,默认 16000 Hz),写法参见音频格式与采样率配置。适用模型:qwen3.5-omni-plus-realtime、qwen3.5-omni-flash-realtime。
output_audio_configdict模型输出音频格式配置。通过 dict(含 type/sample_rate 键)同时设置格式(type:pcm/wav)和采样率(sample_rate:8000/16000/24000/48000)。未指定采样率时默认 16000 Hz;配置输出音频时请显式设置所需采样率,如 24000 Hz。适用模型:qwen3.5-omni-plus-realtime、qwen3.5-omni-flash-realtime。
input_audio_formatstr历史兼容字段,新增接入建议使用 input_audio_config 同时配置输入格式和采样率。
output_audio_formatstr历史兼容字段,新增接入建议使用 output_audio_config 同时配置输出格式和采样率。
smooth_outputbool仅 qwen3-omni-flash-realtime-2025-09-15 支持设置。
  • True:获得口语化的回复
  • False:获得更书面化、正式的回复
    但可能会因为存在难以朗读的内容而导致效果不好。
  • None:模型自动选择口语化或书面化的回复风格
instructionsstr系统消息,用于设定模型的目标或角色。例如:你是某五星级酒店的AI客服专员,请准确且友好地解答客户关于房型、设施、价格、预订政策的咨询。请始终以专业和乐于助人的态度回应,杜绝提供未经证实或超出酒店服务范围的信息。
enable_input_audio_transcriptionbool是否开启输入音频的语音识别。
input_audio_transcription_modelstr用于输入音频转录的语音识别模型,固定为qwen3-asr-flash-realtime,不支持修改。
turn_detection_typestrVAD类型,取值如下:
  • server_vad(默认值):基于声学特征检测用户语音结束。
  • semantic_vad:基于语义有效性检测用户语音结束,可过滤无意义语音(如回应语、背景音)。Qwen3.8-Omni-Flash-Realtime 和 Qwen3.5-Omni-Realtime 系列模型支持。
turn_detection_thresholdfloatVAD检测阈值。建议在嘈杂的环境中增加, 在安静的环境中降低。
  • 取值越接近-1,噪音被判定为语音的概率越大。
  • 取值越接近1,噪音被判定为语音的概率越小。
默认为 0.5,参数范围:[-1.0, 1.0]。
turn_detection_silence_duration_msint检测语音停止的静音持续时间,超过此值后会触发模型响应。默认值为800,参数范围[200, 6000]。
turn_detection_paramdictVAD 扩展参数字典,用于传入 turn_detection 的额外配置项。当前支持传入 idle_timeout_ms(int):静默超时时间(毫秒)。仅在使用qwen3.5-omni-plus-realtime或qwen3.5-omni-flash-realtime模型且 VAD 类型为server_vad时生效。服务端完成音频播报且用户持续静默超过该时间(未触发 speech.started)后,模型将主动触发一轮响应,基于当前上下文引导用户继续对话。取值范围:[5000, 30000]。示例:turn_detection_param={'idle_timeout_ms': 5000}
enable_searchbool适用于 Qwen3.8-Omni-Flash-Realtime 和 Qwen3.5-Omni-Realtime 系列模型。是否启用联网搜索功能。设置为 true 启用,默认为 false。启用后,模型可自主判断是否需要搜索来回应用户的即时问题。
工具调用(tools)和联网搜索(enable_search)不兼容,不可同时开启。
search_optionsobject联网搜索选项配置。需启用 enable_search 后才生效。目前仅支持设置 enable_source(Boolean),表示是否返回搜索结果来源列表,设置为 true 启用。示例:search_options={'enable_source': True}。
toolslist[dict]适用于 Qwen3.8-Omni-Flash-Realtime 和 Qwen3.5-Omni-Realtime 系列模型。工具定义列表。启用后,模型可自主判断是否需要调用外部工具来回应用户的问题。命中 Function Calling 时,模型不生成音频,仅返回工具调用参数。Qwen3.8-Omni-Flash-Realtime 可在同一会话中配置 Function Calling 和 MCP 工具。MCP 配置字段见客户端事件,调用限制见MCP 调用限制。tools 与 enable_search 不可同时开启,该限制也适用于 MCP。以下字段描述 Function Calling 工具。每个工具为一个字典,包含以下字段:
  • type(string,必选):固定为 "function"。
  • function(dict,必选):工具函数的定义,包含以下字段:
    • name(string,必选):自定义的工具函数名称,建议使用与函数相同的名称,如 get_current_weather 或 get_current_time。
    • description(string,可选):对工具函数功能的描述,大模型会参考该字段来选择是否使用该工具函数。
    • parameters(dict,可选):对工具函数入参的描述,大模型会参考该字段来进行入参的提取。如果工具函数不需要输入参数,则无需指定。包含以下字段:
      • type(string,必选):固定为 "object"。
      • properties(dict,可选):描述各入参的名称、数据类型与描述。Key 值为入参的名称,Value 值为包含数据类型(type)与描述(description)的字典。
      • required(list,可选):指定哪些入参为必填项。
temperaturefloat采样温度,控制模型生成内容的多样性。temperature越高,生成的内容更多样,反之,生成的内容更确定。取值范围: [0, 2)由于temperature与top_p均可以控制生成内容的多样性,因此建议只设置其中一个值。
  • qwen3.8-omni-flash-realtime:0.6
  • Qwen3.5-Omni-Realtime系列模型:0.7
  • qwen3-omni-flash-realtime-2025-09-15:0.9
top_pfloat核采样的概率阈值,控制模型生成内容的多样性。top_p越高,生成的内容更多样。反之,生成的内容更确定。取值范围:(0,1.0]由于temperature与top_p均可以控制生成内容的多样性,因此建议只设置其中一个值。top_p默认值:
  • qwen3.8-omni-flash-realtime:0.95
  • Qwen3.5-Omni-Realtime系列模型:0.8
  • qwen3-omni-flash-realtime-2025-09-15:1.0
top_kinteger生成过程中采样候选集的大小。例如,取值为50时,仅将单次生成中得分最高的50个Token组成随机采样的候选集。取值越大,生成的随机性越高;取值越小,生成的确定性越高。取值为None或当top_k大于100时,表示不启用top_k策略,此时仅有top_p策略生效。取值需要大于或等于0。top_k默认值:
  • qwen3.8-omni-flash-realtime:20
  • Qwen3.5-Omni-Realtime系列模型:20
  • qwen3-omni-flash-realtime-2025-09-15:50
max_tokensinteger本次请求返回的最大 Token 数。
max_tokens 的设置不会影响大模型的生成过程,如果模型生成的 Token 数超过max_tokens,本次请求会返回截断后的内容。
qwen3.8-omni-flash-realtime 的取值范围为 [1, 65536]。其他模型的默认值和最大值都是模型的最大输出长度。关于各模型的最大输出长度,请参见百炼控制台。max_tokens参数适用于需要限制字数(如生成摘要、关键词)、控制成本或减少响应时间的场景。
repetition_penaltyfloat模型生成时连续序列中的重复度。提高repetition_penalty时可以降低模型生成的重复度,1.0表示不做惩罚。qwen3.8-omni-flash-realtime 支持取值 0;其他模型没有严格的取值范围,只要大于0即可。repetition_penalty默认值:
  • qwen3.8-omni-flash-realtime:0
  • Qwen3.5-Omni-Realtime系列模型:1.0
  • 其他模型:1.05
presence_penaltyfloat控制模型生成内容的重复度。取值范围:[-2.0, 2.0]。正数会减少重复度,负数会增加重复度。presence_penalty默认值:
  • qwen3.8-omni-flash-realtime:1
  • Qwen3.5-Omni-Realtime系列模型:1.5
  • 其他模型:0.0
适用场景:较高的presence_penalty适用于要求多样性、趣味性或创造性的场景,如创意写作或头脑风暴。较低的presence_penalty适用于要求一致性或专业术语的场景,如技术文档或其他正式文档。
seedinteger设置seed参数会使模型生成过程更具有确定性,通常用于使模型每次运行的结果一致。在每次模型调用时传入相同的seed值(自行指定),并保持其他参数不变,模型将尽可能返回相同的结果。取值范围:0到231−1,默认值-1。

接口参考

RealtimeSession(client.audio.realtime.connect)

实时会话通过client.audio.realtime.connect(model=...)创建:进入with上下文(或调用会话的connect()方法)后建立连接。
方法签名服务端响应事件(通过events()下发)说明
def connect(self) -> RealtimeSession
服务端事件
会话已创建
session.updated
会话配置已更新
和服务端创建连接。进入with上下文时自动调用,勿先connect()再进入同一会话的with。
def update_session(self,
                   output_modalities: List[str] = ...,
                   *,
                   voice: str = ...,
                   input_audio_format: str = ...,
                   output_audio_format: str = ...,
                   enable_input_audio_transcription: bool = ...,
                   input_audio_transcription_model: str = ...,
                   enable_turn_detection: bool = ...,
                   turn_detection_type: str = ...,
                   prefix_padding_ms: int = ...,
                   turn_detection_threshold: float = ...,
                   turn_detection_silence_duration_ms: int = ...,
                   turn_detection_param: dict = ...,
                   input_audio_config: dict = ...,
                   output_audio_config: dict = ...,
                   **kwargs) -> None
session.updated
会话配置已更新
更新本次会话交互的默认配置。参数配置请参考《请求参数》章节。在建立链接后,服务端会及时返回用于此会话的默认输出输入配置。如果需要更新默认会话配置,推荐总是在建立链接后即刻调用此接口。服务端在收到session.update事件后,会进行参数校验,如果参数不合法则返回错误,否则更新服务端侧的会话配置。
def append_audio(self, audio_b64: Union[str, bytes]) -> None
无将音频数据片段追加到云端输入音频缓冲区。str视为已编码的Base64,bytes会自动Base64编码。 音频缓冲区是可以写入并稍后提交的临时存储。
  • 打开"turn_detection",音频缓冲区用于检测语音,服务端决定何时提交。
  • 关闭"turn_detection",客户端可以选择每个事件中放置多少音频量,最多放置 15 MiB。 例如,从客户端流式处理较小的数据块可以让 VAD 响应更迅速。
def append_video(self, video_b64: Union[str, bytes]) -> None
无将图片数据添加到云端视频缓冲区,str视为已编码的Base64,bytes会自动Base64编码。图片数据可以是本地的图片,或从视频流实时采集的图片数据。目前对图片输入有以下限制:
  • 图片格式需要为JPG或JPEG,建议传入的图片分辨率为480P或720P, 最大1080P;
  • 单张图片经Base64编码后不得超过256KB,建议编码前原始图片大小不超过190KB;
  • 图片数据需要经过Base64编码;
  • 建议以 1张/秒 的频率向服务端发送图片;
def clear_appended_audio(self, ) -> None
input_audio_buffer.cleared
清空服务端收到的音频
删除当前云端缓冲区的音频。
def commit(self, ) -> None
input_audio_buffer.committed
服务端收到提交的音频
提交之前通过append添加到云端缓冲区的音视频,如果输入的音频缓冲区为空将产生错误。
  • 打开"turn_detection",客户端不需要发送此事件,服务端会自动提交音频缓冲区。
  • 关闭"turn_detection",客户端必须提交音频缓冲区才能创建用户消息项。
注意:
  1. 如果 input_audio_transcription为会话配置了音频转录,系统会转录音频。
  2. 提交输入音频缓冲区不会从模型创建响应。
def create_response(self,
        modalities: list[str] = ...,
        instructions: str = ...,
        **kwargs) -> None
服务端事件
服务端开始生成响应
response.output_item.added
响应时有新的输出内容
服务端事件
对话项被创建
response.content_part.added
新的输出内容添加到assistant message 项
response.audio_transcript.delta
增量生成的转录文字
response.audio.delta
模型增量生成的音频
response.audio_transcript.done
完成文本转录
response.audio.done
完成音频生成
response.content_part.done
Assistant message 的文本或音频内容流式输出完成
response.output_item.done
Assistant message 的整个输出项流式传输完成
response.done
响应完成
指示服务端创建模型响应。打开"turn_detection"模式下配置会话时,服务端会自动创建模型响应。
def cancel_response(self, ) -> None
无取消正在进行的响应。如果没有任何响应可供取消,服务端将以一个错误进行响应。
def create_item(self, item: dict) -> None
无向服务端发送 conversation.item.create 事件。回传 Function Calling 工具结果时,item 为 dict,包含以下字段:
  • type:固定为 function_call_output。
  • call_id:对应 response.function_call_arguments.done 事件中的 call_id。
  • output:工具执行结果的字符串。
MCP 审批也使用此事件,但 item.type 为 mcp_approval_response;字段见客户端事件中的 MCP 审批回复。
def close(self, ) -> None
无终止任务,并关闭连接(幂等,不发送session.finish)。
session.session_id
session.last_response_id
无获取当前任务的session_id、最近一次response的response_id(会话属性,另有last_first_text_delay/last_first_audio_delay等首包延迟指标)。

音频格式与采样率配置

通过 update_session 的 input_audio_config / output_audio_config 参数(dict,含 type 与 sample_rate 键)同时配置音频格式和采样率。 适用模型:qwen3.5-omni-plus-realtime、qwen3.5-omni-flash-realtime。
# dict 中同时指定格式(type)与采样率(sample_rate)
session.update_session(
    output_modalities=['audio', 'text'],
    voice=voice,
    input_audio_config={"type": "pcm", "sample_rate": 16000},
    output_audio_config={"type": "wav", "sample_rate": 24000},
)

事件迭代(events())

服务端会通过事件的方式,将服务端响应事件和数据返回给客户端。您需要在接收线程中迭代会话的events(),按event["type"]分发处理(完整事件列表参见服务端事件)。
def receive_events(session):
    for event in session.events():
        kind = event.get('type')
        if kind == 'session.created':
            print('start session: {}'.format(event['session']['id']))
        elif kind == 'conversation.item.input_audio_transcription.completed':
            print(f"[User] {event['transcript']}")
        elif kind == 'response.audio.delta':
            # 模型增量生成的音频(Base64),可解码后送入播放设备
            audio = base64.b64decode(event['delta'])
        elif kind == 'response.audio_transcript.done':
            print(f"[LLM] {event['transcript']}")
方法签名参数说明
def events(self) -> Iterator[Dict]
event:服务端事件连续读取并逐个产出服务端事件(dict)。连接关闭或收到session.finished后迭代结束。请由一个接收线程持续消费,不要并发创建多个读取者。
def recv_event(self) -> Optional[Dict]
无阻塞读取单条服务端事件,不自动循环;无事件(连接关闭)时返回None。错误事件会以DashScopeError异常抛出。