Event klien untuk layanan pengenalan ucapan real-time Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime - Alibaba Cloud Model Studio

Topik ini menjelaskan event klien yang dikirim oleh klien ke server melalui WebSocket dalam layanan pengenalan ucapan real-time Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime, termasuk struktur data dan definisi bidang untuk run-task (memulai tugas), dan finish-task (mengakhiri tugas).

Panduan pengguna: Untuk deskripsi model dan panduan pemilihan, lihat Speech-to-text.

Alur interaksi event: Untuk urutan interaksi event, lihat WebSocket API.

run-task

Deskripsi: Memulai tugas pengenalan ucapan dan menetapkan parameter seperti model, format audio, dan laju sampel.

Kapan mengirim: Kirim segera setelah koneksi WebSocket terbentuk.

Event respons: Anda hanya dapat mengirim audio setelah server mengembalikan event task-started.

headerobject(Wajib)

Properti

actionstring(Wajib)

Jenis perintah. Tetapkan ke run-task.

task_idstring(Wajib)

ID tugas yang dihasilkan klien (format UUID) yang menghubungkan event berikutnya dengan tugas ini.

streamingstring(Wajib)

Tetapkan ke duplex.

payloadobject(Wajib)

Properti

task_groupstring(Wajib)

Grup tugas. Tetapkan ke audio.

taskstring(Wajib)

Jenis tugas. Tetapkan ke asr.

functionstring(Wajib)

Jenis fungsi. Tetapkan ke recognition.

modelstring(Wajib)

Nama model. Didukung seri model Qwen-Audio-3.0-ASR-Flash-Streaming dan Fun-ASR-Realtime. Untuk detail selengkapnya, lihat Model dan wilayah yang didukung.

inputobject(Wajib)

Objek input. Berikan {} jika tidak ada konteks yang disediakan.

PentingHanya model qwen-audio-3.0-asr-flash-streaming, fun-asr-realtime, dan fun-asr-realtime-2025-11-07 yang mendukung konteks.

Properti

contextarray(object)(Opsional)

Konteks percakapan meningkatkan akurasi pengenalan untuk kosakata spesifik domain. Untuk detail penggunaan, lihat Peningkatan konteks.

PentingBatasan: Anda dapat memberikan maksimal 5 pesan konteks untuk setiap jenis (input_text dan text). Jika melebihi batas ini, hanya 5 pesan terbaru yang dipertahankan. Panjang total teks per giliran (panjang gabungan bidang text dari pesan user dan assistant) tidak boleh melebihi 400 karakter (dihitung per karakter, masing-masing karakter dihitung sebagai 1). Teks yang melebihi batas ini akan dipotong dari bagian akhir.

PentingSaat menyediakan konteks, pesan dalam context harus mengikuti urutan tertentu. Pesan konteks harus diatur berdasarkan giliran percakapan, dan dalam setiap giliran pesan user (bertipe input_text) harus mendahului pesan assistant yang sesuai (bertipe text).

Properti

rolestring(Wajib)

Peran pesan. Nilai yang valid:

user: Hasil pengenalan dari giliran ucapan pengguna sebelumnya, atau daftar kata spesifik domain.
assistant: Tanggapan dari model bahasa besar pada giliran sebelumnya.

contentarray(object)(Wajib)

Daftar konten pesan.

Properti

typestring(Wajib)

Jenis konten. Nilai yang valid:

input_text: Hasil pengenalan dari giliran ucapan pengguna sebelumnya, atau daftar kata spesifik domain (digunakan saat role adalah user). Anda juga harus menyediakan bidang text.
text: Tanggapan dari model bahasa besar pada giliran sebelumnya (digunakan saat role adalah assistant). Anda juga harus menyediakan bidang text.

textstring(Wajib)

Isi teks. Saat type bernilai input_text, masukkan hasil pengenalan dari giliran ucapan pengguna sebelumnya atau daftar kata spesifik domain. Saat type bernilai text, masukkan tanggapan dari model bahasa besar pada giliran sebelumnya.

parametersobject(Wajib)

Parameter pengenalan ucapan.

Properti

formatstring(Wajib)

Format audio.

Nilai yang valid:

pcm
wav
mp3
opus
speex
aac
amr

Pentingopus/speex: Harus menggunakan enkapsulasi Ogg.

wav: Harus menggunakan encoding PCM.

amr: Hanya tipe AMR-NB yang didukung.

sample_rateinteger(Wajib)

Laju sampel, dalam Hz.

Nilai yang valid: Model 8 kHz hanya mendukung 8000 Hz; model lain mendukung laju sampel apa pun.

vocabulary_idstring(Opsional)

ID daftar kata kunci yang telah dikompilasi sebelumnya.

Hasilkan ID ini terlebih dahulu dengan memanggil API pembuatan daftar kata kunci. Berikan ID tersebut selama pengenalan untuk menggunakan kata kunci dalam daftar.

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 kunci yang telah dikompilasi.

vocabularyobject(Opsional)

Kata kunci instan.

Diberikan sebagai pasangan kunci-nilai, di mana kunci adalah teks kata kunci (string) dan nilai adalah bobot kata kunci (integer). Tidak perlu membuat daftar kata kunci terlebih dahulu. Bobot berkisar antara [1, 5] atau ditetapkan ke 50: nilai dalam [1, 5] membuat model lebih cenderung mengeluarkan kata tersebut seiring peningkatan nilainya; nilai 50 menunjukkan kata kunci super, yang sangat meningkatkan recall, tetapi jumlah kata kunci super tidak boleh melebihi 50.

Cocok untuk optimasi kata kunci sementara tingkat sesi.

Jika dikonfigurasi bersama kata kunci yang telah dikompilasi, hanya kata kunci instan yang berlaku. Untuk detail penggunaannya, lihat tautan tersebut.

PentingHanya qwen-audio-3.0-asr-flash-streaming yang mendukung kata kunci instan.

language_hintsarray[string](Opsional)

Bahasa audio yang akan dikenali. Tidak ada nilai default; jika tidak ditetapkan, model akan mendeteksi bahasa secara otomatis.

Untuk seri model Qwen-Audio-3.0-ASR-Flash-Streaming, Anda dapat menetapkan hingga 4 nilai; jika lebih dari 4, hanya 4 nilai pertama yang berlaku. Untuk seri model Fun-ASR-Realtime, Anda hanya dapat menetapkan 1 nilai; jika menetapkan beberapa nilai, hanya nilai pertama yang berlaku.

Klik untuk melihat kode bahasa yang didukung

qwen-audio-3.0-asr-flash-streaming, 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

semantic_punctuation_enabledboolean(Opsional)

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.

max_sentence_silenceinteger(Opsional)

Ambang batas diam VAD untuk segmentasi, dalam ms. Ketika keheningan setelah segmen ucapan melebihi ambang batas ini, sistem menentukan bahwa kalimat telah berakhir. Saat semantic_punctuation_enabled diatur ke true, parameter ini tidak digunakan sebagai kriteria untuk mengembalikan sentence_end, tetapi pengaturannya terlalu rendah dapat memengaruhi kinerja pengenalan.

Nilai default: 1300.

Nilai yang valid: [200, 6000].

multi_threshold_mode_enabledboolean(Opsional)

PentingHanya berlaku saat semantic_punctuation_enabled bernilai false.

Apakah mode multi-ambang batas diaktifkan. Saat diaktifkan, ini mencegah segmen VAD menjadi terlalu panjang.

Nilai default: false.

heartbeatboolean(Opsional)

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 audio atau aliran data yang tidak mengandung sinyal suara. Anda dapat menghasilkan audio diam dengan beberapa cara, seperti menggunakan perangkat lunak pengedit audio seperti Audacity atau Adobe Audition, atau menggunakan alat command-line seperti FFmpeg.

speech_noise_thresholdfloat(Opsional)

Ambang batas untuk membedakan ucapan dari kebisingan, digunakan untuk menyesuaikan sensitivitas Voice Activity Detection (VAD).

Nilai yang 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 sebagian ucapan difilter.

Ini adalah parameter konfigurasi lanjutan. Penyesuaian dapat berdampak signifikan pada hasil pengenalan. Rekomendasi:

Uji dan verifikasi hasil secara menyeluruh sebelum menyesuaikan.
Lakukan penyesuaian secara bertahap berdasarkan lingkungan audio aktual (langkah 0.1 direkomendasikan).

special_word_filter string(Opsional)

Menentukan kata sensitif yang akan diproses selama pengenalan ucapan serta mendukung pengaturan metode pemrosesan berbeda untuk setiap kata sensitif. Untuk detailnya, lihat Penyaringan kata sensitif.

Permintaan dasar

{
    "header": {
        "action": "run-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "task_group": "audio",
        "task": "asr",
        "function": "recognition",
        "model": "qwen-audio-3.0-asr-flash-streaming",
        "parameters": {
            "format": "pcm",
            "sample_rate": 16000
        },
        "input": {}
    }
}

Dengan konteks

{
    "header": {
        "action": "run-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "task_group": "audio",
        "task": "asr",
        "function": "recognition",
        "model": "qwen-audio-3.0-asr-flash-streaming",
        "parameters": {
            "format": "pcm",
            "sample_rate": 16000
        },
        "input": {
            "context": [
                {
                    "role": "user",
                    "content": [
                        {
                            "type": "input_text",
                            "text": "Hello there"
                        }
                    ]
                },
                {
                    "role": "assistant",
                    "content": [
                        {
                            "type": "text",
                            "text": "Hello, I am Qwen. How can I help you?"
                        }
                    ]
                }
            ]
        }
    }
}

Kata kunci instan

{
    "header": {
        "action": "run-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "task_group": "audio",
        "task": "asr",
        "function": "recognition",
        "model": "qwen-audio-3.0-asr-flash-streaming",
        "parameters": {
            "format": "pcm",
            "sample_rate": 16000,
            "vocabulary": {"John Smith": 5, "Jane Doe": 5}
        },
        "input": {}
    }
}

continue-task

Deskripsi: Memperbarui konteks percakapan selama eksekusi tugas untuk meningkatkan pengenalan.

Kapan mengirim: Kirim selama eksekusi tugas saat Anda perlu memperbarui konteks percakapan.

PentingHanya model qwen-audio-3.0-asr-flash-streaming, fun-asr-realtime, dan fun-asr-realtime-2025-11-07 yang mendukung event ini.

headerobject(Wajib)

Properti

actionstring(Wajib)

Jenis perintah. Tetapkan ke continue-task.

task_idstring(Wajib)

ID tugas yang dihasilkan klien (dalam format UUID) harus sesuai dengan task_id dalam event run-task.

streamingstring(Wajib)

Tetapkan ke duplex.

payloadobject(Wajib)

Properti

inputobject(Wajib)

Objek input.

Properti

context _array(object)_ (Opsional) Konteks percakapan yang meningkatkan akurasi pengenalan terhadap kosakata spesifik domain. Untuk detail penggunaan, lihat Quick start.

PentingBatasan: Anda dapat memberikan maksimal 5 pesan konteks untuk setiap jenis (input_text dan text). Jika melebihi batas ini, hanya 5 pesan terbaru yang dipertahankan. Panjang total teks per giliran (panjang gabungan bidang text dari pesan user dan assistant) tidak boleh melebihi 400 karakter (dihitung per karakter, masing-masing karakter dihitung sebagai 1). Teks yang melebihi batas ini akan dipotong dari bagian akhir.

Properti

user: Hasil pengenalan dari giliran ucapan pengguna sebelumnya atau daftar kata spesifik domain.

assistant: Tanggapan dari model bahasa besar pada giliran sebelumnya.

content array(object) (Wajib) Daftar isi pesan.

input_text: Hasil pengenalan dari giliran ucapan pengguna sebelumnya atau daftar kata spesifik domain (digunakan saat role adalah user). Anda juga harus menyediakan bidang text.

text: Tanggapan dari model bahasa besar pada giliran sebelumnya (digunakan saat role adalah assistant). Anda juga harus menyediakan bidang text.

text string (Wajib) Isi teks. Saat type bernilai input_text, masukkan hasil pengenalan dari giliran ucapan pengguna sebelumnya atau daftar kata spesifik domain. Saat type bernilai text, masukkan tanggapan dari model bahasa besar pada giliran sebelumnya.

{
    "header": {
        "action": "continue-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "input": {
            "context": [
                {
                    "role": "user",
                    "content": [
                        {
                            "type": "input_text",
                            "text": "Hello there"
                        }
                    ]
                },
                {
                    "role": "assistant",
                    "content": [
                        {
                            "type": "text",
                            "text": "Hello, I am Qwen. How can I help you?"
                        }
                    ]
                }
            ]
        }
    }
}

finish-task

Deskripsi: Memberi tahu server bahwa semua audio telah dikirim dan meminta untuk mengakhiri tugas.

Kapan mengirim: Kirim setelah semua data audio dikirim.

Event respons: Server mengembalikan event task-finished.

headerobject(Wajib)

Properti

actionstring(Wajib)

Jenis perintah. Tetapkan ke finish-task.

task_idstring(Wajib)

ID tugas yang dihasilkan klien (format UUID) dan harus sesuai dengan task_id dalam event run-task.

streamingstring(Wajib)

Tetapkan ke duplex.

payloadobject(Wajib)

Properti

inputobject(Wajib)

Tetapkan ke {}.

{
    "header": {
        "action": "finish-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "input": {}
    }
}