Skip to main content

Praktik terbaik pengenalan ucapan

Siapkan audio, gunakan kembali koneksi, kelola konkurensi Java dan tugas asinkron, serta tangani kesalahan dalam aplikasi pengenalan ucapan.

Menyiapkan audio input

Periksa format, sample rate, kanal, dan durasi input berdasarkan spesifikasi audio model tujuan.
  • Utamakan kualitas perekaman dan kurangi kebisingan serta gema. Sebelum mengaktifkan peredam bising atau AEC, bandingkan hasil pengenalan sebelum dan sesudah pemrosesan pada kumpulan audio representatif yang sama dengan transkripsi manual.
  • Untuk audio telepon 8 kHz, pilih model dan sample rate yang sesuai.
  • Pilih model yang mendukung bahasa dan dialek audio.
  • Jika pengenalan istilah khusus kurang akurat, atur hotword atau peningkatan konteks sesuai Meningkatkan akurasi pengenalan.
  • Memeriksa format audio
  • Mengonversi encoding dan sample rate
  • Memotong audio
  • Mengekstrak audio dari video
Gunakan FFprobe untuk memeriksa format kontainer, codec, sample rate, dan kanal:
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.mp3

Pilih metode input file

Metode input file bergantung pada API. Misalnya, Qwen-Audio-ASR-Flash mendukung URL file audio dan Base64 Data URI. Encode audio lokal sebagai Base64 Data URI untuk mengirimkannya secara langsung. Untuk contoh encoding dan pemanggilan, lihat HTTP API Flash. Saat mengirim file melalui URL, pastikan layanan pengenalan dapat mengunduh audio selama pemrosesan tugas. Periksa izin, masa berlaku URL, dan akses dari jaringan publik. Untuk produksi, simpan file di penyimpanan stabil seperti OSS dan kirimkan URL-nya. Gunakan kembali file yang telah diunggah dalam pemrosesan batch untuk mengurangi unggahan berulang. Sebelum memakai fitur unggah file lokal SDK, periksa batas antarmuka tersebut. Mekanisme file sementara dan ketentuannya dijelaskan di Mendapatkan URL file sementara.

Mengelola tugas dan koneksi real-time

Protokol run-task / finish-task pada Qwen-Audio-ASR-Message, Qwen-Audio-ASR-Streaming, Fun-ASR-Realtime, dan Paraformer mendukung penggunaan ulang koneksi secara berurutan:
  1. Kirim run-task dengan task_id unik. Tunggu task-started sebelum mengirim audio.
  2. Setelah mengirim audio, kirim finish-task dengan task_id yang sama.
  3. Tunggu peristiwa task-finished dari server untuk memastikan penyelesaian.
  4. Mulai tugas berikutnya pada koneksi yang sama dengan task_id baru. Jangan jalankan beberapa tugas secara bersamaan pada satu koneksi.
Qwen3-ASR-Realtime menggunakan protokol sesi. Tutup koneksi secara eksplisit setelah sesi berakhir. Untuk prosedur koneksi dan penghentian, lihat Alur interaksi Qwen3-ASR-Realtime.

Menangani koneksi idle dan gagal

  • Koneksi ditutup otomatis jika tidak ada tugas baru selama sekitar 60 detik setelah penyelesaian. Buat koneksi baru setelah periode idle yang panjang.
  • Setelah tugas gagal, jaringan terputus, atau terjadi kesalahan protokol, tutup koneksi lama dan buat objek baru. Invalidasikan objek pool, jangan kembalikan sebagai objek yang siap digunakan.
  • Tutup pool dan koneksinya saat aplikasi keluar atau berhenti menyediakan pengenalan.

Menangani keheningan panjang dalam tugas

Jika tugas yang berjalan perlu menerima audio hening secara terus-menerus, atur heartbeat=true sesuai API dan terus kirim data hening dengan encoding yang diperlukan. Kelola koneksi idle setelah tugas selesai sesuai bagian sebelumnya. Untuk parameter model, lihat referensi berikut. Peristiwa klien Message | Peristiwa klien Streaming | Peristiwa klien Fun-ASR | Peristiwa klien Paraformer

Mengonfigurasi konkurensi Java

Berikan satu objek Recognition secara eksklusif untuk setiap tugas yang berjalan, lalu kembalikan hanya setelah berhasil selesai. Contoh berikut mengelola objek melalui Commons Pool 2. Buat pool sekali dan gunakan kembali di antara panggilan.

Menambahkan dependensi

Selesaikan Mendapatkan API key dan Menginstal SDK terlebih dahulu. Contoh lengkap di bagian ini memerlukan DashScope Java SDK 2.18.0 atau yang lebih baru. Konfigurasi dependensi ini menggunakan DashScope Java SDK 2.23.2 dan Commons Pool 2.12.0:
  • Maven
  • Gradle
<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>

Membedakan kapasitas koneksi, objek, dan permintaan

SDK membaca tiga variabel lingkungan DASHSCOPE_ berikut. Atur sebelum proses dimulai. Kode contoh dalam dokumen ini membaca RECOGNITION_OBJECTPOOL_SIZE.
Variabel lingkunganDefaultFungsi
DASHSCOPE_CONNECTION_POOL_SIZE32Koneksi HTTP idle yang dipertahankan klien OkHttp bersama milik SDK.
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS32Kapasitas penjadwalan konkuren untuk permintaan asinkron SDK. Permintaan di atas kapasitas menunggu jadwal.
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST32Kapasitas penjadwalan permintaan asinkron per host.
RECOGNITION_OBJECTPOOL_SIZE500Jumlah total objek pengenalan dalam contoh ini, dikendalikan oleh maxTotal Commons Pool.
Konkurensi adalah jumlah tugas yang berjalan bersamaan; RPS adalah jumlah permintaan per detik. Atur thread pekerja dan kapasitas pool objek berdasarkan konkurensi aplikasi, lalu kontrol frekuensi mulai tugas sesuai Batas laju model.
Nilai berikut menjadi referensi perencanaan kapasitas aplikasi pengenalan real-time Paraformer. Konkurensi per server berarti jumlah tugas yang berjalan bersamaan. Server hanya menjalankan aplikasi pengenalan tersebut.
  • Untuk kapasitas koneksi HTTP idle, mulai dari setidaknya dua kali konkurensi puncak, lalu sesuaikan.
  • Awalnya, samakan kapasitas penjadwalan asinkron total dan per host dengan kapasitas koneksi tersebut, lalu sesuaikan berdasarkan antrean yang diamati.
  • Untuk pool objek pengenalan, mulai dari 1,5 hingga 2 kali konkurensi puncak. Kapasitas default 500 merupakan konfigurasi aplikasi contoh.
Server Alibaba CloudReferensi konkurensi tugasKapasitas pool pengenalanKapasitas koneksi HTTP idle
4 vCPU, 8 GiB1005002000
8 vCPU, 16 GiB2005002000
16 vCPU, 32 GiB4005002000
Pengaturan ini berlaku untuk server khusus aplikasi pengenalan real-time Paraformer. Sesuaikan kapasitas dengan laju pengiriman audio, sumber daya klien, dan beban aplikasi. Untuk batas API model, lihat Batas laju.

Menerapkan pool objek pengenalan

Gunakan siklus hidup berikut. Saat maxTotal tercapai dan tidak ada objek idle, borrowObject pada contoh ini menunggu objek dikembalikan. Objek dibuat sesuai kebutuhan, dan koneksi WebSocket dibentuk saat permintaan pengenalan dimulai.
  1. Pinjam objek Recognition, mulai pengenalan, dan kirim audio.
  2. Kirim perintah akhir dan tunggu konfirmasi. Untuk panggilan asinkron, periksa juga callback kesalahan.
  3. Setelah berhasil, panggil returnObject agar objek dapat digunakan kembali.
  4. Saat gagal atau terhenti, panggil invalidateObject. destroyObject pada factory akan menutup koneksi.
  5. Setelah semua tugas selesai, tutup pool untuk melepas koneksi yang dimiliki objek idle.
Simpan kode sebagai RecognitionPoolExample.java. Siapkan asr-example.pcm berisi PCM mono, 16 kHz, 16-bit, atur DASHSCOPE_API_KEY, lalu ganti workspace dan alamat dengan konfigurasi region tujuan (lihat Endpoint). Contoh ini memakai tiga thread pekerja untuk memproses sembilan tugas.
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");
            }
        }
    }
}
Contoh ini menetapkan batas tunggu peminjaman objek 30 detik dan penyelesaian tugas 60 detik. Keduanya dapat disesuaikan. Untuk perekaman langsung, atur batas tunggu sesuai latensi awal yang diizinkan dan batasi jumlah tugas dalam antrean. Saat mengganti sumber audio, pertahankan konfirmasi selesai, invalidasi saat gagal, dan pembersihan sumber daya.

Melakukan pemanasan dan mengukur latensi

Lakukan pemanasan dengan mengirim permintaan pengenalan yang sebenarnya untuk membentuk koneksi WebSocket yang dapat digunakan kembali oleh tugas berikutnya.
  1. Sebelum pengukuran, kirim permintaan pada tingkat konkurensi produksi. Satu hingga dua menit dapat menjadi acuan awal, lalu sesuaikan dengan beban.
  2. Pastikan koneksi yang dapat dipakai kembali sudah ada sebelum mengukur kondisi stabil. Pisahkan data cold start dari operasi stabil.
  3. Koneksi dapat ditutup saat aplikasi idle dan perlu dibuat lagi. Lakukan pemanasan ulang bila diperlukan sebelum pengukuran baru.
Catat latensi paket pertama dan terakhir dari SDK beserta latensi ujung-ke-ujung aplikasi. Tentukan titik awal dan akhir setiap metrik. Antrean, pembentukan koneksi, pengiriman audio, dan pemrosesan layanan memengaruhi metrik yang berbeda dan perlu diamati secara terpisah.

Mengelola pekerjaan transkripsi asinkron

Untuk transkripsi batch dengan konkurensi tinggi, utamakan callback penyelesaian tugas agar permintaan polling berkurang. Untuk konfigurasi callback dan format peristiwa, lihat Mengonfigurasi callback tugas asinkron. Saat menerima notifikasi penyelesaian, gunakan data.task_id untuk mengidentifikasi tugas bisnis dan periksa data.task_status. Jika tugas berhasil tetapi notifikasi tidak memuat hasil yang diperlukan, kueri hasil melalui API HTTP model terkait, lalu unduh dan simpan file transkripsi.

Kontrol laju pengiriman, kueri, dan unggah

  • Pengiriman tugas: Kontrol frekuensi pengiriman sesuai Batas laju model tujuan.
  • Kueri status: API kueri memiliki batas default 20 QPS, yang dapat dinaikkan hingga 100 QPS (hubungi account manager Alibaba Cloud untuk meminta peningkatan), per akun utama Alibaba Cloud, termasuk pengguna RAM-nya. Untuk polling, mulai dengan interval 2 hingga 5 detik dan sesuaikan dengan jumlah tugas agar total laju kueri tetap dalam batas. Untuk kueri, kueri batch, dan pembatalan tugas, lihat Mengelola tugas asinkron.
  • Unggah file sementara: API kredensial unggah file dibatasi hingga 100 QPS per akun utama Alibaba Cloud dan model. Batas ini tidak dapat dinaikkan. Gunakan penyimpanan stabil seperti OSS untuk produksi dan beban dengan konkurensi tinggi. Untuk prosedur dan batas unggah sementara, lihat Mendapatkan URL file sementara.

Segera menyimpan hasil pengenalan

Segera unduh dan simpan file hasil setelah tugas berhasil. Misalnya, transcription_url pada HTTP API Qwen-Audio-ASR-Filetrans berlaku selama 24 jam. Unduh dan simpan hasil secara permanen sebelum URL kedaluwarsa.
  • Jika respons berisi array results, periksa setiap subtask_status sebelum mengunduh JSON transkripsi untuk file yang berhasil. Simpan stempel waktu, informasi pembicara, dan bidang lain yang diperlukan aplikasi.
  • Simpan pemetaan tugas ke file dan status akhir. Jika unduhan gagal, pertahankan catatan tugas dan coba kembali selama URL masih berlaku.

Menangani kesalahan dan percobaan ulang

Tentukan apakah perlu mencoba kembali berdasarkan jenis kesalahan. Catat ID permintaan, ID tugas, model, region, dan tahap kegagalan untuk membedakan masalah input atau izin dari kegagalan layanan sementara.
MasalahTindakan
Kesalahan file input atau parameterPeriksa URL, encoding, sample rate, channel, dan rentang parameter. Perbaiki sebelum mengirim ulang.
Kesalahan autentikasi atau endpointPeriksa API key, workspace, dan region endpoint, lalu perbaiki sesuai pesan kesalahan.
Pembatasan lajuKurangi frekuensi permintaan atau awal tugas, dan ikuti Batas laju. Hindari loop percobaan ulang langsung.
Timeout jaringan, gangguan, atau kesalahan server sementara (5xx)Untuk kegagalan kueri atau unduhan, gunakan retry dengan backoff serta batas jumlah percobaan dan total waktu tunggu. Setelah pengiriman asinkron mengalami timeout, kueri status tugas jika task_id telah diterima. Jika belum, tentukan pengiriman ulang sesuai toleransi aplikasi terhadap pemrosesan dan biaya duplikat.
Kegagalan tugas asinkron atau pemrosesan fileSimpan kesalahan tingkat tugas dan file, identifikasi penyebabnya, lalu tentukan apakah input harus diperbaiki atau dikirim ulang.
Gunakan exponential backoff dengan jitter dan batasi jumlah retry serta total waktu tunggu. Misalnya, izinkan maksimal tiga retry dan sesuaikan batas dengan anggaran latensi aplikasi. Setelah koneksi real-time terputus, tutup koneksi lama dan buat tugas dengan ID baru. Catat posisi audio berdasarkan hasil final terakhir yang telah dikonfirmasi. Kirim ulang audio yang belum dikonfirmasi dari buffer aplikasi sesuai kebutuhan, lalu gabungkan dan deduplikasi hasil berdasarkan posisi pada audio asli.

Dokumentasi terkait