Fun-ASR-Realtime Java SDK - Alibaba Cloud Model Studio

Prasyarat

Layanan telah diaktifkan dan Dapatkan Kunci API. Untuk mencegah risiko keamanan akibat kebocoran kode, Konfigurasikan Kunci API sebagai Variabel lingkungan, bukan mengodekannya secara langsung dalam kode Anda.

Instal SDK DashScope terbaru.

Mulai cepat

Kelas Recognition menyediakan antarmuka untuk panggilan sinkron maupun panggilan streaming dua arah. Pilih pendekatan yang sesuai dengan kebutuhan Anda:

Panggilan sinkron: mengenali file lokal dan mengembalikan hasil lengkap sekaligus. Paling cocok untuk memproses audio yang telah direkam sebelumnya.
Panggilan streaming dua arah: mengenali aliran audio secara langsung dan mengembalikan hasil secara real time. Aliran audio dapat berasal dari perangkat eksternal seperti mikrofon atau dibaca dari file lokal. Paling cocok untuk skenario yang memerlukan umpan balik segera.

Panggilan sinkron
Panggilan streaming dua arah: berbasis callback
Panggilan streaming dua arah: berbasis Flowable

Kirim satu tugas pengenalan ucapan real-time dan dapatkan hasil pengenalan secara sinkron dengan memasukkan file lokal. Panggilan ini akan memblokir hingga hasil dikembalikan.Buat instans Kelas Recognition, lalu panggil metode call untuk mengikat parameter permintaan dan file yang akan dikenali. Metode ini melakukan pengenalan dan mengembalikan hasil akhir.

import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.utils.Constants;

import java.io.File;

public class Main {
    public static void main(String[] args) {
        // Berikut adalah konfigurasi untuk wilayah Singapura. Saat memanggil, ganti "{WorkspaceId}" dengan Workspace ID Anda yang sebenarnya. Konfigurasi berbeda tiap wilayah.
        Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference";
        // Buat instans Recognition
        Recognition recognizer = new Recognition();
        // Buat RecognitionParam
        RecognitionParam param =
                RecognitionParam.builder()
                        .model("fun-asr-realtime")
                        // Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                        // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan Kunci API Studio Model Anda: .apiKey("sk-xxx")
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .format("wav")
                        .sampleRate(16000)
                        //.parameter("language_hints", new String[]{"zh"})
                        .build();

        try {
            System.out.println("Hasil pengenalan: " + recognizer.call(param, new File("{YOUR_AUDIO_FILE}")));
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            // Tutup koneksi WebSocket setelah tugas selesai
            recognizer.getDuplexApi().close(1000, "bye");
        }
        System.out.println(
                "[Metric] requestId: "
                        + recognizer.getLastRequestId()
                        + ", first package delay ms: "
                        + recognizer.getFirstPackageDelay()
                        + ", last package delay ms: "
                        + recognizer.getLastPackageDelay());
        System.exit(0);
    }
}

Kirim satu tugas pengenalan ucapan real-time dan alirkan hasil pengenalan real-time dengan mengimplementasikan antarmuka callback.

Mulai pengenalan ucapan streaming Buat instans Kelas Recognition, lalu panggil metode call untuk mengikat parameter permintaan dan antarmuka callback (ResultCallback) serta mulai pengenalan ucapan streaming.
Alirkan audio Panggil metode sendAudioFrame dari Kelas Recognition dalam loop untuk mengirim aliran audio biner ke server dalam segmen. Baca audio dari file lokal atau perangkat seperti mikrofon. Saat data audio dikirim, server mengembalikan hasil pengenalan ke klien secara real time melalui metode onEvent dari antarmuka callback (ResultCallback). Kirim sekitar 100 ms audio per frame, dengan ukuran muatan antara 1 KB hingga 16 KB.
Akhiri proses Panggil metode stop dari Kelas Recognition untuk mengakhiri pengenalan ucapan. Metode ini memblokir thread saat ini hingga callback onComplete atau onError dari antarmuka callback (ResultCallback) dipicu, saat itu thread dilepas.

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 javax.sound.sampled.AudioFormat;
import javax.sound.sampled.AudioSystem;
import javax.sound.sampled.TargetDataLine;

import java.nio.ByteBuffer;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;

public class Main {
    public static void main(String[] args) throws InterruptedException {
        // Berikut adalah konfigurasi untuk wilayah Singapura. Saat memanggil, ganti "{WorkspaceId}" dengan Workspace ID Anda yang sebenarnya. Konfigurasi berbeda tiap wilayah.
        Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference";
        ExecutorService executorService = Executors.newSingleThreadExecutor();
        executorService.submit(new RealtimeRecognitionTask());
        executorService.shutdown();
        executorService.awaitTermination(1, TimeUnit.MINUTES);
        System.exit(0);
    }
}

class RealtimeRecognitionTask implements Runnable {
    @Override
    public void run() {
        RecognitionParam param = RecognitionParam.builder()
                .model("fun-asr-realtime")
                // Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan Kunci API Studio Model Anda: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .format("pcm")
                .sampleRate(16000)
                .build();
        Recognition recognizer = new Recognition();

        ResultCallback<RecognitionResult> callback = new ResultCallback<RecognitionResult>() {
            @Override
            public void onEvent(RecognitionResult result) {
                if (result.isSentenceEnd()) {
                    System.out.println("Hasil Akhir: " + result.getSentence().getText());
                } else {
                    System.out.println("Hasil Sementara: " + result.getSentence().getText());
                }
            }

            @Override
            public void onComplete() {
                System.out.println("Pengenalan selesai");
            }

            @Override
            public void onError(Exception e) {
                System.out.println("Kesalahan RecognitionCallback: " + e.getMessage());
            }
        };
        try {
            recognizer.call(param, callback);
            // Buat format audio
            AudioFormat audioFormat = new AudioFormat(16000, 16, 1, true, false);
            // Sesuaikan perangkat perekaman default berdasarkan format
            TargetDataLine targetDataLine =
                    AudioSystem.getTargetDataLine(audioFormat);
            targetDataLine.open(audioFormat);
            // Mulai merekam
            targetDataLine.start();
            ByteBuffer buffer = ByteBuffer.allocate(1024);
            long start = System.currentTimeMillis();
            // Rekam selama 50 detik dan lakukan transkripsi real-time
            while (System.currentTimeMillis() - start < 50000) {
                int read = targetDataLine.read(buffer.array(), 0, buffer.capacity());
                if (read > 0) {
                    buffer.limit(read);
                    // Kirim data audio yang direkam ke layanan pengenalan streaming
                    recognizer.sendAudioFrame(buffer);
                    buffer = ByteBuffer.allocate(1024);
                    // Laju perekaman dibatasi; tidur sejenak untuk mencegah penggunaan CPU berlebihan
                    Thread.sleep(20);
                }
            }
            recognizer.stop();
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            // Tutup koneksi WebSocket setelah tugas selesai
            recognizer.getDuplexApi().close(1000, "bye");
        }

        System.out.println(
                "[Metric] requestId: "
                        + recognizer.getLastRequestId()
                        + ", first package delay ms: "
                        + recognizer.getFirstPackageDelay()
                        + ", last package delay ms: "
                        + recognizer.getLastPackageDelay());
    }
}

Kirim satu tugas pengenalan ucapan real-time dan alirkan hasil pengenalan real-time dengan mengimplementasikan alur kerja (Flowable).Flowable adalah framework open-source untuk manajemen alur kerja dan proses bisnis, dirilis di bawah lisensi Apache 2.0. Untuk cara menggunakan Flowable, lihat Detail API Flowable.Panggil metode streamCall dari Kelas Recognition secara langsung untuk memulai pengenalan.Metode streamCall mengembalikan instans Flowable<RecognitionResult>. Gunakan metode instans Flowable, seperti blockingForEach atau subscribe, untuk memproses hasil pengenalan. Setiap hasil dibungkus dalam RecognitionResult.Metode streamCall memiliki dua parameter:

Instans RecognitionParam (parameter permintaan): gunakan untuk mengatur model, laju sampel, format audio, dan parameter lain yang diperlukan untuk pengenalan ucapan.
Instans Flowable<ByteBuffer>: buat instans bertipe Flowable<ByteBuffer> dan implementasikan logika penguraian aliran audio di dalamnya.

import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import io.reactivex.BackpressureStrategy;
import io.reactivex.Flowable;

import javax.sound.sampled.AudioFormat;
import javax.sound.sampled.AudioSystem;
import javax.sound.sampled.TargetDataLine;
import java.nio.ByteBuffer;

public class Main {
    public static void main(String[] args) throws NoApiKeyException {
        // Berikut adalah konfigurasi untuk wilayah Singapura. Saat memanggil, ganti "{WorkspaceId}" dengan Workspace ID Anda yang sebenarnya. Konfigurasi berbeda tiap wilayah.
        Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference";
        // Buat Flowable<ByteBuffer>
        Flowable<ByteBuffer> audioSource =
                Flowable.create(
                        emitter -> {
                            new Thread(
                                    () -> {
                                        try {
                                            // Buat format audio
                                            AudioFormat audioFormat = new AudioFormat(16000, 16, 1, true, false);
                                            // Sesuaikan perangkat perekaman default berdasarkan format
                                            TargetDataLine targetDataLine =
                                                    AudioSystem.getTargetDataLine(audioFormat);
                                            targetDataLine.open(audioFormat);
                                            // Mulai merekam
                                            targetDataLine.start();
                                            ByteBuffer buffer = ByteBuffer.allocate(1024);
                                            long start = System.currentTimeMillis();
                                            // Rekam selama 50 detik dan lakukan transkripsi real-time
                                            while (System.currentTimeMillis() - start < 50000) {
                                                int read = targetDataLine.read(buffer.array(), 0, buffer.capacity());
                                                if (read > 0) {
                                                    buffer.limit(read);
                                                    // Kirim data audio yang direkam ke layanan pengenalan streaming
                                                    emitter.onNext(buffer);
                                                    buffer = ByteBuffer.allocate(1024);
                                                    // Laju perekaman dibatasi; tidur sejenak untuk mencegah penggunaan CPU berlebihan
                                                    Thread.sleep(20);
                                                }
                                            }
                                            // Beri tahu bahwa transkripsi telah berakhir
                                            emitter.onComplete();
                                        } catch (Exception e) {
                                            emitter.onError(e);
                                        }
                                    })
                                    .start();
                        },
                        BackpressureStrategy.BUFFER);

        // Buat Recognizer
        Recognition recognizer = new Recognition();
        // Buat RecognitionParam dan masukkan Flowable<ByteBuffer> yang dibuat di atas ke parameter audioFrames
        RecognitionParam param = RecognitionParam.builder()
                .model("fun-asr-realtime")
                // Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan Kunci API Studio Model Anda: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .format("pcm")
                .sampleRate(16000)
                .build();

        // Antarmuka panggilan streaming
        recognizer
                .streamCall(param, audioSource)
                .blockingForEach(
                        result -> {
                            // Langganan hasil output
                            if (result.isSentenceEnd()) {
                                System.out.println("Hasil Akhir: " + result.getSentence().getText());
                            } else {
                                System.out.println("Hasil Sementara: " + result.getSentence().getText());
                            }
                        });
        // Tutup koneksi WebSocket setelah tugas selesai
        recognizer.getDuplexApi().close(1000, "bye");
        System.out.println(
                "[Metric] requestId: "
                        + recognizer.getLastRequestId()
                        + ", first package delay ms: "
                        + recognizer.getFirstPackageDelay()
                        + ", last package delay ms: "
                        + recognizer.getLastPackageDelay());
        System.exit(0);
    }
}

Panggilan konkurensi tinggi

SDK Java DashScope menggunakan pooling koneksi OkHttp3 untuk mengurangi overhead pembentukan koneksi berulang. Untuk detailnya, lihat Praktik terbaik konkurensi tinggi.

Parameter permintaan

Gunakan metode berantai RecognitionParam untuk mengonfigurasi model, laju sampel, format audio, dan parameter lainnya. Masukkan objek parameter yang telah dikonfigurasi ke metode call/streamCall dari Kelas Recognition.

RecognitionParam param = RecognitionParam.builder()
  .model("fun-asr-realtime")
  .format("pcm")
  .sampleRate(16000)
  //.parameter("language_hints", new String[]{"zh"})
  .build();

Parameter	Tipe	Wajib	Deskripsi
`model`	`String`	Ya	Nama model.
`sampleRate`	`Integer`	Ya	Laju sampel, dalam Hz.Nilai valid: model 8 kHz hanya mendukung 8000 Hz; model lain mendukung laju sampel apa pun.
`format`	`String`	Ya	Format audio.Nilai valid: `pcm` `wav` `mp3` `opus` `speex` `aac` `amr` opus/speex: Harus menggunakan enkapsulasi Ogg.wav: Harus menggunakan encoding PCM.amr: Hanya tipe AMR-NB yang didukung.
`vocabularyId`	`String`	Tidak	ID daftar kata panas yang telah dikompilasi sebelumnya.Hasilkan ID ini terlebih dahulu dengan memanggil API pembuatan daftar kata panas. Masukkan ID ini selama pengenalan untuk menggunakan kata-kata panas dalam daftar tersebut.Cocok untuk skenario di mana kosakata diketahui dan relatif stabil, serta Anda perlu menggunakan kembali daftar kata yang sama di berbagai permintaan.Untuk detail penggunaan, lihat Kata panas yang telah dikompilasi.
`semantic_punctuation_enabled`	`boolean`	Tidak	Apakah segmentasi semantik diaktifkan.Nilai default: false. true: Mengaktifkan segmentasi semantik dan menonaktifkan segmentasi VAD. false (default): Mengaktifkan segmentasi VAD dan menonaktifkan segmentasi semantik. Segmentasi semantik lebih akurat dan lebih cocok untuk skenario transkripsi rapat. Segmentasi VAD (Voice Activity Detection) memiliki latensi lebih rendah dan lebih cocok untuk skenario interaktif.Atur `semantic_punctuation_enabled` melalui metode `parameter` atau metode `parameters` dari instans `RecognitionParam`: `RecognitionParam param = RecognitionParam.builder() .model("fun-asr-realtime") .format("pcm") .sampleRate(16000) .parameter("semantic_punctuation_enabled", true) .build();`
`max_sentence_silence`	`Integer`	Tidak	Ambang batas keheningan VAD untuk segmentasi, dalam ms. Ketika keheningan setelah segmen ucapan melebihi ambang batas ini, sistem menentukan bahwa kalimat telah berakhir. Ketika `semantic_punctuation_enabled` diatur ke true, parameter ini tidak digunakan sebagai kriteria untuk mengembalikan `sentence_end`, tetapi mengaturnya terlalu rendah dapat memengaruhi performa pengenalan.Nilai default: 1300.Nilai valid: [200, 6000].Atur `max_sentence_silence` melalui metode `parameter` atau metode `parameters` dari instans `RecognitionParam`: `RecognitionParam param = RecognitionParam.builder() .model("fun-asr-realtime") .format("pcm") .sampleRate(16000) .parameter("max_sentence_silence", 800) .build();`
`multi_threshold_mode_enabled`	`boolean`	Tidak	Hanya berlaku ketika `semantic_punctuation_enabled` bernilai false. Apakah mode multi-ambang batas diaktifkan. Ketika diaktifkan, ini mencegah segmen VAD menjadi terlalu panjang.Nilai default: false.Atur `multi_threshold_mode_enabled` melalui metode `parameter` atau metode `parameters` dari instans `RecognitionParam`: `RecognitionParam param = RecognitionParam.builder() .model("fun-asr-realtime") .format("pcm") .sampleRate(16000) .parameter("multi_threshold_mode_enabled", true) .build();`
`punctuation_prediction_enabled`	`boolean`	Tidak	Mengatur apakah tanda baca ditambahkan secara otomatis ke hasil pengenalan: true (default): ya. Nilai ini tidak dapat diubah. Atur `punctuation_prediction_enabled` melalui metode `parameter` atau metode `parameters` dari instans `RecognitionParam`: `RecognitionParam param = RecognitionParam.builder() .model("fun-asr-realtime") .format("pcm") .sampleRate(16000) .parameter("punctuation_prediction_enabled", false) .build();`
`heartbeat`	`boolean`	Tidak	Apakah paket heartbeat diaktifkan.Nilai default: false. true: Menjaga koneksi ke server tetap aktif meskipun audio diam dikirim terus-menerus. false (default): Meskipun audio diam dikirim terus-menerus, koneksi akan timeout dan ditutup setelah periode waktu tertentu. Audio diam mengacu pada konten dalam file atau aliran data yang tidak mengandung sinyal suara. Anda dapat menghasilkan audio diam dengan beberapa cara, seperti menggunakan perangkat lunak pengeditan audio seperti Audacity atau Adobe Audition, atau menggunakan alat command-line seperti FFmpeg. Untuk menggunakan bidang ini, versi SDK harus 2.19.1 atau lebih baru. Atur `heartbeat` melalui metode `parameter` atau metode `parameters` dari instans `RecognitionParam`: `RecognitionParam param = RecognitionParam.builder() .model("fun-asr-realtime") .format("pcm") .sampleRate(16000) .parameter("heartbeat", true) .build();`
`language_hints`	`String[]`	Tidak	Bahasa audio yang akan dikenali. Tidak ada nilai default; jika tidak diatur, model akan mendeteksi bahasa secara otomatis.Anda dapat menetapkan 1 nilai. Jika lebih, hanya nilai pertama yang berlaku. Klik untuk melihat kode bahasa yang didukung fun-asr-realtime, fun-asr-realtime-2025-11-07: zh: Chinese en: English ja: Japanese ko: Korean vi: Vietnamese th: Thai id: Indonesian ms: Malay tl: Filipino hi: Hindi ar: Arabic fr: French de: German es: Spanish pt: Portuguese ru: Russian it: Italian nl: Dutch sv: Swedish da: Danish fi: Finnish no: Norwegian el: Greek pl: Polish cs: Czech hu: Hungarian ro: Romanian bg: Bulgarian hr: Croatian sk: Slovak fun-asr-realtime-2026-02-28: zh: Chinese en: English ja: Japanese fun-asr-realtime-2025-09-15: zh: Chinese en: English fun-asr-flash-8k-realtime, fun-asr-flash-8k-realtime-2026-01-28: zh: Chinese Atur `language_hints` melalui metode `parameter` atau metode `parameters` dari instans `RecognitionParam`: `RecognitionParam param = RecognitionParam.builder() .model("fun-asr-realtime") .format("pcm") .sampleRate(16000) .parameter("language_hints", new String[]{"zh"}) .build();`
`speech_noise_threshold`	`float`	Tidak	Ambang batas untuk membedakan ucapan dari kebisingan, digunakan untuk menyesuaikan sensitivitas Voice Activity Detection (VAD).Nilai valid: [-1.0, 1.0].Deskripsi nilai: Semakin dekat nilai ke -1: Ambang batas kebisingan menurun, sehingga kebisingan lebih mungkin dikenali sebagai ucapan, yang dapat menyebabkan lebih banyak kebisingan ditranskripsikan. Semakin dekat nilai ke +1: Ambang batas kebisingan meningkat, sehingga ucapan lebih mungkin salah dianggap sebagai kebisingan, yang dapat menyebabkan beberapa ucapan disaring. Ini adalah parameter konfigurasi lanjutan. Penyesuaian dapat memengaruhi hasil pengenalan secara signifikan. Rekomendasi: Uji dan verifikasi hasil secara menyeluruh sebelum menyesuaikan. Atur dengan kenaikan kecil berdasarkan lingkungan audio aktual (langkah 0.1 direkomendasikan). Atur `speech_noise_threshold` melalui metode `parameter` atau metode `parameters` dari instans `RecognitionParam`: `RecognitionParam param = RecognitionParam.builder() .model("fun-asr-realtime") .format("pcm") .sampleRate(16000) .parameter("speech_noise_threshold", -0.5) .build();`
`special_word_filter`	`String`	Tidak	Menentukan kata sensitif yang akan diproses selama pengenalan ucapan, dan mendukung pengaturan metode pemrosesan berbeda untuk kata sensitif berbeda. Untuk detailnya, lihat Penyaringan kata sensitif.Atur `special_word_filter` melalui metode `parameter` atau metode `parameters` dari instans `RecognitionParam`: // 1. Bangun objek terluar JSONObject root = new JSONObject(); root.put("system_reserved_filter", true); // 2. Bangun konfigurasi "hapus sepenuhnya dari hasil" JSONObject root1 = new JSONObject(); JSONArray array1 = new JSONArray(); array1.put("start"); array1.put("proceed"); root1.put("word_list", array1); // 3. Bangun konfigurasi "ganti dengan * sepanjang karakter" JSONObject root2 = new JSONObject(); JSONArray array2 = new JSONArray(); array2.put("test"); root2.put("word_list", array2); // 4. Rakit root.put("filter_with_empty", root1); root.put("filter_with_signed", root2); RecognitionParam param = RecognitionParam.builder() .model("fun-asr-realtime") .format("pcm") .sampleRate(16000) .parameter("special_word_filter", root.toString()) .build();
`input`	Map<String, Object>	Tidak	Objek input yang memasukkan konteks percakapan. Konteks membantu pengenalan dan meningkatkan akurasi pengenalan istilah khusus. Untuk penggunaan, lihat Mulai cepat. Hanya model `fun-asr-realtime`, `fun-asr-realtime-2025-11-07` yang mendukung parameter konteks. Map harus berisi kunci `context` yang nilainya adalah array pesan bertipe `List<Map<String, Object>>`. Setiap pesan berisi bidang berikut: `role` (String, wajib): peran pesan. `user` menunjukkan hasil pengenalan ucapan pengguna dari putaran sebelumnya atau daftar kata khusus domain. `assistant` menunjukkan balasan model bahasa besar dari putaran sebelumnya. `content` (List<Map>, wajib): daftar konten pesan. Setiap elemen berisi `type` (String; diatur ke `input_text` ketika role adalah user, dan `text` ketika role adalah assistant) dan `text` (String, konten teks). Batasan: pesan konteks bertipe `input_text` dan `text` masing-masing dibatasi hingga 5; 5 pesan terbaru dipertahankan ketika batas terlampaui. Panjang total teks per putaran konteks tidak boleh melebihi 400 karakter, dan kelebihannya dipotong dari akhir. Ketika Anda memasukkan konteks, pesan dalam `context` harus mengikuti urutan tertentu: pesan konteks harus diatur berdasarkan putaran percakapan, dan dalam setiap putaran pesan `user` (`input_text`) harus mendahului pesan `assistant` (`text`) yang sesuai. Untuk menggunakan bidang ini, versi SDK harus 2.22.23 atau lebih baru. Atur `input` melalui metode `input` dari instans `RecognitionParam`: // 1. Bangun struktur input Map<String, Object> userContent = new HashMap<>(); userContent.put("type", "input_text"); userContent.put("text", "Hello there"); Map<String, Object> assistantContent = new HashMap<>(); assistantContent.put("type", "text"); assistantContent.put("text", "Hello, I am Qwen. How can I help you?"); Map<String, Object> userMessage = new HashMap<>(); userMessage.put("role", "user"); userMessage.put("content", Arrays.asList(userContent)); Map<String, Object> assistantMessage = new HashMap<>(); assistantMessage.put("role", "assistant"); assistantMessage.put("content", Arrays.asList(assistantContent)); Map<String, Object> input = new HashMap<>(); input.put("context", Arrays.asList(userMessage, assistantMessage)); // 2. Masukkan melalui metode input RecognitionParam param = RecognitionParam.builder() .model("fun-asr-realtime") .format("pcm") .sampleRate(16000) .input(input) .build();
`apiKey`	`String`	Tidak	Kunci API Anda.

Antarmuka utama

Kelas `Recognition`

Impor Recognition dengan import com.alibaba.dashscope.audio.asr.recognition.Recognition;. Antarmuka utamanya sebagai berikut:

Antarmuka/Metode	Parameter	Nilai kembali	Deskripsi
`public void call(RecognitionParam param, final ResultCallback<RecognitionResult> callback)`	`param`: Parameter permintaan `callback`: Antarmuka callback (ResultCallback)	Tidak ada	Pengenalan real-time streaming berbasis callback. Metode ini tidak memblokir thread saat ini.
`public String call(RecognitionParam param, File file)`	`param`: Parameter permintaan `file`: File audio yang akan dikenali.	Hasil pengenalan.	Pengenalan non-streaming file lokal. Metode ini memblokir thread saat ini hingga seluruh file audio dibaca. File harus dapat dibaca.
`public Flowable<RecognitionResult> streamCall(RecognitionParam param, Flowable<ByteBuffer> audioFrame)`	`param`: Parameter permintaan `audioFrame`: Instans `Flowable<ByteBuffer>`.	`Flowable<RecognitionResult>`	Pengenalan real-time streaming berbasis Flowable.
`public void sendAudioFrame(ByteBuffer audioFrame)`	`audioFrame`: Aliran audio biner bertipe `ByteBuffer`.	Tidak ada	Mengirim audio. Pertahankan ukuran setiap chunk audio yang dikirim dalam batas wajar. Ukuran chunk yang direkomendasikan berisi sekitar 100 ms audio dan berukuran 1 KB hingga 16 KB.Hasil pengenalan dikirim melalui metode onEvent dari Antarmuka callback (ResultCallback).
`public void stop()`	Tidak ada	Tidak ada	Menghentikan pengenalan real-time.Metode ini memblokir thread saat ini hingga callback `ResultCallback` memanggil `onComplete` atau `onError`.
`boolean getDuplexApi().close(int code, String reason)`	code: Kode penutupan WebSocket.reason: Alasan penutupan.Untuk panduan mengatur dua parameter ini, lihat Protokol WebSocket.	true	Setelah tugas berakhir, selalu tutup koneksi WebSocket, baik terjadi kesalahan maupun tidak, untuk menghindari kebocoran koneksi. Untuk menggunakan kembali koneksi demi efisiensi yang lebih baik, lihat Optimalkan pengenalan ucapan real-time Paraformer untuk konkurensi tinggi.
`public String getLastRequestId()`	Tidak ada	requestId	Mendapatkan requestId tugas saat ini. Tersedia setelah tugas baru dimulai dengan `call` atau `streamingCall`. Metode ini tersedia hanya di versi SDK 2.18.0 dan lebih baru.
`public long getFirstPackageDelay()`	Tidak ada	Latensi paket pertama.	Mendapatkan latensi paket pertama, yaitu penundaan dari pengiriman paket audio pertama hingga menerima hasil pengenalan pertama. Gunakan setelah tugas selesai. Metode ini tersedia hanya di versi SDK 2.18.0 dan lebih baru.
`public long getLastPackageDelay()`	Tidak ada	Latensi paket terakhir.	Mendapatkan latensi paket terakhir, yaitu waktu dari pengiriman perintah `stop` hingga menerima hasil pengenalan akhir. Gunakan setelah tugas selesai. Metode ini tersedia hanya di versi SDK 2.18.0 dan lebih baru.

Antarmuka callback (`ResultCallback`)

Selama panggilan streaming dua arah, server mengembalikan informasi dan data proses penting ke klien melalui callback. Implementasikan metode callback untuk menangani informasi atau data yang dikembalikan oleh server. Implementasikan metode callback dengan memperluas kelas abstrak ResultCallback. Saat memperluas kelas ini, Anda dapat mengatur tipe generik ke RecognitionResult. RecognitionResult membungkus struktur data yang dikembalikan oleh server. Karena Java mendukung penggunaan kembali koneksi, tidak ada onClose atau onOpen.

ResultCallback<RecognitionResult> callback = new ResultCallback<RecognitionResult>() {
    @Override
    public void onEvent(RecognitionResult result) {
        System.out.println("RequestId: " + result.getRequestId());
        // Tambahkan logika Anda untuk memproses hasil pengenalan ucapan di sini.
    }

    @Override
    public void onComplete() {
        System.out.println("Tugas selesai");
    }

    @Override
    public void onError(Exception e) {
        System.out.println("Tugas gagal: " + e.getMessage());
    }
};

Antarmuka/Metode	Parameter	Nilai kembali	Deskripsi
`public void onEvent(RecognitionResult result)`	`result`: Hasil pengenalan real-time (RecognitionResult)	Tidak ada	Dipanggil ketika server mengirim respons.
`public void onComplete()`	Tidak ada	Tidak ada	Dipanggil setelah tugas selesai.
`public void onError(Exception e)`	`e`: Informasi pengecualian.	Tidak ada	Dipanggil ketika terjadi pengecualian.

Respons

Hasil pengenalan real-time (RecognitionResult)

RecognitionResult merepresentasikan hasil dari satu pengenalan real-time.

Antarmuka/Metode	Parameter	Nilai kembali	Deskripsi
`public String getRequestId()`	Tidak ada	requestId	Mendapatkan requestId.
`public boolean isSentenceEnd()`	Tidak ada	Apakah kalimat lengkap telah terbentuk, yaitu apakah batas kalimat terdeteksi.	Menentukan apakah kalimat yang diberikan telah berakhir.
`public Sentence getSentence()`	Tidak ada	Informasi kalimat (Sentence)	Mendapatkan informasi kalimat, termasuk timestamp dan teks.

Informasi kalimat (`Sentence`)

Antarmuka/Metode	Parameter	Nilai kembali	Deskripsi
`public Long getBeginTime()`	Tidak ada	Waktu mulai kalimat, dalam ms.	Mengembalikan waktu mulai kalimat.
`public Long getEndTime()`	Tidak ada	Waktu akhir kalimat, dalam ms.	Mengembalikan waktu akhir kalimat.
`public String getText()`	Tidak ada	Teks yang dikenali.	Mengembalikan teks yang dikenali.
`public List<Word> getWords()`	Tidak ada	Daftar objek Informasi timestamp tingkat kata (Word).	Mengembalikan informasi timestamp tingkat kata.

Informasi timestamp tingkat kata (Word)

Antarmuka/Metode	Parameter	Nilai kembali	Deskripsi
`public long getBeginTime()`	Tidak ada	Waktu mulai kata, dalam ms.	Mengembalikan waktu mulai kata.
`public long getEndTime()`	Tidak ada	Waktu akhir kata, dalam ms.	Mengembalikan waktu akhir kata.
`public String getText()`	Tidak ada	Kata.	Mengembalikan kata yang dikenali.
`public String getPunctuation()`	Tidak ada	Tanda baca.	Mengembalikan tanda baca.

Kode kesalahan

Jika Anda mengalami kesalahan, lihat Kode kesalahan untuk troubleshooting. Jika masalah berlanjut, bergabunglah dengan komunitas developer untuk melaporkan masalah Anda dan berikan Request ID untuk investigasi lebih lanjut.

FAQ

Fitur

T: Bagaimana cara menjaga koneksi ke server tetap aktif selama periode diam yang panjang?

Atur parameter permintaan heartbeat ke true, dan terus kirim audio diam ke server. Audio diam adalah audio yang tidak mengandung sinyal suara dalam file atau aliran data. Anda dapat menghasilkan audio diam dengan beberapa cara, misalnya dengan menggunakan perangkat lunak pengeditan audio seperti Audacity atau Adobe Audition, atau alat command-line seperti FFmpeg.

T: Bagaimana cara mengonversi audio ke format yang didukung?

Gunakan alat FFmpeg. Untuk penggunaan lebih lanjut, lihat situs resmi FFmpeg.

# Perintah konversi dasar (templat universal)
# -i, tujuan: path file input, contoh nilai: audio.wav
# -c:a, tujuan: penyandi audio, contoh nilai: aac, libmp3lame, pcm_s16le
# -b:a, tujuan: bitrate (kontrol kualitas audio), contoh nilai: 192k, 320k
# -ar, tujuan: laju sampel, contoh nilai: 44100 (CD), 48000, 16000
# -ac, tujuan: jumlah saluran, contoh nilai: 1 (mono), 2 (stereo)
# -y, tujuan: timpa file yang ada (tidak perlu nilai)
ffmpeg -i input_audio.ext -c:a encoder_name -b:a bitrate -ar sample_rate -ac channels output.ext

# Contoh: WAV -> MP3 (pertahankan kualitas asli)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3
# Contoh: MP3 -> WAV (format standar PCM 16-bit)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 44100 -ac 2 output.wav
# Contoh: M4A -> AAC (ekstrak/konversi audio Apple)
ffmpeg -i input.m4a -c:a copy output.aac  # Ekstrak langsung tanpa re-encoding
ffmpeg -i input.m4a -c:a aac -b:a 256k output.aac  # Re-encode untuk kualitas lebih tinggi
# Contoh: FLAC lossless -> Opus (kompresi tinggi)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on output.opus

T: Bagaimana cara mengenali file lokal (rekaman)?

Ada dua cara untuk mengenali file lokal:

Masukkan path file lokal secara langsung: pendekatan ini hanya mengembalikan hasil pengenalan lengkap setelah pengenalan selesai, sehingga tidak cocok untuk skenario yang memerlukan umpan balik segera. Lihat Panggilan sinkron, dan masukkan path file ke metode call dari Kelas Recognition untuk mengenali rekaman secara langsung.
Konversi file lokal ke aliran biner untuk pengenalan: pendekatan ini mengenali file dan mengalirkan hasil secara bersamaan, yang cocok untuk skenario yang memerlukan umpan balik segera.
- Lihat Panggilan streaming dua arah: berbasis callback, dan kirim aliran biner ke server untuk pengenalan melalui metode sendAudioFrame dari Kelas Recognition.
- Lihat Panggilan streaming dua arah: berbasis Flowable, dan kirim aliran biner ke server untuk pengenalan melalui metode streamCall dari Kelas Recognition.

Troubleshooting

T: Mengapa ucapan tidak dapat dikenali (tidak ada hasil pengenalan)?

Periksa bahwa format audio (format) dan laju sampel (sampleRate/sample_rate) dalam parameter permintaan benar dan memenuhi batasan parameter. Kesalahan umum meliputi:
- File audio memiliki ekstensi .wav tetapi sebenarnya dalam format MP3, sedangkan parameter permintaan format diatur ke mp3 (pengaturan parameter salah).
- Laju sampel audio adalah 3600 Hz, tetapi parameter permintaan sampleRate/sample_rate diatur ke 48000 (pengaturan parameter salah).
Gunakan alat ffprobe untuk mendapatkan informasi tentang kontainer, kodek, laju sampel, saluran, dan lainnya tentang audio:

ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx

Periksa bahwa bahasa yang diatur dalam language_hints sesuai dengan bahasa aktual audio. Misalnya, audio sebenarnya dalam bahasa Mandarin, tetapi language_hints diatur ke en (Inggris).
Jika tidak ada masalah yang ditemukan dari pemeriksaan di atas, konfigurasikan kata panas khusus untuk meningkatkan pengenalan istilah tertentu.

​Prasyarat

​Mulai cepat

​Panggilan konkurensi tinggi

​Parameter permintaan

​Antarmuka utama

​Kelas Recognition

​Antarmuka callback (ResultCallback)

​Respons

​Hasil pengenalan real-time (RecognitionResult)

​Informasi kalimat (Sentence)

​Informasi timestamp tingkat kata (Word)

​Kode kesalahan

​FAQ

​Fitur

​T: Bagaimana cara menjaga koneksi ke server tetap aktif selama periode diam yang panjang?

​T: Bagaimana cara mengonversi audio ke format yang didukung?

​T: Bagaimana cara mengenali file lokal (rekaman)?

​Troubleshooting

​T: Mengapa ucapan tidak dapat dikenali (tidak ada hasil pengenalan)?

Prasyarat

Mulai cepat

Panggilan konkurensi tinggi

Parameter permintaan

Antarmuka utama

Kelas `Recognition`

Antarmuka callback (`ResultCallback`)

Respons

Hasil pengenalan real-time (RecognitionResult)

Informasi kalimat (`Sentence`)

Informasi timestamp tingkat kata (Word)

Kode kesalahan

FAQ

Fitur

T: Bagaimana cara menjaga koneksi ke server tetap aktif selama periode diam yang panjang?

T: Bagaimana cara mengonversi audio ke format yang didukung?

T: Bagaimana cara mengenali file lokal (rekaman)?

Troubleshooting

T: Mengapa ucapan tidak dapat dikenali (tidak ada hasil pengenalan)?