Alibaba Cloud Model Studio:Python SDK

Parameter dan antarmuka Python SDK untuk pengenalan ucapan real-time Paraformer.

Panduan pengguna: Untuk pengenalan model dan rekomendasi pemilihan, lihat Pengenalan Ucapan Real-time - Fun-ASR/Paraformer.

Prasyarat

Anda telah mengaktifkan layanan dan Mendapatkan API key. Harap Konfigurasikan API key sebagai Variabel lingkungan alih-alih hardcoding di kode Anda untuk mencegah risiko keamanan akibat kebocoran kode.

• Instal SDK DashScope terbaru.

Daftar model

Mulai

Kelas Recognition menyediakan metode untuk panggilan non-streaming dan streaming dua arah. Anda dapat memilih metode yang sesuai berdasarkan kebutuhan Anda:

• Panggilan non-streaming: Mengenali file lokal dan mengembalikan hasil lengkap sekaligus. Cocok untuk memproses audio yang telah direkam sebelumnya.
• Panggilan streaming dua arah: Mengenali aliran audio 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

Metode ini mengirimkan tugas ucapan-ke-teks real-time untuk file lokal. Proses diblokir hingga hasil transkripsi lengkap dikembalikan.

Buat instance kelas Recognition, atur parameter permintaan, dan panggil metode call untuk melakukan pengenalan atau terjemahan serta memperoleh RecognitionResult.

from http import HTTPStatus
from dashscope.audio.asr import Recognition
# Tiongkok (Beijing): Ganti {WorkspaceId} dengan Workspace ID aktual Anda. Konfigurasi berbeda-beda berdasarkan wilayah.
dashscope.base_websocket_api_url = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference"

# Jika Anda belum mengonfigurasi API key dalam variabel lingkungan, hapus komentar baris kode berikut dan ganti apiKey dengan API key Anda.
# import dashscope
# dashscope.api_key = "apiKey"

recognition = Recognition(model='paraformer-realtime-v2',
                          format='wav',
                          sample_rate=16000,
                          # Parameter "language_hints" hanya didukung oleh model paraformer-realtime-v2.
                          language_hints=['zh', 'en'],
                          callback=None)
result = recognition.call('{YOUR_AUDIO_FILE}')
if result.status_code == HTTPStatus.OK:
    sentences = result.get_sentence()
    for sentence in sentences:
        print(sentence['text'])
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

Metode ini mengirimkan tugas ucapan-ke-teks real-time dan mengembalikan hasil pengenalan secara real time melalui antarmuka callback.

1. Mulai pengenalan ucapan streaming

   Buat instance kelas Recognition, ikat parameter permintaan dan antarmuka callback (RecognitionCallback), lalu panggil metode start untuk memulai pengenalan ucapan streaming.

2. Streaming

   Panggil berulang kali metode send_audio_frame dari kelas Recognition untuk mengirim aliran audio biner dari file lokal atau perangkat (seperti mikrofon) ke server dalam segmen-segmen.

   Saat data audio dikirim, server menggunakan metode on_event dari antarmuka callback RecognitionCallback untuk mengembalikan hasil pengenalan ke klien secara real time.

   Kami merekomendasikan durasi setiap segmen audio yang dikirim sekitar 100 milidetik, dengan ukuran data antara 1 KB hingga 16 KB.

3. Akhiri pemrosesan

   Panggil metode stop dari kelas Recognition untuk menghentikan pengenalan ucapan.

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

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 *
# Tiongkok (Beijing): Ganti {WorkspaceId} dengan Workspace ID aktual Anda. Konfigurasi berbeda-beda berdasarkan wilayah.
dashscope.base_websocket_api_url = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference"

mic = None
stream = None

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

def init_dashscope_api_key():
    """
        Tetapkan API-key DashScope Anda. Informasi lebih lanjut:
        https://github.com/aliyun/alibabacloud-bailian-speech-demo/blob/master/PREREQUISITES.md
    """

    if 'DASHSCOPE_API_KEY' in os.environ:
        dashscope.api_key = os.environ[
            'DASHSCOPE_API_KEY']  # muat API-key dari variabel lingkungan DASHSCOPE_API_KEY
    else:
        dashscope.api_key = '<your-dashscope-api-key>'  # tetapkan API-key secara manual

# 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__':
    init_dashscope_api_key()
    print('Menginisialisasi ...')

    # Buat callback pengenalan
    callback = Callback()

    # Panggil layanan pengenalan dengan mode async, Anda dapat menyesuaikan parameter pengenalan, seperti model, format,
    # sample_rate
    recognition = Recognition(
        model='paraformer-realtime-v2',
        format=format_pcm,
        # 'pcm', 'wav', 'opus', 'speex', 'aac', atau 'amr'. Anda dapat memeriksa format yang didukung dalam dokumen.
        sample_rate=sample_rate,
        # 8000 atau 16000 didukung.
        semantic_punctuation_enabled=False,
        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()

import os
import time
from dashscope.audio.asr import *
# Tiongkok (Beijing): Ganti {WorkspaceId} dengan Workspace ID aktual Anda. Konfigurasi berbeda-beda berdasarkan wilayah.
dashscope.base_websocket_api_url = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference"

# Jika Anda belum mengonfigurasi API key dalam variabel lingkungan, hapus komentar baris kode berikut dan ganti apiKey dengan API key Anda.
# import dashscope
# dashscope.api_key = "apiKey"

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() + ' Recognition completed')  # pengenalan selesai

    def on_error(self, result: RecognitionResult) -> None:
        print('Recognition task_id: ', result.request_id)
        print('Recognition error: ', result.message)
        exit(0)

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

callback = Callback()

recognition = Recognition(model='paraformer-realtime-v2',
                          format='wav',
                          sample_rate=16000,
                          # Parameter "language_hints" hanya didukung oleh model paraformer-realtime-v2.
                          language_hints=['zh', 'en'],
                          callback=callback)

recognition.start()

try:
    audio_data: bytes = None
    f = open("{YOUR_AUDIO_FILE}", 'rb')
    if os.path.getsize("{YOUR_AUDIO_FILE}"):
        while True:
            audio_data = f.read(3200)
            if not audio_data:
                break
            else:
                recognition.send_audio_frame(audio_data)
            time.sleep(0.1)
    else:
        raise Exception(
            'File yang diberikan kosong (panjang nol byte)')
    f.close()
except Exception as e:
    raise e

recognition.stop()

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 konkuren

Dalam Python, karena adanya Global Interpreter Lock (GIL), hanya satu thread yang dapat menjalankan kode Python pada satu waktu (meskipun beberapa library berorientasi performa mungkin menghilangkan batasan ini). Jika Anda ingin memanfaatkan sumber daya komputasi komputer multi-inti secara lebih baik, kami merekomendasikan penggunaan multiprocessing atau concurrent.futures.ProcessPoolExecutor. Multithreading dapat meningkatkan latensi panggilan SDK secara signifikan dalam kondisi konkurensi tinggi.

Parameter permintaan

Parameter permintaan diatur dalam konstruktor (init) dari kelas Recognition.

Antarmuka utama

Kelas Recognition

Kelas Recognition diimpor menggunakan from dashscope.audio.asr import *.

def call(self, file: str, phrase_id: str = None, **kwargs) -> RecognitionResult

def start(self, phrase_id: str = None, **kwargs)

def send_audio_frame(self, buffer: bytes)

def stop(self)

def get_last_request_id(self)

def get_first_package_delay(self)

def get_last_package_delay(self)

Antarmuka callback (RecognitionCallback)

Selama panggilan streaming dua arah, server menggunakan callback untuk mengembalikan informasi dan data proses kunci ke klien. Anda harus mengimplementasikan metode callback untuk memproses informasi dan data yang dikembalikan.

class Callback(RecognitionCallback):
    def on_open(self) -> None:
        print('Koneksi berhasil')

    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 pengecualian: ', result)

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

callback = Callback()

def on_open(self) -> None

def on_event(self, result: RecognitionResult) -> None

def on_complete(self) -> None

def on_error(self, result: RecognitionResult) -> None

def on_close(self) -> None

Hasil respons

Hasil pengenalan (RecognitionResult)

RecognitionResult merepresentasikan hasil pengenalan dari satu pengenalan real-time dalam panggilan streaming dua arah atau panggilan non-streaming.

def get_sentence(self) -> Union[Dict[str, Any], List[Any]]

def get_request_id(self) -> str

@staticmethod
def is_sentence_end(sentence: Dict[str, Any]) -> bool

Sentence (Sentence)

Anggota kelas Sentence adalah sebagai berikut:

Informasi timestamp kata (Word)

Anggota kelas Word adalah sebagai berikut:

Kode error

Jika Anda mengalami error, lihat Kode error untuk troubleshooting.

Jika masalah berlanjut, bergabunglah dengan komunitas developer untuk melaporkan masalah Anda dan berikan Request ID untuk investigasi lebih lanjut.

Contoh lainnya

Untuk contoh lainnya, lihat GitHub.

FAQ

Fitur

T: Bagaimana cara mempertahankan koneksi panjang dengan server selama diam berkepanjangan?

Atur parameter permintaan heartbeat ke true dan terus-menerus kirimkan audio diam ke server.

Audio diam mengacu pada file audio atau aliran data yang tidak mengandung sinyal suara. Audio diam dapat dihasilkan melalui berbagai metode, seperti menggunakan perangkat lunak pengeditan audio seperti Audacity atau Adobe Audition, atau melalui alat command-line seperti FFmpeg.

T: Bagaimana cara mengonversi audio ke format yang didukung?

Anda dapat menggunakan tool FFmpeg. Untuk penggunaan lebih lanjut, rujuk situs resmi FFmpeg.

# Perintah konversi dasar (templat universal)
# -i: Jalur file input. Contoh: audio.wav
# -c:a: Kodek audio. Contoh: aac, libmp3lame, pcm_s16le
# -b:a: Bitrate (kontrol kualitas). Contoh: 192k, 320k
# -ar: Laju sampel. Contoh: 44100 (CD), 48000, 16000
# -ac: Jumlah saluran. Contoh: 1 (mono), 2 (stereo)
# -y: Timpa file yang 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 -> 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 (ekstraksi/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 kualitas lebih tinggi
# Contoh: FLAC lossless -> Opus (kompresi tinggi)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on output.opus

T: Apakah mendukung melihat rentang waktu untuk setiap kalimat?

Ya. Hasil pengenalan ucapan mencakup timestamp awal dan akhir untuk setiap kalimat, yang dapat digunakan untuk menentukan rentang waktu setiap kalimat.

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

Ada dua cara untuk mengenali file lokal:

• Langsung berikan jalur file lokal: Metode ini mengembalikan hasil pengenalan lengkap setelah file sepenuhnya diproses. Tidak cocok untuk skenario yang memerlukan umpan balik segera.

  Berikan jalur file ke metode call dari kelas Recognition untuk langsung mengenali file audio. Untuk informasi lebih lanjut, lihat Panggilan non-streaming.

• Konversi file lokal menjadi aliran biner untuk pengenalan: Metode ini mengembalikan hasil pengenalan sebagai aliran saat file sedang diproses. Cocok untuk skenario yang memerlukan umpan balik segera.

  Anda dapat menggunakan metode send_audio_frame dari kelas Recognition untuk mengirim aliran biner ke server untuk pengenalan. Untuk informasi lebih lanjut, lihat panggilan streaming dua arah.

Troubleshooting

T: Apa penyebab kegagalan mengenali ucapan (tidak ada hasil pengenalan)?

1. Periksa apakah format audio (format) dan laju sampel (sampleRate/sample_rate) dalam parameter permintaan diatur dengan benar dan mematuhi batasan parameter. Berikut adalah contoh kesalahan umum:

   • Ekstensi file audio adalah .wav, tetapi format sebenarnya adalah MP3, dan 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).

   Anda dapat menggunakan tool ffprobe untuk memperoleh informasi 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

2. Ketika menggunakan model paraformer-realtime-v2, periksa apakah bahasa yang diatur dalam language_hints sesuai dengan bahasa aktual audio.

   Contoh: Audio sebenarnya dalam bahasa Tionghoa, tetapi language_hints diatur ke en (Inggris).

3. Jika semua pemeriksaan di atas lolos, Anda dapat menggunakan hot word kustom untuk meningkatkan akurasi pengenalan untuk kata-kata tertentu.