naia-model-dev — Naia मैनुअल

कोड से Naia मॉडल का उपयोग करने के लिए डेवलपर गाइड। मॉडल को 4.4 Naia मॉडल डाउनलोड के माध्यम से चलाने के बाद, स्थानीय रूप से सर्व की गई OpenAI-संगत API का (कोई गेटवे नहीं, कोई कतार नहीं) उपयोग ज्यों का त्यों करें। किसी भी OpenAI SDK या टूल के साथ, आप केवल baseURL को इस मॉडल की ओर इंगित करते हैं।

केवल naia-os/शेल तक सीमित नहीं — कोई भी कोड जो OpenAI Realtime/Chat/Audio/Embeddings बोलता है ज्यों का त्यों जुड़ जाता है, और आप इस मॉडल के ऊपर नए अनुप्रयोग बना और चला सकते हैं।

1. कनेक्ट · प्रमाणीकरण

REST बेस: http://<host>:8892/v1 (समान PC पर 127.0.0.1)
Realtime (WS): ws://<host>:8892/v1/realtime (नंगा ws://<host>:8892 भी काम करता है — पथ /v1/realtime + डिफ़ॉल्ट मॉडल स्वतः लागू)
कनेक्ट: स्थानीय (127.0.0.1) / Tailscale पर, किसी प्रमाणीकरण की आवश्यकता नहीं — कंटेनर अपने लाइसेंस का स्वयं सत्यापन करता है। जिन क्लाइंट्स को कुंजी फ़ील्ड चाहिए (OpenAI SDK आदि) वे कोई भी मान (naia) पास कर सकते हैं। दूरस्थ रूप से उजागर करते समय, उसके सामने §4.4 Tailscale/VPN लगाएँ।

🔑 एक कुंजी — सब्सक्रिप्शन कुंजी

सब्सक्रिप्शन कुंजी — वह सब्सक्रिप्शन कुंजी जो आपको पोर्टल से मिलती है। उपयोग केवल कंटेनर रन टाइम पर (सक्रियण के समय) (-e NAIA_ACCOUNT_TOKEN=<subscription-key>)। यह सब्सक्रिप्शन की जाँच करती है और एक समय-सीमित लाइसेंस (प्रमाणपत्र) प्राप्त करती है।
कोई अलग कनेक्शन कुंजी नहीं है। सक्रिय होने के बाद, कंटेनर प्रमाणपत्र से स्थानीय रूप से स्वयं सत्यापन करता है, इसलिए क्लाइंट्स (naia-os, OpenAI SDK) को बस URL द्वारा कनेक्ट करना है — समान PC पर 127.0.0.1, या दूसरे डिवाइस से Tailscale/VPN (§4.4)। यह प्रति-कनेक्शन गेटवे को कॉल नहीं करता।
नीचे दिए गए उदाहरणों में api_key एक प्लेसहोल्डर है (OpenAI SDK को इस फ़ील्ड की आवश्यकता है) — ऑफ़लाइन कंटेनर इसे जाँचता नहीं है, इसलिए "naia" जैसा कोई भी मान काम करता है।

2. एंडपॉइंट (OpenAI-संगत)

एंडपॉइंट	उपयोग
`GET /health`	तत्परता `{"ready":true,"services":{tts,stt,llm},"vad":true}` (कोई प्रमाणीकरण नहीं)
`GET /v1/models`	मॉडल सूची
`WS /v1/realtime`	रीयल-टाइम वॉयस सत्र (VAD, बार्ज-इन, भावना)
`POST /v1/chat/completions`	चैट (स्ट्रीमिंग)
`POST /v1/audio/speech`	टेक्स्ट-टू-स्पीच (TTS)
`POST /v1/audio/transcriptions`	स्पीच-टू-टेक्स्ट (STT)
`POST /v1/embeddings`	एम्बेडिंग्स

चैट (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) — बस 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)

ट्रांसक्रिप्शन (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. रीयल-टाइम वॉयस — कनेक्शन प्रवाह (WS)

वही प्रवाह जो 4.3 लाइव डेमो उपयोग करता है। (ऑफ़लाइन तुरंत शुरू होता है, बिना किसी गेटवे कतार/असाइनमेंट के।)

कनेक्ट — ws://<host>:8892 खोलें।
पहला फ़्रेम (प्रमाणीकरण · भाषा) — ब्राउज़र WebSockets हेडर नहीं भेज सकते, इसलिए पहले संदेश के रूप में भेजें:
```
{ "setup": { "apiKey": "naia", "locale": "en" } }
```

जब सर्वर session.created भेजे, तो सत्र को session.update से कॉन्फ़िगर करें:

{
  "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)>"
  }
}

आदान-प्रदान

क्लाइंट → सर्वर
वॉयस इनपुट	`{"type":"input_audio_buffer.append","audio":"<base64 PCM16 24kHz>"}` (सर्वर VAD भाषण के अंत का पता लगाता है)
टेक्स्ट इनपुट	`conversation.item.create` फिर `response.create`
बार्ज-इन	`response.cancel`

सर्वर → क्लाइंट
`response.audio.delta`	base64 PCM16 24kHz ऑडियो खंड
`response.audio_transcript.delta` / `response.text.delta`	उत्तर पाठ (स्ट्रीमिंग)
`conversation.item.input_audio_transcription.completed`	आपके भाषण का ट्रांसक्रिप्ट
`emotion.updated`	भावना / प्रोसोडी टैग (§5)
`response.done`	एक टर्न का अंत

4. भाषाएँ — 30 भाषाएँ (डिफ़ॉल्ट = auto/global)

मॉडल 30 भाषाओं का समर्थन करता है (अरबी, बर्मी, चीनी, डेनिश, डच, अंग्रेज़ी, फ़िनिश, फ़्रेंच, जर्मन, ग्रीक, हिब्रू, हिंदी, इंडोनेशियाई, इतालवी, जापानी, ख़मेर, कोरियाई, लाओ, मलय, नॉर्वेजियन, पोलिश, पुर्तगाली, रूसी, स्पेनिश, स्वाहिली, स्वीडिश, टैगालॉग, थाई, तुर्की, वियतनामी)।

डिफ़ॉल्ट (अनसेट) = global/auto — यह उस भाषा का पता लगाता है जो आपने बोली और उसी भाषा में उत्तर देता है (प्रति टर्न)।
किसी विशिष्ट भाषा को पिन करने के लिए, setup.locale में या session.update के input_audio_transcription.language में एक ISO-639-1 कोड (जैसे ko/en/ja) दें।

5. आउटपुट प्रारूप (भावना · प्रोसोडी टैग)

आउटपुट प्रारूप वॉयस संवाद के लिए ट्यून किया गया है — यदि क्लाइंट इसे जानता है, तो वह अधिक समृद्धता से अभिव्यक्त कर सकता है।

प्रोसोडी टैग: उत्तर पाठ में जहाँ भावना बदलती है वहाँ [laughing], [sigh], [breath], [pause], [hesitation] जैसे लोअरकेस अंग्रेज़ी ब्रैकेट टैग मिश्रित होते हैं (भाषण प्रोसोडी के लिए)। मॉडल को निर्देश है कि वह [웃음] जैसे कोरियाई टैग, (smiling) जैसे कोष्ठक में मंच-निर्देश, या *smiles* जैसे तारांकन का उपयोग न करे। ज्ञात शब्दावली: laughing/laugh/laughter/chuckle/giggle · sigh/exhale · breath/inhale · pause · hesitation · gasp/cough/sneeze/yawn/sniff/hum · cry/sob/moan/whisper/shout/cheer (अन्य टैग ज्यों के त्यों पास किए जाते हैं)।
प्रत्येक टैग के लिए, सर्वर 1:1 emotion.updated इवेंट भेजता है (state == टैग नाम, लोअरकेस):
```
{ "type": "emotion.updated", "state": "laughing", "tag": "[laughing]", "known": true }
```
TTS पथ टैग रखता है और उन्हें भाषण प्रोसोडी के लिए संश्लेषण में फीड करता है, जबकि चैट text.delta टैग हटाकर स्वच्छ पाठ भेजता है। (आउटपुट में कोई इमोजी, markdown, या कोष्ठक में स्व-कथन नहीं।)
क्लाइंट मैपिंग (naia-os संदर्भ): emotion.updated.state (प्रोसोडी टैग) को अवतार अभिव्यक्तियों से मैप करें — laughing/chuckle/giggle/cheer → happy, sigh/exhale/cry/sob → sad, gasp → surprised, shout → angry, hesitation → think। breath·pause जैसा गैर-भावनात्मक प्रोसोडी अभिव्यक्ति नहीं बदलता (पिछली बनाए रखें — ताकि हर साँस पर यह न्यूट्रल पर न झपके)।
मज़बूत हैंडलिंग अनुशंसित: LLM आउटपुट हमेशा सटीक नहीं होता। emotion.updated को प्राथमिकता दें, पर यदि यह गायब हो, तो ट्रांसक्रिप्ट में ही टैग का स्वतः पता लगाएँ (अपरकेस [HAPPY] / लोअरकेस प्रोसोडी टैग) या लीक हुए मंच-निर्देश ((smiles)·*sigh*) और उन्हें अभिव्यक्ति में दर्शाएँ; यदि कोई संकेत न हो, तो वर्तमान अभिव्यक्ति बनाए रखें (तुलना करें naia-os shell/src/lib/vrm/expression.ts extractExpression)।

6. संवाद मॉडल बदलना · नया संस्करण अपलोड करना (संचालन)

कमांड लाइन से सीधे बदलने की विस्तृत मार्गदर्शिका। व्यक्तिगत सब्सक्राइबर इसे ज्यों का त्यों उपयोग कर सकते हैं (कोई कुंजी आवश्यक नहीं), और इसमें साझा/कियोस्क संचालन के लिए लॉक विकल्प भी शामिल हैं। आसान सारांश के लिए 4.4 ऑफ़लाइन देखें।

6.1 संवाद मॉडल बदलना (0.91 से)

कंटेनर को वैसा ही छोड़ते हुए, चलते-चलते केवल वह मॉडल बदलें जो संवाद संभालता है। आवाज़ (बोलना · सुनना), वॉटरमार्क और सब्सक्रिप्शन प्रमाणीकरण वैसे ही बने रहते हैं।

पहले तीन बातें जान लें:

डिफ़ॉल्ट मॉडल एक बिल्ट-इन ओपन LLM है। बदलने के बाद आप किसी भी समय डिफ़ॉल्ट पर वापस लौट सकते हैं।
जो नया मॉडल आप अपलोड करें वह GGUF प्रारूप में होना चाहिए। और चूँकि वॉयस फ़ंक्शन लगभग 10GB मेमोरी का उपयोग करता है, संवाद मॉडल लगभग 14GB तक जा सकता है। बड़े मॉडल अस्वीकृत हो जाते हैं, और यदि अपलोड के दौरान कुछ विफल हो भी जाए, तो यह स्वतः उस मॉडल पर वापस लौट जाता है जिसका आप उपयोग कर रहे थे (संवाद बाधित नहीं होता)।
व्यक्तिगत सब्सक्राइबर्स को अलग कुंजी की आवश्यकता नहीं है। आपकी अपनी मशीन का सब्सक्रिप्शन प्रमाणीकरण (लाइसेंस) ही आपका अधिकार है, इसलिए बस नीचे दिए गए कमांड से बदल दें — ठीक वैसे ही जैसे आवाज़ के लिए कोई कुंजी आवश्यक नहीं है। (केवल साझा/कियोस्क बॉक्स पर जहाँ कई लोग साथ उपयोग करते हैं, संचालक रन टाइम पर -e NAIA_ADMIN_KEY=आपका_चुना_हुआ_पासवर्ड से लॉक लगा सकता है, और तब अनुरोधों के साथ -H "Authorization: Bearer आपका_चुना_हुआ_पासवर्ड" भी भेजा जाता है।)

अभ्यास — बस पता तय कर लें:

BASE=http://127.0.0.1:8892     # दूसरे डिवाइस पर हो तो §4.4 का https पता (जैसे ...:8443)

① देखें कि अभी कौन-सा मॉडल है और कितनी मेमोरी बची है:

curl -s $BASE/admin/llm/status

② मॉडल बदलें — डबल कोट्स के अंदर केवल मॉडल वाला हिस्सा बदलकर पेस्ट करें। HuggingFace मॉडल कार्ड का पता (https://huggingface.co/Qwen/Qwen2.5-7B-Instruct-GGUF) या उसकी id (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}'

hf.co/ उपसर्ग या क्वांट (quant) स्वतः जुड़ जाता है (डिफ़ॉल्ट Q4_K_M है)। यदि कोई विशिष्ट क्वांट चाहिए, तो Qwen/Qwen2.5-7B-Instruct-GGUF:Q5_K_M की तरह अंत में लिखें। मॉडल पहली बार लाने में कुछ दसियों सेकंड से कुछ मिनट लग सकते हैं।

②-ऑफ़लाइन — इंटरनेट के बिना, अपने पास मौजूद GGUF फ़ाइल से बदलना। प्रदर्शनी · परामर्श जैसी स्थितियों में जहाँ इंटरनेट नहीं है, HuggingFace से लाने के बजाय पहले से मौजूद GGUF फ़ाइल को पंजीकृत कर बदलें। (पहचान का नियम: यदि नाम में संगठन/रिपॉज़िटरी की तरह स्लैश है तो HuggingFace ऑनलाइन, बिना स्लैश का सरल नाम हो तो लोकल मॉडल।)

एक-एक पंक्ति कॉपी कर पेस्ट करें। mymodel की जगह अपना मनचाहा नाम, और mymodel.gguf की जगह वास्तविक फ़ाइल नाम लिखें:

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

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

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

⚠️ स्वयं रूपांतरित · मर्ज की गई GGUF में चैट टेम्पलेट छूट सकता है, जिससे उत्तर अनर्गल हो सकते हैं या कट सकते हैं। उस स्थिति में चरण 2 के Modelfile में मॉडल परिवार का चैट टेम्पलेट (TEMPLATE) और स्टॉप टोकन (PARAMETER stop) जोड़कर पंजीकृत करें — डेवलपर के लिए विवरण [संदर्भ कार्यान्वयन §7] में। (HuggingFace आधिकारिक Instruct GGUF में यह आमतौर पर अंतर्निहित होता है, इसलिए ज्यों का त्यों उपयोग कर सकते हैं।)

③ डिफ़ॉल्ट मॉडल पर वापस लौटें:

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

साझा/कियोस्क बॉक्स (जहाँ संचालक ने NAIA_ADMIN_KEY लगाया है) पर ऊपर के प्रत्येक कमांड में -H "Authorization: Bearer आपका_चुना_हुआ_पासवर्ड" जोड़ें। व्यक्तिगत सब्सक्राइबर्स को इसकी आवश्यकता नहीं है।

बदलने के बाद भी naia-os जैसे ऐप्स को उसी पते से ज्यों का त्यों कनेक्ट करें (फिर से कनेक्ट करने की आवश्यकता नहीं)। यदि आप चाहते हैं कि पुनः आरंभ या अपडेट के बाद भी यह उसी मॉडल से शुरू हो, तो कंटेनर चलाते समय -e NAIA_LLM_MODEL=Qwen/Qwen2.5-7B-Instruct-GGUF से डिफ़ॉल्ट मॉडल निर्दिष्ट कर दें।

6.2 नए संस्करण में अपडेट करना

जब नया संस्करण आए, तो केवल इमेज (संस्करण) बदलें और सब्सक्रिप्शन · सेटिंग्स वैसी ही छोड़ दें। नया संस्करण पहली बार चालू करते समय कंटेनर इंटरनेट के माध्यम से स्वतः पुनः प्रमाणीकरण करता है (मौजूदा सब्सक्रिप्शन · डिवाइस वैसा ही — कुंजी हाथ से फिर डालने की आवश्यकता नहीं)। इसलिए अपडेट करते समय इंटरनेट से जुड़े रहना आवश्यक है।

podman pull ghcr.io/nextain/naia-0.9-omni-24g:latest      # नवीनतम संस्करण लाएँ
podman stop naia-omni && podman rm naia-omni      # केवल कंटेनर हटाएँ (नीचे सावधानी देखें)
# पहली बार इंस्टॉल करते समय जिस रन कमांड का उपयोग किया था, उसे ज्यों का त्यों फिर से चलाएँ — बस वही लाइसेंस वॉल्यूम जोड़ दें, और हो गया।

⚠️ अपडेट करते समय "डिवाइस रिलीज़ (release)" न दबाएँ। रिलीज़ केवल तब उपयोग किया जाता है जब आप जिस कंप्यूटर का उपयोग कर रहे थे उसे दूसरे कंप्यूटर पर ले जाते हैं। अपडेट करते हुए रिलीज़ कर दिया तो शुरू से फिर प्रमाणीकरण करना पड़ेगा। अपडेट में केवल लाइसेंस वॉल्यूम वैसा ही रखने पर सब्सक्रिप्शन और डिवाइस पंजीकरण बना रहता है।

पहले से प्रमाणित किए हुए उपयोगकर्ता बस ऊपर बताए अनुसार नवीनतम संस्करण लाकर फिर से चालू कर देने से, मॉडल बदलने योग्य नए संस्करण पर ज्यों का त्यों चले जाते हैं (प्रमाणीकरण बना रहता है)। किसी विशिष्ट संस्करण को खासतौर पर लाना हो, तो :latest के बजाय :0.91 की तरह संस्करण संख्या लिखें।

7. यह भी देखें

संदर्भ कार्यान्वयन / नमूना कोड (ओपन सोर्स): naia-os का वॉयस क्लाइंट shell/src/lib/voice/ (Apache 2.0) — इसमें वह वास्तविक क्लाइंट है जो इस API से बात करता है (naia-omni.ts) और भावना/प्रोसोडी हैंडलिंग (emotion-tags.ts; अभिव्यक्ति मैपिंग और मज़बूत निष्कर्षण vrm/expression.ts में)। इसे नए मॉडल परीक्षण और Tauri ऐप बनाने के लिए शुरुआती बिंदु के रूप में उपयोग करें। इसे 4.3 लाइव डेमो पर लाइव आज़माएँ।
लाइनअप और मूल्य निर्धारण: 4.1 मॉडल मूल्य निर्धारण
क्लाउड (योजनाबद्ध): 4.6 ऑनलाइन

4.5. naia-model-dev