Qwen-Audio-3.0-Realtimeリアルタイム音声会話Android SDK - Alibaba Cloud Model Studio

Qwen-Audio-3.0-Realtime 用の Android SDK を使用して、音声入力と音声またはテキスト出力を備えたリアルタイム音声対話を構築します。

ユーザーガイド：モデルの紹介と選択のアドバイスについては、リアルタイム音声会話を参照してください。

クイックスタート

APIキーを取得して設定します。
SDKをダウンロードしてサンプルコードを実行します:
- 最新のSDKパッケージをダウンロードします。
- ZIPパッケージを抽出します。app/libsからAAR SDKを取得し、プロジェクトの依存関係に追加します。Android C++統合の場合、ZIPパッケージ内のandroid_libsとandroid_includeを使用して、動的ライブラリとヘッダーファイルを取得します。
- Android Studioでプロジェクトを開きます。サンプルコードはDashQwenAudioChatActivity.javaにあります。APIキーを置き換えて、機能を試してください。

呼び出し手順

SDKを初期化します。
ユースケースに合わせてパラメータを設定します。initializeのparameters引数を使用して接続および制御パラメータを設定し、setParamsを使用して音声会話パラメータを設定します。
startDialog を呼び出して会話を開始します。
onNuiAudioStateChangedで、音声状態に基づいて録音デバイスを開始します。
onNuiNeedAudioDataで録音データを継続的に供給するか、updateAudioを呼び出して録音データをアクティブにプッシュします。
onNuiAssistEventCallbackで、モデルから返される音声を受信し続けます。
イベントをリッスンし、onNuiEventCallback でイベント情報を取得します。
stopDialogを呼び出して会話を停止し、EVENT_TRANSCRIBER_COMPLETEをリッスンして終了したことを確認します。
会話機能が不要になったら、releaseを呼び出してSDKリソースを解放します。

リクエストパラメータ

接続および制御パラメータ

initialize の parameters 引数にJSON文字列を渡します。

例：以下のJSON文字列には、すべてのパラメータがリストされているわけではありません。ユースケースに応じて必要に応じてパラメータを追加してください。

{
  "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
  "apikey": "st-****",
  "device_id": "my_device_id",
  "service_mode": "1"
}

パラメータ

パラメータ	型	必須	説明
`url`	`String`	はい	サービスエンドポイント： `wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=<model_name>` 中国（北京）：`wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>` シンガポール: `wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>` 置き換え `{WorkspaceId}` 実際のワークスペースID.
`apikey`	`String`	はい	API キー。
`service_mode`	`String`	はい	ランタイムモード。リアルタイム音声会話の場合、このパラメータを `"1"` に設定します。
`device_id`	`String`	はい	エンドユーザーを識別する一意の文字列です。アプリ内ユーザーIDまたはクライアント生成のデバイス識別子を使用できます。このIDは主にログのトレースとトラブルシューティングに使用されます。
`audio_update_manually`	`String`	いいえ	音声データをアクティブにプッシュするかどうかです。デフォルト：`"false"`。`"true"`に設定されており、SDKがAECやVADなどのデバイス上音声機能をサポートしている場合、それらの機能はデフォルトで有効になります。
`workspace`	`String`	いいえ	デバイス上リソースファイルの保存パスです。このパラメータは、`audio_update_manually`が`"true"`であり、AECやVADなどのデバイス上音声機能が有効になっている場合に必須です。
`debug_path`	`String`	いいえ	ログファイルの保存パスです。このパラメータは、`initialize`で`save_log`が`true`の場合にのみ有効になります。この場合、パスは必須です。SDKはローカルに最大2つのログファイルを保持します。
`save_wav`	`String`	いいえ	`debug_path`の下にデバッグ音声を保存するかどうかです。デフォルト：`"false"`。有効な値は`"true"`および`"false"`です。このパラメータは、`save_log`が`true`であり、かつ`debug_path`も設定されている場合にのみ有効になります。
`max_log_file_size`	`int`	いいえ	バイト単位の最大ログファイルサイズです。このパラメータは、`save_log`が`true`の場合にのみ有効になります。デフォルト：`104857600`（100 × 1024 × 1024バイト、または100 MiB）。
`log_track_level`	`int`	いいえ	`onNuiLogTrackCallback`を通じて送信されるログのフィルターレベルです。デフォルト：`2`。有効な値：`0`（VERBOSE）、`1`（DEBUG）、`2`（INFO）、`3`（WARNING）、`4`（ERROR）、および`5`（NONE）。ログは、そのレベルが`log_track_level`と`initialize`に渡される`level`の両方以上の場合にのみ返されます。たとえば、`log_track_level`が`2`（INFO）で`level`が`3`（WARNING）の場合、WARNING以上のレベルのログ（`3`以上の値）のみが返されます。
`aec_params`	`object`	いいえ	高度なデバイス上AEC設定です。このオブジェクトは、`audio_update_manually`が`"true"`の場合にのみ有効になります。
`aec_params.enable_aec`	`boolean`	いいえ	デバイス上AECを有効にするかどうかです。`audio_update_manually`が`"true"`であり、SDKがデバイス上AECをサポートしている場合、AECはデフォルトで有効になります。
`aec_params.save_audio`	`boolean`	いいえ	デバイス上AECモジュールによって処理された音声を保存するかどうかです。`save_wav`が`"true"`であり、`debug_path`が設定されている場合、この機能はデフォルトで有効になり、音声は`debug_path`の下に保存されます。
`aec_params.enable_aec_data_callback`	`boolean`	いいえ	`onNuiAssistEventCallback`の`EVENT_AEC_DATA`を通じてAEC処理済みの音声を返すかどうかです。デフォルト：`false`。
`vad_params`	`object`	いいえ	高度なデバイス上VAD設定です。このオブジェクトは、`audio_update_manually`が`"true"`の場合にのみ有効になります。
`vad_params.enable_vad`	`boolean`	いいえ	デバイス上VADを有効にするかどうかです。`audio_update_manually`が`"true"`であり、SDKがデバイス上VADをサポートしている場合、VADはデフォルトで有効になります。
`vad_params.save_audio`	`boolean`	いいえ	デバイス上VADモジュールによって処理された音声を保存するかどうかです。`save_wav`が`"true"`であり、`debug_path`が設定されている場合、この機能はデフォルトで有効になり、音声は`debug_path`の下に保存されます。

音声会話パラメータ

setParams の params 引数にJSON文字列を渡します。

{
  "service_type": 4,
  "nls_config": {
    "model": "qwen-audio-3.1-realtime-plus",
    "sr_format": "pcm"
  }
}

パラメータ

トップレベルパラメータ	型	必須	説明
`service_type`	`int`	はい	音声サービスタイプ。リアルタイム音声会話の場合、このパラメータを `4` に設定します。
`nls_config`	`object`	はい	モデルの選択や会話の動作を含む、コアとなる音声会話の設定。
`nls_config.model`	`string`	はい	モデル名です。`qwen-audio-3.1-realtime-plus`、`qwen-audio-3.0-realtime-plus`、および`qwen-audio-3.0-realtime-flash`モデルシリーズをサポートします。
`nls_config.sr_format`	`string`	はい	入力オーディオ形式。`pcm` のみがサポートされています。デフォルトの形式は 16 kHz、16 ビット、モノラルPCMです。
`nls_config.modalities`	`string`	いいえ	出力モダリティの配列を含む文字列です。有効な値： `["text"]`: テキストのみを返します。 `["audio", "text"]` (デフォルト): オーディオとテキストの両方を返します。
`nls_config.voice`	`string`	いいえ	TTS音声です。デフォルトは、3.1 Plusの場合は`longanqian_v3.1`、3.0 Plus/Flashの場合は`longanqian`です。このパラメータは、最初の`session.update`でのみ設定でき、それ以降の値は無視されます。システム音声：`longanqian`、`longanlingxin`、`longanlingxi`、`longanxiaoxin`、および`longanlufeng`。音声クローンAPIを通じて作成されたクローン`voice_id`を指定することもできます。音声設定を参照してください。 3.1 Plusは、`longanqian_v3.1`、`longanhuan_v3.1`、`longanlingxin_v3.1`、`longanfengyue_v3.1`、`xunanchuan_v3.1`、`beth_v3.1`、`betty_v3.1`、`cally_v3.1`もサポートしています。
`nls_config.enable_speech_emotion`	`boolean`	いいえ	強化された感情表現を有効にするかどうかです。有効にすると、応答音声の感情の変化がより顕著になります。デフォルト：`true`。有効な値：`true`および`false`。
`nls_config.instructions`	`string`	いいえ	セッション全体におけるモデルの役割、応答スタイル、および動作の好みを定義するシステム指示です。
`nls_config.max_history_turns`	`int`	いいえ	リクエストで許可される過去の質問と回答のターンの最大数です。有効な値：1～50。デフォルト：`20`。
`nls_config.tools`	`string`	いいえ	Function Callingツール定義の配列を含む文字列です。このパラメータを設定すると、モデルはユーザー入力に基づいてツールを呼び出すかどうかを決定します。各定義は`type`（必須、`function`に固定）と、`name`（必須）、`description`（オプション）、および`parameters`（オプション）を含む`function`オブジェクトを使用します。関数に引数がない場合は、`parameters`を省略します。例： `[ { "type": "function", "function": { "name": "get_weather", "description": "Queries weather information for a specified city.", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "City" } }, "required": [ "city" ] } } } ]`
`nls_config.turn_detection`	`string`	いいえ	ターン検出用のJSONオブジェクトを含む文字列です。省略した場合、セッションはプッシュトゥートークモードを使用し、音声がコミットされ、推論が手動でトリガーされます。設定されている場合、デュプレックス会話モードが有効になります。
`nls_config.turn_detection.type`	`string`	いいえ	VADタイプです。`server_vad`（デフォルト）は音響特徴から発話境界を検出し、自動的に推論をトリガーします。`smart_turn`は音響信号と意味信号を組み合わせており、フィラー音などの意味内容を持たない音はターンを開始したり、モデルの再生を中断したりしません。
`nls_config.turn_detection.threshold`	`float`	いいえ	VAD感度です。このパラメータは`server_vad`にのみ適用され、`smart_turn`には影響しません。値が低いほど、VADは静かな音や背景ノイズに対して敏感になり、値が高いほど、より明瞭で大きな音声が求められます。有効な範囲：`[-1.0, 1.0]`。デフォルト：`0.5`。
`nls_config.turn_detection.silence_duration_ms`	`int`	いいえ	発話後のモデル応答がトリガーされるまでの最小無音期間（ミリ秒単位）です。このパラメータは`server_vad`にのみ適用され、`smart_turn`には影響しません。値が低いほどレイテンシは短縮されますが、短い一時停止でトリガーされる可能性があります。有効な範囲：`[200, 6000]`。デフォルト：`800`。会話での推奨値：`400`～`800`。
`nls_config.turn_detection.voiceprint_audio_urls`	`string`	いいえ	ターゲットスピーカー用の公開アクセス可能な事前録音済み音声URLの配列を含む文字列です。このパラメータは`smart_turn`にのみ適用されます。デュプレックス会話では、モデルがターゲットスピーカーに集中し、他のスピーカーや背景ノイズを無視するのに役立ちます。最大5つのURLがサポートされています。音声は16 kHz PCMまたはWAVである必要があります。

主要API

NativeNui

initialize

音声会話SDKインスタンスを初期化します。SDKはシングルトンです。releaseを呼び出す前に、複数回初期化しないでください。

このメソッドはブロックされるため、非UIスレッドで呼び出してください。

メソッドシグネチャ

public synchronized int initialize(final INativeNuiCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)

パラメータ

パラメータ	型	説明
`callback`	INativeNuiCallback	イベントおよびデータコールバックインターフェースの実装。
`parameters`	`String`	認証、接続、およびデバッグパラメータを含むJSON文字列です。接続および制御パラメータを参照してください。
`level`	`Constants.LogLevel`	SDK独自のログの出力レベルを制御します。
`save_log`	`boolean`	ローカルログを保存するかどうかです。`true`に設定した場合、接続および制御パラメータの`debug_path`を通じてパスを指定し、オプションで`max_log_file_size`を通じてファイルサイズを設定します。

setParams

JSON形式で音声会話パラメータを設定します。startDialogの前にこのメソッドを呼び出します。

メソッドシグネチャ

public synchronized int setParams(String params)

パラメータ

パラメータ	型	説明
`params`	`String`	音声会話パラメータ。

startDialog

会話を開始します。

メソッドシグネチャ

public synchronized int startDialog(VadMode vad_mode, String dialog_params)

パラメータ

パラメータ 型説明

パラメータ	型	説明
`vad_mode`	`VadMode`	VADモード。`VadMode.TYPE_P2T` に固定されています。
`dialog_params`	`String`	接続および制御パラメータの`apikey`が一時的なAPIキーである場合、有効期限が切れた後にここで更新します。 JSON形式： `{ "apikey": "st-****" }`

vad_mode

VadMode

VADモード。VadMode.TYPE_P2T に固定されています。

dialog_params

String

接続および制御パラメータのapikeyが一時的なAPIキーである場合、有効期限が切れた後にここで更新します。
JSON形式：

{
  "apikey": "st-****"
}

stopDialog

会話を終了します。このメソッドを呼び出すと、サーバーは最終的な会話結果を返し、タスクを終了します。

メソッドシグネチャ

public synchronized int stopDialog();

cancelDialog

会話を即座に終了します。このメソッドを呼び出すと、サーバーが最終的な会話結果を返すのを待たずに、タスクがすぐに終了します。

メソッドシグネチャ

public synchronized int cancelDialog();

updateAction

インタラクション中に会話アクションコマンドを送信し、会話コンテキストなどのランタイム動作を更新します。

メソッドシグネチャ

public synchronized int updateAction(String params);

パラメータ

パラメータ	型	説明
`params`	`String`	会話コンテキストなどのランタイムの動作を更新するために使用されるJSON文字列。
`params.type`	`String`	`"action"` に設定します。
`params.command`	`String`	ランタイムコマンドです。有効な値： `function_call`: 関数呼び出しリクエストを更新します。 `play_start`: オンデバイスAECが使用されている場合、オーディオの再生が開始されたことをSDKに通知します。 `play_over`: オンデバイスAECが使用されている場合、オーディオの再生が終了したことをSDKに通知します。
`params.context`	`String`	関数呼び出しリクエストの更新。`command` が `"function_call"` の場合に使用されます。
`params.context.type`	`String`	イベントタイプです。このパラメータは、`command`が`"function_call"`の場合に必須です。`conversation.item.create`は、過去のコンテキスト、補足テキスト、またはツール結果の会話アイテムを挿入します。`conversation.item.create`を送信した後、`response.create`を使用して別の推論をトリガーします。
`params.context.item`	`object`	`params.context.type` が `conversation.item.create` の場合に必須。作成する会話アイテム。
`params.context.response`	`object`	`params.context.type`が`response.create`の場合はオプションです。この推論のセッションデフォルトを上書きします。省略した場合、現在のセッション設定が使用されます。

context.item パラメータ:

パラメータ	型	説明
`id`	`String`	オプションの一意な会話アイテムIDです。省略した場合、サーバーが生成します。指定されたIDが既に存在する場合はエラーが返されます。
`type`	`String`	必須のアイテムタイプです。有効な値： `message`: 通常のメッセージ。 `function_call`：関数呼び出しリクエストです。このタイプは通常、サーバーによって生成されます。クライアントはこれを使用して過去のコンテキストを追加することもできます。 `function_call_output`：ツール実行結果です。`function_call`を受信した後、クライアントはツールを実行し、このタイプを使用して結果を書き戻します。
`role`	`String`	`message` に必須。有効な値: `system`、`user`、および `assistant`。
`content`	`array`	`message`に必須です。各アイテムには`type`と関連するデータフィールドが含まれます。`system`は`text`を持つ`input_text`をサポートし、`user`は`text`を持つ`input_text`およびBase64エンコードされた`audio`を持つ`input_audio`をサポートし、`assistant`は`text`を持つ`output_text`をサポートします。
`call_id`	`String`	`function_call`および`function_call_output`に必須です。関数呼び出しリクエストとその結果を関連付ける一意のIDです。
`name`	`String`	`function_call` に必須。呼び出す関数の名前。
`arguments`	`String`	`function_call` に必須。JSON文字列としての関数の引数。
`output`	`String`	`function_call_output` に必須。JSON文字列としてのツール実行結果。

context.response パラメータ:

パラメータ	型	説明
`modalities`	`array`	出力モダリティです。`["text"]`はテキストのみを返します。`["audio", "text"]`（デフォルト）は音声とテキストの両方を返します。
`voice`	`string`	この推論のTTS音声をオーバーライドします。

例:

{
  "type": "action",
  "command": "function_call",
  "context": {
    "item": {
      "call_id": "call_xxxx",
      "output": "{\"city\":\"Hangzhou\",\"condition\":\"sunny\",\"temperature\":18}",
      "type": "function_call_output"
    },
    "type": "conversation.item.create"
  }
}

{
  "type": "action",
  "command": "function_call",
  "context": {
    "response": {
      "modalities": ["text", "audio"]
    },
    "type": "response.create"
  }
}

updateAudio

audio_update_manuallyが"true"に設定されている場合、onNuiNeedAudioDataを通じてデータを供給する代わりに、このメソッドを呼び出して録音データをアクティブにプッシュします。

メソッドシグネチャ

public synchronized int updateAudio(byte[] data, int len,
                                    boolean first_pack);

パラメータ

パラメータ	型	説明
`data`	`byte[]`	プッシュするオーディオデータ。
`len`	`int`	プッシュするオーディオデータのバイト数。
`first_pack`	`boolean`	このパラメータは無視してください。

updateRefAudio

audio_update_manuallyが"true"に設定されており、デバイス上AECが有効になっている場合、このメソッドを呼び出して、プレーヤーで再生される音声を参照信号としてプッシュします。

メソッドシグネチャ

public synchronized int updateRefAudio(byte[] data, int len,
                                       boolean first_pack);

パラメータ

パラメータ	型	説明
`data`	`byte[]`	プッシュするオーディオデータ。
`len`	`int`	プッシュするオーディオデータのバイト数。
`first_pack`	`boolean`	このパラメータは無視してください。

release

SDKのすべての内部リソースを解放します。このメソッドを呼び出すと、SDKインスタンスは使用できなくなります。再度使用するには、initializeを呼び出して再初期化する必要があります。

メソッドシグネチャ

public synchronized int release();

GetVersion

現在のSDKバージョン情報を取得します。

メソッドシグネチャ

public synchronized String GetVersion();

戻り値

現在のSDKバージョン情報。

INativeNuiCallback: リスナーコールバック

onNuiEventCallback: イベント情報のリッスン

メソッドシグネチャ

void onNuiEventCallback(NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult);

パラメータ

パラメータ	型	説明
`event`	NuiEvent	コールバックイベント。
`resultCode`	`int`	`EVENT_ASR_ERROR` イベントが発生した場合にのみ有効です。
`arg2`	`int`	予約済みパラメータ。
`asrResult`	`AsrResult`	音声認識結果。
`kwsResult`	`KwsResult`	音声ウェイクアップ機能。このパラメータを使用する必要はありません。

onNuiAudioStateChanged: オーディオ状態のリッスン

SDKは、このコールバックを使用して、録音の開始または停止のタイミングを通知します。

メソッドシグネチャ

void onNuiAudioStateChanged(AudioState state);

AudioStateの状態

状態	説明
`STATE_OPEN`	インタラクションが開始されました。録音デバイスを開いて録音を開始できます。
`STATE_PAUSE`	インタラクションが停止しました。録音を停止できます。
`STATE_CLOSE`	SDKインスタンスがリリースされました。録音デバイスを完全に閉じることができます。

onNuiNeedAudioData: オーディオデータの供給

会話開始後、このコールバックは継続的にトリガーされます。このコールバックで音声データを供給します。audio_update_manuallyが"true"に設定されている場合、このコールバックを使用する必要はありません。

メソッドシグネチャ

int onNuiNeedAudioData(byte[] buffer, int len);

パラメータ

パラメータ	型	説明
`buffer`	`byte[]`	格納するオーディオデータ。
`len`	`int`	格納するオーディオデータのバイト数。

戻り値

実際に格納されたバイト数。

onNuiAssistEventCallback：補助イベントとデータの受信

このコールバックは、SDKから補助イベントおよび関連データを受信します。

メソッドシグネチャ

void onNuiAssistEventCallback_(int event, byte[] info, int info_len,
                               byte[] data);

パラメータ

パラメータ	型	説明
`event`	`int`	`NuiEvent`イベントです。
`info`	`String`	このパラメータは無視してください。
`info_len`	`int`	このパラメータは無視してください。
`data`	`byte[]`	モデルから返されたTTSオーディオなどの補助データ。

onNuiLogTrackCallback: トレースログのリッスン

このコールバックは、トラブルシューティングとデバッグに役立つSDKからの詳細な内部ログを受信します。

default void onNuiLogTrackCallback(Constants.LogLevel level, String log)

`NuiEvent`: イベントタイプ

イベント	説明
`EVENT_TRANSCRIBER_STARTED`	タスクが正常に開始されました。
`EVENT_VAD_START`	タスク開始直後にトリガーされます。これは、発話の開始が検出されたことを意味するものではありません。
`EVENT_VAD_END`	発話の終わりが検出されました。
`EVENT_ASR_PARTIAL_RESULT`	中間音声認識結果。
`EVENT_ASR_ERROR`	音声会話中にエラーが発生しました。
`EVENT_MIC_ERROR`	2秒連続でオーディオデータが受信されなかった場合にトリガーされます。
`EVENT_SENTENCE_END`	文の終わりが検出され、完全な認識結果が返されました。
`EVENT_TRANSCRIBER_COMPLETE`	音声会話が終了しました。
`EVENT_AUDIO_TRANSCRIPTION`	音声出力の増分テキスト転記イベントです。転記セグメントはストリーミングモードで返されます。
`EVENT_AUDIO_TRANSCRIPTION_COMPLETED`	オーディオ出力のトランスクリプトが完了しました。
`EVENT_OTHER_RESULT`	Function Callingの結果などのその他のイベント情報。
`EVENT_ASR_TTS_START`	モデルがTTSオーディオの返送を開始しました。
`EVENT_ASR_TTS_DATA`	モデルから返されたTTSオーディオ。
`EVENT_ASR_TTS_COMPLETE`	モデルがTTSオーディオの返送を完了しました。
`EVENT_AEC_DATA`	AECによって処理されたオーディオデータ。

クイックスタート

呼び出し手順

リクエストパラメータ

接続および制御パラメータ

音声会話パラメータ

主要API

NativeNui

initialize

setParams

startDialog

stopDialog

cancelDialog

updateAction

updateAudio

updateRefAudio

release

GetVersion

INativeNuiCallback: リスナーコールバック

onNuiEventCallback: イベント情報のリッスン

onNuiAudioStateChanged: オーディオ状態のリッスン

onNuiNeedAudioData: オーディオデータの供給

onNuiAssistEventCallback：補助イベントとデータの受信

onNuiLogTrackCallback: トレースログのリッスン

NuiEvent: イベントタイプ

`NuiEvent`: イベントタイプ