介紹語音辨識應用中的音訊準備、連線重複使用、Java 並行處理、非同步作業管理和異常處理方法。
準備輸入音訊
根據目標模型的音訊規格,檢查輸入的格式、取樣率、聲道和時長。
- 優先保證採集品質,減少背景噪音和回聲。需要降噪或 AEC 時,使用同一組具代表性的標註音訊比較處理前後的辨識結果,再決定是否啟用相應處理。
- 8 kHz 電話音訊選擇匹配的模型和取樣率。
- 根據音訊的語種和方言選擇支援的模型。
- 專業名詞辨識不準時,可設定熱詞或上下文增強,使用方法參見提升辨識準確率。
音訊檢查與處理
檢查音訊格式
使用 FFprobe 查看檔案的容器格式、編碼、取樣率和聲道數:
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.mp3
轉換編碼與取樣率
需要統一輸入格式時,可使用 FFmpeg 轉換。例如,將 MP3 轉為 16 kHz、16-bit、單聲道 WAV:
ffmpeg -i input.mp3 -ac 1 -ar 16000 -sample_fmt s16 output.wav
Java 物件集區範例使用無 WAV 檔案頭的 PCM 資料,可按以下命令生成 asr-example.pcm:
ffmpeg -i input.mp3 -ac 1 -ar 16000 -c:a pcm_s16le -f s16le asr-example.pcm
裁剪音訊
例如,從 WAV 檔案的第 1 分 30 秒起截取 2 分鐘。-c copy 直接複製音訊流,保留原編碼和取樣率:
ffmpeg -i long_audio.wav -ss 00:01:30 -t 00:02:00 -c copy output_clip.wav
擷取影片音軌
需要單獨處理影片中的音訊時,可擷取音軌並轉為 16 kHz、16-bit、單聲道 WAV;輸出格式依目標模型要求調整:
ffmpeg -i input.mp4 -vn -ac 1 -ar 16000 -c:a pcm_s16le output.wav
選擇檔案輸入方式
檔案輸入方式由所用介面決定。例如,Qwen-Audio-ASR-Flash 支援音訊檔案 URL 和 Base64 Data URI。本機音訊可編碼為 Base64 Data URI 後直接提交,編碼方法和呼叫範例參見Flash HTTP API。
透過 URL 提交檔案時,確保辨識服務能在任務處理期間下載音訊,並檢查存取權限、URL 有效期和公網可達性。
生產環境可將檔案托管到 OSS 等穩定存儲,再通過 URL 提交。批量處理時重複使用已上傳的檔案,減少重復上傳。使用 SDK 的本地檔案上傳能力前,核對對應介面的上傳限制;臨時檔案機制及適用條件請參見取得臨時檔案 URL。
管理即時任務與連線
Qwen-Audio-ASR-Message、Qwen-Audio-ASR-Streaming、Fun-ASR-Realtime 和 Paraformer 的 run-task / finish-task 協議支持串行重複使用連線:
- 發送
run-task,為本次任務生成唯一task_id,等待task-started後發送音訊。 - 發送音訊結束後,以相同
task_id發送finish-task。 - 等待伺服器端傳回
task-finished,確認當前任務已完成。 - 在同一連線上使用新的
task_id發起下一項任務;同一連線不並行執行多個任務。
Qwen3-ASR-Realtime 使用會話協議,會話結束後需主動斷開連線;其接入和結束流程參見Qwen3-ASR-Realtime 交互流程。
處理閒置與失敗連線
- 任務結束後約 60 秒沒有新任務,連線會自動斷開。長時間閒置後應重新建立連線。
- 任務失敗、網絡中斷或協議異常後,主動關閉舊連線並重新建立辨識物件;池化物件應廢棄,不歸還為可用物件。
- 應用退出或停止提供辨識服務時,關閉物件集區及其持有的連線。
處理任務中的長時間靜音
任務執行期間需要持續傳送靜音音訊時,按對應 API 設定 heartbeat=true,並持續傳送符合編碼要求的靜音資料。任務結束後的閒置連線按上一節的規則管理。各模型的參數說明見以下文件。
Message 用戶端事件 | Streaming 用戶端事件 | Fun-ASR 用戶端事件 | Paraformer 用戶端事件
配置 Java 並行處理
並行辨識時,每個正在執行的任務獨佔一個 Recognition 物件,任務成功結束後再歸還。以下範例基於 Commons Pool 2 自行管理辨識物件,不需要為每次呼叫重新建立物件集區。
添加依賴
先完成取得 API Key和安裝 SDK。本節完整範例要求 DashScope Java SDK 2.18.0 及以上。以下依賴設定使用 DashScope Java SDK 2.23.2、Commons Pool 2.12.0:
Maven
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>dashscope-sdk-java</artifactId>
<version>2.23.2</version>
</dependency>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-pool2</artifactId>
<version>2.12.0</version>
</dependency>
Gradle
dependencies {
implementation 'com.alibaba:dashscope-sdk-java:2.23.2'
implementation 'org.apache.commons:commons-pool2:2.12.0'
}
區分連線、物件和請求容量
以下三個 DASHSCOPE_ 環境變數由 SDK 讀取,需在進程啟動前設置;RECOGNITION_OBJECTPOOL_SIZE 由本文範例程式碼讀取。
環境變數 | 預設值 | 作用 |
|---|---|---|
| 32 | SDK 共享 OkHttp 用戶端保留的閒置 HTTP 連線數。 |
| 32 | SDK 非同步請求的並行排程容量,超過容量的請求等待排程。 |
| 32 | 同一主機的非同步請求排程容量。 |
| 500 | 本文範例允許同時持有的辨識物件總數,由 Commons Pool 的 |
說明並行數是同一時刻執行的任務數,RPS 是每秒請求數。按業務並行量設定工作執行緒數和物件集區容量,並根據模型介面的限流控制任務發起頻率。
Paraformer 配置參考
以下為 Paraformer 即時辨識應用的容量規劃參考。單機並行表示同一時刻執行的辨識任務數;伺服器僅承載該辨識應用。
- HTTP 閒置連線容量可從峰值並行數的 2 倍以上開始調整。
- 非同步請求排程容量、單主機排程容量可先取與該連線容量一致的值,再按實際排隊情況調整。
- 辨識物件集區容量可從峰值並行數的 1.5~2 倍開始調整。本文範例的預設容量為 500,屬於應用配置。
阿里雲伺服器規格 | 任務並行參考 | 辨識物件集區容量 | HTTP 閒置連線容量 |
|---|---|---|---|
4 核 8 GiB | 100 | 500 | 2000 |
8 核 16 GiB | 200 | 500 | 2000 |
16 核 32 GiB | 400 | 500 | 2000 |
說明以上設定適用於僅承載 Paraformer 即時辨識應用的伺服器。實際容量按音訊傳送速率、用戶端資源和業務處理負載調整;模型介面的限流見限流。
實現辨識物件集區
物件集區的完整生命週期如下。達到 maxTotal 且沒有閒置物件時,本例的 borrowObject 等待物件歸還;物件按需建立,並在發起辨識請求時建立 WebSocket 連線。
- 借用一個
Recognition物件,啟動辨識並行送音訊。 - 發送結束指令並等待完成確認;非同步呼叫同時檢查錯誤回呼。
- 成功完成後呼叫
returnObject,讓後續任務重複使用該物件。 - 失敗或中斷時呼叫
invalidateObject;工廠的destroyObject主動關閉連線。 - 所有任務結束後關閉物件集區,釋放閒置物件持有的連線。
將以下程式碼儲存為 RecognitionPoolExample.java。準備 16 kHz、16-bit、單聲道 PCM 檔案 asr-example.pcm,配置 DASHSCOPE_API_KEY,並將程式碼中的業務空間和地址替換為對應地域的配置(參見接入地址)。範例啟動 3 個工作執行緒,處理 9 個辨識任務。
import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionResult;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.utils.Constants;
import org.apache.commons.pool2.BasePooledObjectFactory;
import org.apache.commons.pool2.PooledObject;
import org.apache.commons.pool2.impl.DefaultPooledObject;
import org.apache.commons.pool2.impl.GenericObjectPool;
import org.apache.commons.pool2.impl.GenericObjectPoolConfig;
import java.io.InputStream;
import java.nio.ByteBuffer;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.Callable;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import java.util.concurrent.atomic.AtomicReference;
public class RecognitionPoolExample {
private static final int WORKERS = 3;
private static final int TASKS = 9;
private static final int COMPLETION_TIMEOUT_SECONDS = 60;
public static void main(String[] args) {
int exitCode = 0;
try {
run(args);
} catch (Exception e) {
e.printStackTrace();
exitCode = 1;
}
// Exit this standalone example after all owned resources are closed.
System.exit(exitCode);
}
private static void run(String[] args) throws Exception {
String apiKey = System.getenv("DASHSCOPE_API_KEY");
if (apiKey == null || apiKey.isEmpty()) {
throw new IllegalArgumentException("Set DASHSCOPE_API_KEY first");
}
// Replace {WorkspaceId} with the workspace ID for the endpoint region.
Constants.baseWebsocketApiUrl =
"wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
Path audio = Paths.get(args.length == 0 ? "asr-example.pcm" : args[0]);
if (!Files.isReadable(audio)) {
throw new IllegalArgumentException("Audio file is not readable: " + audio);
}
int capacity = Integer.parseInt(System.getenv().getOrDefault(
"RECOGNITION_OBJECTPOOL_SIZE", "500"));
if (capacity <= 0) {
throw new IllegalArgumentException("Pool size must be positive");
}
GenericObjectPoolConfig<Recognition> config = new GenericObjectPoolConfig<>();
config.setMaxTotal(capacity);
config.setMaxIdle(capacity);
config.setBlockWhenExhausted(true);
config.setMinIdle(0);
GenericObjectPool<Recognition> pool =
new GenericObjectPool<>(new RecognitionFactory(), config);
ExecutorService executor = Executors.newFixedThreadPool(WORKERS);
ExecutorService completionExecutor = Executors.newFixedThreadPool(WORKERS);
try {
List<Callable<Void>> tasks = new ArrayList<>();
for (int i = 0; i < TASKS; i++) {
tasks.add(() -> {
recognize(pool, audio, apiKey, completionExecutor);
return null;
});
}
// Wait for every task, then propagate any task failure.
List<Future<Void>> results = executor.invokeAll(tasks);
for (Future<Void> result : results) {
result.get();
}
} finally {
executor.shutdown();
completionExecutor.shutdownNow();
try {
if (!executor.awaitTermination(1, TimeUnit.MINUTES)) {
executor.shutdownNow();
}
if (!completionExecutor.awaitTermination(1, TimeUnit.MINUTES)) {
completionExecutor.shutdownNow();
}
} finally {
pool.close();
System.out.printf("Pool closed: created=%d, destroyed=%d, active=%d, idle=%d%n",
pool.getCreatedCount(), pool.getDestroyedCount(),
pool.getNumActive(), pool.getNumIdle());
}
}
}
private static void recognize(GenericObjectPool<Recognition> pool,
Path audio, String apiKey,
ExecutorService completionExecutor) throws Exception {
// Example timeout; adjust it to the application's queueing policy.
Recognition recognizer = pool.borrowObject(Duration.ofSeconds(30));
boolean reusable = false;
AtomicReference<Exception> failure = new AtomicReference<>();
CountDownLatch completed = new CountDownLatch(1);
try (InputStream input = Files.newInputStream(audio)) {
RecognitionParam param = RecognitionParam.builder()
.model("qwen-audio-3.1-asr-flash-streaming")
.apiKey(apiKey).format("pcm").sampleRate(16000).build();
ResultCallback<RecognitionResult> callback = new ResultCallback<RecognitionResult>() {
@Override
public void onEvent(RecognitionResult result) {
if (result.isSentenceEnd() && result.getSentence() != null) {
System.out.println(result.getSentence().getText());
}
}
@Override
public void onComplete() {
completed.countDown();
}
@Override
public void onError(Exception error) {
failure.set(error);
completed.countDown();
}
};
recognizer.call(param, callback);
// 100 ms of PCM16 mono audio at 16 kHz is 3,200 bytes.
byte[] buffer = new byte[3200];
int count;
while ((count = input.read(buffer)) != -1) {
if (failure.get() != null) {
throw failure.get();
}
recognizer.sendAudioFrame(ByteBuffer.wrap(buffer, 0, count));
Thread.sleep(100);
buffer = new byte[3200];
}
// stop() blocks in the SDK, so apply the deadline to the stop call itself.
long deadline = System.nanoTime()
+ TimeUnit.SECONDS.toNanos(COMPLETION_TIMEOUT_SECONDS);
Future<?> stopTask = completionExecutor.submit(recognizer::stop);
try {
stopTask.get(Math.max(0, deadline - System.nanoTime()), TimeUnit.NANOSECONDS);
long remaining = Math.max(0, deadline - System.nanoTime());
if (!completed.await(remaining, TimeUnit.NANOSECONDS)) {
throw new TimeoutException("Timed out waiting for task completion");
}
} finally {
stopTask.cancel(true);
}
if (failure.get() != null) {
throw failure.get();
}
reusable = true;
System.out.printf("Completed: request_id=%s, first_packet_ms=%d, last_packet_ms=%d%n",
recognizer.getLastRequestId(), recognizer.getFirstPackageDelay(),
recognizer.getLastPackageDelay());
} finally {
if (reusable) {
pool.returnObject(recognizer);
} else {
// destroyObject closes the connection before discarding the object.
pool.invalidateObject(recognizer);
}
}
}
private static class RecognitionFactory extends BasePooledObjectFactory<Recognition> {
@Override
public Recognition create() {
return new Recognition();
}
@Override
public PooledObject<Recognition> wrap(Recognition recognizer) {
return new DefaultPooledObject<>(recognizer);
}
@Override
public void destroyObject(PooledObject<Recognition> object) {
if (object.getObject().getDuplexApi() != null) {
object.getObject().getDuplexApi().close(1000, "pool cleanup");
}
}
}
}
程式碼中的物件借用等待上限為 30 秒,結束任務的等待上限為 60 秒,均為可調整的範例設定。即時採集場景需按允許的啟動延遲設定等待上限,並限制排隊任務數。更換音訊來源時,保留結束確認、異常作廢和資源關閉流程。
預熱與耗時統計
透過發起實際辨識請求預熱,建立後續任務可重複使用的 WebSocket 連線。
- 按正式業務的並行級別提前發起呼叫,持續 1~2 分鐘可作為起始參考,再按負載調整。
- 確認已有可重複使用連線後,再採集正式延遲資料;冷啟動和穩定執行的資料分別統計。
- 業務閒置導致連線斷開後,再次呼叫可能重新建連;重新進行性能統計前,按需預熱。
可同時記錄 SDK 傳回的首個封包、最後封包耗時,以及業務端的端到端耗時,並明確各自的起止點。排隊、建連、音訊發送和服務處理會影響不同指標,應分開觀察。
管理非同步轉寫作業
高並行批次轉寫優先透過回呼接收任務完成通知,減少輪詢請求。回呼設定和事件格式請參閱設定非同步任務回呼。
收到完成通知後,使用 data.task_id 關聯業務任務,並檢查 data.task_status。任務成功且通知中未包含所需結果時,依照對應模型的 HTTP API查詢任務結果,再下載並儲存轉寫檔案。
控制提交、查詢與上傳頻率
- 任務提交:根據目標模型的限流控制提交頻率。
- 狀態查詢:查詢介面預設限流為 20 QPS,最高可擴容至 100 QPS(擴容請聯絡阿里雲商務經理),按阿里雲主帳號(含其子帳號)計算。使用主動輪詢時,可從 2~5 秒的查詢間隔開始,並按任務數量調整,確保總查詢頻率在限額內。查詢、批次查詢及取消任務的方法參見管理非同步任務。
- 臨時檔案上傳:檔案上傳憑證介面限流為 100 QPS,按阿里雲主帳號 + 模型維度計算,不支援擴容。生產環境和高並行場景使用 OSS 等穩定儲存;臨時檔案上傳的使用方式及限制參見取得臨時檔案 URL。
及時儲存辨識結果
收到任務成功狀態後,應盡快下載並儲存結果檔案。以Qwen-Audio-ASR-Filetrans HTTP API為例,transcription_url 有效期為 24 小時,需在到期前下載並持久儲存結果檔案。
- 傳回
results陣列時,逐項檢查subtask_status,再下載成功檔案的轉寫 JSON,儲存業務需要的時間戳記、說話者等欄位。 - 儲存任務與檔案的對應關係及最終狀態;結果下載失敗時保留任務記錄,並在有效期內重試下載。
處理異常與重試
先根據錯誤類型決定是否重試。記錄請求 ID、任務 ID、模型、地域和失敗階段,便於區分輸入問題、權限問題與臨時服務異常。
問題類型 | 處理方式 |
|---|---|
輸入檔案或參數錯誤 | 檢查 URL、編碼、取樣率、聲道及參數範圍,修正後再提交。 |
鑒權或接入配置錯誤 | 核對 API Key、業務空間及接入地址所屬地域,按具體錯誤信息修正配置。 |
限流 | 降低請求頻率或任務啟動速率,按限流處理,不立即循環重試。 |
網路逾時、中斷或暫時性伺服器錯誤(5xx) | 查詢或下載失敗時,採用有次數和總等待時限的退避重試。非同步提交逾時後,已取得 |
非同步任務或檔案處理失敗 | 保留任務及檔案級錯誤信息,先判斷原因,再決定修正輸入或重新提交。 |
重試採用指數退避並加入隨機抖動,同時限制重試次數和總等待時間,例如最多重試 3 次,具體上限按業務延遲預算調整。即時連線中斷後關閉舊連線,以新任務 ID 重建任務;根據最後確認的最終結果記錄音訊位置,按業務需要重播應用程式緩衝區中的未確認片段,並按原始音訊位置合併結果、去重。