Skip to main content

Qwen-Audio-Realtime HarmonyOS SDK

Gunakan SDK HarmonyOS percakapan suara realtime Qwen-Audio-Realtime untuk mengaktifkan input audio realtime serta output suara atau teks.

Untuk koneksi dan autentikasi, lihat Akses WebSocket. Untuk bidang peristiwa dan contoh JSON, lihat Peristiwa klien dan Peristiwa server. Panduan pengguna: Untuk pengenalan model dan saran pemilihan, lihat Percakapan suara real-time.

Prasyarat

  1. Dapatkan dan konfigurasikan API Key. Jangan hardcode API Key jangka panjang di aplikasi seluler. Kami menyarankan server aplikasi Anda membuat API Key sementara terlebih dahulu, lalu mengirimkannya ke klien.

Instal SDK

  • Unduh paket SDK terbaru.
  • Ekstrak paket integrasi SDK dalam format .tar.gz. Dapatkan SDK dalam format HAR dari direktori entry/libs dan tambahkan ke dependensi proyek Anda. Untuk integrasi C++, gunakan native/libs dan native/include dalam paket untuk mendapatkan pustaka dinamis dan file header.

Mulai cepat

Buka proyek di DevEco Studio. Kode contoh berada di DashQwenAudioChatPage.ets. Ganti API Key lalu coba fitur-fiturnya.

Prosedur pemanggilan

  1. Inisialisasi SDK.
  2. Atur parameter sesuai kebutuhan bisnis: atur parameter koneksi dan kontrol melalui parameter parameters dari antarmuka initialize; atur parameter percakapan melalui antarmuka setParams.
  3. Panggil startDialog untuk memulai percakapan.
  4. Di onNuiAudioStateChanged, mulai perangkat perekaman berdasarkan status audio.
  5. Sediakan data perekaman secara terus-menerus di onNuiNeedAudioData, atau panggil updateAudio untuk mendorong data perekaman secara aktif.
  6. Terima data suara yang dikembalikan oleh AI secara terus-menerus di onNuiAssistEventCallback.
  7. Dengarkan event dan dapatkan informasi event di onNuiEventCallback.
  8. Panggil stopDialog untuk menghentikan percakapan, dan konfirmasi bahwa percakapan telah berakhir dengan mendengarkan event EVENT_TRANSCRIBER_COMPLETE.
  9. Saat fitur percakapan tidak lagi diperlukan, panggil release untuk melepaskan sumber daya SDK.

Parameter permintaan

Parameter koneksi dan kontrol

Dikonfigurasi dengan meneruskan string JSON ke parameter parameters dari antarmuka initialize. Contoh parameter: Berikut adalah contoh string JSON dan tidak mencantumkan semua parameter. Tambahkan parameter sesuai kebutuhan saat coding: Contoh ini menggunakan qwen-audio-3.1-realtime-plus. Saat Anda mengganti model, perbarui model dalam URL dan nls_config.model pada parameter percakapan sesuai.
{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=qwen-audio-3.1-realtime-plus",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
Deskripsi parameter
ParameterTipeWajibDeskripsi
urlStringYaAlamat layanan:
  • wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • Tiongkok (Beijing) 2: wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
Saat memanggil API, ganti {WorkspaceId} dengan ID Workspace Anda yang sebenarnya.
apikeyStringYaAPI key.
service_modeStringYaMode operasi. Untuk percakapan suara realtime, nilainya tetap "1".
device_idStringYaString unik yang mengidentifikasi pengguna akhir. Anda dapat menggunakan ID pengguna dalam aplikasi atau pengidentifikasi perangkat yang dibuat klien. ID ini terutama digunakan untuk pelacakan log dan pemecahan masalah.
audio_update_manuallyStringTidakApakah akan mengaktifkan mode pendorongan data audio aktif. Nilai default: "false".
Saat parameter ini diatur ke "true" untuk mengaktifkan mode pendorongan data audio aktif dan versi SDK mendukung kemampuan audio on-device (seperti AEC dan VAD), kemampuan audio on-device diaktifkan secara default.
workspaceStringTidakSaat parameter audio_update_manually diatur ke "true" dan kemampuan audio on-device (seperti AEC dan VAD) diaktifkan, Anda wajib menetapkan workspace, yaitu jalur tempat file sumber daya on-device disimpan.
debug_pathStringTidakJalur penyimpanan file log. Parameter ini hanya berlaku saat save_log diatur ke true ketika memanggil API initialize. Dalam hal ini, Anda wajib menetapkan jalur file log; jika tidak, kesalahan akan dilaporkan. Maksimal dua file log disimpan secara lokal.
save_wavStringTidakApakah akan menyimpan file audio untuk debugging. File audio disimpan di bawah debug_path.
Nilai default: "false".
Nilai yang valid:
  • "true": Ya
  • "false": Tidak
Parameter ini hanya berlaku saat save_log diatur ke true ketika memanggil API initialize. Selain itu, debug_path juga harus diatur.
max_log_file_sizeintTidakJumlah byte maksimum untuk file log.
Parameter ini hanya berlaku saat save_log diatur ke true ketika memanggil API initialize.
Nilai default: 104857600 (100 × 1024 × 1024 byte, yaitu 100MiB).
log_track_levelintTidakMengontrol tingkat filter konten log yang dikirim ke luar melalui callback log (onNuiLogTrackCallback).
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 API initialize) bersama-sama menentukan log yang akhirnya di-callback. Log hanya di-callback jika nilai tingkatnya lebih besar dari atau sama dengan log_track_level dan level. Misalnya, jika log_track_level diatur ke 2 (INFO) dan level diatur ke 3 (WARNING), hanya log pada tingkat WARNING ke atas (nilai >= 3) yang di-callback.
aec_paramsobjectTidakObjek konfigurasi parameter tingkat lanjut untuk kemampuan AEC on-device. Objek konfigurasi ini hanya diaktifkan saat parameter audio_update_manually diatur ke "true".
aec_params.enable_aecbooleanTidakApakah akan mengaktifkan kemampuan pembatalan gema AEC on-device.
Saat parameter audio_update_manually diatur ke "true" dan versi SDK mendukung kemampuan audio AEC on-device, kemampuan ini diaktifkan secara default.
aec_params.save_audiobooleanTidakApakah akan mengaktifkan fitur penyimpanan audio modul pembatalan gema AEC on-device. Saat save_wav adalah "true" dan debug_path diatur, fitur ini diaktifkan secara default, dan data audio runtime AEC disimpan di bawah debug_path.
aec_params.enable_aec_data_callbackbooleanTidakApakah akan mengirim data pasca-AEC kepada pengguna. Nilai default: false. Setelah fitur ini diaktifkan, data diterima di EVENT_AEC_DATA pada onNuiAssistEventCallback.
vad_paramsobjectTidakObjek konfigurasi parameter tingkat lanjut untuk kemampuan VAD on-device.
Objek konfigurasi ini hanya diaktifkan saat parameter audio_update_manually diatur ke "true".
vad_params.enable_vadbooleanTidakApakah akan mengaktifkan kemampuan deteksi suara VAD on-device.
Saat parameter audio_update_manually diatur ke "true" dan versi SDK mendukung kemampuan audio VAD on-device, kemampuan ini diaktifkan secara default.
vad_params.save_audiobooleanTidakApakah akan mengaktifkan fitur penyimpanan audio modul deteksi suara VAD on-device.
Saat save_wav adalah "true" dan debug_path diatur, fitur ini diaktifkan secara default, dan data audio runtime VAD disimpan di bawah debug_path.

Parameter percakapan suara

Dikonfigurasi dengan meneruskan string JSON ke parameter params dari API setParams. Contoh parameter: Berikut adalah contoh string JSON dan tidak mencantumkan semua parameter. Tambahkan parameter sesuai kebutuhan saat coding:
{
    "service_type": 4,
    "nls_config": {
        "model": "qwen-audio-3.1-realtime-plus",
        "sr_format": "pcm"
    }
}
Deskripsi parameter
Parameter tingkat atasTipeWajibDeskripsi
service_typeintYaTipe layanan suara. Atur parameter ini ke 4 untuk percakapan suara real-time.
nls_configobjectYaKonfigurasi inti percakapan suara, termasuk pemilihan model dan perilaku percakapan.
nls_config.modelstringYaMenentukan nama model. Mendukung model seri qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, dan qwen-audio-3.0-realtime-flash.
nls_config.sr_formatstringYaFormat audio input. Saat ini hanya pcm (16kHz 16bit mono) yang didukung, yang merupakan nilai default.
nls_config.modalitiesstringTidakString dalam format array, menentukan pengaturan modalitas output model. Nilai yang valid:
  • ["text"]: Hanya mengeluarkan teks.
  • ["audio", "text"] (nilai default): Mengeluarkan teks dan audio.
nls_config.voicestringTidakNama suara TTS. Nilai default untuk 3.1 Plus/Flash adalah longanqian_v3.1, dan nilai default untuk 3.0 Plus/Flash adalah longanqian. Hanya dapat diatur pada session.update pertama; nilai yang diteruskan selanjutnya akan diabaikan.
  • Suara sistem 3.1 Plus/Flash: Nilai yang valid mencakup longanqian_v3.1 dan semua suara dalam daftar suara 3.1 TTS Plus/Flash. Untuk rentang lengkapnya, lihat Konfigurasi suara.
  • Suara sistem 3.0 Plus/Flash: longanqian, longanlingxin, longanlingxi, longanxiaoxin, longanlufeng.
  • Suara hasil kloning suara: Dibuat melalui API kloning suara. Isi voice_id yang dikembalikan pada parameter ini. Untuk informasi selengkapnya, lihat Konfigurasi suara.
nls_config.enable_speech_emotionbooleanTidakApakah akan mengaktifkan fitur peningkatan emosi. Saat diaktifkan, perubahan emosional suara balasan lebih kentara. Nilai default: true. Nilai yang valid: true, false.
nls_config.instructionsstringTidakInstruksi sistem yang digunakan untuk menentukan identitas peran, gaya respons, dan preferensi perilaku model. Berlaku untuk seluruh sesi.
nls_config.max_history_turnsintTidakJumlah maksimum giliran tanya-jawab historis yang diizinkan per permintaan. Rentang nilai 1-50, nilai default 20.
nls_config.toolsstringTidakString dalam format array. Daftar definisi alat Function Calling. Saat dikonfigurasi, model dapat secara mandiri memutuskan apakah akan memanggil alat berdasarkan input pengguna.
Deskripsi parameter internal:
typestring(wajib)
Tetap function.
function.namestring(wajib)
Nama fungsi alat.
function.descriptionstring(opsional)
Deskripsi fungsi alat, berdasarkan hal tersebut model menentukan apakah akan memanggil alat.
function.parametersobject(opsional)
Deskripsi parameter input fungsi alat, berdasarkan hal tersebut model mengekstrak parameter yang diperlukan. Jika fungsi tidak memerlukan parameter input, bagian ini dapat dihilangkan.
Contoh:
[
 {
 "type": "function",
 "function": {
 "name": "get_weather",
 "description": "查询指定城市的天气信息。",
 "parameters": {
 "type": "object",
 "properties": {
 "city": {
 "type": "string",
 "description": "城市"
 }
 },
 "required": [
 "city"
 ]
 }
 }
 }
]
nls_config.turn_detectionstringTidakDeskripsi bidang deteksi giliran berikut berlaku untuk qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, dan qwen-audio-3.0-realtime-flash.String dalam format objek JSON. Konfigurasi deteksi giliran. Jika tidak diatur, akan beralih ke mode push-to-talk (kirim audio dan picu inferensi secara manual). Jika diatur, mode percakapan dupleks diaktifkan.
nls_config.turn_detection.typestringTidakTipe VAD. Nilai yang valid:
  • server_vad (default): Mendeteksi awal dan akhir ucapan berdasarkan fitur akustik, otomatis memicu inferensi.
  • smart_turn: Deteksi giliran cerdas yang menggabungkan persepsi akustik dengan pemahaman semantik, menentukan batas giliran melalui penilaian akustik dan semantik ganda. Suara non-semantik (seperti "uh" dan "ah") tidak akan memicu giliran dialog atau mengganggu pemutaran model.
  • smart_turn_v2 (direkomendasikan): Meningkatkan pemahaman konteks percakapan di atas smart_turn, lebih baik menentukan niat interaksi dalam skenario multi-pembicara. Mengurangi balasan palsu dan gangguan palsu yang disebabkan oleh suara orang di sekitar atau intervensi yang tidak relevan.
nls_config.turn_detection.thresholdfloatTidakSensitivitas VAD. Berlaku untuk server_vad, smart_turn, dan smart_turn_v2. Semakin rendah nilainya, semakin mudah suara samar (termasuk kebisingan latar belakang) dikenali sebagai ucapan; semakin tinggi nilainya, semakin jelas dan keras ucapan yang diperlukan untuk memicu deteksi.
Rentang nilai [-1.0, 1.0], nilai default 0.5.
nls_config.turn_detection.silence_duration_msintTidakDurasi hening minimum (dalam milidetik) setelah ucapan berakhir. Hanya efektif dalam mode server_vad (tidak efektif dalam mode smart_turn dan smart_turn_v2). Setelah hening mencapai durasi ini, respons model dipicu. Semakin rendah nilainya, semakin cepat responsnya, tetapi jeda singkat juga dapat menyebabkan pemicuan palsu.
Rentang nilai [200, 6000], nilai default 800. 400-800 direkomendasikan untuk skenario percakapan.
nls_config.turn_detection.voiceprint_audio_urlsstringTidakString dalam format array. Efektif dalam mode smart_turn dan smart_turn_v2. Daftar URL yang dapat diakses publik dari audio prarekam pengguna target, digunakan untuk peningkatan pembicara. Model menggunakan file audio ini untuk mengunci pembicara target dalam percakapan dupleks, mengabaikan suara orang di sekitar dan kebisingan latar belakang. Mendukung hingga 5 URL. Persyaratan format audio: PCM atau WAV 16kHz.

Referensi API

Manajemen perangkat audio

Tidak seperti Android yang menggunakan AudioRecord / AudioTrack, HarmonyOS menyediakan kemampuan penangkapan dan pemutaran audio melalui @kit.AudioKit, masing-masing menggunakan AudioCapturer (perekaman) dan AudioRenderer (pemutaran). Contoh untuk produk ini telah mengenkapsulasinya menjadi dua kelas utilitas, AudioRecorder.ets dan AudioPlayer.ets, yang dapat langsung digunakan kembali.

Perekaman (AudioCapturer)

  • Buat: Dibuat secara asinkron melalui audio.createAudioCapturer(capturerOptions), dengan laju sampel tetap 16kHz, 16-bit, mono (SAMPLE_RATE_16000/CHANNEL_1/SAMPLE_FORMAT_S16LE/ENCODING_TYPE_RAW).
  • Sumber audio (audio.SourceType):
    • SOURCE_TYPE_MIC: Sumber audio mikrofon mentah, digunakan saat AEC internal SDK diaktifkan (data dikirim ke SDK melalui updateAudio).
    • SOURCE_TYPE_VOICE_COMMUNICATION: Sumber audio panggilan suara, dengan pembatalan gema yang telah diterapkan oleh sistem saat penangkapan, digunakan saat AEC internal SDK dinonaktifkan (audio ditarik melalui onNuiNeedAudioData).
  • Event data: Terima data perekaman secara terus-menerus melalui capturer.on('readData', (buffer: ArrayBuffer) => void).
  • Event status: Dipantau melalui capturer.on('stateChange', (state: audio.AudioState) => void); STATE_RUNNING menunjukkan perekaman telah dimulai, STATE_STOPPED menunjukkan perekaman telah berhenti.
  • Kontrol: start() untuk memulai, stop() untuk menghentikan, release() untuk melepaskan.
import { audio } from '@kit.AudioKit';

const audioStreamInfo: audio.AudioStreamInfo = {
  samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_16000,
  channels: audio.AudioChannel.CHANNEL_1,
  sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
  encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
};
const audioCapturerInfo: audio.AudioCapturerInfo = {
  source: audio.SourceType.SOURCE_TYPE_MIC,
  capturerFlags: 0
};
const options: audio.AudioCapturerOptions = { streamInfo: audioStreamInfo, capturerInfo: audioCapturerInfo };

audio.createAudioCapturer(options).then((capturer) => {
  capturer.on('readData', (buffer: ArrayBuffer) => {
    // 将录音数据送入SDK
    nuiInstance.updateAudio(buffer, false);
  });
  capturer.start();
});
Catatan: AudioCapturer HarmonyOS dibuat secara asinkron, dan start() hanya dapat dipanggil setelah pembuatan selesai. Oleh karena itu, jangan membuat dan langsung memulai perekam saat STATE_OPEN — buat terlebih dahulu, lalu panggil start() di callback STATE_OPEN (contoh membuatnya di tahap doInit dan memulainya di tahap onNuiAudioStateChanged).

Pemutaran (AudioRenderer)

  • Buat: Dibuat secara asinkron melalui audio.createAudioRenderer(rendererOptions).
  • Laju sampel: Audio respons ucapan yang disintesis oleh DashScope realtime adalah 24kHz (diteruskan saat membangun AudioPlayer).
  • Event data: Tarik audio yang akan diputar melalui renderer.on('writeData', (data: ArrayBuffer): audio.AudioDataCallbackResult => ...); mengembalikan AudioDataCallbackResult.VALID menunjukkan data telah diisi, INVALID menunjukkan tidak ada data.
  • Event status: Pantau mulai dan berakhirnya pemutaran melalui renderer.on('stateChange', (state: audio.AudioState) => void).
  • Kontrol: start() untuk memulai, stop() untuk menghentikan, pause() untuk menjeda (menjeda mempertahankan data yang di-buffer).
import { audio } from '@kit.AudioKit';

const audioStreamInfo: audio.AudioStreamInfo = {
  samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_24000,
  channels: audio.AudioChannel.CHANNEL_1,
  sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
  encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
};
const audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_VOICE_ASSISTANT,
  rendererFlags: 0
};
const options: audio.AudioRendererOptions = { streamInfo: audioStreamInfo, rendererInfo: audioRendererInfo };

audio.createAudioRenderer(options, (err, renderer) => {
  renderer.on('writeData', (data: ArrayBuffer): audio.AudioDataCallbackResult => {
    // 从队列取出AI返回的音频填入data, 返回VALID/INVALID
    return audio.AudioDataCallbackResult.VALID;
  });
  renderer.start();
});
Sinyal referensi AEC: Saat AEC internal SDK diaktifkan, audio yang dikeluarkan pemutar harus dikirim ke SDK sebagai sinyal referensi, dengan memanggil nuiInstance.pushReferenceData(data, false) (sesuai dengan updateRefAudio Android).

Deklarasi izin

Untuk menggunakan fitur perekaman, deklarasikan izin mikrofon di module.json5:
{
  "requestPermissions": [
    { "name": "ohos.permission.MICROPHONE" }
  ]
}

NativeNui

initialize · Inisialisasi SDK

Menginisialisasi instans SDK percakapan suara. SDK menggunakan pola singleton. Jangan menginisialisasinya lagi sebelum Anda memanggil release. Antarmuka ini bersifat memblokir dan harus dipanggil pada thread non-UI. Signature metode
public initialize(callback: INativeNuiCallback,
                  parameters: string,
                  level: number,
                  save_log: boolean = false): number
Deskripsi parameter
ParameterTipeDeskripsi
callbackINativeNuiCallbackImplementasi antarmuka callback event dan data.
parametersstringString JSON yang berisi parameter autentikasi, koneksi, dan debugging. Lihat Parameter koneksi dan kontrol.
levelnumberMengontrol tingkat log SDK itu sendiri.
save_logbooleanApakah akan menyimpan log secara lokal. Jika true, Anda wajib menentukan jalur melalui debug_path di parameter koneksi dan kontrol, dan Anda dapat mengatur ukuran file melalui max_log_file_size.

setParams

Mengatur parameter percakapan suara dalam format JSON. Panggil metode ini sebelum startDialog. Signature metode
public setParams(params: string): number
Deskripsi parameter
ParameterTipeDeskripsi
paramsstringParameter percakapan suara.

startDialog

Memulai percakapan. Signature metode
public startDialog(vad_mode: Constants.VadMode, dialog_params: string): number
Deskripsi parameter
ParameterTipeDeskripsi
vad_modeConstants.VadModeMode VAD. Tetap pada Constants.VadMode.TYPE_P2T.
dialog_paramsstringJika parameter apikey dalam parameter koneksi dan kontrol menggunakan API key sementara, Anda dapat memperbaruinya di sini saat kedaluwarsa.
Kontennya dalam format JSON:
{
 "apikey": "st-****"
}

stopDialog

Mengakhiri percakapan. Setelah Anda memanggil metode ini, server akan mengembalikan hasil percakapan akhir dan mengakhiri tugas. Signature metode
public stopDialog(): number

cancelDialog

Mengakhiri percakapan segera. Setelah Anda memanggil metode ini, tugas berakhir tanpa menunggu server mengembalikan hasil percakapan akhir. Signature metode
public cancelDialog(): number

dialogAction

Mengirimkan perintah tindakan percakapan selama interaksi untuk memperbarui perilaku runtime seperti konteks percakapan. Signature metode
public dialogAction(params: string): number
Deskripsi parameter
ParameterTipeDeskripsi
paramsstringString JSON yang digunakan untuk memperbarui perilaku runtime seperti konteks percakapan.
params.typeStringTetap "action".
params.commandStringPerintah runtime spesifik. Saat ini mendukung "function_call", "play_start", dan "play_over".
  • function_call: Perintah untuk memperbarui permintaan function call.
  • play_start: Saat AEC on-device digunakan, perintah ini memberi tahu pemutar AEC internal SDK untuk mulai memutar audio.
  • play_over: Saat AEC on-device digunakan, perintah ini memberi tahu pemutar AEC internal SDK bahwa pemutaran telah selesai.
params.contextStringSaat command adalah "function_call", memperbarui permintaan function call.
params.context.typeStringTipe event. Wajib saat command adalah "function_call".
  • conversation.item.create: Menyisipkan item percakapan ke dalam konteks percakapan secara manual. Dapat digunakan untuk menyuntikkan konteks historis, melengkapi informasi teks, atau menulis kembali hasil eksekusi alat Function Calling.
  • response.create: Setelah perintah conversation.item.create dikirim, perintah ini memicu putaran inferensi kedua.
params.context.itemobjectWajib saat params.context.type adalah conversation.item.create, menunjukkan item percakapan yang akan dibuat. Lihat berikut untuk detailnya.
params.context.responseobjectOpsional saat params.context.type adalah response.create, menunjukkan konfigurasi sesi default yang digunakan untuk menimpa putaran inferensi saat ini. Jika tidak ditentukan, konfigurasi sesi saat ini yang digunakan. Lihat berikut untuk detailnya.
Parameter context.item:
ParameterTipeDeskripsi
idStringOpsional. Pengidentifikasi unik item percakapan. Jika tidak ditentukan, dibuat secara otomatis oleh server. Jika ID yang ditentukan sudah ada dalam percakapan, kesalahan akan dikembalikan.
typeStringWajib. Tipe item percakapan. Nilai yang valid:
  • message: Pesan percakapan reguler.
  • function_call: Permintaan pemanggilan fungsi. Biasanya dibuat oleh server; klien juga dapat menggunakannya untuk melengkapi konteks historis.
  • function_call_output: Hasil eksekusi alat. Klien mengeksekusi alat setelah menerima function_call dan menulis kembali hasilnya dengan tipe ini.
roleStringWajib untuk tipe message. Peran pesan. Nilai yang valid: system, user, assistant.
contentarrayWajib untuk tipe message. Daftar konten pesan. Setiap elemen berisi type dan bidang data terkait.
Tipe konten yang didukung oleh setiap peran:
system
input_text: Pesan sistem, dengan bidang wajib text.
user
  • input_text: Input teks pengguna, bidang wajib text.
  • input_audio: Input audio pengguna, bidang wajib audio (dienkode Base64).
assistant
output_text: Output teks asisten, bidang wajib text.
call_idString(Wajib untuk tipe function_call / function_call_output )
Pengidentifikasi unik pemanggilan fungsi, digunakan untuk menghubungkan permintaan dan hasilnya.
nameString(Wajib untuk tipe function_call )
Nama fungsi yang akan dipanggil.
argumentsStringfunction_call type required)
Parameter pemanggilan fungsi, dalam format string JSON.
outputString(Wajib untuk tipe function_call_output )
Hasil alat, dalam format string JSON.
Parameter context.response:
ParameterTipeDeskripsi
modalitiesarrayString dalam format array, menentukan pengaturan modalitas output model. Nilai yang valid:
  • ["text"]: Hanya mengeluarkan teks.
  • ["audio", "text"] (nilai default): Mengeluarkan teks dan audio.
voicestringMenimpa suara TTS untuk giliran ini.
Contoh:
{
  "type": "action",
  "command": "function_call",
  "context": {
    "item": {
      "call_id": "call_xxxx",
      "output": "{\"city\":\"杭州\",\"condition\":\"晴\",\"temperature\":18}",
      "type": "function_call_output"
    },
    "type": "conversation.item.create"
  }
}

{
  "type": "action",
  "command": "function_call",
  "context": {
    "response": {
      "modalities": [
        "text",
        "audio"
      ]
    },
    "type": "response.create"
  }
}

updateAudio

Saat parameter audio_update_manually diatur ke "true", data perekaman tidak lagi diisi melalui onNuiNeedAudioData; sebagai gantinya, data didorong secara aktif melalui API ini. Signature metode
public updateAudio(data: ArrayBuffer, first_pack: boolean): number
Deskripsi parameter
ParameterTipeDeskripsi
dataArrayBufferData audio untuk di-push (PCM).
first_packbooleanApakah ini adalah paket audio pertama. SDK menghitung jumlah byte dari data.byteLength.

pushReferenceData (sesuai dengan updateRefAudio Android)

Saat parameter audio_update_manually diatur ke "true" dan kemampuan pembatalan gema AEC on-device diaktifkan, Anda wajib menggunakan API ini untuk mendorong data audio yang diputar oleh pemutar sebagai sinyal referensi. Signature metode
public pushReferenceData(data: ArrayBuffer, first_pack: boolean): number
Deskripsi parameter
ParameterTipeDeskripsi
dataArrayBufferData audio untuk di-push (PCM).
first_packbooleanApakah ini adalah paket audio pertama. SDK menghitung jumlah byte dari data.byteLength.

release · Lepaskan resource SDK

Melepaskan semua sumber daya internal SDK. Instans SDK menjadi tidak tersedia setelah panggilan ini. Untuk menggunakan SDK lagi, panggil initialize untuk menginisialisasi ulangnya. Signature metode
public release(): number

GetVersion

Mendapatkan informasi versi SDK saat ini. Signature metode
public GetVersion(): string
Deskripsi nilai kembalian Informasi versi SDK saat ini.

INativeNuiCallback: Mendengarkan callback

onNuiEventCallback: mendengarkan informasi event

Signature metode
onNuiEventCallback: (event: Constants.NuiEvent, resultCode: number, arg2: number,
                    kwsResult: KwsResult, asrResult: AsrResult) => void;
Deskripsi parameter
ParameterTipeDeskripsi
eventConstants.NuiEventEvent callback.
resultCodenumberHanya valid saat event EVENT_ASR_ERROR terjadi.
arg2numberParameter yang dicadangkan.
asrResultAsrResultHasil pengenalan ucapan.
kwsResultKwsResultFitur wake-up suara. Anda dapat mengabaikan parameter ini.

onNuiAudioStateChanged: mendengarkan status audio

SDK menggunakan callback ini untuk memberi tahu kapan harus memulai atau menghentikan perekaman. Signature metode
onNuiAudioStateChanged: (state: Constants.AudioState) => void
Deskripsi status AudioState
StatusDeskripsi
STATE_OPENInteraksi telah dimulai. Anda dapat membuka perangkat perekaman dan memulai perekaman.
STATE_PAUSEInteraksi telah berhenti. Anda dapat menghentikan perekaman.
STATE_CLOSEInstans SDK telah dilepaskan. Anda dapat menutup perangkat perekaman sepenuhnya.

onNuiAudioRMSChanged: mendengarkan volume perekaman

Mendengarkan volume data audio yang direkam, yang dapat digunakan untuk tampilan UI. Signature metode
onNuiAudioRMSChanged: (val: number) => number
Deskripsi parameter
ParameterTipeDeskripsi
valnumberNilai volume data audio yang direkam.

onNuiNeedAudioData: memasok data audio

Setelah percakapan dimulai, callback ini dipicu secara terus-menerus, dan Anda harus menyediakan data audio yang akan diproses di dalamnya. Anda dapat mengabaikan callback ini saat parameter audio_update_manually diatur ke "true". Signature metode
onNuiNeedAudioData: (buffer: ArrayBuffer) => number
Deskripsi parameter
ParameterTipeDeskripsi
bufferArrayBufferData audio yang akan diberikan. SDK menggunakan buffer.byteLength sebagai jumlah byte yang diminta.
Deskripsi nilai kembalian Jumlah byte aktual yang diisi.

onNuiAssistEventCallback: Data dan hasil informasi tambahan

Callback ini digunakan untuk menerima event tambahan dan data terkait dari dalam SDK. Signature metode
onNuiAssistEventCallback?: (event: Constants.NuiEvent, info: string, infoLen: number,
                            data: ArrayBuffer) => void;
Deskripsi parameter
ParameterTipeDeskripsi
eventConstants.NuiEventEvent NuiEvent.
infostringInformasi tambahan, biasanya berupa string JSON.
infoLennumberPanjang informasi tambahan.
dataArrayBufferData biner tambahan, seperti audio TTS yang dikembalikan oleh AI.
Catatan: Di HarmonyOS, callback ini bersifat opsional (?) dan dapat dibiarkan tidak diimplementasikan jika Anda tidak memerlukannya.

onNuiLogTrackCallback: mendengarkan log trace

Callback ini digunakan untuk menerima log terperinci dari dalam SDK, memfasilitasi pemecahan masalah dan debugging.
onNuiLogTrackCallback: (level: Constants.LogLevel, log: string) => void

NuiEvent: Tipe event

Dalam SDK HarmonyOS, tipe event didefinisikan oleh enumerasi Constants.NuiEvent. Berikut mencantumkan event yang terkait dengan percakapan suara realtime:
EventDeskripsi
EVENT_TRANSCRIBER_STARTEDTugas berhasil dimulai.
EVENT_VAD_STARTDipicu segera setelah tugas dimulai. Ini tidak berarti bahwa awal ucapan telah terdeteksi.
EVENT_VAD_ENDAkhir ucapan terdeteksi.
EVENT_ASR_PARTIAL_RESULTHasil pengenalan ucapan sementara.
EVENT_ASR_RESULTHasil pengenalan ucapan yang lengkap.
EVENT_ASR_ERRORTerjadi kesalahan selama percakapan suara.
EVENT_MIC_ERRORDipicu ketika tidak ada data audio yang diterima selama dua detik berturut-turut.
EVENT_SENTENCE_STARTAwal kalimat telah terdeteksi.
EVENT_SENTENCE_ENDAkhir kalimat terdeteksi dan hasil pengenalan lengkap dikembalikan.
EVENT_TRANSCRIBER_COMPLETEPercakapan suara berakhir.
EVENT_AUDIO_TRANSCRIPTIONEvent inkremental subjudul teks dalam mode audio, yang mengembalikan fragmen subjudul secara streaming.
EVENT_AUDIO_TRANSCRIPTION_COMPLETEDEvent penyelesaian output subjudul dalam mode audio.
EVENT_OTHER_RESULTInformasi event lain yang belum diklasifikasikan, misalnya hasil pengembalian function_call.
EVENT_ASR_TTS_STARTAI mulai mengembalikan data TTS.
EVENT_ASR_TTS_DATAData TTS yang dikembalikan oleh AI.
EVENT_ASR_TTS_COMPLETEAI selesai mengembalikan data TTS.
EVENT_RESULT_TRANSLATEDHasil terjemahan sementara.
EVENT_RESULT_TRANSLATED_ENDOutput hasil terjemahan telah selesai.
EVENT_AEC_DATAData audio yang diproses oleh AEC.