全部產品
Search
文件中心

Alibaba Cloud Model Studio:Qwen-Audio-Realtime Flutter SDK

更新時間:Nov 19, 2026

Qwen-Audio-Realtime 的 Flutter SDK 接入指南,包含 Dart 呼叫流程、請求參數和事件。

Qwen-Audio-Realtime 接收即時音訊並傳回模型回覆。應用程式可設定接收文字和語音。

先決條件

  • 為目標平台設定 Flutter 開發環境。範例專案需要 Dart 3.4 以上、低於 4.0 的版本。
  • 取得 API Key。選擇與 API Key 位於相同地區的服務端點。若使用工作空間專屬網域,請一併取得業務空間 ID。

請勿在行動應用程式的程式碼中寫入長期 API Key。對於支援臨時 API Key 的模型,請由應用程式伺服器產生臨時 API Key,再傳送給用戶端。

安裝 SDK

開啟行動裝置語音 SDK 選型與下載,在 Flutter 分頁下載並解壓縮整合包。

將解壓縮後的 SDK 目錄複製到 Flutter 專案中的 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
    
  2. 在範例應用程式首頁開啟 百炼(DashScope)。選擇服務端點並填寫 API Key。若使用工作空間專屬網域,也請填寫 WorkspaceId。

  3. 開啟 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 分別使用「請求參數」中的連線 JSON 和任務 JSON。每次呼叫成功後再執行下一步。

  1. 先訂閱 eventStream 和 ttsAudioStream,再呼叫下列方法。

  2. 設定連線和任務參數後啟動工作階段。

    await nui.nuiInitialize(params: initJson);
    await nui.dialogSetParams(sessionJson);
    await nui.dialogStart(vadMode: VadMode.p2t.code, dialogParams: sessionJson);
    
  3. 工作階段啟動後擷取音訊,並透過 sendAudio 持續傳送 PCM 資料。整合包內的錄音範例採集 16 kHz、16 位元的單聲道 PCM。

    在 iOS 上,先啟動麥克風,再啟動播放器。如果播放器已啟動,請在麥克風啟動後重新啟動播放器,以免回覆語音無聲。

  4. 停止擷取後呼叫 dialogStop。處理完最後的事件後,呼叫 nuiRelease 並取消訂閱。

請求參數

下例使用整合包內的一個模型。其他設定請見整合包內的 example/lib/dashscope_params.dart。更多參數說明請參閱Android SDK、iOS SDK、HarmonyOS SDK。

將 YOUR_WS_HOST 取代為所在區域的 WebSocket 主機名稱、YOUR_DEVICE_ID 取代為裝置識別碼,並填寫該區域的 YOUR_API_KEY。

連線參數

將範例 JSON 當成字串傳入 Dart 方法。

{
  "device_id": "YOUR_DEVICE_ID",
  "url": "wss://YOUR_WS_HOST/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。在這個 Dart SDK 的請求中,modalities 和 turn_detection 都是 JSON 字串。

API 參考

方法

回傳 Future<int> 的方法以結果碼 0 表示成功。sendAudio 的回傳類型為 Future<Object?>。

方法簽名用途
Future<int> nuiInitialize({required String params, int logLevel = 0, bool saveLog = false})以 JSON 字串傳入連線參數並初始化 SDK。
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任務失敗