Qwen-Audio-ASR-Message Python SDK - Alibaba Cloud Model Studio

Topik ini menjelaskan parameter dan antarmuka Python SDK untuk model pengenalan ucapan real-time Qwen-Audio-ASR-Message.

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.

Instal SDK DashScope versi terbaru.

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

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='qwen-audio-3.1-asr-flash-message',
                          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(),
    ))

Panggilan streaming dua arah

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

Mulai pengenalan ucapan streaming.

Buat instans dari kelas Recognition, ikat Parameter permintaan dan Antarmuka callback (RecognitionCallback), lalu panggil metode start untuk memulai pengenalan ucapan streaming.
Streaming audio.

Panggil metode send_audio_frame dari kelas Recognition dalam loop untuk mengirim aliran audio biner ke server dalam segmen. Aliran tersebut dibaca dari file lokal atau perangkat seperti mikrofon.

Saat audio dikirim, server mengembalikan hasil pengenalan ke klien secara real-time melalui metode on_event dari Antarmuka callback (RecognitionCallback).

Kirim sekitar 100 ms audio per frame, dan pastikan ukuran setiap frame antara 1 KB hingga 16 KB.
Akhiri tugas.

Panggil metode stop dari kelas Recognition untuk mengakhiri pengenalan ucapan.

Metode ini memblokir thread saat ini hingga callback on_complete atau on_error dari Antarmuka callback (RecognitionCallback) dipicu.

Kenali ucapan dari mikrofon

import os
import signal  # untuk penanganan event keyboard (tekan "Ctrl+C" untuk menghentikan perekaman)
import sys

import dashscope
import pyaudio
from dashscope.audio.asr import *

mic = None
stream = None

# Atur parameter perekaman
sample_rate = 16000  # laju sampel (Hz)
channels = 1  # saluran mono
dtype = 'int16'  # tipe data
format_pcm = 'pcm'  # format data audio
block_size = 3200  # jumlah frame per buffer

# Callback pengenalan ucapan real-time
class Callback(RecognitionCallback):
    def on_open(self) -> None:
        global mic
        global stream
        print('RecognitionCallback open.')
        mic = pyaudio.PyAudio()
        stream = mic.open(format=pyaudio.paInt16,
                          channels=1,
                          rate=16000,
                          input=True)

    def on_close(self) -> None:
        global mic
        global stream
        print('RecognitionCallback close.')
        stream.stop_stream()
        stream.close()
        mic.terminate()
        stream = None
        mic = None

    def on_complete(self) -> None:
        print('RecognitionCallback completed.')  # pengenalan selesai

    def on_error(self, message) -> None:
        print('RecognitionCallback task_id: ', message.request_id)
        print('RecognitionCallback error: ', message.message)
        # Hentikan dan tutup aliran audio jika sedang berjalan
        if 'stream' in globals() and stream.active:
            stream.stop()
            stream.close()
        # Keluar dari program secara paksa
        sys.exit(1)

    def on_event(self, result: RecognitionResult) -> None:
        sentence = result.get_sentence()
        if 'text' in sentence:
            print('RecognitionCallback text: ', sentence['text'])
            if RecognitionResult.is_sentence_end(sentence):
                print(
                    'RecognitionCallback sentence end, request_id:%s, usage:%s'
                    % (result.get_request_id(), result.get_usage(sentence)))

def signal_handler(sig, frame):
    print('Ctrl+C ditekan, hentikan pengenalan ...')
    # Hentikan pengenalan
    recognition.stop()
    print('Pengenalan dihentikan.')
    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(),
        ))
    # Keluar dari program secara paksa
    sys.exit(0)

# fungsi utama
if __name__ == '__main__':
    # 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'

    # Buat callback pengenalan
    callback = Callback()

    # Panggil layanan pengenalan dalam mode async, Anda dapat menyesuaikan parameter pengenalan seperti model, format,
    # sample_rate
    recognition = Recognition(
        model='qwen-audio-3.1-asr-flash-message',
        format=format_pcm,
        # 'pcm'、'wav'、'opus'、'speex'、'aac'、'amr', Anda dapat memeriksa format yang didukung di dokumen
        sample_rate=sample_rate,
        callback=callback)

    # Mulai pengenalan
    recognition.start()

    signal.signal(signal.SIGINT, signal_handler)
    print("Tekan 'Ctrl+C' untuk menghentikan perekaman dan pengenalan...")
    # Buat pendengar keyboard hingga "Ctrl+C" ditekan

    while True:
        if stream:
            data = stream.read(3200, exception_on_overflow=False)
            recognition.send_audio_frame(data)
        else:
            break

    recognition.stop()

Kenali file audio lokal

import os
import time
import dashscope
from dashscope.audio.asr import *

# 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'

from datetime import datetime

def get_timestamp():
    now = datetime.now()
    formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
    return formatted_timestamp

class Callback(RecognitionCallback):
    def on_complete(self) -> None:
        print(get_timestamp() + ' Pengenalan selesai')  # pengenalan selesai

    def on_error(self, result: RecognitionResult) -> None:
        print('Task_id pengenalan: ', result.request_id)
        print('Error pengenalan: ', result.message)
        exit(0)

    def on_event(self, result: RecognitionResult) -> None:
        sentence = result.get_sentence()
        if 'text' in sentence:
            print(get_timestamp() + ' Teks RecognitionCallback: ', sentence['text'])
        if RecognitionResult.is_sentence_end(sentence):
            print(get_timestamp() +
                  'Akhir kalimat RecognitionCallback, request_id:%s, usage:%s'
                  % (result.get_request_id(), result.get_usage(sentence)))

callback = Callback()

recognition = Recognition(model='qwen-audio-3.1-asr-flash-message',
                          format='wav',
                          sample_rate=16000,
                          callback=callback)

try:
    audio_data: bytes = None
    f = open("{YOUR_AUDIO_FILE}", 'rb')
    if os.path.getsize("{YOUR_AUDIO_FILE}"):
        # Baca semua data file ke buffer sekaligus
        file_buffer = f.read()
        f.close()
        print("Mulai Pengenalan")
        recognition.start()

        # Kirim 3200 byte dari buffer setiap kali
        buffer_size = len(file_buffer)
        offset = 0
        chunk_size = 3200

        while offset < buffer_size:
            # Hitung ukuran chunk data yang akan dikirim kali ini
            remaining_bytes = buffer_size - offset
            current_chunk_size = min(chunk_size, remaining_bytes)

            # Ekstrak chunk data saat ini dari buffer
            audio_data = file_buffer[offset:offset + current_chunk_size]

            # Kirim frame data audio
            recognition.send_audio_frame(audio_data)
            # Perbarui offset
            offset += current_chunk_size

            # Tambahkan jeda untuk mensimulasikan transmisi real-time
            time.sleep(0.1)

        recognition.stop()
    else:
        raise Exception(
            'File yang diberikan kosong (panjang nol byte)')
except Exception as e:
    raise e

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.

Parameter	Tipe	Wajib	Deskripsi
`model`	`str`	Ya	Nama model.
`sample_rate`	`int`	Ya	Laju sampel dalam Hz. Hanya `16000` yang didukung.
`format`	`str`	Ya	Format audio. Nilai 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.
`keep_dialect`	`bool`	Tidak	Default: `false`, yang mentranskripsikan dialek menjadi bahasa Mandarin standar. Tetapkan ke `true` untuk mempertahankan ungkapan dialek. Teruskan sebagai argumen kata kunci dengan nama yang sama. Parameter ini hanya berlaku pada hasil akhir (`sentence_end=true`) dan tidak didukung pada hasil sementara (`sentence_end=false`).
`vad_model`	`str`	Tidak	Model VAD: `near_meeting_16k` (jarak dekat) atau `far_field_meeting_16k` (jarak jauh, default). Teruskan sebagai argumen kata kunci dengan nama yang sama.
`disfluency_removal_enabled`	`bool`	Tidak	Menentukan apakah kata pengisi difilter dan teks keluaran dirapikan. Default: `false`. Tetapkan ke `true` untuk mengaktifkan. Teruskan sebagai argumen kata kunci dengan nama yang sama.
`intermediate_result_enabled`	`bool`	Tidak	Menentukan apakah hasil streaming sementara dikembalikan. Default: `false`. Tetapkan ke `true` untuk menerimanya. Teruskan sebagai argumen kata kunci dengan nama yang sama.
`vocabulary_id`	`str`	Tidak	ID 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.
`vocabulary`	`dict`	Tidak	Kata kunci panas instan. Diteruskan 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 panas terlebih dahulu. Bobot berkisar antara [1, 5] atau diatur ke 50: nilai dalam [1, 5] membuat model lebih cenderung mengeluarkan kata tersebut seiring peningkatan nilainya; nilai 50 menunjukkan kata kunci super panas, yang sangat meningkatkan recall, tetapi jumlah kata kunci super panas tidak boleh melebihi 50. Cocok untuk optimasi kata kunci panas sementara pada tingkat sesi. Jika dikonfigurasi bersama dengan kata kunci panas yang telah dikompilasi, hanya kata kunci panas instan yang berlaku. Untuk detail penggunaan, lihat Kata kunci panas instan. PentingHanya `qwen-audio-3.1-asr-flash-message` yang mendukung kata kunci panas instan. Contoh: `from dashscope.audio.asr import Recognition vocab = {"John Smith": 5, "Jane Doe": 5} recognition = Recognition( model='qwen-audio-3.1-asr-flash-message', format='wav', sample_rate=16000, vocabulary=vocab, callback=None)`
`language_hints`	`list[str]`	Tidak	Bahasa audio yang akan dikenali. Tidak ada nilai default; jika tidak diatur, model akan mendeteksi bahasa secara otomatis. Anda dapat menetapkan hingga 4 nilai. Jika lebih, hanya 4 nilai pertama yang berlaku. Klik untuk melihat kode bahasa yang didukung 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 Teruskan sebagai argumen kata kunci dengan nama yang sama. Parameter ini hanya berlaku pada hasil akhir (`sentence_end=true`) dan tidak didukung pada hasil sementara (`sentence_end=false`).
`max_sentence_silence`	`int`	Tidak	Ambang keheningan VAD untuk segmentasi, dalam milidetik. Kalimat dianggap selesai jika keheningan setelah ucapan melebihi ambang ini. Default: `800`. Rentang valid: `[200, 6000]`.
`heartbeat`	`bool`	Tidak	Apakah 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.
`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 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).
`callback`	`RecognitionCallback`	Tidak	Antarmuka callback (RecognitionCallback).

Teruskan parameter berikut sebagai argumen kata kunci ke metode call atau start dari instans Recognition.

Parameter Tipe Wajib Deskripsi

Parameter	Tipe	Wajib	Deskripsi
`raw_input`	`dict`	Tidak	Objek input yang digunakan untuk meneruskan konteks percakapan. Peningkatan konteks meningkatkan akurasi pengenalan untuk istilah spesifik domain. Untuk penggunaan, lihat Mulai cepat. PentingParameter konteks hanya didukung oleh model `qwen-audio-3.1-asr-flash-message`. 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). PentingBatasan: 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. PentingSaat 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`). CatatanField 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)`

raw_input

dict

Tidak

Objek input yang digunakan untuk meneruskan konteks percakapan. Peningkatan konteks meningkatkan akurasi pengenalan untuk istilah spesifik domain. Untuk penggunaan, lihat Mulai cepat.

PentingParameter konteks hanya didukung oleh model qwen-audio-3.1-asr-flash-message.

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).

PentingBatasan: 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.

PentingSaat 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).

CatatanField 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 anggota	Signature metode	Deskripsi
`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()

Metode	Parameter	Nilai kembalian	Deskripsi
`def on_open(self) -> None`	`None`	None	Dipanggil segera setelah koneksi ke server terbentuk.
`def on_event(self, result: RecognitionResult) -> None`	`result`: Hasil pengenalan (RecognitionResult)	None	Dipanggil saat server memiliki respons.
`def on_complete(self) -> None`	`None`	None	Dipanggil setelah semua hasil pengenalan dikembalikan.
`def on_error(self, result: RecognitionResult) -> None`	`result`: Hasil pengenalan (RecognitionResult)	None	Dipanggil saat terjadi error.
`def on_close(self) -> None`	`None`	None	Dipanggil 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 anggota Signature metode Deskripsi

Metode anggota	Signature metode	Deskripsi
`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`.

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:

Parameter	Tipe	Deskripsi
`begin_time`	`int`	Waktu mulai kalimat, dalam ms.
`end_time`	`int`	Waktu akhir kalimat, dalam ms.
`text`	`str`	Teks yang dikenali.
`words`	Daftar Informasi timestamp tingkat kata (Word)	Informasi timestamp tingkat kata.

Informasi timestamp tingkat kata (Word)

Anggota kelas Word adalah sebagai berikut:

Parameter	Tipe	Deskripsi
`begin_time`	`int`	Waktu mulai kata, dalam ms.
`end_time`	`int`	Waktu akhir kata, dalam ms.
`text`	`str`	Kata tersebut.
`punctuation`	`str`	Tanda 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)?

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

Jika tidak ada masalah yang ditemukan dari pemeriksaan di atas, tambahkan kata kunci panas kustom untuk meningkatkan pengenalan istilah tertentu.