Skip to main content
Fun-ASR-Realtime

Fun-ASR-Realtime Python SDK

Topik ini menjelaskan parameter dan antarmuka Python SDK untuk model pengenalan ucapan real-time Fun-ASR-Realtime.

Prasyarat

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

Mulai cepat

Kelas Recognition menyediakan antarmuka untuk panggilan non-streaming maupun streaming dua arah. Pilih metode panggilan yang sesuai dengan kebutuhan Anda:
  • Panggilan non-streaming: Mengenali file lokal dan mengembalikan hasil lengkap dalam satu respons. Cocok untuk memproses audio yang telah direkam sebelumnya.
  • Panggilan streaming dua arah: Mengenali aliran audio secara langsung dan menghasilkan hasil secara real-time. Aliran audio dapat berasal dari perangkat eksternal seperti mikrofon atau dibaca dari file lokal. Cocok untuk skenario yang memerlukan umpan balik segera.
  • Panggilan non-streaming
  • Panggilan streaming dua arah
Kirim satu tugas pengenalan ucapan real-time dan dapatkan hasil pengenalan secara sinkron dengan memasukkan file lokal.Buat instans dari kelas Recognition, ikat Parameter permintaan, lalu panggil call untuk menjalankan pengenalan atau terjemahan dan mendapatkan Hasil pengenalan (RecognitionResult) akhir.
from http import HTTPStatus
import dashscope
from dashscope.audio.asr import Recognition
import os

# 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: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# Berikut adalah konfigurasi untuk wilayah Singapura. Saat memanggil, ganti "{WorkspaceId}" dengan ID ruang kerja Anda yang sebenarnya. Konfigurasi berbeda berdasarkan wilayah.
dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'

recognition = Recognition(model='fun-asr-realtime',
                          format='wav',
                          sample_rate=16000,
                          callback=None)
result = recognition.call('{YOUR_AUDIO_FILE}')
if result.status_code == HTTPStatus.OK:
    print('Hasil pengenalan:')
    print(result.get_sentence())
else:
    print('Error: ', result.message)

print(
    '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
    .format(
        recognition.get_last_request_id(),
        recognition.get_first_package_delay(),
        recognition.get_last_package_delay(),
    ))

Parameter permintaan

Atur parameter permintaan melalui konstruktor (init) dari kelas Recognition.
ParameterTipeWajibDeskripsi
modelstrYaNama model.
sample_rateintYaLaju sampel, dalam Hz.Nilai valid: model 8 kHz hanya mendukung 8000 Hz; model lain mendukung laju sampel apa pun.
formatstrYaFormat 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.
vocabulary_idstrTidakID daftar kata kunci panas yang telah dikompilasi sebelumnya.Hasilkan ID ini terlebih dahulu dengan memanggil API pembuatan daftar kata kunci panas. Masukkan ID ini selama pengenalan untuk menggunakan kata-kata 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 kunci panas yang telah dikompilasi.
semantic_punctuation_enabledboolTidakApakah segmentasi semantik diaktifkan.Default: False.
  • True: Mengaktifkan segmentasi semantik dan menonaktifkan segmentasi VAD.
  • False (default): Mengaktifkan segmentasi VAD dan menonaktifkan segmentasi semantik.
Segmentasi semantik lebih akurat dan cocok untuk transkripsi rapat. Segmentasi VAD (Voice Activity Detection) memiliki latensi lebih rendah dan cocok untuk skenario interaktif.
max_sentence_silenceintTidakAmbang batas keheningan 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 performa pengenalan.Nilai default: 1300.Nilai valid: [200, 6000].
multi_threshold_mode_enabledboolTidak
Hanya berlaku ketika semantic_punctuation_enabled bernilai false.
Apakah mode multi-ambang batas diaktifkan. Saat diaktifkan, mencegah segmentasi VAD menghasilkan segmen yang terlalu panjang.Default: False.
punctuation_prediction_enabledboolTidakApakah tanda baca ditambahkan secara otomatis ke hasil pengenalan:
  • True (default): Ya. Nilai ini tidak dapat diubah.
heartbeatboolTidakApakah paket heartbeat diaktifkan.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 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 pengeditan audio seperti Audacity atau Adobe Audition, atau menggunakan alat command-line seperti FFmpeg.Field ini memerlukan SDK versi 1.23.1 atau lebih baru.
language_hintslist[str]TidakBahasa 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.
  • 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
speech_noise_thresholdfloatTidakAmbang batas untuk membedakan ucapan dari kebisingan, digunakan untuk menyesuaikan sensitivitas Voice Activity Detection (VAD).Nilai valid: [-1.0, 1.0].Deskripsi nilai:
  • Semakin mendekati -1: Ambang batas kebisingan menurun, sehingga kebisingan lebih mungkin dikenali sebagai ucapan, yang dapat menyebabkan lebih banyak kebisingan ditranskripsikan.
  • Semakin mendekati +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_filterstrTidakMenentukan kata sensitif yang akan diproses selama pengenalan ucapan, dan mendukung pengaturan metode pemrosesan berbeda untuk kata sensitif berbeda. Untuk detailnya, lihat Penyaringan kata sensitif.
callbackRecognitionCallbackTidakAntarmuka callback (RecognitionCallback).
Teruskan parameter berikut sebagai argumen kata kunci ke metode call atau start dari instans Recognition.
ParameterTipeWajibDeskripsi
raw_inputdictTidakObjek input yang digunakan untuk meneruskan konteks percakapan. Peningkatan konteks meningkatkan akurasi pengenalan untuk istilah spesifik domain. Untuk penggunaan, lihat Mulai cepat.
Parameter konteks hanya didukung oleh model fun-asr-realtime, fun-asr-realtime, dan fun-asr-realtime-2025-11-07.
Dict harus mencakup kunci context yang nilainya adalah daftar pesan (list[dict]). Setiap pesan berisi bidang berikut:
  • role (str, wajib): Peran pesan. user merepresentasikan hasil pengenalan dari giliran pengguna sebelumnya atau daftar kata spesifik domain. assistant merepresentasikan respons model bahasa besar dari giliran sebelumnya.
  • content (list[dict], wajib): Daftar konten pesan. Setiap elemen berisi type (str; diatur ke input_text saat role adalah user, dan text saat role adalah assistant) dan text (str, konten teks).
Batasan: Pesan konteks dengan tipe input_text dan text masing-masing dibatasi hingga 5 pesan. Saat batas terlampaui, hanya 5 pesan terbaru yang dipertahankan. Panjang total teks per giliran konteks tidak boleh melebihi 400 karakter, dan kelebihannya dipotong dari akhir.
Saat Anda meneruskan konteks, pesan dalam context harus mengikuti urutan tertentu: pesan konteks harus diatur berdasarkan giliran percakapan, dan dalam setiap giliran, pesan user (tipe input_text) harus mendahului pesan assistant yang sesuai (tipe text).
Field ini memerlukan SDK versi 1.25.23 atau lebih baru.
Teruskan raw_input ke metode start atau call dari instans Recognition:
# Bangun input untuk diteruskan
      input_context = {
          "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?"
                      }
                  ]
              }
          ]
      }

      # Teruskan melalui parameter raw_input
      recognition.start(raw_input=input_context)
      # Atau
      recognition.call(raw_input=input_context)

Antarmuka utama

Kelas Recognition

Impor Recognition dengan from dashscope.audio.asr import *.
Metode anggotaSignature metodeDeskripsi
call
def call(self, file: str, phrase_id: str = None, **kwargs) -> RecognitionResult
Panggilan non-streaming berbasis file lokal. Metode ini memblokir thread saat ini hingga semua audio dibaca, dan memerlukan izin baca pada file.Hasil pengenalan dikembalikan sebagai objek RecognitionResult.
start
def start(self, phrase_id: str = None, **kwargs)
Memulai pengenalan ucapan.Pengenalan real-time streaming berbasis callback. Metode ini tidak memblokir thread saat ini. Gunakan bersama dengan send_audio_frame dan stop.
send_audio_frame
def send_audio_frame(self, buffer: bytes)
Mendorong audio. Pastikan setiap frame audio yang didorong tidak terlalu besar atau terlalu kecil: sekitar 100 ms per frame, antara 1 KB hingga 16 KB.Hasil pengenalan diperoleh melalui metode on_event dari Antarmuka callback (RecognitionCallback).
stop
def stop(self)
Menghentikan pengenalan ucapan. Memblokir hingga server selesai mengenali semua audio yang diterima, lalu mengakhiri tugas.
get_last_request_id
def get_last_request_id(self)
Mendapatkan request_id. Tersedia setelah konstruktor dipanggil (objek dibuat).
get_first_package_delay
def get_first_package_delay(self)
Mendapatkan delay paket pertama: latensi dari pengiriman paket audio pertama hingga menerima hasil pengenalan pertama. Gunakan setelah tugas selesai.
get_last_package_delay
def get_last_package_delay(self)
Mendapatkan delay paket terakhir: waktu dari pengiriman perintah stop hingga menerima hasil pengenalan terakhir. Gunakan setelah tugas selesai.
get_response
def get_response(self)
Mendapatkan pesan terakhir. Gunakan untuk mengambil error kegagalan tugas.

Antarmuka callback (RecognitionCallback)

Selama panggilan streaming dua arah, server mengembalikan informasi proses utama dan data ke klien melalui callback. Implementasikan metode callback untuk menangani informasi dan data yang dikembalikan oleh server.
class Callback(RecognitionCallback):
    def on_open(self) -> None:
        print('Koneksi terbentuk')

    def on_event(self, result: RecognitionResult) -> None:
        # Implementasikan logika untuk menerima hasil pengenalan
        pass

    def on_complete(self) -> None:
        print('Tugas selesai')

    def on_error(self, result: RecognitionResult) -> None:
        print('Terjadi error:', result)

    def on_close(self) -> None:
        print('Koneksi ditutup')

callback = Callback()
MetodeParameterNilai kembalianDeskripsi
def on_open(self) -> None
NoneNoneDipanggil segera setelah koneksi ke server terbentuk.
def on_event(self, result: RecognitionResult) -> None
result: Hasil pengenalan (RecognitionResult)NoneDipanggil saat server memiliki respons.
def on_complete(self) -> None
NoneNoneDipanggil setelah semua hasil pengenalan dikembalikan.
def on_error(self, result: RecognitionResult) -> None
result: Hasil pengenalan (RecognitionResult)NoneDipanggil saat terjadi error.
def on_close(self) -> None
NoneNoneDipanggil setelah server menutup koneksi.

Respons

Hasil pengenalan (RecognitionResult)

RecognitionResult merepresentasikan hasil dari satu pengenalan real-time dalam panggilan streaming dua arah, atau hasil dari panggilan non-streaming.
Metode anggotaSignature metodeDeskripsi
get_sentence
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]
Mendapatkan kalimat yang dikenali saat ini dan informasi timestamp-nya. Callback mengembalikan satu kalimat, sehingga metode ini mengembalikan Dict[str, Any].Untuk detailnya, lihat Kalimat (Sentence).
get_request_id
def get_request_id(self) -> str
Mendapatkan request_id dari permintaan.
is_sentence_end
@staticmethod
def is_sentence_end(sentence: Dict[str, Any]) -> bool
Menentukan apakah kalimat yang diberikan telah berakhir. Metode ini memeriksa apakah field end_time dalam sentence bernilai None: end_time yang tidak None menunjukkan bahwa kalimat telah berakhir. Panggil sebagai RecognitionResult.is_sentence_end(sentence), di mana sentence adalah dict kalimat tunggal yang dikembalikan oleh get_sentence(), bukan field boolean pada instans Sentence.

Informasi kalimat (Sentence)

Anggota kelas Sentence adalah sebagai berikut:
ParameterTipeDeskripsi
begin_timeintWaktu mulai kalimat, dalam ms.
end_timeintWaktu akhir kalimat, dalam ms.
textstrTeks yang dikenali.
wordsDaftar Informasi timestamp tingkat kata (Word)Informasi timestamp tingkat kata.

Informasi timestamp tingkat kata (Word)

Anggota kelas Word adalah sebagai berikut:
ParameterTipeDeskripsi
begin_timeintWaktu mulai kata, dalam ms.
end_timeintWaktu akhir kata, dalam ms.
textstrKata tersebut.
punctuationstrTanda baca.

Kode error

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

FAQ

Fitur

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

Atur parameter permintaan heartbeat ke true, dan terus kirim audio diam ke server. Audio diam adalah konten dalam file audio atau aliran 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 alat command-line seperti FFmpeg.

T: Bagaimana cara mengonversi audio ke format yang didukung?

Gunakan FFmpeg. Untuk penggunaan lebih lanjut, lihat situs resmi FFmpeg.
# Perintah konversi dasar (templat serbaguna)
# -i, tujuan: path file input, contoh nilai: audio.wav
# -c:a, tujuan: kodek 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 sudah ada (tidak perlu nilai)
ffmpeg -i input_audio.ext -c:a codec_name -b:a bitrate -ar sample_rate -ac channels output.ext

# Contoh: WAV ke MP3 (pertahankan kualitas asli)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3
# Contoh: MP3 ke WAV (format standar PCM 16-bit)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 44100 -ac 2 output.wav
# Contoh: M4A ke AAC (ekstraksi atau konversi audio Apple)
ffmpeg -i input.m4a -c:a copy output.aac  # Ekstraksi langsung tanpa re-encoding
ffmpeg -i input.m4a -c:a aac -b:a 256k output.aac  # Re-encode untuk meningkatkan kualitas
# Contoh: FLAC lossless ke 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:
  • Teruskan path file lokal secara langsung: Cara ini hanya mengembalikan hasil lengkap setelah pengenalan selesai, sehingga tidak cocok untuk skenario yang memerlukan umpan balik segera. Lihat Panggilan non-streaming, dan teruskan path file ke metode call dari kelas Recognition untuk mengenali rekaman secara langsung.
  • Konversi file lokal ke aliran biner untuk pengenalan: Cara ini mengenali file sambil mengalirkan hasil, sehingga cocok untuk skenario yang memerlukan umpan balik segera. Lihat Panggilan streaming dua arah, dan kirim aliran biner ke server untuk pengenalan melalui metode send_audio_frame dari kelas Recognition.

Troubleshooting

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

  1. 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 container, kodek, laju sampel, saluran, dan lainnya dari audio:
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx
  1. Jika tidak ada masalah yang ditemukan dari pemeriksaan di atas, tambahkan kata kunci panas kustom untuk meningkatkan pengenalan istilah tertentu.
Pembuatan Gambar
  • FAQ
Video Generation
Model Dunia
Audio
  • Pembuatan audio
Realtime API
Penyematan Teks
TokenPlan
Model production