Skip to main content

SDK iOS pengenalan ucapan non-real-time Qwen-Audio-ASR-Filetrans

Panduan ini memandu Anda melalui SDK iOS pengenalan ucapan non-real-time Qwen-Audio-ASR-Filetrans, sehingga Anda dapat mengonversi audio menjadi teks.

Untuk persyaratan input seperti format audio yang didukung, batas ukuran file, dan batas durasi, lihat Spesifikasi audio.

Mulai cepat

  1. Dapatkan Kunci API:Dapatkan kunci API
  2. Unduh SDK dan jalankan kode contoh:
    • Unduh bundel SDK terbaru.
    • Ekstrak paket ZIP dan tambahkan nuisdk.framework yang disertakan ke proyek Anda.
    • Di bawah Build Phases → Link Binary With Libraries, tambahkan nuisdk.xcframework.
    • Di bawah General → Frameworks, Libraries, and Embedded Content, atur nuisdk.xcframework ke Embed & Sign.
    • Buka proyek contoh di Xcode. Kode contoh terletak di DashFunAsrFileTranscriberViewController.m. Ganti API Key untuk mencoba fitur tersebut.

Langkah panggilan

  • Mode sinkron
  • Mode asinkron
  1. Inisialisasi SDK.
  2. Konfigurasikan parameter yang relevan untuk kasus penggunaan Anda.
  3. Atur async_request ke false dan panggil nui_file_trans_start untuk mengirimkan permintaan pengenalan ucapan non-real-time dan menunggu hasilnya.
  4. Pada callback onFileTransEventCallback, dengarkan event EVENT_FILE_TRANS_RESULT untuk mendapatkan hasil pengenalan akhir.
  5. Panggil nui_release untuk melepaskan sumber daya SDK.

Parameter permintaan

Parameter koneksi dan kontrol

Konfigurasikan parameter ini dengan meneruskan string JSON dalam argumen parameters dari antarmuka nui_initialize. Contoh parameter Berikut ini adalah contoh string JSON. Tidak semua parameter dicantumkan. Tambahkan yang Anda butuhkan saat menulis kode:
{
    "url": "wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
Deskripsi parameter
ParameterTipeWajibDeskripsi
urlStringYaEndpoint layanan:
  • wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription
  • Tiongkok (Beijing): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
  • Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
Ganti {WorkspaceId} dengan ID Workspace Anda yang sebenarnya.
apikeyStringYaKunci API.
service_modeStringYaMode eksekusi. Diatur tetap ke "1" untuk pengenalan suara non-real-time.
device_idStringYaString unik yang mengidentifikasi pengguna akhir. Atur ke ID pengguna dalam aplikasi atau pengenal perangkat yang dihasilkan oleh klien. ID ini terutama digunakan untuk pelacakan log dan pemecahan masalah.
debug_pathStringTidakJalur penyimpanan untuk file log.Parameter ini hanya berlaku ketika save_log diatur ke YES saat Anda memanggil antarmuka nui_initialize. Dalam hal ini, Anda harus mengatur jalur file log; jika tidak, error akan dikembalikan.Maksimal dua file log disimpan secara lokal.
max_log_file_sizeintTidakUkuran maksimum file log, dalam byte.Parameter ini hanya berlaku ketika save_log diatur ke YES saat Anda memanggil antarmuka nui_initialize.Nilai default: 104857600 (100 * 1024 * 1024 byte, yaitu, 100 MiB).
log_track_levelintTidakMengontrol tingkat filter konten log yang dikirim melalui callback log (onFileTransLogTrackCallback).Nilai default: 2.Nilai yang valid:
  • 0: LOG_LEVEL_VERBOSE
  • 1: LOG_LEVEL_DEBUG
  • 2: LOG_LEVEL_INFO
  • 3: LOG_LEVEL_WARNING
  • 4: LOG_LEVEL_ERROR
  • 5: LOG_LEVEL_NONE (menonaktifkan fitur ini)
Catatan: log_track_level dan level (diatur melalui antarmuka nui_initialize) bersama-sama menentukan log mana yang akhirnya dikirim ke callback. Nilai tingkat log harus lebih besar dari atau sama dengan log_track_level dan level sebelum dikirim ke callback. Misalnya, jika log_track_level diatur ke 2 (INFO) dan level diatur ke 3 (WARNING), hanya log pada tingkat WARNING atau lebih tinggi (nilai >= 3) yang dikirim ke callback.

Parameter efek pengenalan suara

Konfigurasikan semua parameter pengenalan suara melalui antarmuka nui_file_trans_start. Contoh parameter Berikut ini adalah contoh string JSON. Tidak semua parameter dicantumkan. Tambahkan yang Anda butuhkan saat menulis kode:
{
    "apikey": "st-****",
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false
    }
}
Deskripsi parameter
ParameterTipeWajibDeskripsi
file_urlsarray[string]YaDaftar URL file audio atau video yang akan ditranskripsikan. HTTP dan HTTPS didukung. Satu permintaan hanya mendukung satu URL. Untuk persyaratan input seperti format audio yang didukung, batas ukuran file, dan batas durasi, lihat Spesifikasi audio.Jika rekaman disimpan di Alibaba Cloud OSS, API RESTful mendukung URL sementara dengan awalan oss://, sedangkan SDK tidak mendukung URL sementara dengan awalan oss://.
  • URL sementara berlaku selama 48 jam dan tidak dapat digunakan setelah kedaluwarsa. Jangan gunakan dalam produksi.
  • Antarmuka kredensial unggahan dibatasi hingga 100 QPS dan tidak dapat ditingkatkan. Jangan gunakan dalam skenario produksi, konkurensi tinggi, atau pengujian beban.
  • Untuk produksi, gunakan penyimpanan stabil seperti Alibaba Cloud OSS agar file tetap tersedia dalam jangka panjang dan menghindari pembatasan laju.
  • Jika URL file audio yang diatur ke URL publik sementara OSS tidak dapat dijangkau, atur X-DashScope-OssResourceResolve ke enable di header permintaan (tidak disarankan). SDK tidak mendukung konfigurasi header permintaan.
async_requestbooleanTidakApakah permintaan pengenalan suara bersifat asinkron.Nilai default: false.Nilai yang valid:
  • true: permintaan asinkron
  • false: permintaan sinkron
apikeystringTidakJika apikey di Parameter koneksi dan kontrol adalah API Key sementara, Anda dapat memperbaruinya di sini untuk mencegah kedaluwarsa.
nls_configobjectYaObjek konfigurasi pengenalan suara inti. Ini berisi parameter kunci seperti pemilihan model dan kontrol efek pengenalan.
nls_config.modelstringYaNama model.
nls_config.special_word_filterobjectTidakKata sensitif yang akan diproses selama pengenalan suara. Anda dapat mengatur metode penanganan yang berbeda untuk setiap kata sensitif. Untuk detailnya, lihat Pemfilteran kata sensitif.
nls_config.channel_idarray[integer]TidakIndeks trek audio yang akan dikenali dalam file audio multi-trek. Indeks dimulai dari 0. Misalnya, [0] mengenali trek pertama, dan [0, 1] mengenali trek pertama dan kedua secara bersamaan. Jika Anda menghilangkan parameter ini, hanya trek pertama yang diproses.
Setiap trek yang ditentukan ditagih secara independen. Misalnya, meminta [0, 1] untuk satu file akan menimbulkan dua tagihan terpisah.
Nilai default: [0].
nls_config.diarization_enabledbooleanTidakApakah akan mengaktifkan diarization pembicara. Dinonaktifkan secara default.Hanya berlaku untuk audio mono. Audio multi-saluran tidak mendukung diarization pembicara.Saat diaktifkan, hasil pengenalan menyertakan bidang speaker_id yang membedakan pembicara yang berbeda.
Saat diarization pembicara diaktifkan, pertahankan durasi audio dalam 2 jam. Jika tidak, pengenalan mungkin gagal atau habis waktu.
Nilai default: false.Untuk contoh speaker_id, lihat Deskripsi hasil pengenalan.
nls_config.speaker_countintegerTidak
Hanya berlaku ketika diarization pembicara diaktifkan (diarization_enabled diatur ke true).
Nilai referensi untuk jumlah pembicara. Rentang yang valid adalah bilangan bulat dari 2 hingga 100 (inklusif).Secara default, jumlah pembicara dideteksi secara otomatis. Jika Anda mengatur nilai ini, ini hanya memandu algoritme untuk menghasilkan jumlah yang ditentukan jika memungkinkan dan tidak menjamin jumlah yang tepat tersebut.Tidak ada nilai default.
nls_config.vocabulary_idstringTidakID dari daftar hotword yang telah dikompilasi sebelumnya.Hasilkan ID ini terlebih dahulu dengan memanggil API buat daftar hotword. Teruskan ID selama pengenalan untuk menggunakan hotword dalam daftar.Cocok untuk skenario di mana kosakata diketahui dan relatif stabil, dan di mana Anda perlu menggunakan kembali daftar kata yang sama di berbagai permintaan.Untuk detail penggunaan, lihat Hotword yang telah dikompilasi sebelumnya.
nls_config.input_contextarrayTidakDaftar pesan yang berisi konteks percakapan opsional untuk meningkatkan akurasi pengenalan.
Konteks membantu meningkatkan pengenalan istilah khusus domain. Untuk penggunaan, lihat Peningkatan konteks.Anda dapat menyertakan hingga 5 pesan dari setiap tipe konteks: input_text dan text. Jika batas ini terlampaui, hanya 5 pesan terbaru dari setiap tipe yang dipertahankan. Panjang gabungan bidang text dalam pesan user dan assistant di setiap giliran tidak boleh melebihi 400 karakter. Setiap karakter dihitung sebagai 1. Teks berlebih dipotong dari akhir.
Saat Anda menyertakan konteks, atur messages berdasarkan giliran percakapan. Di setiap giliran, pesan user (tipe input_text) harus mendahului pesan assistant yang sesuai (tipe text). Pesan user yang berisi input_audio harus menjadi pesan terakhir dalam array messages.
[
  {
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "你好啊,我是通义千问,有什么可以帮助你的?"
      }
    ]
  }
]
nls_config.instant_vocabularyobjectTidakHotword instan, diteruskan sebagai pasangan kunci-nilai. Setiap kunci adalah teks hotword (string), dan setiap nilai adalah bobotnya (integer). Tidak diperlukan daftar hotword yang telah dikompilasi sebelumnya. Gunakan parameter ini untuk hotword sementara tingkat sesi.Bobot yang valid adalah bilangan bulat dari 1 hingga 5, atau 50. Bobot yang lebih tinggi dari 1 hingga 5 membuat model lebih mungkin menghasilkan hotword. Bobot 50 mendefinisikan super hotword dan secara signifikan meningkatkan recall. Anda dapat menentukan hingga 50 super hotword.Jika Anda juga mengonfigurasi hotword yang telah dikompilasi sebelumnya, kedua set akan digabungkan. Jika set yang digabungkan melebihi 2000 hotword, 2000 akan dipilih secara acak. Untuk penggunaan, lihat Hotword instan.
Untuk model dan batas yang berlaku untuk hotword instan, lihat Hotword instan.
{
  "张三": 5,
  "李四": 5
}
nls_config.language_hintsarray[string]TidakKode bahasa yang akan dikenali. Jika Anda tidak dapat menentukan bahasa terlebih dahulu, biarkan tidak diatur dan model akan mendeteksi bahasa secara otomatis.Anda dapat menetapkan hingga 4 nilai. Jika lebih, hanya 4 nilai pertama yang berlaku.
  • zh: Tiongkok
  • en: Inggris
  • ja: Jepang
  • ko: Korea
  • vi: Vietnam
  • th: Thai
  • id: Indonesia
  • ms: Melayu
  • tl: Filipino
  • hi: Hindi
  • ar: Arab
  • fr: Prancis
  • de: Jerman
  • es: Spanyol
  • pt: Portugis
  • ru: Rusia
  • it: Italia
  • nl: Belanda
  • sv: Swedia
  • da: Denmark
  • fi: Finlandia
  • no: Norwegia
  • el: Yunani
  • pl: Polandia
  • cs: Ceko
  • hu: Hungaria
  • ro: Rumania
  • bg: Bulgaria
  • hr: Kroasia
  • sk: Slovakia

Antarmuka utama

NeoNui

nui_initialize

Menginisialisasi instance SDK pengenalan ucapan. SDK ini adalah singleton. Jangan menginisialisasinya lagi sebelum Anda memanggil nui_release. Signature metode
-(NuiResultCode) nui_initialize:(const char *)parameters
                       logLevel:(NuiSdkLogLevel)level
                        saveLog:(BOOL)save_log;
Deskripsi parameter
ParameterTipeDeskripsi
parameterschar*String JSON yang berisi parameter autentikasi, koneksi, dan debugging. Lihat Parameter koneksi dan kontrol.
levelNuiSdkLogLevelMengontrol tingkat pencetakan log SDK itu sendiri.
save_logBOOLApakah akan menyimpan log secara lokal. Jika diatur ke YES, Anda harus menentukan jalur melalui debug_path di Parameter koneksi dan kontrol, dan Anda dapat mengatur ukuran file melalui max_log_file_size.

nui_set_params

Gunakan antarmuka ini untuk mengatur atau memperbarui parameter nls_config secara independen. Jika Anda menyediakan semua parameter sekaligus di nui_file_trans_start, Anda tidak perlu memanggil metode ini. Signature metode
-(NuiResultCode) nui_set_params:(const char *)params;
Deskripsi parameter
ParameterTipeDeskripsi
paramschar*Parameter nls_config di Parameter efek pengenalan ucapan. Parameter selain nls_config tidak dapat diatur melalui metode ini.Contoh:
{
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false
    }
}

nui_file_trans_start

Memulai pengenalan. Signature metode
-(NuiResultCode) nui_file_trans_start:(const char *)params
                               taskId:(char *)task_id;
Deskripsi parameter
ParameterTipeDeskripsi
paramschar*Parameter efek pengenalan suara.Contoh:
{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false
    }
}
task_idchar*ID tugas. SDK menghasilkan string acak secara internal dan mengembalikan task_id ketika antarmuka ini berhasil dipanggil.

nui_file_trans_query

Gunakan antarmuka ini untuk secara aktif mengkueri status dan hasil saat ini dari tugas asinkron. Setelah panggilan berhasil, hasil dikembalikan melalui event EVENT_FILE_TRANS_QUERY_RESULT di callback onFileTransEventCallback.
Dapatkan task_id yang diteruskan ke metode ini dari event EVENT_FILE_TRANS_UPLOADED.
Signature metode
-(NuiResultCode) nui_file_trans_query:(const char *)task_id;
Deskripsi parameter
ParameterTipeDeskripsi
task_idchar*ID tugas yang akan dikueri, diperoleh dari event EVENT_FILE_TRANS_UPLOADED.

nui_file_trans_cancel

Membatalkan tugas saat ini secara langsung. Signature metode
-(NuiResultCode) nui_file_trans_cancel:(const char *)task_id;
Deskripsi parameter
ParameterTipeDeskripsi
task_idchar*ID tugas yang akan dibatalkan, diperoleh dari event EVENT_FILE_TRANS_UPLOADED.

nui_release

Melepaskan semua sumber daya internal SDK dan menghentikan paksa semua tugas yang sedang berlangsung. Setelah Anda memanggil metode ini, instance SDK menjadi tidak tersedia. Untuk menggunakannya lagi, Anda harus memanggil nui_initialize lagi untuk menginisialisasinya. Signature metode
-(NuiResultCode) nui_release;

nui_get_version

Mendapatkan informasi versi SDK saat ini. Signature metode
-(const char*) nui_get_version;
Nilai kembalian Informasi versi SDK saat ini.

NeoNuiSdkDelegate: pantau callback

onFileTransEventCallback: pantau event dan hasil pengenalan suara

Signature metode
-(void) onFileTransEventCallback:(NuiCallbackEvent)nuiEvent
                       asrResult:(const char *)asr_result
                          taskId:(const char *)task_id
                        ifFinish:(BOOL)finish
                         retCode:(int)code;
Deskripsi parameter
ParameterTipeDeskripsi
nuiEventNuiCallbackEventEvent callback.
asr_resultchar*Hasil pengenalan ucapan.
task_idchar*ID tugas.
finishBOOLMenunjukkan apakah putaran pengenalan ini telah selesai.
codeintHanya valid saat event EVENT_ASR_ERROR terjadi.

onFileTransLogTrackCallback: pantau log pelacakan

Gunakan callback ini untuk menerima log internal SDK yang terperinci untuk pemecahan masalah dan debugging.
-(void)onFileTransLogTrackCallback:(NuiSdkLogLevel)level
                        logMessage:(const char *)log;

NuiCallbackEvent: tipe event

EventDeskripsi
EVENT_FILE_TRANS_CONNECTEDBerhasil terhubung ke layanan.
EVENT_FILE_TRANS_UPLOADEDFile audio yang akan dikenali berhasil diunggah. Anda sekarang dapat memperoleh task_id dari tugas saat ini.
EVENT_FILE_TRANS_QUERY_RESULTHasil tugas kueri.
EVENT_FILE_TRANS_RESULTHasil pengenalan akhir.
EVENT_ASR_ERRORTerjadi error selama pengenalan ucapan.