4.5. naia-model-dev

Panduan pengembang untuk menggunakan model Naia dari kode. Setelah menjalankan model melalui 4.4 Unduh Model Naia, gunakan API yang kompatibel dengan OpenAI yang dilayani secara lokal (tanpa gateway, tanpa antrean) apa adanya. Dengan SDK atau alat OpenAI apa pun, Anda cukup mengarahkan baseURL ke model ini.

Bukan hanya untuk naia-os/antarmuka — kode apa pun yang berbicara OpenAI Realtime/Chat/Audio/Embeddings terhubung apa adanya, dan Anda dapat membangun serta menjalankan aplikasi baru di atas model ini.

1. Hubungkan · autentikasi

• Basis REST: http://<host>:8892/v1 (127.0.0.1 di PC yang sama)
• Realtime (WS): ws://<host>:8892/v1/realtime (ws://<host>:8892 polos juga berfungsi — jalur /v1/realtime + model default diterapkan otomatis)
• Koneksi: secara lokal (127.0.0.1) / Tailscale, tidak diperlukan autentikasi — kontainer memverifikasi lisensinya sendiri. Klien yang memerlukan kolom kunci (OpenAI SDK dll.) dapat memberikan nilai apa pun (naia). Saat mengekspos dari jarak jauh, pasang Tailscale/VPN §4.4 di depannya.

🔑 Satu kunci — kunci langganan

• Kunci langganan — kunci langganan yang Anda dapatkan dari portal. Digunakan hanya saat menjalankan kontainer (aktivasi) (-e NAIA_ACCOUNT_TOKEN=<subscription-key>). Kunci ini memeriksa langganan dan memperoleh lisensi dengan batas waktu (sertifikat).
• Tidak ada kunci koneksi terpisah. Setelah diaktifkan, kontainer memverifikasi secara lokal sendiri dengan sertifikat, sehingga klien (naia-os, OpenAI SDK) cukup terhubung melalui URL — 127.0.0.1 di PC yang sama, atau Tailscale/VPN (§4.4) dari perangkat lain. Kontainer tidak memanggil gateway per koneksi.
• api_key pada contoh di bawah adalah placeholder (OpenAI SDK memerlukan kolom ini) — kontainer offline tidak memeriksanya, sehingga nilai apa pun seperti "naia" berfungsi.

2. Endpoint (kompatibel dengan OpenAI)

Chat (curl):

curl -s http://127.0.0.1:8892/v1/chat/completions \
  -H "Authorization: Bearer naia" -H "Content-Type: application/json" \
  -d '{"model":"naia-0.9-omni-24g","messages":[{"role":"user","content":"hi"}],"stream":false}'

OpenAI SDK (Python) — cukup ganti baseURL:

from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8892/v1", api_key="naia")
print(client.chat.completions.create(
    model="naia-0.9-omni-24g",
    messages=[{"role": "user", "content": "hi"}],
).choices[0].message.content)

Transkripsi (STT):

curl -s http://127.0.0.1:8892/v1/audio/transcriptions \
  -H "Authorization: Bearer naia" \
  -F file=@sample.wav -F model=naia-0.9-omni-24g

3. Suara real-time — alur koneksi (WS)

Alur yang sama dengan yang digunakan 4.3 demo langsung. (Offline langsung mulai, tanpa antrean/penugasan gateway.)

1. Hubungkan — buka ws://<host>:8892.

2. Frame pertama (autentikasi · bahasa) — WebSocket browser tidak dapat mengirim header, jadi kirim sebagai pesan pertama:

   Copy

   { "setup": { "apiKey": "naia", "locale": "en" } }
   

3. Saat server mengirim session.created, konfigurasikan sesi dengan session.update:

   Copy

   {
     "type": "session.update",
     "session": {
       "modalities": ["text", "audio"],
       "input_audio_format": "pcm16",
       "output_audio_format": "pcm16",
       "instructions": "<persona instructions>",
       "turn_detection": { "type": "server_vad" },
       "input_audio_transcription": { "language": "en" },
       "ref_audio_url": "<URL of a voice sample to mimic (optional)>"
     }
   }
   

4. Pertukaran

   Klien → Server
   Masukan suara	{"type":"input_audio_buffer.append","audio":"<base64 PCM16 24kHz>"} (server VAD mendeteksi akhir ucapan)
   Masukan teks	conversation.item.create lalu response.create
   Barge-in	response.cancel

   Server → Klien
   response.audio.delta	potongan audio base64 PCM16 24kHz
   response.audio_transcript.delta / response.text.delta	teks jawaban (streaming)
   conversation.item.input_audio_transcription.completed	transkrip ucapan Anda
   emotion.updated	tag emosi / prosodi (§5)
   response.done	akhir satu giliran

4. Bahasa — 30 bahasa (default = auto/global)

Model mendukung 30 bahasa (Arab, Burma, Mandarin, Denmark, Belanda, Inggris, Finlandia, Prancis, Jerman, Yunani, Ibrani, Hindi, Indonesia, Italia, Jepang, Khmer, Korea, Lao, Melayu, Norwegia, Polandia, Portugis, Rusia, Spanyol, Swahili, Swedia, Tagalog, Thai, Turki, Vietnam).

• Default (tidak diatur) = global/auto — model mendeteksi bahasa yang Anda gunakan dan menjawab dalam bahasa tersebut (per giliran).
• Untuk menetapkan bahasa tertentu, berikan kode ISO-639-1 (misalnya ko/en/ja) di setup.locale atau di input_audio_transcription.language pada session.update.

5. Format keluaran (emosi · tag prosodi)

Format keluaran disetel untuk percakapan suara — jika klien mengetahuinya, klien dapat berekspresi lebih kaya.

• Tag prosodi: teks jawaban berisi tag dalam kurung siku berbahasa Inggris huruf kecil seperti [laughing], [sigh], [breath], [pause], [hesitation] yang disisipkan di tempat emosi berubah (untuk prosodi ucapan). Model diinstruksikan untuk tidak menggunakan tag Korea seperti [웃음], arahan panggung dalam tanda kurung seperti (smiling), atau tanda bintang seperti *smiles*. Kosakata yang dikenal: laughing/laugh/laughter/chuckle/giggle · sigh/exhale · breath/inhale · pause · hesitation · gasp/cough/sneeze/yawn/sniff/hum · cry/sob/moan/whisper/shout/cheer (tag lain diteruskan apa adanya).
• Untuk setiap tag, server mengirim satu peristiwa emotion.updated 1:1 (state == nama tag, huruf kecil):
  Copy

  { "type": "emotion.updated", "state": "laughing", "tag": "[laughing]", "known": true }
  

• Jalur TTS mempertahankan tag dan memasukkannya ke sintesis untuk prosodi ucapan, sementara chat text.delta mengirim teks bersih dengan tag dihapus. (Tanpa emoji, markdown, atau narasi diri dalam tanda kurung pada keluaran.)
• Pemetaan di klien (referensi naia-os): petakan emotion.updated.state (tag prosodi) ke ekspresi avatar — laughing/chuckle/giggle/cheer → happy, sigh/exhale/cry/sob → sad, gasp → surprised, shout → angry, hesitation → think. Prosodi non-emosional seperti breath·pause tidak mengubah ekspresi (pertahankan yang sebelumnya — agar avatar tidak berkedip ke netral pada setiap napas).
• Disarankan penanganan yang tangguh: keluaran LLM tidak selalu tepat. Utamakan emotion.updated, tetapi jika hilang, deteksi otomatis tag dalam transkrip itu sendiri (huruf besar [HAPPY] / tag prosodi huruf kecil) atau arahan panggung yang bocor ((smiles)·*sigh*) dan cerminkan ke ekspresi; jika tidak ada petunjuk, pertahankan ekspresi saat ini (lih. naia-os shell/src/lib/vrm/expression.ts extractExpression).

6. Mengganti model percakapan · menaikkan versi baru (operasi)

Ini panduan terperinci untuk mengganti langsung dari baris perintah. Pelanggan langganan pribadi pun dapat menggunakannya apa adanya (tanpa perlu kunci), dan disertakan juga opsi penguncian untuk operasi bersama/kios. Ringkasan mudahnya ada di 4.4 Offline.

6.1 Mengganti model percakapan (sejak 0.91)

Biarkan kontainer apa adanya dan ganti hanya model yang menangani percakapan saat berjalan. Suara (berbicara · mendengar), watermark, dan autentikasi langganan tetap dipertahankan.

Tiga hal yang perlu diketahui terlebih dahulu:

1. Model default adalah LLM terbuka bawaan. Anda dapat menggantinya dan kembali ke default kapan saja.
2. Model yang akan dinaikkan harus berupa format GGUF. Selain itu, karena fitur suara menggunakan memori sekitar 10GB, model percakapan dapat naik hingga sekitar 14GB. Model yang lebih besar akan ditolak, dan jika gagal saat dinaikkan, sistem otomatis kembali ke model yang sedang dipakai (percakapan tidak terputus).
3. Pelanggan langganan pribadi tidak memerlukan kunci terpisah. Karena autentikasi langganan (lisensi) di mesin Anda sendiri sudah menjadi izinnya, cukup ganti dengan perintah di bawah — sama seperti suara yang tidak memerlukan kunci. (Hanya pada kotak bersama · kios yang dipakai banyak orang, operator dapat memasang penguncian dengan -e NAIA_ADMIN_KEY=kata_sandi_yang_ditetapkan saat menjalankan, dan saat itu sertakan -H "Authorization: Bearer kata_sandi_yang_ditetapkan" pada permintaan.)

Latihan — tetapkan dulu alamatnya:

BASE=http://127.0.0.1:8892     # jika dilakukan dari perangkat lain, gunakan alamat https di §4.4 (mis. ...:8443)

① Lihat model apa yang sedang dipakai sekarang dan berapa memori yang tersisa:

curl -s $BASE/admin/llm/status

② Ganti modelnya — cukup ganti bagian model di dalam tanda kutip lalu tempel. Tempelkan apa adanya alamat kartu model HuggingFace (https://huggingface.co/Qwen/Qwen2.5-7B-Instruct-GGUF) atau id-nya (Qwen/Qwen2.5-7B-Instruct-GGUF):

curl -s -X POST $BASE/admin/llm/swap \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen2.5-7B-Instruct-GGUF","pull":true}'

Awalan hf.co/ dan kualitas (quant) ditambahkan otomatis (default Q4_K_M). Jika ingin kualitas tertentu, tuliskan di belakang seperti Qwen/Qwen2.5-7B-Instruct-GGUF:Q5_K_M. Saat pertama kali mengunduh model, prosesnya memakan waktu beberapa puluh detik hingga beberapa menit.

②-offline — mengganti dengan file GGUF milik Anda sendiri, tanpa internet. Jika tidak ada internet seperti pada pameran · konsultasi, jangan mengunduh dari HuggingFace, melainkan daftarkan file GGUF yang sudah Anda miliki untuk menggantinya. (Aturan pembeda: jika nama memiliki garis miring seperti organisasi/repositori maka itu HuggingFace online, sedangkan nama sederhana tanpa garis miring berarti model lokal.)

Salin dan tempel satu baris demi satu. Tuliskan nama yang diinginkan pada bagian model_saya, dan nama file sebenarnya pada bagian model_saya.gguf:

podman cp ./model_saya.gguf naia-omni:/app/models/model_saya.gguf

podman exec naia-omni sh -lc 'printf "FROM /app/models/model_saya.gguf\n" > /tmp/Modelfile && ollama create model_saya -f /tmp/Modelfile'

curl -s -X POST $BASE/admin/llm/swap -H "Content-Type: application/json" -d '{"model":"model_saya:latest","pull":false}'

⚠️ GGUF yang Anda konversi · gabung sendiri mungkin tidak menyertakan templat chat sehingga jawabannya jadi ngawur/terpotong. Dalam kasus itu, tambahkan templat chat seri model (TEMPLATE) dan token penghenti (PARAMETER stop) pada Modelfile di langkah ②, lalu daftarkan — detail untuk pengembang ada di [implementasi referensi §7]. (GGUF Instruct resmi dari HuggingFace biasanya sudah menyertakannya sehingga bisa langsung dipakai.)

③ Kembali ke model default:

curl -s -X POST $BASE/admin/llm/restore

Untuk kotak bersama · kios (jika operator memasang NAIA_ADMIN_KEY), tambahkan -H "Authorization: Bearer kata_sandi_yang_ditetapkan" pada setiap perintah di atas. Pelanggan langganan pribadi tidak memerlukannya.

Setelah diganti pun, aplikasi seperti naia-os tetap terhubung ke alamat yang sama apa adanya (tidak perlu menyambung ulang). Jika ingin tetap memulai dengan model itu bahkan setelah restart atau pembaruan, tetapkan model default saat menjalankan kontainer dengan -e NAIA_LLM_MODEL=Qwen/Qwen2.5-7B-Instruct-GGUF.

6.2 Memperbarui ke versi baru

Saat versi baru keluar, ganti hanya image (versi) dan biarkan langganan · pengaturan apa adanya. Saat pertama kali menyalakan versi baru, kontainer mengautentikasi ulang otomatis melalui internet (langganan · perangkat tetap seperti sebelumnya — tidak perlu memasukkan kunci secara manual lagi). Karena itu, saat memperbarui pastikan terhubung ke internet.

podman pull ghcr.io/nextain/naia-0.9-omni-24g:latest      # unduh versi terbaru
podman stop naia-omni && podman rm naia-omni      # hanya bersihkan kontainer (lihat catatan di bawah)
# Jalankan kembali persis perintah run yang dipakai saat instalasi pertama — cukup pasang volume lisensi yang sama.

⚠️ Jangan menekan "lepas perangkat (release)" saat memperbarui. Pelepasan hanya digunakan saat memindahkan komputer yang dipakai ke komputer lain. Jika Anda melepas saat hendak memperbarui, Anda harus mengautentikasi ulang dari awal. Pembaruan cukup membiarkan volume lisensi apa adanya untuk mempertahankan langganan dan pendaftaran perangkat.

Pengguna yang sudah terautentikasi sebelumnya cukup mengunduh versi terbaru lalu menyalakannya kembali seperti di atas, dan langsung beralih ke versi baru yang bisa mengganti model (autentikasi tetap dipertahankan). Untuk mengunduh versi tertentu secara spesifik, gunakan nomor versi seperti :0.91 alih-alih :latest.

7. Lihat juga

• Implementasi referensi / kode contoh (sumber terbuka): klien suara naia-os shell/src/lib/voice/ (Apache 2.0) — berisi klien sebenarnya yang berbicara dengan API ini (naia-omni.ts) dan penanganan emosi/prosodi (emotion-tags.ts; pemetaan ekspresi & ekstraksi tangguh di vrm/expression.ts). Gunakan sebagai titik awal untuk menguji model baru dan membangun aplikasi Tauri. Coba langsung di 4.3 demo langsung.
• Jajaran & harga: 4.1 Harga Model
• Cloud (direncanakan): 4.6 Online