全部產品
Search
文件中心

Alibaba Cloud Model Studio:語音辨識最佳實務

更新時間:Nov 12, 2026

介紹語音辨識應用中的音訊準備、連線重複使用、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 協議支持串行重複使用連線:

  1. 發送 run-task,為本次任務生成唯一 task_id,等待 task-started 後發送音訊。
  2. 發送音訊結束後,以相同 task_id 發送 finish-task。
  3. 等待伺服器端傳回 task-finished,確認當前任務已完成。
  4. 在同一連線上使用新的 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 由本文範例程式碼讀取。

環境變數

預設值

作用

DASHSCOPE_CONNECTION_POOL_SIZE

32

SDK 共享 OkHttp 用戶端保留的閒置 HTTP 連線數。

DASHSCOPE_MAXIMUM_ASYNC_REQUESTS

32

SDK 非同步請求的並行排程容量,超過容量的請求等待排程。

DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST

32

同一主機的非同步請求排程容量。

RECOGNITION_OBJECTPOOL_SIZE

500

本文範例允許同時持有的辨識物件總數,由 Commons Pool 的 maxTotal 控制。

說明並行數是同一時刻執行的任務數,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 連線。

  1. 借用一個 Recognition 物件,啟動辨識並行送音訊。
  2. 發送結束指令並等待完成確認;非同步呼叫同時檢查錯誤回呼。
  3. 成功完成後呼叫 returnObject,讓後續任務重複使用該物件。
  4. 失敗或中斷時呼叫 invalidateObject;工廠的 destroyObject 主動關閉連線。
  5. 所有任務結束後關閉物件集區,釋放閒置物件持有的連線。

將以下程式碼儲存為 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. 按正式業務的並行級別提前發起呼叫,持續 1~2 分鐘可作為起始參考,再按負載調整。
  2. 確認已有可重複使用連線後,再採集正式延遲資料;冷啟動和穩定執行的資料分別統計。
  3. 業務閒置導致連線斷開後,再次呼叫可能重新建連;重新進行性能統計前,按需預熱。

可同時記錄 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)

查詢或下載失敗時,採用有次數和總等待時限的退避重試。非同步提交逾時後,已取得 task_id 的任務先查詢狀態;未取得 task_id 時,按業務對重複處理和重複計費的容忍程度決定是否重新提交。

非同步任務或檔案處理失敗

保留任務及檔案級錯誤信息,先判斷原因,再決定修正輸入或重新提交。

重試採用指數退避並加入隨機抖動,同時限制重試次數和總等待時間,例如最多重試 3 次,具體上限按業務延遲預算調整。即時連線中斷後關閉舊連線,以新任務 ID 重建任務;根據最後確認的最終結果記錄音訊位置,按業務需要重播應用程式緩衝區中的未確認片段,並按原始音訊位置合併結果、去重。

相關文檔