Python SDK_大模型服务平台百炼(Model Studio)-阿里云帮助中心

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

前期准备

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

快速开始

请访问github下载示例代码。我们提供了三种调用方式的示例代码：

音频对话示例：麦克风采集实时音频输入，开启VAD 模式（自动检测语音起止），支持语音打断。
enable_turn_detection参数需设为 True。
推荐您使用耳机播放音频，避免回声触发语音打断。
音视频对话示例：麦克风和摄像头采集实时音视频输入，开启VAD 模式（自动检测语音起止），支持语音打断。
enable_turn_detection参数需设为 True。
推荐您使用耳机播放音频，避免回声触发语音打断。
本地调用：本地音频和图片作为输入，开启Manual 模式（手动控制发送节奏）。
enable_turn_detection参数需设为 False。

请求参数

下述请求参数可以通过OmniRealtimeConversation的构造方法（_init_）进行设置。

参数	类型	说明
model	str	omni系列模型名称。参见模型列表。

下述请求参数可以通过update_session接口配置。

参数	类型	说明
output_modalities	list[MultiModality]	模型输出模态设置，支持设置[MultiModality.TEXT]（仅输出文本）或[MultiModality.TEXT, [MultiModality.AUDIO]（输出音频和文本）。
voice	str	模型生成音频的音色，支持："Chelsie", "Serena", "Ethan", "Cherry"。音色效果请参见：支持的音频音色。
input_audio_format	AudioFormat	用户输入音频的格式，当前只支持设置为PCM_16000HZ_MONO_16BIT。
output_audio_format	AudioFormat	模型输出音频的格式，当前只支持设置为PCM_24000HZ_MONO_16BIT。
enable_input_audio_transcription	bool	是否开启输入音频的语音识别。
input_audio_transcription_model	str	用于输入音频转录的语音识别模型，当前仅支持设置为"gummy-realtime-v1"
enable_turn_detection	bool	是否开启语音活动检测(VAD)，如果关闭后，由用户手动提交音频创建omni回复。
turn_detection_type	str	服务端VAD类型，目前固定为"server_vad"。
turn_detection_threshold	float	VAD检测阈值。建议在嘈杂的环境中增加，在安静的环境中降低。取值越接近-1，噪音被判定为语音的概率越大。取值越接近1，噪音被判定为语音的概率越小。默认为 0.2, 参数范围：[-1.0, 1.0]。
turn_detection_silence_duration_ms	int	检测语音停止的静音持续时间，超过此值后会触发模型响应。默认值为800，参数范围[200, 6000]。

关键接口

OmniRealtimeConversation类

OmniRealtimeConversation通过from dashscope.audio.qwen_omni import OmniRealtimeConversation方法引入。

方法签名	服务端响应事件（通过回调下发）	说明
`def connect(self) -> None`	session.created 会话已创建 session.updated 会话配置已更新	和服务端创建连接。
def update_session(self, output_modalities: list[MultiModality], voice: str, input_audio_format: AudioFormat = AudioFormat. PCM_16000HZ_MONO_16BIT, output_audio_format: AudioFormat = AudioFormat. PCM_16000HZ_MONO_16BIT, enable_input_audio_transcription: bool = True, input_audio_transcription_model: str = None, enable_turn_detection: bool = True, turn_detection_type: str = 'server_vad', prefix_padding_ms: int = 300, turn_detection_threshold: float = 0.2, turn_detection_silence_duration_ms: int = 800, turn_detection_param: dict = None, **kwargs) -> None	session.updated 会话配置已更新	更新本次会话交互的默认配置。参数配置请参考《请求参数》章节。在您建立链接，服务端会及时返回用于此会话的默认输出输入配置。如果您需要更新默认会话配置，我们也推荐您总是在建立链接后即刻调用此接口。服务端在收到session.update事件后，会进行参数校验，如果参数不合法则返回错误，否则更新服务端侧的会话配置。
`def append_audio(self, audio_b64: str) -> None`	无	将base64编码后的音频数据片段追加到云端输入音频缓冲区。音频缓冲区是你可以写入并稍后提交的临时存储。打开"turn_detection"，音频缓冲区用于检测语音，服务器决定何时提交。关闭"turn_detection"，客户端可以选择每个事件中放置多少音频量，最多放置 15 MiB。例如，从客户端流式处理较小的数据块可以让 VAD 响应更迅速。
`def append_video(self, video_b64: str) -> None`	无	将base64编码后的图片数据添加到云端视频缓冲区。图片数据可以是本地的图片，或从视频流实时采集的图片数据。目前对图片输入有以下限制：图片格式需要为JPG或JPEG，建议传入的图片分辨率为480P或720P，最大1080P；单张图片大小不大于500KB；图片数据需要经过Base64编码；建议您以 1张/秒的频率向服务端发送图片；
`def clear_appended_audio(self, ) -> None`	input_audio_buffer.cleared 清空服务端收到的音频	删除当前云端缓冲区的音频。
`def commit(self, ) -> None`	input_audio_buffer.commited 服务器收到提交的音频	提交之前通过append添加到云端缓冲区的音视频，如果输入的音频缓冲区为空将产生错误。打开"turn_detection"，客户端不需要发送此事件，服务器会自动提交音频缓冲区。关闭"turn_detection"，客户端必须提交音频缓冲区才能创建用户消息项。注意⚠️：如果 input_audio_transcription为会话配置了音频转录，系统会转录音频。提交输入音频缓冲区不会从模型创建响应。
`def create_response(self, instructions: str = None, output_modalities: list[MultiModality] = None) -> None`	response.created 服务端开始生成响应 response.output_item.added 响应时有新的输出内容 conversation.item.created 对话项被创建 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 mesasge 的文本或音频内容流式输出完成 response.output_item.done Assistant mesasge 的整个输出项流式传输完成 response.done 响应完成	指示服务器创建模型响应。打开"turn_detection"模式下配置会话时，服务器会自动创建模型响应。
`def cancel_response(self, ) -> None`	无	取消正在进行的响应。如果没有任何响应可供取消，服务器将以一个错误进行响应。
`def close(self, ) -> None`	无	终止任务，并关闭连接。
`def get_session_id(self) -> str`	无	获取当前任务的session_id。
`def get_last_response_id(self) -> str`	无	获取最近一次response的response_id。
`def get_last_first_text_delay(self)`	无	获取最近一次response的首包音频延迟。
`def get_last_first_audio_delay(self)`	无	获取最近一次response的首包文本延迟。

回调接口（OmniRealtimeCallback）

服务端会通过回调的方式，将服务端响应事件和数据返回给客户端。您需要实现回调方法，处理服务端返回的信息或者数据。

通过from dashscope.audio.qwen_omni import OmniRealtimeCallback引入。

方法	参数	返回值	描述
`def on_open(self) -> None`	无	无	当和服务端建立连接完成后，该方法立刻被回调。
`def on_event(self, message: str) -> None`	message：服务端响应事件。	无	包括对接口调用的回复响应和模型生成的文本和音频。具体可以参考：服务端事件
`def on_close(self, close_status_code, close_msg) -> None`	close_status_code：关闭websokcet的状态码。 close_msg：关闭websocket的关闭信息。	无	当服务已经关闭连接后进行回调。

常见问题

Q：输入的音频和图片要如何对齐？

omni-realtime模型的输入将音频作为时间轴，图片会按照发送的时间，插入到音频中。您可以在音频时间轴的任意时刻添加图片。

在实时交互场景下，您可以在任意时刻打开或关闭视频输入。

Q：输入图片和音频的推荐频率？

在实时交互场景，推荐按照1 fps或2 fps的帧率发送图片，按照100ms一包的音频发送音频。

Q：turn_detection开关两种模式的区别？

目前turn_detection打开后只支持server_vad模式：

打开"turn_detection"：
- 输入状态：云端的VAD（语音事件监测）会根据输入音频判断输入的一句话结束，并且立刻自动调用omni的推理下发回复文本和语音。
- 回复状态：在此状态下，音视频可以继续输入，不需要在模型回复阶段中断。回复结束后会回到输入状态等待语音。
- 打断：如果在模型回复期间，如果检测到用户开始说话则会触发打断，服务会立刻停止这一次的回复并且转换到输入状态。
关闭"turn_detection"：
- 用户需要自己判断一轮音视频输入的结束，并且手动通过commit和create_response触发omni的推理，获得回复。
- 在模型回复状态，需要停止音视频的输入。在模型回复结束后才可以继续输入下一轮音视频。
- 需要通过response_cancel接口打断模型回复。

注意，在打开"turn_detection"时，依旧可以通过commit和create_response主动触发回复，通过response_cancel主动打断。

Q：input_audio_transcription为何要选择其他模型？

omni是端到端的多模态大模型，文本输出是对输入的回答，因此不会直接产生输入音频的转录。需要接入其他ASR模型转录。目前只支持gummy-realtime-v1。关于gummy可以通过语音识别/翻译-Gummy了解。