Paraformer リアルタイム音声認識 HarmonyOS SDK_Alibaba Cloud Model Studio(Model Studio) - Alibaba Cloud Model Studio

このガイドでは、Paraformer リアルタイム音声認識 HarmonyOS SDK を使用して音声をテキストに変換する方法について説明します。

重要Alibaba Cloud Model Studio は、中国（北京）リージョン向けにワークスペース固有のドメインを導入しました。このドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。dashscope.aliyuncs.com から {WorkspaceId}.cn-beijing.maas.aliyuncs.com への移行を推奨します。

{WorkspaceId} を実際のワークスペース ID に置き換えてください。既存のドメインも引き続き利用可能です。

ユーザーガイド：モデルの紹介および選択に関する推奨事項については、リアルタイム音声認識 - Fun-ASR および Paraformer を参照してください。

オンライン体験：paraformer-realtime-v2、paraformer-realtime-8k-v2、および paraformer-realtime-v1 のみがオンライン体験をサポートしています。

クイックスタート

API キーの取得： API キーの取得と設定。セキュリティのため、API キーを環境変数として設定することを推奨します。

注記サードパーティのアプリケーションやユーザーに一時的なアクセス権を付与する場合、または機密データへのアクセスや削除などの高リスク操作を厳密に制御する場合は、一時的な API キーを使用してください。一時的な API キーの有効期間はデフォルトで 60 秒です。有効期限が切れた後は、新しいキーを取得してください。
SDK をダウンロードしてサンプルコードを実行します：
- 最新のSDKパッケージをダウンロードしてください。
- TARパッケージを展開します。neonuiディレクトリからHAR形式のSDKを取得し、プロジェクトの依存関係に追加してください。 C++統合の場合は、TARパッケージ内のnative/libsおよびnative/includeから動的ライブラリとヘッダーファイルを取得してください。
- DevEco Studioでプロジェクトを開きます。サンプルコードはDashParaformerSpeechTranscriberPage.etsにあります。APIキーを置き換えて機能を試してください。

呼び出し手順

SDK を初期化します。
ビジネス要件に基づいてパラメータを設定します。initialize の parameters パラメータを使用して接続および制御パラメータを設定し、setParams を使用して音声認識効果パラメータを設定します。
startDialog を呼び出して認識を開始します。
onNuiAudioStateChanged コールバックで、音声状態に基づいて録音デバイスを開始します。
onNuiNeedAudioData コールバックで、録音された音声データを継続的に提供します。
onNuiEventCallback コールバックで、イベントをリッスンし音声認識結果を取得します。
stopDialog を呼び出して認識を停止し、EVENT_TRANSCRIBER_COMPLETE イベントをリッスンして認識が終了したことを確認します。
音声認識が不要になったら、release を呼び出して SDK リソースを解放してください。

リクエストパラメーター

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

以下のパラメータを設定するには、JSON 文字列を initialize の parameters パラメータに渡してください。例：以下の JSON 文字列は一例であり、すべてのパラメータを含んでいるわけではありません。必要に応じてパラメータを追加してください。

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

パラメータの説明

パラメーター	タイプ	必須	説明
`url`	`string`	はい	エンドポイント。これは`wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference`に固定されています。`{WorkspaceId}`を実際のワークスペースIDに置き換えてください。
`apikey`	`string`	はい	APIキー。長期的なキーの漏洩リスクを軽減するため、有効期間の短い、より安全な一時APIキーの使用を推奨します。
`service_mode`	`string`	はい	動作モード。リアルタイム音声認識の場合、これは `"1"` に固定されています。
`device_id`	`string`	はい	エンドユーザーを識別する一意の文字列。アプリ内のユーザーIDや、クライアントによって生成された一意のデバイス識別子に設定できます。このIDは主にログ追跡およびトラブルシューティングに使用されます。
`debug_path`	`string`	いいえ	ログファイルの保存パスです。このパラメーターは、initialize を呼び出す際に `save_log` を true に設定した場合にのみ有効になります。この場合、ログファイルのパスを指定する必要があります。指定しない場合はエラーが発生します。ローカルには最大2つのログファイルが保持されます。
`save_wav`	`string`	いいえ	デバッグ用にオーディオファイルを保存するかどうかを指定します。オーディオファイルは `debug_path` の下に保存されます。デフォルト値：`"false"`。有効な値：- `"true"`：はい - `"false"`：いいえ。このパラメーターは、initialize を呼び出す際に `save_log` を true に設定した場合にのみ有効になります。`debug_path` も設定する必要があります。
`max_log_file_size`	`number`	いいえ	ログファイルの最大サイズをバイト単位で設定します。このパラメーターは、initialize を呼び出す際に `save_log` を true に設定した場合にのみ有効になります。デフォルト値：104857600（100 * 1024 * 1024 バイト、つまり 100 MiB）。
`log_track_level`	`number`	いいえ	`onNuiLogTrackCallback` コールバックを通じて外部に送信されるログコンテンツのフィルタリングレベルを制御します。デフォルト値：2。有効な値：- 0：LOG_LEVEL_VERBOSE - 1：LOG_LEVEL_DEBUG - 2：LOG_LEVEL_INFO - 3：LOG_LEVEL_WARNING - 4：LOG_LEVEL_ERROR - 5：LOG_LEVEL_NONE（この機能を無効化します）。注意：initialize で設定される `log_track_level` と `level` が、どのログをコールバックに送信するかを共同で決定します。ログレベルが `log_track_level` と `level` の両方以上である場合にのみ、コールバックがトリガーされます。例えば、`log_track_level` が 2（INFO）で `level` が 3（WARNING）の場合、WARNING レベル以上のログ（値 >=3）のみがコールバックをトリガーします。

音声認識効果パラメータ

以下のパラメータを設定するには、JSON 文字列を setParams の params パラメータに渡してください。例：以下の JSON 文字列は一例であり、すべてのパラメータを含んでいるわけではありません。必要に応じてパラメータを追加してください。

{
    "service_type": 4,
    "nls_config": {
        "model": "paraformer-realtime-v2",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}

パラメータの説明

レベル 1 パラメータ	タイプ	必須	説明
`service_type`	`int`	はい	音声サービスタイプ。リアルタイム音声認識の場合、これは `4` に固定されています。
`nls_config`	`object`	はい	モデル選択および認識効果制御のための主要なパラメータを含む、コアとなる音声認識設定オブジェクト。
`nls_config.model`	`string`	はい	音声認識モデル。
`nls_config.sr_format`	`string`	はい	認識する音声のフォーマット。対応フォーマット：pcm、wav、および opus。重要 opus：ソース音声は PCM エンコードされている必要があります。SDK がそれを OPUS にエンコードします。 wav/pcm：音声は PCM エンコードされている必要があります。
`nls_config.sample_rate`	`int`	はい	認識対象オーディオのサンプリングレート（Hz 単位）です。モデルによって異なります。- paraformer-realtime-v2 は任意のサンプリングレートをサポートします。- paraformer-realtime-v1 は 16000 Hz のみをサポートします。- paraformer-realtime-8k-v2 は 8000 Hz のみをサポートします。- paraformer-realtime-8k-v1 は 8000 Hz のみをサポートします。
`nls_config.disfluency_removal_enabled`	`boolean`	いいえ	フィラーワードなどの言い淀みを除去するかどうかを指定します。デフォルト値：false。
`nls_config.language_hints`	`array[string]`	いいえ	認識対象オーディオの言語コードを指定します。事前に言語を特定できない場合は、このパラメータを省略するとモデルが自動的に言語を検出します。サポートされている言語コード：- zh：中国語 - en：英語 - ja：日本語 - yue：広東語 - ko：韓国語 - de：ドイツ語 - fr：フランス語 - ru：ロシア語。このパラメータは、複数の言語をサポートするモデルでのみ有効です。
`nls_config.semantic_punctuation_enabled`	`boolean`	いいえ	文分割モードを指定します。デフォルト値は false です。有効な値は次のとおりです。- true：意味分割を有効にし、VAD 分割を無効にします。- false：VAD 分割を有効にし、意味分割を無効にします。意味分割はより正確で、会議の文字起こしに適しています。VAD（Voice Activity Detection）分割はレイテンシが低く、リアルタイム対話に適しています。このパラメータは v2 以降のモデルでのみ有効です。
`nls_config.max_sentence_silence`	`int`	いいえ	VAD（Voice Activity Detection）による文分割の無音閾値（ミリ秒単位）です。デフォルト値は 800 です。有効範囲は `[200, 6000]` です。セグメント後の無音時間がこの閾値を超えると、システムは文が終了したと判断します。このパラメータは、`semantic_punctuation_enabled` が false であり、かつモデルが v2 以降の場合にのみ有効です。
`nls_config.multi_threshold_mode_enabled`	`boolean`	いいえ	過長セグメント防止モードを有効にするかどうかを指定します。このモードは、VAD セグメントが長くなりすぎるのを防ぎます。デフォルト値は false（無効）です。有効な値は次のとおりです。- true：モードを有効にする - false：モードを無効にする。このパラメータは、`semantic_punctuation_enabled` が false であり、かつモデルが v2 以降の場合にのみ有効です。
`nls_config.punctuation_prediction_enabled`	`boolean`	いいえ	認識結果に句読点を自動的に付与するかどうかを指定します。デフォルト値は true です。有効な値は次のとおりです。- true：はい - false：いいえ。このパラメータは v2 以降のモデルでのみ有効です。
`nls_config.heartbeat`	`boolean`	いいえ	サーバーとの永続接続を維持するかどうかを指定します。デフォルト値は false です。有効な値は次のとおりです。- true：無音オーディオが連続して送信されている間、接続はアクティブなままです。- false：無音オーディオが連続して送信されていても、一定時間後に接続がタイムアウトします。タイムアウト時間はサーバー側のデフォルト値であり、クライアント側で設定することはできません。このパラメータは v2 以降のモデルでのみ有効です。
`nls_config.inverse_text_normalization_enabled`	`boolean`	いいえ	逆テキスト正規化（ITN）を有効にするかどうかを指定します。有効にすると、漢数字がアラビア数字に変換されます。デフォルト値は true（有効）です。有効な値は次のとおりです。- true：有効 - false：無効。このパラメータは v2 以降のモデルでのみ有効です。
`nls_config.vocabulary_id`	`string`	いいえ	ホットワード語彙 ID で、特定の単語の認識精度を向上させます。このパラメータは v2 以降のモデルに適用されます。詳細については、カスタムホットワードを参照してください。
`nls_config.resources`	`array[object]`	いいえ	v1 モデル用のホットワードリソース設定です。`vocabulary_id` と同じ機能を提供しますが、設定方法が異なります。`resources` はオブジェクトの配列です。各オブジェクトには `resource_id` と `resource_type` が含まれます：- `resource_id`：ホットワードIDを指定する `string` です。- `resource_type`：`asr_phrase` に固定された `string` です。例：`{ "nls_config": { "resources": [ { "resource_id": "xxxxxxxxxxxx", "resource_type": "asr_phrase" } ] } }`。詳細については、「Paraformer 音声認識のホットワードを作成および管理する」を参照してください。

主要インターフェース

NativeNui

initialize

音声認識 SDK インスタンスを初期化します。release を呼び出す前に、インスタンスを再度初期化しないでください。

このインターフェースは呼び出し元のスレッドをブロックします。UIスレッド以外から呼び出してください。

メソッドシグネチャ

public initialize(callback: INativeNuiCallback,
                  parameters: string,
                  level: number,
                  save_log: boolean = false): number

パラメータの説明

パラメーター	タイプ	説明
`callback`	`INativeNuiCallback`	イベントおよびデータコールバックインターフェースの実装。
`parameters`	`string`	認証、接続、およびデバッグパラメータを含むJSON文字列。接続および制御パラメータを参照してください。
`level`	`number`	SDKのログレベルを制御します。有効な値はConstants.LogLevel列挙型で定義されています。
`save_log`	`boolean`	ローカルログを保存するかどうかを指定します。このパラメーターが `true` の場合、接続および制御パラメーターの `debug_path` を使用してパスを指定してください。また、`max_log_file_size` を使用してファイルサイズを設定することもできます。

戻り値

setParams

JSON 形式で音声認識効果パラメータを設定します。startDialog の前にこのインターフェースを呼び出してください。

メソッドシグネチャ

public setParams(params: string): number

パラメータの説明

パラメーター	タイプ	説明
`params`	`string`	音声認識効果パラメータ。

戻り値

startDialog

認識を開始します。

メソッドシグネチャ

public startDialog(vad_mode: Constants.VadMode, dialog_params: string): number

パラメータの説明

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

戻り値

stopDialog

認識を停止します。このインターフェースを呼び出すと、サーバーは最終認識結果を返し、タスクを終了します。

メソッドシグネチャ

public stopDialog(): number

戻り値

cancelDialog

サーバーが最終認識結果を返すのを待たずに、即座に認識を停止します。

メソッドシグネチャ

public cancelDialog(): number

戻り値

release

すべての内部 SDK リソースを解放します。このメソッドが呼び出された後、SDK インスタンスは使用できなくなります。再度使用する場合は、initialize を呼び出して再初期化してください。

メソッドシグネチャ

public release(): number

戻り値

GetVersion

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

メソッドシグネチャ

public GetVersion(): string

戻り値

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

INativeNuiCallback

リアルタイム音声認識中のイベント、音声状態、音量変化、およびログをリッスンします。

onNuiEventCallback

認識イベントをリッスンし、音声認識結果を取得します。

メソッドシグネチャ

onNuiEventCallback: (event: Constants.NuiEvent, resultCode: number, arg2: number,
                    kwsResult: KwsResult, asrResult: AsrResult) => void;

パラメータの説明

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

onNuiAudioStateChanged

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

メソッドシグネチャ

onNuiAudioStateChanged: (state: Constants.AudioState) => void

AudioState の説明

状態	説明
`STATE_OPEN`	インタラクションが開始されます。録音デバイスを開始できます。
`STATE_PAUSE`	インタラクションが一時停止中です。録音を一時停止できます。
`STATE_CLOSE`	インタラクションが停止します。録音デバイスを完全に停止できます。

onNuiAudioRMSChanged

UI 表示用に録音された音声データの音量を監視します。

メソッドシグネチャ

onNuiAudioRMSChanged: (val: number) => number

パラメータの説明

パラメーター	タイプ	説明
`val`	`number`	録音された音声データの音量。出力範囲は通常 `[-160, 0]` です。

onNuiNeedAudioData

認識開始後、このコールバックは継続的にトリガーされます。コールバック内で認識対象の音声データを供給してください。

メソッドシグネチャ

onNuiNeedAudioData: (buffer: ArrayBuffer) => number

パラメータの説明

パラメーター	タイプ	説明
`buffer`	`ArrayBuffer`	供給する音声データ。SDK は `buffer.byteLength` を要求バイト数として使用します。

戻り値

実際に供給されたバイト数。戻り値が <=0 の場合は、エラーまたはデータなしを示します。

onNuiLogTrackCallback

このコールバックは、トラブルシューティングおよびデバッグ用の詳細なSDK内部ログを受信します。

onNuiLogTrackCallback: (level: Constants.LogLevel, log: string) => void

Constants.NuiEvent

HarmonyOS SDK のイベントタイプは Constants.NuiEvent 列挙型によって定義されます。以下のイベントがリアルタイム音声認識に適用されます。

イベント	説明
`EVENT_TRANSCRIBER_STARTED`	タスクが正常に開始されます。
`EVENT_VAD_START`	このイベントはタスク開始直後にトリガーされます。発話の開始が検出されたことを示すものではありません。
`EVENT_VAD_END`	発話の終わりが検出されました。
`EVENT_ASR_PARTIAL_RESULT`	中間音声認識結果。
`EVENT_ASR_RESULT`	完全な音声認識結果。
`EVENT_ASR_ERROR`	音声認識中にエラーが発生しました。
`EVENT_MIC_ERROR`	このイベントは、音声データが 2 秒間連続して受信されなかった場合にトリガーされます。
`EVENT_SENTENCE_START`	文の開始が検出されます。
`EVENT_SENTENCE_END`	文の終了が検出され、完全な認識結果が返されます。
`EVENT_TRANSCRIBER_COMPLETE`	音声認識が終了します。

補助タイプ

Constants.LogLevel

levelパラメータの列挙値は以下の通りです：

値	説明
`LOG_LEVEL_VERBOSE`	最も詳細なログ。
`LOG_LEVEL_DEBUG`	デバッグログ。
`LOG_LEVEL_INFO`	情報ログ（デフォルト）。
`LOG_LEVEL_WARNING`	警告ログ。
`LOG_LEVEL_ERROR`	エラーログ。
`LOG_LEVEL_NONE`	ロギングを無効にします。

オーディオデバイス管理

AudioRecordを使用するAndroidとは異なり、HarmonyOSでは音声キャプチャに@kit.AudioKitのAudioCapturerを使用します。製品サンプルではこのロジックがAudioRecorder.etsユーティリティクラスにカプセル化されており、そのまま再利用できます。

作成：audio.createAudioCapturer(capturerOptions) は、サンプリングレート 16 kHz、ビット深度 16 ビット、チャンネル数 1（SAMPLE_RATE_16000/CHANNEL_1/SAMPLE_FORMAT_S16LE/ENCODING_TYPE_RAW）のキャプチャを非同期で作成します。
データイベント：capturer.on('readData', (buffer: ArrayBuffer) => void) は録音されたオーディオデータを継続的に取得します。onNuiNeedAudioData コールバックが随時データを取得できるよう、キューにデータをバッファリングしてください。
ステートイベント：capturer.on('stateChange', (state: audio.AudioState) => void)。STATE_RUNNING は録音が開始されたことを示し、STATE_STOPPED は録音が停止されたことを示します。
制御：start() でキャプチャラーを開始し、stop() で停止し、release() で解放します。

注記HarmonyOS では AudioCapturer を非同期で作成します。作成が完了した後にのみ start() を呼び出してください。したがって、STATE_OPEN が発生した際にレコーダーを作成してすぐに開始しないでください。まず作成を行い、その後 STATE_OPEN コールバック内で start() を呼び出してください。サンプルでは doInit 中にレコーダーを作成し、onNuiAudioStateChanged 中に開始します。STATE_CLOSE が発生した場合は、レコーダーを停止しますが、インスタンスは再利用のために保持してください。release でリリースしてください。

権限の宣言

録音を使用するには、module.json5 でマイクの権限を宣言してください。

{
  "requestPermissions": [
    { "name": "ohos.permission.MICROPHONE" }
  ]
}