このトピックでは、Paraformer 非リアルタイム音声認識 Java SDK のパラメーターとインターフェイスの詳細について説明します。
重要Alibaba Cloud Model Studio は、中国 (北京) リージョン向けにワークスペース専用のドメインをリリースしました。この新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。 dashscope.aliyuncs.com から {WorkspaceId}.cn-beijing.maas.aliyuncs.com への移行を推奨します。
{WorkspaceId} を実際の ワークスペース ID に置き換えてください。既存のドメインも引き続き完全に機能します。
重要このドキュメントは 中国 (北京) リージョンにのみ適用されます。モデルを使用するには、中国 (北京) リージョンの API キー を使用する必要があります。
ユーザーガイド:非リアルタイム音声認識
前提条件
サービスを有効化し、API キーを取得していること。コードの漏洩によるセキュリティリスクを防ぐため、API キーをコードにハードコーディングするのではなく、API キーを環境変数として設定してください。
注記サードパーティのアプリケーションやユーザーに一時的なアクセス権を付与する必要がある場合や、機密データへのアクセスや削除などの高リスク操作を厳密に制御したい場合は、一時的な認証トークンの使用を推奨します。
長期的な API キーと比較して、一時的な認証トークンは有効期間が短く (60 秒)、セキュリティが高いため、一時的な呼び出しシナリオに適しており、API キー漏洩のリスクを効果的に低減します。
使用方法:コード内で、認証に元々使用していた API キーを取得した一時的な認証トークンに置き換えます。
クイックスタート
コアクラス (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) を返します。
クリックして完全な例を表示
import com.alibaba.dashscope.audio.asr.transcription.*;
import com.google.gson.*;
import java.util.Arrays;
public class Main {
public static void main(String[] args) {
// 以下の設定は中国 (北京) リージョン用です。「{WorkspaceId}」を実際のワークスペース ID に置き換えてください。設定はリージョンによって異なります。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
// 文字起こしリクエストパラメーターを作成
TranscriptionParam param =
TranscriptionParam.builder()
// API キーが環境変数に設定されていない場合は、apiKey をご自身の API キーに置き換えてください
//.apiKey("apikey")
.model("paraformer-v2")
// "language_hints" は paraformer-v2 モデルでのみサポートされています
.parameter("language_hints", new String[]{"zh", "en"})
.fileUrls(
Arrays.asList(
"{YOUR_AUDIO_URL}"))
.build();
try {
Transcription transcription = new Transcription();
// 文字起こしリクエストを送信
TranscriptionResult result = transcription.asyncCall(param);
System.out.println("RequestId: " + result.getRequestId());
// タスクが完了するまでブロックして待機し、結果を取得
result = transcription.wait(
TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
// 結果を出力
System.out.println(result.getOutput());
} catch (Exception e) {
System.out.println("error: " + e);
}
System.exit(0);
}
}
非同期送信 + 非同期クエリ
-
リクエストパラメーターを設定します。
-
コアクラス (Transcription) をインスタンス化します。
-
コアクラス (Transcription) の
asyncCallメソッドを呼び出して、タスクを非同期に送信します。注記
- ファイル文字起こしサービスは、API を通じて送信されたタスクをベストエフォート方式で処理します。送信後、タスクはキューイング中 (
PENDING) 状態になります。キュー時間はキューの長さとファイルの長さに依存し、正確に見積もることはできませんが、通常は数分以内に完了します。処理が開始されると、音声認識はリアルタイムの数百倍の速度で完了します。 - 各タスクの完了後、認識結果と URL ダウンロードリンクは 24 時間有効です。有効期限が切れると、以前に提供された URL を通じてタスクをクエリしたり、結果をダウンロードしたりすることはできません。
- ファイル文字起こしサービスは、API を通じて送信されたタスクをベストエフォート方式で処理します。送信後、タスクはキューイング中 (
-
最終的なタスク結果を取得するまで、コアクラス (Transcription) の
fetchメソッドをループで呼び出します。タスクステータスが
SUCCEEDEDまたはFAILEDになったら、ポーリングを停止して結果を処理します。fetchは タスク結果 (TranscriptionResult) を返します。
クリックして完全な例を表示
import com.alibaba.dashscope.audio.asr.transcription.*;
import com.alibaba.dashscope.common.TaskStatus;
import com.google.gson.*;
import java.util.Arrays;
public class Main {
public static void main(String[] args) {
// 以下の設定は中国 (北京) リージョン用です。「{WorkspaceId}」を実際のワークスペース ID に置き換えてください。設定はリージョンによって異なります。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
// 文字起こしリクエストパラメーターを作成
TranscriptionParam param =
TranscriptionParam.builder()
// API キーが環境変数に設定されていない場合は、apiKey をご自身の API キーに置き換えてください
//.apiKey("apikey")
.model("paraformer-v2")
// "language_hints" は paraformer-v2 モデルでのみサポートされています
.parameter("language_hints", new String[]{"zh", "en"})
.fileUrls(
Arrays.asList(
"{YOUR_AUDIO_URL}"))
.build();
try {
Transcription transcription = new Transcription();
// 文字起こしリクエストを送信
TranscriptionResult result = transcription.asyncCall(param);
System.out.println("RequestId: " + result.getRequestId());
// タスクが終了するまでループでタスク結果を取得
while (true) {
result = transcription.fetch(TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
if (result.getTaskStatus() == TaskStatus.SUCCEEDED || result.getTaskStatus() == TaskStatus.FAILED) {
break;
}
Thread.sleep(1000);
}
// 結果を出力
System.out.println(result.getOutput());
} catch (Exception e) {
System.out.println("error: " + e);
}
System.exit(0);
}
}
リクエストパラメーター
リクエストパラメーターは TranscriptionParam のチェーンメソッドを通じて設定されます。
クリックして例を表示
TranscriptionParam param = TranscriptionParam.builder()
.model("paraformer-v2")
// "language_hints" は paraformer-v2 モデルでのみサポートされています
.parameter("language_hints", new String[]{"zh", "en"})
.fileUrls(
Arrays.asList(
"{YOUR_AUDIO_URL}"))
.build();
| パラメーター | 型 | デフォルト | 必須 | 説明 |
|---|---|---|---|---|
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 番目のトラックの両方を同時に認識することを意味します。このパラメーターを省略した場合、デフォルトで最初のトラックのみが処理されます。 重要指定された各トラックは独立して課金されます。例えば、1 つのファイルに対して [0, 1] をリクエストすると、2 回分の料金が発生します。 |
disfluencyRemovalEnabled | Boolean | false | いいえ | フィラーワードをフィルターします。デフォルトでは無効です。 |
timestampAlignmentEnabled | Boolean | false | いいえ | タイムスタンプアライメント機能を有効にするかどうか。デフォルトでは無効です。 |
specialWordFilter | String | いいえ | 音声認識中に処理する禁止用語を指定し、異なる禁止用語に対して異なる処理方法を設定できます。 このパラメーターが提供されない場合、システムは組み込みの禁止用語フィルタリングロジックを使用し、認識結果で Alibaba Cloud Model Studio 禁止用語リスト に一致する単語は、同じ長さの このパラメーターが提供される場合、以下の禁止用語処理戦略を実装できます:
このパラメーターの値は、次の構造を持つ JSON 文字列である必要があります: JSON フィールドの説明:
| |
language_hints | String[] | ["zh", "en"] | いいえ | 認識する音声の言語コードを指定します。 このパラメーターは paraformer-v2 モデルにのみ適用されます。 サポートされている言語コード:
注記 |
diarizationEnabled | Boolean | false | いいえ | 自動話者分離。デフォルトでは無効です。 モノラル音声にのみ適用されます。マルチチャンネル音声は話者分離をサポートしていません。 この機能が有効な場合、認識結果には異なる話者を区別するための 注記話者分離を有効にする場合、音声の長さが 2 時間を超えないようにすることを推奨します。超えると認識が失敗したり、タイムアウトしたりする可能性があります。
|
speakerCount | Integer | いいえ | 話者数の参考値。有効な値:2 から 100 までの整数 (両端を含む)。 話者分離が有効な場合 ( デフォルトでは、システムが自動的に話者数を決定します。このパラメーターを設定した場合、アルゴリズムに対して指定された話者数を出力しようとするヒントとしてのみ機能し、正確な数が保証されるわけではありません。 | |
apiKey | String | いいえ | API キー。API キーがすでに環境変数に設定されている場合は、コードで設定する必要はありません。そうでない場合は、コードで設定する必要があります。 |
応答
タスク結果 (TranscriptionResult)
TranscriptionResult は現在のタスク結果をカプセル化します。
| インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|---|---|---|---|
| なし | requestId | requestId を取得します。 |
| なし | taskId | taskId を取得します。 |
| なし |
| タスクステータスを取得します。
注記タスクに複数のサブタスクが含まれている場合、いずれかのサブタスクが成功すれば、全体のタスクステータスは |
| なし | サブタスク結果 (TranscriptionTaskResult) を取得します。 各タスクは 1 つ以上の音声ファイルを認識します。異なる音声ファイルは異なるサブタスクで処理されるため、各タスクは 1 つ以上のサブタスクに対応します。 | |
| なし | JSON 形式のタスク結果 | タスク結果を取得します。 結果は JSON 形式です。 クリックして JSON の例を表示 正常な例 エラーの例「 |
サブタスク結果 (TranscriptionTaskResult)
TranscriptionTaskResult はサブタスクの結果をカプセル化します。サブタスクは単一の音声ファイルを認識します。
| インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|---|---|---|---|
| なし | 認識された音声ファイルの URL | 認識された音声ファイルの URL を取得します。 |
| なし | 認識結果の URL | 認識結果の URL を取得します。この URL は 24 時間有効です。有効期限が切れると、以前に提供された URL を通じてタスクをクエリしたり、結果をダウンロードしたりすることはできません。 認識結果は JSON ファイルとして保存されます。上記の URL を通じてファイルをダウンロードするか、HTTP リクエストを通じて直接その内容を読み取ることができます。 JSON データ内の各フィールドの意味については、「認識結果の説明」をご参照ください。 |
| なし |
| サブタスクのステータスを取得します。
|
| なし | タスク実行中の主要な情報、空の場合もあります | タスク実行中の主要な情報を取得します。 タスクが失敗した場合、この内容を確認して原因を分析できます。 |
認識結果の説明
認識結果は JSON ファイルとして保存されます。
クリックして認識結果の例を表示
{
"file_url":"{YOUR_AUDIO_URL}",
"properties":{
"audio_format":"pcm_s16le",
"channels":[
0
],
"original_sampling_rate":16000,
"original_duration_in_milliseconds":3834
},
"transcripts":[
{
"channel_id":0,
"content_duration_in_milliseconds":3720,
"text":"Hello world, this is the Alibaba speech laboratory.",
"sentences":[
{
"begin_time":100,
"end_time":3820,
"text":"Hello world, this is the Alibaba speech laboratory.",
"sentence_id":1,
"speaker_id":0, //このフィールドは自動話者分離が有効な場合にのみ表示されます
"words":[
{
"begin_time":100,
"end_time":596,
"text":"Hello ",
"punctuation":""
},
{
"begin_time":596,
"end_time":844,
"text":"world",
"punctuation":", "
}
// その他の内容はここで省略
]
}
]
}
]
}
主要なパラメーターは以下の通りです:
パラメーター | 型 | 説明 |
|---|---|---|
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 インスタンスを作成します。
クリックして例を表示
// 文字起こしリクエストパラメーターを作成
TranscriptionParam param =
TranscriptionParam.builder()
// API キーが環境変数に設定されていない場合は、apiKey をご自身の API キーに置き換えてください
//.apiKey("apikey")
.model("paraformer-v2")
// "language_hints" は paraformer-v2 モデルでのみサポートされています
.parameter("language_hints", new String[]{"zh", "en"})
.fileUrls(
Arrays.asList(
"{YOUR_AUDIO_URL}"))
.build();
try {
Transcription transcription = new Transcription();
// 文字起こしリクエストを送信
TranscriptionResult result = transcription.asyncCall(param);
System.out.println("RequestId: " + result.getRequestId());
TranscriptionQueryParam queryParam = TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId());
} catch (Exception e) {
System.out.println("error: " + e);
}
| インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|---|---|---|---|
|
|
|
|
コアクラス (Transcription)
Transcription は「import com.alibaba.dashscope.audio.asr.transcription.*;」でインポートできます。その主要なインターフェイスは以下の通りです:
| インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|---|---|---|---|
|
| 音声認識タスクを非同期に送信します。 | |
|
| 非同期タスクが終了するまで (タスクステータスが | |
|
| 現在のタスク結果を非同期にクエリします。 |
エラーコード
エラーが発生した場合は、「エラーコード」を参照してトラブルシューティングを行ってください。
問題が解決しない場合は、開発者コミュニティ に参加して問題を報告し、さらなる調査のためにリクエスト ID を提供してください。
タスクに複数のサブタスクが含まれている場合、いずれかのサブタスクが成功すれば、全体のタスクステータスは SUCCEEDED とマークされます。各サブタスクの結果を判断するには、subtask_status フィールドを確認する必要があります。
エラー応答の例:
{
"task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
"task_status": "SUCCEEDED",
"submit_time": "2024-12-16 16:30:59.170",
"scheduled_time": "2024-12-16 16:30:59.204",
"end_time": "2024-12-16 16:31:02.375",
"results": [
{
"file_url": "{YOUR_AUDIO_URL}",
"code": "InvalidFile.DownloadFailed",
"message": "The audio file cannot be downloaded.",
"subtask_status": "FAILED"
}
],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 0,
"FAILED": 1
}
}
その他の例
その他の例については、GitHub をご参照ください。
よくある質問
機能に関する質問
Q:Base64 エンコードされた音声をサポートしていますか?
いいえ。Base64 エンコードされた音声はサポートされていません。パブリックにアクセス可能な URL を介してアクセスできる音声のみがサポートされています。バイナリストリームや直接のローカルファイル認識はサポートされていません。
Q:音声ファイルをパブリックにアクセス可能な URL として提供するにはどうすればよいですか?
一般的に、以下の手順に従います (これは一般的なアプローチであり、詳細はストレージ製品によって異なります。音声を Alibaba Cloud OSS にアップロードすることを推奨します):
1. ストレージとホスティング方法を選択する
例:
-
Object Storage Service (推奨):
- クラウドプロバイダーのオブジェクトストレージサービス (例:Alibaba Cloud OSS) を使用して音声ファイルをバケットにアップロードし、パブリックアクセスに設定します。
- 利点:高可用性、CDN アクセラレーションのサポート、簡単な管理。
-
Web サーバー:
- HTTP/HTTPS アクセスをサポートする Web サーバー (Nginx や Apache など) に音声ファイルを配置します。
- 利点:小規模プロジェクトやローカルテストに適しています。
-
コンテンツデリバリーネットワーク (CDN):
- CDN に音声ファイルをホストし、CDN が提供する URL を介してアクセスします。
- 利点:ファイル配信の高速化、高同時実行シナリオに適しています。
2. 音声ファイルをアップロードする
選択したストレージ/ホスティング方法に基づいて音声ファイルをアップロードします。例:
-
Object Storage Service:
- クラウドプロバイダーのコンソールにログインし、バケットを作成します。
- 音声ファイルをアップロードし、ファイルの権限を「パブリック読み取り」に設定するか、一時的なアクセスリンクを生成します。
-
Web サーバー:
- サーバーの指定されたディレクトリ (例:
/var/www/html/audio/) に音声ファイルを配置します。 - ファイルが HTTP/HTTPS を介してアクセス可能であることを確認します。
- サーバーの指定されたディレクトリ (例:
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 のアクセシビリティを確認する
パブリックネットワーク環境で、生成された URL がアクセス可能であることを確認します。例:
- ブラウザで URL を開き、音声ファイルが再生できるか確認します。
- ツール (
curlや Postman など) を使用して、URL が正しい HTTP 応答 (状態コード 200) を返すか確認します。
SDK を使用する場合、音声ファイルが Alibaba Cloud OSS に保存されている場合、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の設定が正しいか確認してください。- 上記のいずれでも問題が解決しない場合は、カスタムホットワードを使用して特定の単語の認識を向上させることができます。
その他の質問
GitHub の QA をご参照ください。