本文介绍 DashScope Python SDK 调用 Qwen-Omni 实时模型 时的关键接口与请求参数。
连接与鉴权参见 WebSocket 接入;事件字段与 JSON 示例参见客户端事件和服务端事件。
SDK 版本需要不低于 2.0.1。请先阅读实时多模态交互流程。
使用
下述请求参数可以通过
下述请求参数可以通过update_session接口配置。
实时会话通过
通过
服务端会通过事件的方式,将服务端响应事件和数据返回给客户端。您需要在接收线程中迭代会话的
前提条件
SDK 版本需要不低于 2.0.1。请先阅读实时多模态交互流程。
快速开始
使用 qwen3.8-omni-flash-realtime 时,将会话构造参数 model 设为该模型名,默认音色为 Tina。Python SDK 会话配置和视频聚合参数示例见实时调用指南。
请访问GitHub下载示例代码。我们提供了三种调用方式的示例代码:
-
音频对话示例:麦克风采集实时音频输入,开启VAD 模式(自动检测语音起止),支持语音打断。
enable_turn_detection参数需设为 True。推荐使用耳机播放音频,避免回声触发语音打断。
-
音视频对话示例:麦克风和摄像头采集实时音视频输入,开启VAD 模式(自动检测语音起止),支持语音打断。
enable_turn_detection参数需设为 True。推荐使用耳机播放音频,避免回声触发语音打断。
-
本地调用:本地音频和图片作为输入,开启Manual 模式(手动控制发送节奏)。
enable_turn_detection参数需设为 False。
请求参数
下述请求参数可以通过client.audio.realtime.connect方法进行设置。服务端事件不再通过回调下发,改为在接收线程中迭代会话的events()并按event["type"]分发处理(参见事件迭代)。
参数 | 类型 | 说明 |
|---|---|---|
model | str | Qwen-Omni系列模型名称。参见模型列表。 |
ws_url | str | 完整WebSocket端点,未指定时按
调用时请将 |
| 参数 | 类型 | 说明 |
|---|---|---|
| output_modalities | list[str] | 模型输出模态设置,支持设置['text'](仅输出文本)或['text', 'audio'](输出音频和文本)。 |
| voice | str | 模型生成音频的音色,支持的音色参见音色列表。默认音色:
|
| input_audio_config | dict | 用户输入音频格式配置。通过 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_config | dict | 模型输出音频格式配置。通过 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_format | str | 历史兼容字段,新增接入建议使用 input_audio_config 同时配置输入格式和采样率。 |
| output_audio_format | str | 历史兼容字段,新增接入建议使用 output_audio_config 同时配置输出格式和采样率。 |
| smooth_output | bool | 仅 qwen3-omni-flash-realtime-2025-09-15 支持设置。
|
| instructions | str | 系统消息,用于设定模型的目标或角色。例如:你是某五星级酒店的AI客服专员,请准确且友好地解答客户关于房型、设施、价格、预订政策的咨询。请始终以专业和乐于助人的态度回应,杜绝提供未经证实或超出酒店服务范围的信息。 |
| enable_input_audio_transcription | bool | 是否开启输入音频的语音识别。 |
| input_audio_transcription_model | str | 用于输入音频转录的语音识别模型,固定为qwen3-asr-flash-realtime,不支持修改。 |
| turn_detection_type | str | VAD类型,取值如下:
|
| turn_detection_threshold | float | VAD检测阈值。建议在嘈杂的环境中增加, 在安静的环境中降低。
|
| turn_detection_silence_duration_ms | int | 检测语音停止的静音持续时间,超过此值后会触发模型响应。默认值为800,参数范围[200, 6000]。 |
| turn_detection_param | dict | VAD 扩展参数字典,用于传入 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_search | bool | 适用于 Qwen3.8-Omni-Flash-Realtime 和 Qwen3.5-Omni-Realtime 系列模型。是否启用联网搜索功能。设置为 true 启用,默认为 false。启用后,模型可自主判断是否需要搜索来回应用户的即时问题。工具调用(tools)和联网搜索(enable_search)不兼容,不可同时开启。 |
| search_options | object | 联网搜索选项配置。需启用 enable_search 后才生效。目前仅支持设置 enable_source(Boolean),表示是否返回搜索结果来源列表,设置为 true 启用。示例:search_options={'enable_source': True}。 |
| tools | list[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 工具。每个工具为一个字典,包含以下字段:
|
| temperature | float | 采样温度,控制模型生成内容的多样性。temperature越高,生成的内容更多样,反之,生成的内容更确定。取值范围: [0, 2)由于temperature与top_p均可以控制生成内容的多样性,因此建议只设置其中一个值。
|
| top_p | float | 核采样的概率阈值,控制模型生成内容的多样性。top_p越高,生成的内容更多样。反之,生成的内容更确定。取值范围:(0,1.0]由于temperature与top_p均可以控制生成内容的多样性,因此建议只设置其中一个值。top_p默认值:
|
| top_k | integer | 生成过程中采样候选集的大小。例如,取值为50时,仅将单次生成中得分最高的50个Token组成随机采样的候选集。取值越大,生成的随机性越高;取值越小,生成的确定性越高。取值为None或当top_k大于100时,表示不启用top_k策略,此时仅有top_p策略生效。取值需要大于或等于0。top_k默认值:
|
| max_tokens | integer | 本次请求返回的最大 Token 数。
qwen3.8-omni-flash-realtime 的取值范围为 [1, 65536]。其他模型的默认值和最大值都是模型的最大输出长度。关于各模型的最大输出长度,请参见百炼控制台。max_tokens参数适用于需要限制字数(如生成摘要、关键词)、控制成本或减少响应时间的场景。 |
| repetition_penalty | float | 模型生成时连续序列中的重复度。提高repetition_penalty时可以降低模型生成的重复度,1.0表示不做惩罚。qwen3.8-omni-flash-realtime 支持取值 0;其他模型没有严格的取值范围,只要大于0即可。repetition_penalty默认值:
|
| presence_penalty | float | 控制模型生成内容的重复度。取值范围:[-2.0, 2.0]。正数会减少重复度,负数会增加重复度。presence_penalty默认值:
|
| seed | integer | 设置seed参数会使模型生成过程更具有确定性,通常用于使模型每次运行的结果一致。在每次模型调用时传入相同的seed值(自行指定),并保持其他参数不变,模型将尽可能返回相同的结果。取值范围:0到231−1,默认值-1。 |
接口参考
RealtimeSession(client.audio.realtime.connect)
实时会话通过client.audio.realtime.connect(model=...)创建:进入with上下文(或调用会话的connect()方法)后建立连接。
| 方法签名 | 服务端响应事件(通过events()下发) | 说明 |
|---|---|---|
服务端事件会话已创建session.updated 会话配置已更新 | 和服务端创建连接。进入with上下文时自动调用,勿先connect()再进入同一会话的with。 | |
session.updated会话配置已更新 | 更新本次会话交互的默认配置。参数配置请参考《请求参数》章节。在建立链接后,服务端会及时返回用于此会话的默认输出输入配置。如果需要更新默认会话配置,推荐总是在建立链接后即刻调用此接口。服务端在收到session.update事件后,会进行参数校验,如果参数不合法则返回错误,否则更新服务端侧的会话配置。 | |
| 无 | 将音频数据片段追加到云端输入音频缓冲区。str视为已编码的Base64,bytes会自动Base64编码。 音频缓冲区是可以写入并稍后提交的临时存储。
| |
| 无 | 将图片数据添加到云端视频缓冲区,str视为已编码的Base64,bytes会自动Base64编码。图片数据可以是本地的图片,或从视频流实时采集的图片数据。目前对图片输入有以下限制:
| |
input_audio_buffer.cleared清空服务端收到的音频 | 删除当前云端缓冲区的音频。 | |
input_audio_buffer.committed服务端收到提交的音频 | 提交之前通过append添加到云端缓冲区的音视频,如果输入的音频缓冲区为空将产生错误。
| |
服务端事件服务端开始生成响应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"模式下配置会话时,服务端会自动创建模型响应。 | |
| 无 | 取消正在进行的响应。如果没有任何响应可供取消,服务端将以一个错误进行响应。 | |
| 无 | 向服务端发送 conversation.item.create 事件。回传 Function Calling 工具结果时,item 为 dict,包含以下字段:
item.type 为 mcp_approval_response;字段见客户端事件中的 MCP 审批回复。 | |
| 无 | 终止任务,并关闭连接(幂等,不发送session.finish)。 | |
| 无 | 获取当前任务的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。
事件迭代(events())
服务端会通过事件的方式,将服务端响应事件和数据返回给客户端。您需要在接收线程中迭代会话的events(),按event["type"]分发处理(完整事件列表参见服务端事件)。
| 方法签名 | 参数 | 说明 |
|---|---|---|
| event:服务端事件 | 连续读取并逐个产出服务端事件(dict)。连接关闭或收到session.finished后迭代结束。请由一个接收线程持续消费,不要并发创建多个读取者。 | |
| 无 | 阻塞读取单条服务端事件,不自动循环;无事件(连接关闭)时返回None。错误事件会以DashScopeError异常抛出。 |