このトピックでは、Paraformer 非リアルタイム音声認識 Java SDK のパラメーターとインターフェイスの詳細について説明します。
前提条件
クイックスタート
コアクラス (Transcription) は、タスクを非同期に送信し、タスクの完了を同期的に待機し、タスク結果を非同期にクエリするためのインターフェイスを提供します。非リアルタイム音声認識には、次の 2 つの呼び出し方法を使用できます。
- 非同期送信 + 同期待機:タスクを送信した後、タスクが終了して認識結果が取得されるまで現在のスレッドをブロックします。
- 非同期送信 + 非同期クエリ:タスクを送信した後、クエリインターフェイスを呼び出すことでいつでもタスク結果を照会できます。
非同期送信 + 同期待機
- リクエストパラメーターを設定します。
- コアクラス (Transcription) をインスタンス化します。
-
コアクラス (Transcription) の
asyncCallメソッドを呼び出して、タスクを非同期に送信します。- ファイル文字起こしサービスは、API を通じて送信されたタスクをベストエフォート方式で処理します。送信後、タスクはキューイング中 (
PENDING) 状態になります。キュー時間はキューの長さとファイルの長さに依存し、正確に見積もることはできませんが、通常は数分以内に完了します。処理が開始されると、音声認識はリアルタイムの数百倍の速度で完了します。 - 各タスクの完了後、認識結果と URL ダウンロードリンクは 24 時間有効です。有効期限が切れると、以前に提供された URL を通じてタスクをクエリしたり、結果をダウンロードしたりすることはできません。
- ファイル文字起こしサービスは、API を通じて送信されたタスクをベストエフォート方式で処理します。送信後、タスクはキューイング中 (
-
コアクラス (Transcription) の
waitメソッドを呼び出して、タスクが終了するのを同期的に待機します。 タスクステータスにはPENDING、RUNNING、SUCCEEDED、FAILEDがあります。タスクがPENDINGまたはRUNNING状態の場合、waitインターフェイスはブロックされます。タスクがSUCCEEDEDまたはFAILED状態の場合、waitインターフェイスはブロックされなくなり、タスク結果を返します。waitは タスク結果 (TranscriptionResult) を返します。
クリックして完全な例を表示
クリックして完全な例を表示
非同期送信 + 非同期クエリ
- リクエストパラメーターを設定します。
- コアクラス (Transcription) をインスタンス化します。
-
コアクラス (Transcription) の
asyncCallメソッドを呼び出して、タスクを非同期に送信します。- ファイル文字起こしサービスは、API を通じて送信されたタスクをベストエフォート方式で処理します。送信後、タスクはキューイング中 (
PENDING) 状態になります。キュー時間はキューの長さとファイルの長さに依存し、正確に見積もることはできませんが、通常は数分以内に完了します。処理が開始されると、音声認識はリアルタイムの数百倍の速度で完了します。 - 各タスクの完了後、認識結果と URL ダウンロードリンクは 24 時間有効です。有効期限が切れると、以前に提供された URL を通じてタスクをクエリしたり、結果をダウンロードしたりすることはできません。
- ファイル文字起こしサービスは、API を通じて送信されたタスクをベストエフォート方式で処理します。送信後、タスクはキューイング中 (
-
最終的なタスク結果を取得するまで、コアクラス (Transcription) の
fetchメソッドをループで呼び出します。 タスクステータスがSUCCEEDEDまたはFAILEDになったら、ポーリングを停止して結果を処理します。fetchは タスク結果 (TranscriptionResult) を返します。
クリックして完全な例を表示
クリックして完全な例を表示
リクエストパラメーター
リクエストパラメーターは TranscriptionParam のチェーンメソッドを通じて設定されます。
クリックして例を表示
クリックして例を表示
| パラメーター | 型 | デフォルト | 必須 | 説明 |
|---|---|---|---|---|
| model | String | はい | 音声/動画ファイルの文字起こしに使用する Paraformer モデル名を指定します。詳細については、「サポートされているモデル」をご参照ください。 | |
| fileUrls | List<String> | はい | 文字起こし対象の音声/動画ファイルの URL リスト。HTTP/HTTPS プロトコルをサポートします。リクエストごとに 1 つの URL のみがサポートされます。音声ファイルが Alibaba Cloud OSS に保存されている場合、SDK は oss:// プレフィックスを持つ一時的な URL をサポートしません。 | |
| vocabularyId | String | いいえ | 最新のホットワード ID。言語設定を持つ最新の v2 シリーズモデルをサポートします。この ID に関連付けられたホットワードが、この音声認識で有効になります。デフォルトでは無効です。使用方法については、「カスタムホットワード」をご参照ください。 | |
| channelId | List<Integer> | [0] | いいえ | マルチトラック音声ファイルで認識するオーディオトラックのインデックスを指定します。インデックスは 0 から始まります。例えば、[0] は最初のトラックを認識することを意味し、[0, 1] は最初のトラックと 2 番目のトラックの両方を同時に認識することを意味します。このパラメーターを省略した場合、デフォルトで最初のトラックのみが処理されます。 |
| disfluencyRemovalEnabled | Boolean | false | いいえ | フィラーワードをフィルターします。デフォルトでは無効です。 |
| timestampAlignmentEnabled | Boolean | false | いいえ | タイムスタンプアライメント機能を有効にするかどうか。デフォルトでは無効です。 |
| specialWordFilter | String | いいえ | 音声認識中に処理する禁止用語を指定し、異なる禁止用語に対して異なる処理方法を設定できます。このパラメーターが提供されない場合、システムは組み込みの禁止用語フィルタリングロジックを使用し、認識結果で Alibaba Cloud Model Studio 禁止用語リスト に一致する単語は、同じ長さの * に置き換えられます。このパラメーターが提供される場合、以下の禁止用語処理戦略を実装できます:
| |
| language_hints | String[] | ["zh", "en"] | いいえ | 認識する音声の言語コードを指定します。このパラメーターは paraformer-v2 モデルにのみ適用されます。サポートされている言語コード:
language_hints は、TranscriptionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定する必要があります: |
| diarizationEnabled | Boolean | false | いいえ | 自動話者分離。デフォルトでは無効です。モノラル音声にのみ適用されます。マルチチャンネル音声は話者分離をサポートしていません。この機能が有効な場合、認識結果には異なる話者を区別するための speaker_id フィールドが含まれます。話者分離を有効にする場合、音声の長さが 2 時間を超えないようにすることを推奨します。超えると認識が失敗したり、タイムアウトしたりする可能性があります。 speaker_id の例については、「認識結果の説明」をご参照ください。 |
| speakerCount | Integer | いいえ | 話者数の参考値。有効な値:2 から 100 までの整数 (両端を含む)。話者分離が有効な場合 (diarizationEnabled が true に設定されている場合) に効果があります。デフォルトでは、システムが自動的に話者数を決定します。このパラメーターを設定した場合、アルゴリズムに対して指定された話者数を出力しようとするヒントとしてのみ機能し、正確な数が保証されるわけではありません。 | |
| apiKey | String | いいえ | API キー。API キーがすでに環境変数に設定されている場合は、コードで設定する必要はありません。そうでない場合は、コードで設定する必要があります。 |
応答
タスク結果 (TranscriptionResult)
TranscriptionResult は現在のタスク結果をカプセル化します。
| インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|---|---|---|---|
| なし | requestId | requestId を取得します。 | |
| なし | taskId | taskId を取得します。 | |
| なし | TaskStatus、タスクステータス | タスクステータスを取得します。TaskStatus は列挙型クラスです。以下の 4 つのステータスにのみ注目する必要があります:PENDING、RUNNING、SUCCEEDED、FAILED。タスクに複数のサブタスクが含まれている場合、いずれかのサブタスクが成功すれば、全体のタスクステータスは SUCCEEDED とマークされます。各サブタスクの結果を判断するには、subtask_status フィールドを確認する必要があります。 | |
| なし | サブタスク結果 (TranscriptionTaskResult) | サブタスク結果 (TranscriptionTaskResult) を取得します。各タスクは 1 つ以上の音声ファイルを認識します。異なる音声ファイルは異なるサブタスクで処理されるため、各タスクは 1 つ以上のサブタスクに対応します。 | |
| なし | JSON 形式のタスク結果 | タスク結果を取得します。結果は JSON 形式です。getOutput インターフェイスを使用してタスク結果を取得する場合、自分で解析する必要があります。
クリックして JSON の例を表示 正常な例 code」はエラーコード、「message」はエラーメッセージです。これら 2 つのフィールドはエラーシナリオでのみ表示されます。エラーコード を参照して問題をトラブルシューティングできます。 |
サブタスク結果 (TranscriptionTaskResult)
TranscriptionTaskResult はサブタスクの結果をカプセル化します。サブタスクは単一の音声ファイルを認識します。
| インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|---|---|---|---|
| なし | 認識された音声ファイルの URL | 認識された音声ファイルの URL を取得します。 | |
| なし | 認識結果の URL | 認識結果の URL を取得します。この URL は 24 時間有効です。有効期限が切れると、以前に提供された URL を通じてタスクをクエリしたり、結果をダウンロードしたりすることはできません。認識結果は JSON ファイルとして保存されます。上記の URL を通じてファイルをダウンロードするか、HTTP リクエストを通じて直接その内容を読み取ることができます。JSON データ内の各フィールドの意味については、「認識結果の説明」をご参照ください。 | |
| なし | TaskStatus、サブタスクのステータス | サブタスクのステータスを取得します。TaskStatus は列挙型クラスです。以下の 4 つのステータスにのみ注目する必要があります:PENDING、RUNNING、SUCCEEDED、FAILED。 | |
| なし | タスク実行中の主要な情報、空の場合もあります | タスク実行中の主要な情報を取得します。タスクが失敗した場合、この内容を確認して原因を分析できます。 |
認識結果の説明
認識結果は JSON ファイルとして保存されます。
クリックして認識結果の例を表示
クリックして認識結果の例を表示
パラメーター | 型 | 説明 |
|---|---|---|
audio_format | string | ソースファイルの音声フォーマット。 |
channels | array[integer] | ソースファイルのオーディオトラックのインデックス情報。モノラル音声の場合は [0]、デュアルトラック音声の場合は [0, 1] などを返します。 |
original_sampling_rate | integer | ソースファイル内の音声のサンプリングレート (Hz)。 |
original_duration | integer | ソースファイルの元の音声の長さ (ms)。 |
channel_id | integer | 文字起こし結果のオーディオトラックのインデックス、0 から始まります。 |
content_duration | integer | オーディオトラック内で音声として識別されたコンテンツの長さ (ms)。 Paraformer 音声認識モデルサービスは、オーディオトラック内で音声として識別されたコンテンツのみを文字起こしおよび計測し、それに応じて課金します。非音声コンテンツは計測も課金もされません。通常、音声コンテンツの長さは元の音声の長さよりも短くなります。音声コンテンツが存在するかどうかの判断は AI モデルによって行われるため、実際の状況とは多少のずれが生じる可能性があります。 |
transcript | string | 段落レベルの音声文字起こし結果。 |
sentences | array | 文レベルの音声文字起こし結果。 |
words | array | 単語レベルの音声文字起こし結果。 |
begin_time | integer | 開始タイムスタンプ (ms)。 |
end_time | integer | 終了タイムスタンプ (ms)。 |
text | string | 音声文字起こし結果。 |
speaker_id | integer | 現在の話者のインデックス、0 から始まり、異なる話者を区別するために使用されます。 このフィールドは、話者分離が有効な場合にのみ認識結果に表示されます。 |
punctuation | string | 単語の後に予測される句読点 (もしあれば)。 |
主要なインターフェイス
タスククエリパラメータークラス (TranscriptionQueryParam)
TranscriptionQueryParam は、タスクの完了を待機する場合 (Transcription の wait メソッドを呼び出す) や、タスク結果をクエリする場合 (Transcription の fetch メソッドを呼び出す) に使用されます。
静的メソッド FromTranscriptionParam を通じて TranscriptionQueryParam インスタンスを作成します。
クリックして例を表示
クリックして例を表示
| インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|---|---|---|---|
| TranscriptionQueryParam インスタンス | TranscriptionQueryParam インスタンスを作成します。 |
コアクラス (Transcription)
Transcription は「import com.alibaba.dashscope.audio.asr.transcription.*;」でインポートできます。その主要なインターフェイスは以下の通りです:
| インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|---|---|---|---|
param:音声認識パラメーター、TranscriptionParam インスタンス | タスク結果 (TranscriptionResult) | 音声認識タスクを非同期に送信します。 | |
queryParam:TranscriptionQueryParam インスタンス | タスク結果 (TranscriptionResult) | 非同期タスクが終了するまで (タスクステータスが SUCCEEDED または FAILED になるまで) 現在のスレッドをブロックします。 | |
queryParam:TranscriptionQueryParam インスタンス | タスク結果 (TranscriptionResult) | 現在のタスク結果を非同期にクエリします。 |
エラーコード
エラーが発生した場合は、「エラーコード」を参照してトラブルシューティングを行ってください。
問題が解決しない場合は、開発者コミュニティ に参加して問題を報告し、さらなる調査のためにリクエスト ID を提供してください。
タスクに複数のサブタスクが含まれている場合、いずれかのサブタスクが成功すれば、全体のタスクステータスは SUCCEEDED とマークされます。各サブタスクの結果を判断するには、subtask_status フィールドを確認する必要があります。
エラー応答の例:
その他の例
その他の例については、GitHub をご参照ください。
よくある質問
機能に関する質問
Q:Base64 エンコードされた音声をサポートしていますか?
いいえ。Base64 エンコードされた音声はサポートされていません。パブリックにアクセス可能な URL を介してアクセスできる音声のみがサポートされています。バイナリストリームや直接のローカルファイル認識はサポートされていません。
Q:音声ファイルをパブリックにアクセス可能な URL として提供するにはどうすればよいですか?
一般的に、以下の手順に従います (これは一般的なアプローチであり、詳細はストレージ製品によって異なります。音声を Alibaba Cloud OSS にアップロードすることを推奨します):
1. ストレージとホスティング方法を選択する
1. ストレージとホスティング方法を選択する
-
Object Storage Service (推奨):
- クラウドプロバイダーのオブジェクトストレージサービス (例:Alibaba Cloud OSS) を使用して音声ファイルをバケットにアップロードし、パブリックアクセスに設定します。
- 利点:高可用性、CDN アクセラレーションのサポート、簡単な管理。
-
Web サーバー:
- HTTP/HTTPS アクセスをサポートする Web サーバー (Nginx や Apache など) に音声ファイルを配置します。
- 利点:小規模プロジェクトやローカルテストに適しています。
-
コンテンツデリバリーネットワーク (CDN):
- CDN に音声ファイルをホストし、CDN が提供する URL を介してアクセスします。
- 利点:ファイル配信の高速化、高同時実行シナリオに適しています。
2. 音声ファイルをアップロードする
2. 音声ファイルをアップロードする
-
Object Storage Service:
- クラウドプロバイダーのコンソールにログインし、バケットを作成します。
- 音声ファイルをアップロードし、ファイルの権限を「パブリック読み取り」に設定するか、一時的なアクセスリンクを生成します。
-
Web サーバー:
- サーバーの指定されたディレクトリ (例:
/var/www/html/audio/) に音声ファイルを配置します。 - ファイルが HTTP/HTTPS を介してアクセス可能であることを確認します。
- サーバーの指定されたディレクトリ (例:
3. パブリックにアクセス可能な URL を生成する
3. パブリックにアクセス可能な URL を生成する
-
Object Storage Service:
- アップロード後、システムは自動的にパブリックアクセス URL を生成します (通常は
https://<bucket-name>.<region>.aliyuncs.com/<file-name>の形式)。 - よりユーザーフレンドリなドメインが必要な場合は、カスタムドメインをバインドして HTTPS を有効にすることができます。
- アップロード後、システムは自動的にパブリックアクセス URL を生成します (通常は
-
Web サーバー:
- ファイルアクセス URL は通常、サーバーアドレスとファイルパスを組み合わせたものです (例:
https://your-domain.com/audio/file.mp3)。
- ファイルアクセス URL は通常、サーバーアドレスとファイルパスを組み合わせたものです (例:
-
CDN:
- CDN アクセラレーションを設定した後、CDN が提供する URL を使用します (例:
https://cdn.your-domain.com/audio/file.mp3)。
- CDN アクセラレーションを設定した後、CDN が提供する URL を使用します (例:
4. URL のアクセシビリティを確認する
4. URL のアクセシビリティを確認する
- ブラウザで URL を開き、音声ファイルが再生できるか確認します。
- ツール (
curlや Postman など) を使用して、URL が正しい HTTP 応答 (状態コード 200) を返すか確認します。
oss:// プレフィックスを持つ一時的な URL はサポートされません。
RESTful API を使用する場合、音声ファイルが Alibaba Cloud OSS に保存されている場合、oss:// プレフィックスを持つ一時的な URL はサポートされます:
- 一時的な URL は 48 時間有効で、有効期限が切れると使用できません。本番環境では使用しないでください。
- アップロード認証情報を取得するための API は 100 QPS に制限されており、スケーリングアウトをサポートしていません。本番環境、高同時実行シナリオ、またはストレステストシナリオでは使用しないでください。
- 本番環境では、OSS などの安定したストレージサービスを使用して、長期的なファイルの可用性を確保し、レート制限の問題を回避してください。
Q:認識結果を取得するのにどれくらい時間がかかりますか?
送信後、タスクはキューイング中 (PENDING) 状態になります。キュー時間はキューの長さとファイルの長さに依存し、正確に見積もることはできませんが、通常は数分以内に完了します。しばらくお待ちください。長い音声ファイルはより多くの処理時間を必要とします。
トラブルシューティング
コードエラーが発生した場合は、「エラーコード」の情報に基づいてトラブルシューティングを行ってください。
Q:認識結果と音声再生が同期しない場合はどうすればよいですか?
リクエストパラメーター の timestampAlignmentEnabled を true に設定してタイムスタンプアライメント機能を有効にすると、認識結果が音声再生と同期します。
Q:継続的なポーリング後も結果を取得できませんか?
これはレート制限が原因である可能性があります。しばらくお待ちください。容量拡張が必要な場合は、開発者コミュニティ に参加して申請してください。
Q:なぜ認識結果がないのですか (音声を認識できない)?
- 音声が要件 (フォーマット、サンプリングレート) を満たしているか確認してください。
paraformer-v2モデルを使用している場合は、language_hintsの設定が正しいか確認してください。- 上記のいずれでも問題が解決しない場合は、カスタムホットワードを使用して特定の単語の認識を向上させることができます。