跳转到主要内容
Flutter SDK

Qwen-Audio-Realtime Flutter SDK

使用 Flutter SDK 接入 Qwen-Audio-Realtime 实时语音对话,包含 Dart 调用流程、请求参数和事件。

Qwen-Audio-Realtime 接收实时音频并返回模型回复。应用可根据配置接收回复文本和语音。

前提条件

移动端应用请勿硬编码长期 API Key。调用支持临时 API Key 的模型时,由应用服务端生成临时 API Key并下发给客户端。

安装 SDK

在 SDK 下载页面获取移动端语音 SDK 整合包。解压后将 Flutter SDK 目录复制到项目的 packages/aliyun_neonui,并在 pubspec.yaml 中添加本地依赖。
dependencies:
  aliyun_neonui:
    path: packages/aliyun_neonui
运行 flutter pub get,然后在 Dart 文件中导入 SDK。
import 'package:aliyun_neonui/neonui.dart';

快速开始

  1. 连接目标设备,在解压后的 SDK 目录中运行示例。
cd example
flutter pub get
flutter run
  1. 打开示例应用,选择服务地址并填写 API Key。
  2. 打开 Qwen-Audio 实时语音对话示例并运行,运行时允许应用使用麦克风。
完整示例见整合包中的 example/lib/pages/dashscope/dash_qwen_audio_chat_page.dart。 包内示例包含以下模型:
  • qwen-audio-3.1-realtime-plus
  • qwen-audio-3.0-realtime-plus
  • qwen-audio-3.0-realtime-flash

调用步骤

通过 NativeNui() 获取实例后调用以下方法。下文 initJson 和 sessionJson 分别对应「请求参数」中的连接参数和任务参数,每次调用成功后再执行下一步。
  1. 先订阅 eventStream 和 ttsAudioStream,再初始化并启动会话。
await nui.nuiInitialize(params: initJson);
await nui.dialogSetParams(sessionJson);
await nui.dialogStart(vadMode: VadMode.p2t.code, dialogParams: sessionJson);
  1. 会话启动后采集音频,通过 sendAudio 持续发送 PCM 数据。包内录音示例采集 16 kHz、16 位、单声道 PCM。
在 iOS 上,先启动麦克风,再启动播放器。如果播放器已启动,请在麦克风启动后重启播放器,以免回复语音无声。
  1. 停止采集后调用 dialogStop,处理完最后的事件后调用 nuiRelease 并取消订阅。

请求参数

以下示例使用包内示例的一个模型。需要调整其他字段时,可参考整合包中的 example/lib/dashscope_params.dart。更多参数说明见 Android SDK、iOS SDK、HarmonyOS SDK。

连接参数

示例中的 JSON 作为字符串传入 Dart 方法。
{
  "device_id": "YOUR_DEVICE_ID",
  "url": "wss://maas.qianwenaiapi.com/api-ws/v1/realtime?model=qwen-audio-3.1-realtime-plus",
  "service_mode": "1",
  "audio_update_manually": "false"
}

任务参数

示例中的 JSON 作为字符串传入 Dart 方法。
{
  "apikey": "YOUR_API_KEY",
  "nls_config": {
    "model": "qwen-audio-3.1-realtime-plus",
    "sr_format": "pcm",
    "modalities": "[\"text\",\"audio\"]",
    "voice": "longanqian_v3.1",
    "turn_detection": "{\"type\":\"server_vad\",\"threshold\":0.5,\"silence_duration_ms\":800}"
  },
  "service_type": 4
}
URL 查询参数中的 model 与 nls_config.model 使用同一模型 ID。modalities 和 turn_detection 在这个 Dart SDK 的请求中是 JSON 字符串。

接口参考

方法

返回 Future<int> 的方法中,结果码 0 表示成功。音频发送方法 sendAudio 的返回类型为 Future<Object?>。
方法签名用途
Future<int> nuiInitialize({required String params, int logLevel = 0, bool saveLog = false})初始化 SDK。params 为连接参数 JSON 字符串。
Future<int> dialogSetParams(String params)设置当前会话的 JSON 参数。
Future<int> dialogStart({required int vadMode, String dialogParams = "{}"})开始会话。vadMode 指定断句模式,dialogParams 可传入本次会话要使用的 JSON 参数。
Future<Object?> sendAudio(Uint8List data)发送一段 PCM 音频。
Future<int> dialogStop()结束当前采集会话并保留连接。
Future<int> dialogCancel()取消当前会话或合成。
Future<int> nuiRelease()释放 SDK 资源。
Future<int> dialogAction(String actionParams)向会话提交工具调用结果。

事件与音频流

事件从 eventStream 读取。收到 Dart Map 时,以 event 识别事件名,任务类事件的 resultCode 可用于判断错误。 音频流 ttsAudioStream 返回音频分片。应用负责播放音频。
事件用途
EVENT_ASR_PARTIAL_RESULT临时识别结果
EVENT_SENTENCE_END当前句的最终识别结果
EVENT_AUDIO_TRANSCRIPTION_COMPLETED语音回复的文本转写完成
EVENT_ASR_TTS_START合成或回复音频开始
EVENT_ASR_TTS_COMPLETE任务或当前音频输出完成
EVENT_ASR_ERROR任务失败