# User Guide (Kiswahili) 🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/USER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USER_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/USER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USER_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/USER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USER_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/USER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/USER_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/USER_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/USER_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/USER_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/USER_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/USER_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/USER_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/USER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USER_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/USER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USER_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/USER_GUIDE.md) --- 🌐 **Languages:** 🇺🇸 [English](../../../../guides/USER_GUIDE.md) · 🇪🇹 [am](../../../am/docs/guides/USER_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/guides/USER_GUIDE.md) · 🇦🇿 [az](../../../az/docs/guides/USER_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/guides/USER_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/guides/USER_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/guides/USER_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/guides/USER_GUIDE.md) · 🇩🇰 [da](../../../da/docs/guides/USER_GUIDE.md) · 🇩🇪 [de](../../../de/docs/guides/USER_GUIDE.md) · 🇬🇷 [el](../../../el/docs/guides/USER_GUIDE.md) · 🇪🇸 [es](../../../es/docs/guides/USER_GUIDE.md) · 🇪🇪 [et](../../../et/docs/guides/USER_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/guides/USER_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/guides/USER_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/guides/USER_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/guides/USER_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/guides/USER_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/guides/USER_GUIDE.md) · 🇮🇱 [he](../../../he/docs/guides/USER_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/guides/USER_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/guides/USER_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/guides/USER_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/guides/USER_GUIDE.md) · 🇮🇩 [id](../../../id/docs/guides/USER_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/guides/USER_GUIDE.md) · 🇮🇹 [it](../../../it/docs/guides/USER_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/guides/USER_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/guides/USER_GUIDE.md) · 🇰🇭 [km](../../../km/docs/guides/USER_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/guides/USER_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/guides/USER_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/guides/USER_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/guides/USER_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/guides/USER_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/guides/USER_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/guides/USER_GUIDE.md) · 🇲🇲 [my](../../../my/docs/guides/USER_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/guides/USER_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/guides/USER_GUIDE.md) · 🇳🇴 [no](../../../no/docs/guides/USER_GUIDE.md) · 🇮🇳 [or](../../../or/docs/guides/USER_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/guides/USER_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/guides/USER_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/guides/USER_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/guides/USER_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/guides/USER_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/guides/USER_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/guides/USER_GUIDE.md) · 🇱🇰 [si](../../../si/docs/guides/USER_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/guides/USER_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/guides/USER_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/guides/USER_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/guides/USER_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/guides/USER_GUIDE.md) · 🇮🇳 [te](../../../te/docs/guides/USER_GUIDE.md) · 🇹🇭 [th](../../../th/docs/guides/USER_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/guides/USER_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/guides/USER_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/guides/USER_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/guides/USER_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/guides/USER_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/guides/USER_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/guides/USER_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/guides/USER_GUIDE.md) Mwongozo kamili wa kusanidi watoa huduma, kuunda michanganyiko, kuunganisha zana za CLI, na kupeleka OmniRoute. --- ## Yaliyomo - [Muhtasari wa Bei](#-pricing-at-a-glance) - [Matumizi](#-use-cases) - [Usanidi wa Mtoa Huduma](#-provider-setup) - [Ujumuishaji wa CLI](#-cli-integration) - [Usambazaji](#-deployment) - [Modeli Zinazopatikana](#-available-models) - [Vipengele vya Kina](#-advanced-features) - [Uelekezaji Otomatiki (Bila usanidi)](#-auto-routing-zero-config) - [Ujumuishaji wa MCP na A2A](#-mcp--a2a-integration) - [Mfumo wa Ujuzi](#-skills-system) - [Mfumo wa Kumbukumbu](#-memory-system) - [Webhooks](#-webhooks) - [Mawakala wa Wingu](#-cloud-agents) - [Usimamizi wa Kiprogramu](#-programmatic-management) - [CLI ya Ndani](#-internal-cli) - [Programu ya Eneo-kazi (Electron)](#-desktop-application-electron) --- ## 💰 Muhtasari wa Bei | Kiwango | Mtoa Huduma | Gharama | Uwekaji Upya wa Mgao | Inafaa Zaidi Kwa | | --------------------- | ----------------- | ------------------- | --------------------------------- | ------------------------------- | | **💳 USAJILI** | Claude Code (Pro) | $20/mwezi | Saa 5 + kila wiki | Waliojisajili tayari | | | Codex (Plus/Pro) | $20-200/mwezi | Saa 5 + kila wiki | Watumiaji wa OpenAI | | | GitHub Copilot | $10-19/mwezi | Kila mwezi | Watumiaji wa GitHub | | **🔑 UFUNGUO WA API** | DeepSeek | Lipa kwa matumizi | Hakuna | Uchanganuzi wa bei nafuu | | | Groq | Lipa kwa matumizi | Hakuna | Uinferensi wa kasi ya juu sana | | | xAI (Grok) | Lipa kwa matumizi | Hakuna | Uchanganuzi wa Grok 4 | | | Mistral | Lipa kwa matumizi | Hakuna | Modeli zinazopangishwa EU | | | Perplexity | Lipa kwa matumizi | Hakuna | Utafutaji ulioboreshwa | | | Together AI | Lipa kwa matumizi | Hakuna | Modeli za chanzo huria | | | Fireworks AI | Lipa kwa matumizi | Hakuna | Picha za FLUX za kasi | | | Cerebras | Lipa kwa matumizi | Hakuna | Kasi ya kiwango cha kaki | | | Cohere | Lipa kwa matumizi | Hakuna | Command R+ RAG | | | NVIDIA NIM | Lipa kwa matumizi | Hakuna | Modeli za biashara | | | Baidu Qianfan | Lipa kwa matumizi | Hakuna | Modeli za ERNIE | | **💰 NAFUU** | GLM-4.7 | $0.6/1M | Kila siku saa 10AM | Nakala mbadala ya gharama nafuu | | | MiniMax M2.1 | $0.2/1M | Mzunguko wa saa 5 | Chaguo la bei nafuu zaidi | | | Kimi K2 | $9/mwezi bei maalum | Tokeni 10M/mwezi | Gharama inayotabirika | | **🆓 BURE** | Qoder | $0 | Vikomo vya mtoa huduma vinatumika | Thibitisha katalogi ya sasa | | | Kiro | $0 | ~salio 50/mwezi | Claude bila malipo | --- ## 🎯 Matumizi ### Hali ya 1: "Nina usajili wa Claude Pro" **Tatizo:** Mgao unaisha muda bila kutumika, na vikomo vya kiwango cha matumizi hutokea wakati wa uandishi mzito wa msimbo ``` Mchanganyiko: "maximize-claude" 1. cc/claude-opus-4-7 (tumia usajili kikamilifu) 2. glm/glm-4.7 (mbadala wa bei nafuu mgao unapoisha) 3. if/qwen3.8-max-preview (mbadala wa dharura usiolipishwa) Gharama ya kila mwezi: $20 (usajili) + ~$5 (mbadala) = jumla ya $25 dhidi ya $20 + kufikia vikomo = kufadhaika ``` ### Hali ya 2: "Nataka kutotumia gharama yoyote" **Tatizo:** Siwezi kumudu usajili, ninahitaji AI ya kuandika msimbo inayotegemeka ``` Mchanganyiko: "zero-cost" 1. if/kimi-k2.7-code (imeorodheshwa kuwa na ufikiaji bila malipo; vikomo vya kiwango vinaweza kutumika) 2. kr/qwen3-coder-next (mbadala wa Kiro usiolipishwa) Gharama ya kila mwezi: $0 Ubora: thibitisha modeli, vikomo, faragha na SLA kwa mzigo wako wa kazi ``` ### Hali ya 3: "Ninahitaji kuandika msimbo saa 24/7 bila kukatizwa" **Tatizo:** Nina makataa, siwezi kumudu muda wa kutopatikana kwa huduma ``` Mchanganyiko: "always-on" 1. cc/claude-opus-4-7 (ubora bora zaidi) 2. cx/gpt-5.5 (usajili wa pili) 3. glm/glm-4.7 (nafuu, huwekwa upya kila siku) 4. minimax/MiniMax-M2.1 (nafuu zaidi, huwekwa upya baada ya saa 5) 5. if/deepseek-v4-flash (imeorodheshwa kuwa na ufikiaji bila malipo; vikomo vya kiwango vinaweza kutumika) Matokeo: Ngazi 5 za mbadala huongeza uthabiti; upatikanaji wa huduma za chanzo haujahakikishwa Gharama ya kila mwezi: $20-200 (usajili) + $10-20 (mbadala) ``` ### Hali ya 4: "Nataka AI ya BURE katika OpenClaw" **Tatizo:** Ninahitaji msaidizi wa AI katika programu za ujumbe, bila malipo kabisa ``` Mchanganyiko: "openclaw-free" 1. if/qwen3.8-max-preview (imeorodheshwa kuwa na ufikiaji bila malipo; vikomo vya kiwango vinaweza kutumika) 2. if/deepseek-v4-flash (imeorodheshwa kuwa na ufikiaji bila malipo; vikomo vya kiwango vinaweza kutumika) 3. if/kimi-k2.7-code (imeorodheshwa kuwa na ufikiaji bila malipo; vikomo vya kiwango vinaweza kutumika) Gharama ya kila mwezi: $0 Ufikiaji kupitia: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... ``` --- ## 📖 Usanidi wa Watoa Huduma Ili kuongeza kwa wingi miunganisho ya funguo za API kutoka kwenye faili la CSV au JSON, tumia **Dashboard → Providers → Import from file**. Safu wima hufuata mpangilio maalum (`provider,name,apiKey,baseUrl,priority`); `provider` lazima iwe tayari ipo kama mtoa huduma anayesimamiwa au nodi inayooana. Tazama [Kuleta watoa huduma kutoka kwenye faili la CSV au JSON](../providers/CSV-IMPORT.md). ### 🔐 Watoa Huduma wa Usajili #### Claude Code (Pro/Max) ```bash Dashboard → Providers → Connect Claude Code → Kuingia kupitia OAuth → Uonyeshaji upya wa tokeni kiotomatiki → Ufuatiliaji wa kikomo cha saa 5 + kila wiki Modeli: cc/claude-opus-4-7 cc/claude-sonnet-4-6 cc/claude-haiku-4-5-20251001 ``` **Kidokezo cha Kitaalamu:** Tumia Opus kwa kazi changamano na Sonnet kwa kasi. OmniRoute hufuatilia kikomo kwa kila modeli! Njia zinazooana na Claude na Claude Code huhifadhi kiwango cha juhudi za kufikiri cha `max` kwa modeli za Opus na Sonnet. Modeli za Haiku hazikubali kiwango cha juhudi cha `max`, kwa hivyo OmniRoute hushusha ombi hilo hadi kwenye bajeti ya juu ya kufikiri kabla ya kulituma kwa mtoa huduma wa juu. #### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex → Kuingia kupitia OAuth (port 1455) → Uwekaji upya baada ya saa 5 + kila wiki Modeli: cx/gpt-5.5 cx/gpt-5.4 cx/gpt-5.3-codex cx/gpt-5.3-codex-spark ``` #### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub → OAuth kupitia GitHub → Uwekaji upya kila mwezi (tarehe 1 ya mwezi) Modeli: gh/gpt-5.5 gh/gpt-5.4 gh/claude-sonnet-4.6 gh/claude-opus-4.7 gh/gemini-3.1-pro-preview ``` ### 💰 Watoa Huduma wa Bei Nafuu #### GLM-4.7 (Huwekwa upya kila siku, $0.6/1M) 1. Jisajili: [Zhipu AI](https://open.bigmodel.cn) 2. Pata ufunguo wa API kutoka Coding Plan 3. Dashboard → Add API Key: Provider: `glm`, API Key: `your-key` **Matumizi:** `glm/glm-4.7` — **Kidokezo cha Kitaalamu:** Coding Plan hutoa kikomo mara 3 kwa gharama ya 1/7! Huwekwa upya kila siku saa 10:00 AM. #### MiniMax M2.1 (Huwekwa upya baada ya saa 5, $0.20/1M) 1. Jisajili: [MiniMax](https://www.minimax.io) 2. Pata ufunguo wa API → Dashboard → Add API Key **Matumizi:** `minimax/MiniMax-M2.1` — **Kidokezo cha Kitaalamu:** Chaguo la bei nafuu zaidi kwa muktadha mrefu (tokeni 1M)! #### Kimi K2 ($9/mwezi bila kubadilika) 1. Jisajili: [Moonshot AI](https://platform.kimi.ai?aff=omniroute) 2. Pata ufunguo wa API → Dashboard → Add API Key **Matumizi:** `kimi/kimi-k2.5` — **Kidokezo cha Kitaalamu:** Bei isiyobadilika ya $9/mwezi kwa tokeni 10M = gharama halisi ya $0.90/1M! #### Baidu Qianfan / ERNIE 1. Jisajili: [Baidu AI Cloud Qianfan](https://cloud.baidu.com/product/wenxinworkshop) 2. Unda ufunguo wa API wa Qianfan → Dashboard → Add API Key: Provider: `qianfan` **Matumizi:** `qianfan/ernie-5.1`, `qianfan/ernie-x1.1`, au kitambulisho kingine cha modeli ya Qianfan kinachooana na OpenAI. ### 🆓 Watoa Huduma BILA MALIPO Watoa huduma wasiohitaji uthibitishaji wana swichi kando ya **No authentication required** kwenye ukurasa wao wa mtoa huduma. Kuizima hulemaza mtoa huduma huyo, humwondoa kwenye mionekano ya Providers iliyosanidiwa/iliyofupishwa, na huondoa modeli zake kutoka `/v1/models`. #### Qoder (modeli 9 BILA MALIPO) ```bash Dashboard → Connect Qoder → Kuingia kupitia OAuth → Ufikiaji hutegemea vikomo vya sasa vya mtoa huduma Modeli: if/qwen3.8-max-preview, if/qwen3.7-max, if/qwen3.7-plus, if/kimi-k3, if/kimi-k2.7-code, if/glm-5.2, if/deepseek-v4-pro, if/deepseek-v4-flash, if/minimax-m3 ``` #### Kiro (Claude BILA MALIPO) ```bash Dashboard → Connect Kiro → AWS Builder ID au Google/GitHub → Takriban salio 50/mwezi Modeli: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 ``` --- ## 🎨 Michanganyiko Unaweza kupanga upya kadi za michanganyiko moja kwa moja katika **Dashibodi → Michanganyiko** kwa kuburuta kishikio kwenye kila kadi. Mpangilio huhifadhiwa katika SQLite na kurejeshwa wakati wa kupakia upya. ### Mfano wa 1: Ongeza Matumizi ya Usajili → Nakala Mbadala ya Bei Nafuu ``` Dashibodi → Michanganyiko → Unda Mpya Jina: premium-coding Miundo: 1. cc/claude-opus-4-7 (Usajili wa msingi) 2. glm/glm-4.7 (Nakala mbadala ya bei nafuu, $0.6/1M) 3. minimax/MiniMax-M2.7 (Chaguo la mwisho la bei nafuu zaidi, $0.3/1M) Tumia katika CLI: premium-coding ``` ### Mfano wa 2: Bila Malipo Pekee (Gharama Sifuri) ``` Jina: free-combo Miundo: 1. if/kimi-k2.7-code (ufikiaji umeorodheshwa kuwa bila malipo; vikomo vya mtoa huduma vinaweza kutumika) 2. kr/qwen3-coder-next (chaguo la mwisho lisilo na malipo la Kiro) Gharama: kwa sasa imeorodheshwa kama $0; masharti na upatikanaji vinaweza kubadilika ``` --- ## 🔧 Muunganisho wa CLI ### Cursor IDE **Kutumia Cursor kama kiteja cha OmniRoute** (pitisha gumzo la Cursor kupitia OmniRoute): ``` Mipangilio → Miundo → Kina: URL ya Msingi ya API ya OpenAI: http://localhost:20128/v1 Ufunguo wa API ya OpenAI: [kutoka kwenye dashibodi ya omniroute] Muundo: cc/claude-opus-4-7 ``` **Kutumia OmniRoute kama mtoa huduma wa Cursor** (OmniRoute huita huduma ya juu ya Cursor): pendelea **Dashibodi → Watoa Huduma → Cursor → Ingia kwa Cursor**. Katika Docker, angalia [`docs/providers/CURSOR-DOCKER.md`](../providers/CURSOR-DOCKER.md). ### Claude Code Hariri `~/.claude/settings.json`: ```json { "env": { "ANTHROPIC_BASE_URL": "http://localhost:20128", "ANTHROPIC_AUTH_TOKEN": "your-omniroute-api-key" } } ``` Tumia endpoint ya msingi inayooana na Claude hapa. Usiongeze `/v1` mwishoni mwa `ANTHROPIC_BASE_URL`. ### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` ### OpenClaw Hariri `~/.openclaw/openclaw.json`: ```json { "agents": { "defaults": { "model": { "primary": "omniroute/if/kimi-k2.7-code" } } }, "models": { "providers": { "omniroute": { "baseUrl": "http://localhost:20128/v1", "apiKey": "your-omniroute-api-key", "api": "openai-completions", "models": [{ "id": "if/kimi-k2.7-code", "name": "Kimi K2.7 Code" }] } } } } ``` **Au tumia Dashibodi:** Zana za CLI → OpenClaw → Usanidi otomatiki ### Cline / Continue / RooCode ``` Mtoa Huduma: Inaoana na OpenAI URL ya Msingi: http://localhost:20128/v1 Ufunguo wa API: [kutoka kwenye dashibodi] Muundo: cc/claude-opus-4-7 ``` --- ## 🚀 Usambazaji ### Usakinishaji wa kimataifa wa npm (Unapendekezwa) ```bash npm install -g omniroute # Unda saraka ya usanidi mkdir -p ~/.omniroute # Unda faili la .env (angalia .env.example) cp .env.example ~/.omniroute/.env # Anzisha seva omniroute # Au kwa port maalum: omniroute --port 3000 ``` CLI hupakia `.env` kiotomatiki kutoka `~/.omniroute/.env` au `./.env`. ### Hali ya trei Anzisha OmniRoute katika trei ya mfumo: ```bash omniroute serve --tray ``` Amri hukamilika baada ya seva na trei kuwa tayari. Seva huendelea kufanya kazi bila terminali. Hali ya trei inatumia macOS, Windows na vipindi vya Linux vyenye kiolesura cha picha. Hali ya trei haifungui dashibodi kiotomatiki. Tumia menyu ya trei kutekeleza vitendo hivi: - Fungua dashibodi. - Fungua `/dashboard/logs`. - Badilisha uanzishaji otomatiki. - Simamisha OmniRoute. Usichanganye `--tray` na chaguo hizi: - `--daemon` - `--log` - `--no-recovery` Hali hizi zinahitaji umiliki tofauti wa mchakato. Washa uanzishaji wakati wa kuingia kwenye mashine mara inayofuata: ```bash omniroute autostart enable ``` Uanzishaji otomatiki hutumia hali ya trei kwenye macOS, Windows na vipindi vya Linux vyenye kiolesura cha picha. Linux isiyo na kiolesura cha picha hutumia huduma iliyopo ya mtumiaji ya systemd. Zima uanzishaji wakati wa kuingia: ```bash omniroute autostart disable ``` ### Kuondoa Usakinishaji Usipohitaji tena OmniRoute, tunatoa hati mbili za haraka za kuiondoa kabisa: | Amri | Kitendo | | ------------------------ | ---------------------------------------------------------------------------------------- | | `npm run uninstall` | Huondoa programu ya mfumo lakini **huhifadhi DB na usanidi wako** katika `~/.omniroute`. | | `npm run uninstall:full` | Huondoa programu NA **hufuta kabisa usanidi, funguo na hifadhidata zote**. | > Kumbuka: Ili kutekeleza amri hizi, nenda kwenye folda ya mradi wa OmniRoute (ikiwa uliinakili kwa clone) na uzitekeleze. Vinginevyo, ikiwa ilisakinishwa kimataifa, unaweza kutekeleza tu `npm uninstall -g omniroute`. ### Usambazaji wa VPS ```bash git clone https://github.com/diegosouzapw/OmniRoute.git cd OmniRoute && npm install && npm run build export JWT_SECRET="your-secure-secret-change-this" export INITIAL_PASSWORD="your-password" export DATA_DIR="/var/lib/omniroute" export PORT="20128" export HOSTNAME="0.0.0.0" export NODE_ENV="production" export NEXT_PUBLIC_BASE_URL="http://localhost:20128" export API_KEY_SECRET="endpoint-proxy-api-key-secret" npm run start # Au: pm2 start npm --name omniroute -- start ``` ### Usambazaji wa PM2 (Kumbukumbu Ndogo) Kwa seva zenye RAM ndogo, tumia chaguo la kikomo cha kumbukumbu: ```bash # Kwa kikomo cha 512MB (chaguomsingi) pm2 start npm --name omniroute -- start # Au kwa kikomo maalum cha kumbukumbu OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start # Au ukitumia ecosystem.config.js pm2 start ecosystem.config.js ``` Unda `ecosystem.config.js`: ```javascript module.exports = { apps: [ { name: "omniroute", script: "npm", args: "start", env: { NODE_ENV: "production", OMNIROUTE_MEMORY_MB: "512", JWT_SECRET: "your-secret", INITIAL_PASSWORD: "your-password", }, node_args: "--max-old-space-size=512", max_memory_restart: "300M", }, ], }; ``` ### Docker ```bash # Unda image (chaguomsingi = runner-cli yenye codex/claude/droid zilizosakinishwa mapema) docker build -t omniroute:cli . # Hali inayohamishika (inapendekezwa) docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli ``` Kwa hali iliyounganishwa na mfumo mwenyeji pamoja na faili tekelezi za CLI, angalia sehemu ya Docker katika nyaraka kuu. ### Void Linux (xbps-src) Watumiaji wa Void Linux wanaweza kufungasha na kusakinisha OmniRoute kwa njia asilia kwa kutumia mfumo wa ukalimani mtambuka wa `xbps-src`. Hii huendesha kiotomatiki uundaji wa pekee wa Node.js pamoja na viunganishi asilia vinavyohitajika vya `better-sqlite3`.
Tazama kiolezo cha xbps-src ```bash # Faili ya kiolezo ya 'omniroute' pkgname=omniroute version=3.8.0 revision=1 hostmakedepends="nodejs python3 make" depends="openssl" short_desc="Lango jumuishi la AI lenye uelekezaji mahiri kwa watoa huduma wengi wa LLM" maintainer="zenobit " license="MIT" homepage="https://github.com/diegosouzapw/OmniRoute" distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz" checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b system_accounts="_omniroute" omniroute_homedir="/var/lib/omniroute" export NODE_ENV=production export npm_config_engine_strict=false export npm_config_loglevel=error export npm_config_fund=false export npm_config_audit=false do_build() { # Tambua usanifu lengwa wa CPU kwa node-gyp local _gyp_arch case "$XBPS_TARGET_MACHINE" in aarch64*) _gyp_arch=arm64 ;; armv7*|armv6*) _gyp_arch=arm ;; i686*) _gyp_arch=ia32 ;; *) _gyp_arch=x64 ;; esac # 1) Sakinisha vitegemezi vyote – ruka hati NODE_ENV=development npm ci --ignore-scripts # 2) Unda kifurushi cha pekee cha Next.js npm run build # 3) Nakili rasilimali tuli kwenye kifurushi cha pekee cp -r .next/static .next/standalone/.next/static [ -d public ] && cp -r public .next/standalone/public || true # 4) Kalimani kiunganishi asilia cha better-sqlite3 local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch") # 5) Weka kiunganishi kilichokalimaniwa kwenye kifurushi cha pekee local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release mkdir -p "$_bs3_release" cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/" # 6) Ondoa vifurushi vya sharp vinavyotegemea usanifu rm -rf .next/standalone/node_modules/@img # 7) Nakili vitegemezi vya wakati wa utekelezaji vya pino vilivyoachwa na uchanganuzi tuli wa Next.js: for _mod in pino-abstract-transport split2 process-warning; do cp -r "node_modules/$_mod" .next/standalone/node_modules/ done } do_check() { npm run test:unit } do_install() { vmkdir usr/lib/omniroute/.next vcopy .next/standalone/. usr/lib/omniroute/.next/standalone # Zuia uondoaji wa saraka tupu za kipanga njia cha programu cha Next.js na kitendo cha baada ya usakinishaji for _d in \ .next/standalone/.next/server/app/dashboard \ .next/standalone/.next/server/app/dashboard/settings \ .next/standalone/.next/server/app/dashboard/providers; do touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep" done cat > "${WRKDIR}/omniroute" <<'EOF' #!/bin/sh export PORT="${PORT:-20128}" export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}" export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}" mkdir -p "${DATA_DIR}" exec node /usr/lib/omniroute/.next/standalone/server.js "$@" EOF vbin "${WRKDIR}/omniroute" } post_install() { vlicense LICENSE } ```
### Vigezo vya Mazingira | Kigezo | Chaguo-msingi | Maelezo | | --------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `JWT_SECRET` | `omniroute-default-secret-change-me` | Siri ya kusaini JWT (**ibadilishe katika mazingira ya uzalishaji**) | | `INITIAL_PASSWORD` | `CHANGEME` | Nenosiri la kuingia kwa mara ya kwanza | | `DATA_DIR` | `~/.omniroute` | Saraka ya data (hifadhidata, matumizi, kumbukumbu) | | `PORT` | chaguo-msingi la mfumo | Porti ya huduma (`20128` katika mifano) | | `HOSTNAME` | chaguo-msingi la mfumo | Seva pangishi ya kuunganisha (chaguo-msingi la Docker ni `0.0.0.0`) | | `NODE_ENV` | chaguo-msingi la mazingira ya utekelezaji | Weka `production` kwa ajili ya upelekaji | | `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | URL ya msingi ya umma inayoonyeshwa kwenye dashibodi na kufichuliwa kwa seva (inachukua nafasi ya `BASE_URL` ya zamani) | | `NEXT_PUBLIC_CLOUD_URL` | `https://omniroute.dev` | URL ya msingi ya kituo cha usawazishaji wa wingu (inachukua nafasi ya `CLOUD_URL` ya zamani) | | `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Siri ya HMAC kwa funguo za API zinazozalishwa | | `REQUIRE_API_KEY` | `false` | Lazimisha ufunguo wa API wa Bearer kwenye `/v1/*` | | `ALLOW_API_KEY_REVEAL` | `false` | Ruhusu watumiaji wa dashibodi waliothibitishwa kufichua thamani kamili za funguo za API zilizohifadhiwa wanapohitaji | | `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES` | `70` | Ratiba ya kuonyesha upya data iliyohifadhiwa ya Provider Limits upande wa seva; vitufe vya kuonyesha upya kwenye UI bado huanzisha usawazishaji mwenyewe | | `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Zima vijipicha vya kiotomatiki vya SQLite kabla ya uandishi/uletaji/urejeshaji; hifadhi rudufu za mikono bado hufanya kazi | | `APP_LOG_TO_FILE` | `true` | Huwezesha kuandika kumbukumbu za programu na ukaguzi kwenye diski | | `AUTH_COOKIE_SECURE` | `false` | Lazimisha kidakuzi cha uthibitishaji cha `Secure` (nyuma ya proksi geuzi ya HTTPS) | | `CLOUDFLARED_BIN` | haijawekwa | Tumia faili tekelezi iliyopo ya `cloudflared` badala ya upakuaji unaodhibitiwa | | `CLOUDFLARED_PROTOCOL` | `http2` | Usafirishaji kwa Quick Tunnels zinazodhibitiwa (`http2`, `quic`, au `auto`) | | `OMNIROUTE_MEMORY_MB` | `512` | Kikomo cha heap cha Node.js katika MB | | `PROMPT_CACHE_MAX_SIZE` | `50` | Idadi ya juu zaidi ya maingizo ya akiba ya prompt | | `SEMANTIC_CACHE_MAX_SIZE` | `100` | Idadi ya juu zaidi ya maingizo ya akiba ya kisemantiki | Kwa marejeleo kamili ya vigezo vya mazingira, angalia [README](../README.md). --- ## 📊 Miundo Inayopatikana
Tazama miundo yote inayopatikana > Orodha iliyo hapa chini imeteuliwa kutoka `open-sse/config/providerRegistry.ts` kwa v3.8.0. Katalogi za wingu (Gemini, OpenRouter, n.k.) husawazishwa kwa njia inayobadilika — ili kuona katalogi kamili ya moja kwa moja, fungua **Dashibodi → Watoa Huduma → [mtoa huduma] → Miundo Inayopatikana** au piga `GET /api/models/catalog`. > > Ikiwa orodha iliyojengewa ndani ya mtoa huduma imepitwa na wakati, tumia **Leta kutoka /models** kwenye ukurasa huo (au washa **Usawazishaji Kiotomatiki**) ili kuvuta katalogi ya sasa kutoka chanzo cha juu. Hili lilithibitishwa katika v3.8.50 kwa LLM7.io (`gemini-3.1-flash-lite`) na UncloseAI (`solidrust/Hermes-3-Llama-3.1-8B-AWQ`); ufikiaji bila utambulisho wa Pollinations uliendelea kuwa na mipaka iliyowekwa na chanzo cha juu wakati wa awamu hiyo hiyo ya majaribio. **Claude Code (`cc/`)** — OAuth ya Pro/Max: `cc/claude-opus-4-8`, `cc/claude-opus-4-7`, `cc/claude-opus-4-6`, `cc/claude-opus-4-5-20251101`, `cc/claude-sonnet-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` **Codex (`cx/`)** — OAuth ya Plus/Pro: `cx/gpt-5.5` (+ viwango vya juhudi: `gpt-5.5-xhigh`, `gpt-5.5-high`, `gpt-5.5-medium`, `gpt-5.5-low`), `cx/gpt-5.4`, `cx/gpt-5.4-mini`, `cx/gpt-5.3-codex`, `cx/gpt-5.3-codex-spark` **GitHub Copilot (`gh/`)** — OAuth: `gh/gpt-5.5`, `gh/gpt-5.4`, `gh/gpt-5.4-mini`, `gh/gpt-5-mini`, `gh/gpt-5.3-codex`, `gh/claude-opus-4.7`, `gh/claude-opus-4.6`, `gh/claude-opus-4-5-20251101`, `gh/claude-sonnet-4.6`, `gh/claude-sonnet-4.5`, `gh/claude-haiku-4.5`, `gh/gemini-3.1-pro-preview`, `gh/gemini-3-flash-preview`, `gh/oswe-vscode-prime` **Kiro (`kr/`)** — OAuth BILA MALIPO: tumia katalogi ya moja kwa moja iliyoonyeshwa chini ya **Dashibodi → Watoa Huduma → Kiro → Miundo Inayopatikana**. Upatikanaji hutegemea akaunti na mpango. **Qoder (`if/`)** — OAuth BILA MALIPO: `if/qwen3.8-max-preview`, `if/qwen3.7-max`, `if/qwen3.7-plus`, `if/kimi-k3`, `if/kimi-k2.7-code`, `if/glm-5.2`, `if/deepseek-v4-pro`, `if/deepseek-v4-flash`, `if/minimax-m3` **GLM (`glm/`, `glm-cn/`, `zai/`, `glmt/`)** — $0.2–0.6/1M: `glm/glm-5.1`, `glm/glm-5`, `glm/glm-5-turbo`, `glm/glm-4.7`, `glm/glm-4.7-flash`, `glm/glm-4.6`, `glm/glm-4.6v`, `glm/glm-4.5`, `glm/glm-4.5v`, `glm/glm-4.5-air` **MiniMax (`minimax/`, `minimax-cn/`)** — $0.2/1M: `minimax/MiniMax-M2.7`, `minimax/MiniMax-M2.7-highspeed`, `minimax/MiniMax-M2.5`, `minimax/MiniMax-M2.5-highspeed` **Kimi (`kimi/`, `kimi-coding/`, `kimi-coding-apikey/`)** — $9/mo kwa kiwango kisichobadilika au kwa matumizi: `kimi/kimi-k2.6`, `kimi/kimi-k2.5` **DeepSeek (`ds/`)** — Ufunguo wa API: `ds/deepseek-v4-pro`, `ds/deepseek-v4-flash` **Groq (`groq/`)** — Kasi ya juu sana: `groq/llama-3.3-70b-versatile`, `groq/meta-llama/llama-4-maverick-17b-128e-instruct`, `groq/qwen/qwen3-32b`, `groq/openai/gpt-oss-120b` **xAI (`xai/`)** — Grok asilia: `xai/grok-4.3`, `xai/grok-4.20-multi-agent-0309`, `xai/grok-4.20-0309-reasoning`, `xai/grok-4.20-0309-non-reasoning` **Mistral (`mistral/`)** — Imepangishwa katika EU: `mistral/mistral-large-latest`, `mistral/mistral-medium-3-5`, `mistral/mistral-small-latest`, `mistral/devstral-latest`, `mistral/codestral-latest` **Perplexity (`pplx/`)** — Imeboreshwa kwa utafutaji: `pplx/sonar-deep-research`, `pplx/sonar-reasoning-pro`, `pplx/sonar-pro`, `pplx/sonar` **Together AI (`together/`)** — Chanzo huria: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo-Free` (bila malipo), `together/meta-llama/Llama-Vision-Free`, `together/deepseek-ai/DeepSeek-R1-Distill-Llama-70B-Free`, `together/deepseek-ai/DeepSeek-R1`, `together/Qwen/Qwen3-235B-A22B`, `together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8` **Fireworks AI (`fireworks/`)** — Ujalizaji wa haraka: `fireworks/accounts/fireworks/models/kimi-k2p6`, `fireworks/accounts/fireworks/models/minimax-m2p7`, `fireworks/accounts/fireworks/models/qwen3p6-plus`, `fireworks/accounts/fireworks/models/glm-5p1`, `fireworks/accounts/fireworks/models/deepseek-v4-pro` **Cerebras (`cerebras/`)** — Kiwango cha kaki: `cerebras/zai-glm-4.7`, `cerebras/gpt-oss-120b` **Cohere (`cohere/`)** — Inayolenga RAG: `cohere/command-a-reasoning-08-2025`, `cohere/command-a-vision-07-2025`, `cohere/command-a-03-2025`, `cohere/command-r-08-2024` **NVIDIA NIM (`nvidia/`)** — Kwa biashara: `nvidia/z-ai/glm-5.1`, `nvidia/minimaxai/minimax-m2.7`, `nvidia/google/gemma-4-31b-it`, `nvidia/mistralai/mistral-small-4-119b-2603`, `nvidia/mistralai/mistral-large-3-675b-instruct-2512`, `nvidia/qwen/qwen3.5-397b-a17b`, `nvidia/deepseek-ai/deepseek-v4-pro`, `nvidia/openai/gpt-oss-120b`, `nvidia/nvidia/nemotron-3-super-120b-a12b` **Baidu Qianfan (`qianfan/`)** — ERNIE: `qianfan/ernie-5.1`, `qianfan/ernie-5.0-thinking-latest`, `qianfan/ernie-x1.1` **Ollama Cloud (`ollama-cloud/`)**: `ollama-cloud/deepseek-v4-pro`, `ollama-cloud/deepseek-v4-flash`, `ollama-cloud/kimi-k2.6`, `ollama-cloud/glm-5.1`, `ollama-cloud/minimax-m2.7`, `ollama-cloud/gemma4:31b`, `ollama-cloud/qwen3.5:397b` **Gemini (Google Cloud `gemini/`)**: Husawazishwa moja kwa moja kwa kila ufunguo wa API kutoka Google — hakuna orodha tuli. Unganisha ufunguo katika **Dashibodi → Watoa Huduma**, kisha utumie **Miundo Inayopatikana** kuleta katalogi ya sasa (k.m. `gemini/gemini-3-pro`, `gemini/gemini-3-flash`). **Watoa huduma wengine wanaooana** (walioteuliwa): `cohere`, `databricks`, `snowflake`, `together`, `vertex`, `alibaba`, `alibaba-cn`, `bedrock` (kupitia `aws-bedrock`), `azure-ai`, `openrouter` (katalogi inayopitishwa moja kwa moja), `siliconflow`, `hyperbolic`, `huggingface`, `featherless-ai`, `cloudflare-ai`, `scaleway`, `deepinfra`, `vercel-ai-gateway`, `bazaarlink`, `friendliai`, `nous-research`, `reka`, `volcengine`, `ai21`, `gigachat`. Kila mmoja hudumisha orodha yake ya miundo katika `providerRegistry.ts` na anaweza kusawazishwa kiotomatiki mtoa huduma anapotoa endpoint ya `/models`. **Dokezo kuhusu vitambulisho vya miundo:** OmniRoute hutumia vitambulisho asilia vya watoa huduma (`claude-opus-4-8`, `gpt-5.5`, `glm-5.1`, `MiniMax-M2.7`, `kimi-k2.5`, `grok-4.20-0309-reasoning`). Baadhi ya vitambulisho vinajumuisha matoleo yenye nukta kwa sababu hivyo ndivyo API ya chanzo cha juu inavyovitarajia. Ikiwa muundo haujaorodheshwa hapo juu, endesha `omniroute models --search ` au piga `GET /api/models/catalog` ili kuthibitisha upatikanaji.
--- ## 🧩 Vipengele vya Kina ### Modeli Maalum Ongeza kitambulisho chochote cha modeli kwa mtoa huduma yeyote bila kusubiri sasisho la programu: ```bash # Kupitia API curl -X POST http://localhost:20128/api/provider-models \ -H "Content-Type: application/json" \ -d '{"provider": "openai", "modelId": "gpt-5.2", "modelName": "GPT-5.2"}' # Orodha: curl http://localhost:20128/api/provider-models?provider=openai # Ondoa: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-5.2" ``` Au tumia Dashibodi: **Watoa Huduma → [Mtoa Huduma] → Modeli Maalum**. Vidokezo: - Watoa huduma wa OpenRouter na wale wanaooana na OpenAI/Anthropic hudhibitiwa kutoka **Modeli Zinazopatikana** pekee. Uongezaji wa moja kwa moja, uingizaji, na usawazishaji wa kiotomatiki vyote huingia kwenye orodha ileile ya modeli zinazopatikana, kwa hivyo hakuna sehemu tofauti ya Modeli Maalum kwa watoa huduma hao. - Sehemu ya **Modeli Maalum** imekusudiwa kwa watoa huduma ambao hawatoi uingizaji unaodhibitiwa wa modeli zinazopatikana. ### Kuunganisha Peers za OmniRoute kwa Mnyororo Lango jingine la OmniRoute linaweza kuongezwa kama mtoa huduma **Maalum anayeoana na OpenAI**. Tumia URL msingi ya `/v1` ya peer na ufunguo maalum wa API wenye ruhusa chache zaidi uliotolewa na peer huyo. Kwa minyororo ya pande zote au yenye hatua nyingi, washa kinga ya hiari dhidi ya mizunguko kwenye kila lango: ```bash # gateway-a OMNIROUTE_INSTANCE_ID=gateway-a OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1 OMNIROUTE_PEER_MAX_HOPS=4 ``` ```bash # gateway-b OMNIROUTE_INSTANCE_ID=gateway-b OMNIROUTE_PEER_URLS=http://gateway-a:20128/v1 OMNIROUTE_PEER_MAX_HOPS=4 ``` Ni maombi yanayotumwa kwa URL ya peer iliyoidhinishwa wazi pekee ndiyo yanayopokea kichwa cha `X-OmniRoute-Peer-Trace`. Lango hukataa kitambulisho cha instance kilichorudiwa au kikomo cha hatua kilichoisha kwa HTTP `508 Loop Detected`; watoa huduma wa kawaida wa upstream hawapokei metadata yoyote ya peer. Kuunganisha peers kwa mnyororo si urudufu wa hifadhidata wala failover ya host. Kila lango huhifadhi hali ya SQLite, cache, vihesabio vya kiwango, na vipindi vyake kwa kujitegemea. Tumia reverse proxy inayokaguliwa afya au failover ya mteja kwa upatikanaji wa active/passive au active/active, na kamwe usiunganishe hifadhidata moja ya SQLite kwenye instances nyingi za OmniRoute zinazoendeshwa. ### Njia Maalum za Watoa Huduma Elekeza maombi moja kwa moja kwa mtoa huduma mahususi huku modeli ikithibitishwa: ```bash POST http://localhost:20128/v1/providers/openai/chat/completions POST http://localhost:20128/v1/providers/openai/embeddings POST http://localhost:20128/v1/providers/fireworks/images/generations ``` Kiambishi awali cha mtoa huduma huongezwa kiotomatiki ikiwa hakipo. Modeli zisizolingana hurejesha `400`. ### Usanidi wa Proksi ya Mtandao ```bash # Weka proksi ya jumla curl -X PUT http://localhost:20128/api/settings/proxy \ -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}' # Proksi kwa kila mtoa huduma curl -X PUT http://localhost:20128/api/settings/proxy \ -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}' # Jaribu proksi curl -X POST http://localhost:20128/api/settings/proxy/test \ -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' ``` **Mpangilio wa Kipaumbele:** Mahususi kwa ufunguo → Mahususi kwa Combo → Mahususi kwa mtoa huduma → Jumla → Mazingira. ### API ya Katalogi ya Modeli ```bash curl http://localhost:20128/api/models/catalog ``` Hurejesha modeli zilizopangwa kwa makundi kulingana na mtoa huduma pamoja na aina (`chat`, `embedding`, `image`). ### Usawazishaji wa Wingu - Sawazisha watoa huduma, combo, na mipangilio kwenye vifaa mbalimbali - Usawazishaji wa kiotomatiki wa chinichini wenye muda wa kuisha + kushindwa mapema - Pendelea `NEXT_PUBLIC_BASE_URL`/`NEXT_PUBLIC_CLOUD_URL` ya upande wa seva katika mazingira ya uzalishaji ### Cloudflare Quick Tunnel - Inapatikana katika **Dashibodi → Endpoints** kwa Docker na usambazaji mwingine unaojipangisha - Huunda URL ya muda ya `https://*.trycloudflare.com` inayoelekeza kwenye endpoint yako ya sasa ya `/v1` inayoana na OpenAI - Uwashaji wa kwanza husakinisha `cloudflared` tu inapohitajika; uanzishaji upya wa baadaye hutumia tena binary ileile inayodhibitiwa - Quick Tunnels hazirejeshwi kiotomatiki baada ya OmniRoute au container kuanzishwa upya; ziwashe tena kutoka kwenye dashibodi inapohitajika - URL za tunnel ni za muda mfupi na hubadilika kila unapozima/kuwasha tunnel - Quick Tunnels zinazodhibitiwa hutumia usafirishaji wa HTTP/2 kwa chaguo-msingi ili kuepuka maonyo mengi ya bafa ya QUIC UDP katika container zenye rasilimali finyu - Weka `CLOUDFLARED_PROTOCOL=quic` au `auto` ikiwa unataka kubatilisha chaguo la usafirishaji linalodhibitiwa - Weka `CLOUDFLARED_BIN` ikiwa unapendelea kutumia binary ya `cloudflared` iliyosakinishwa mapema badala ya upakuaji unaodhibitiwa - Paneli za Cloudflare Quick Tunnel, Tailscale Funnel, na ngrok Tunnel zinaweza kuonyeshwa au kufichwa katika **Mipangilio → Mwonekano**. Kuficha paneli hakusimamishi tunnel inayoendeshwa. ### Uerevu wa Lango la LLM (Awamu ya 9) - **Cache ya Kisemantiki** — Huhifadhi kiotomatiki kwenye cache majibu yasiyo ya kutiririsha, yenye temperature=0 (iepuke kwa `X-OmniRoute-No-Cache: true`) - **Idempotency ya Maombi** — Huondoa marudio ya maombi ndani ya sekunde 5 kupitia kichwa cha `Idempotency-Key` au `X-Request-Id` - **Ufuatiliaji wa Maendeleo** — Matukio ya hiari ya SSE ya `event: progress` kupitia kichwa cha `X-OmniRoute-Progress: true` --- ### Mazingira ya Majaribio ya Kitafsiri Fikia kupitia **Dashibodi → Kitafsiri**. Tatua hitilafu na uone jinsi OmniRoute inavyotafsiri maombi ya API kati ya watoa huduma. | Hali | Madhumuni | | ---------------------------------- | --------------------------------------------------------------------------------------------------- | | **Mazingira ya Majaribio** | Chagua miundo ya chanzo/lengo, bandika ombi, na uone matokeo yaliyotafsiriwa papo hapo | | **Kijaribu Gumzo** | Tuma ujumbe wa moja kwa moja wa gumzo kupitia proksi na ukague mzunguko mzima wa ombi/jibu | | **Benchi la Majaribio** | Endesha majaribio ya kundi kwenye michanganyiko mingi ya miundo ili kuthibitisha usahihi wa tafsiri | | **Kifuatiliaji cha Moja kwa Moja** | Tazama tafsiri za wakati halisi maombi yanapopita kwenye proksi | **Matumizi:** - Tatua sababu ya mchanganyiko mahususi wa mteja/mtoa huduma kushindwa - Thibitisha kwamba tagi za kufikiri, miito ya zana, na prompt za mfumo zinatafsiriwa kwa usahihi - Linganisha tofauti za miundo kati ya OpenAI, Claude, Gemini, na miundo ya Responses API --- ### Mikakati ya Uelekezaji Sanidi kupitia **Dashibodi → Mipangilio → Uelekezaji**. Dashibodi huonyesha mikakati sita inayotumiwa zaidi; michanganyiko na kielekezaji-otomatiki hutumia mikakati mingi zaidi kwa ndani. **Mikakati inayoonekana kwenye dashibodi (uelekezaji wa kiwango cha akaunti):** | Mkakati | Maelezo | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **Jaza ya Kwanza** | Hutumia akaunti kulingana na mpangilio wa kipaumbele — akaunti msingi hushughulikia maombi yote hadi isipatikane | | **Zamu kwa Zamu** | Huzunguka kwenye akaunti zote kwa kikomo kinachoweza kusanidiwa cha kushikilia akaunti (chaguomsingi: miito 3 kwa kila akaunti) | | **P2C (Nguvu ya Chaguo Mbili)** | Huchagua akaunti 2 bila mpangilio na kuelekeza kwa iliyo na hali bora zaidi — husawazisha mzigo huku ikizingatia hali | | **Bila Mpangilio** | Huchagua akaunti bila mpangilio kwa kila ombi kwa kutumia uchanganyaji wa Fisher-Yates | | **Iliyotumika kwa Uchache Zaidi** | Huelekeza kwa akaunti yenye muhuri wa muda wa zamani zaidi wa `lastUsedAt`, na kusambaza trafiki kwa usawa | | **Iliyoboreshwa kwa Gharama** | Huelekeza kwa akaunti yenye thamani ya chini zaidi ya kipaumbele, na kuboresha matumizi ya watoa huduma wenye gharama ya chini zaidi | **Mikakati ya kina ya michanganyiko na otomatiki** (inaweza kusanidiwa kwa kila mchanganyiko au kupitia viambishi awali vya `auto/*` — angalia [AUTO-COMBO.md](../routing/AUTO-COMBO.md)): - `priority` — mpangilio thabiti, haitumii kamwe zamu kwa zamu - `weighted` — mgawanyo sawia wa trafiki kulingana na uzani wa kila modeli - `fill-first` — tumia modeli ya kwanza hadi vikomo vifikiwe - `round-robin` / `strict-random` / `random` - `p2c` (Nguvu ya Chaguo Mbili) - `least-used` na `cost-optimized` - `auto` — huongozwa na alama katika chaguo zote - `lkgp` (Mtoa Huduma Mzuri wa Mwisho Aliyejulikana) — hushikilia mtoa huduma aliyefanikiwa mwisho, kisha hutumia kanuni mbadala - `context-optimized` — huchagua modeli yenye dirisha kubwa zaidi la muktadha lililo huru - `context-relay` — huunganisha modeli za muktadha mrefu kwa zamu zinazofuata #### Kichwa cha Kipindi Kinachoshikamana cha Nje Kwa uhusishaji wa kipindi cha nje (kwa mfano, ajenti za Claude Code/Codex zilizo nyuma ya proksi za kinyume), tuma: ```http X-Session-Id: your-session-key ``` OmniRoute pia hukubali `x_session_id` na kurejesha ufunguo halisi wa kipindi katika `X-OmniRoute-Session-Id`. Ikiwa unatumia Nginx na kutuma vichwa vyenye mistari ya chini, wezesha: ```nginx underscores_in_headers on; ``` #### Lakabu za Modeli zenye Vibambo-Jumuishi Unda ruwaza zenye vibambo-jumuishi ili kubadilisha majina ya modeli: ``` Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-6 Pattern: gpt-* → Target: gh/gpt-5.3-codex ``` Vibambo-jumuishi vinaweza kutumia `*` (vibambo vyovyote) na `?` (kibambo kimoja). #### Minyororo ya Mbadala Bainisha minyororo ya jumla ya mbadala inayotumika kwa maombi yote: ``` Chain: production-fallback 1. cc/claude-opus-4-7 2. gh/gpt-5.3-codex 3. glm/glm-4.7 ``` --- ### Ustahimilivu na Vivunja Saketi Sanidi kupitia **Dashibodi → Mipangilio → Ustahimilivu**. OmniRoute hutekeleza ustahimilivu wa kiwango cha mtoa huduma kwa vipengele vitano: 1. **Foleni na Upangaji wa Kasi ya Maombi** — Udhibiti wa maombi katika kiwango cha mfumo: - **Maombi kwa Dakika (RPM)** — Idadi ya juu zaidi ya maombi kwa dakika kwa kila akaunti - **Muda wa Chini Kati ya Maombi** — Pengo la chini zaidi kwa milisekunde kati ya maombi - **Idadi ya Juu ya Maombi ya Wakati Mmoja** — Idadi ya juu zaidi ya maombi ya wakati mmoja kwa kila akaunti 2. **Kipindi cha Kusubiri cha Muunganisho** — Usanidi kwa kila aina ya uthibitishaji kwa muunganisho mmoja baada ya hitilafu zinazoweza kujaribiwa tena: - **Kipindi cha Msingi cha Kusubiri** — Kipindi chaguomsingi cha kusubiri kwa hitilafu za mtoa huduma wa juu zinazoweza kujaribiwa tena - **Tumia Vidokezo vya Kujaribu Tena vya Mtoa Huduma wa Juu** — Hufuata vidokezo halali vya `Retry-After` au vya kuweka upya vinapotolewa - **Hatua za Juu za Ongezeko la Muda wa Kusubiri** — Kiwango cha juu zaidi cha ongezeko la kipeo la muda wa kusubiri kwa hitilafu zinazojirudia 3. **Kivunja Saketi cha Mtoa Huduma** — Hufuatilia hitilafu za mtoa huduma kutoka mwanzo hadi mwisho, humtambulisha mtoa huduma kuwa amedhoofika katika kiwango cha onyo kilichosanidiwa, na hufungua kivunja saketi kiwango cha hitilafu kilichosanidiwa kinapofikiwa: - **Kiwango cha Kudhoofika** — Hitilafu mfululizo za mtoa huduma kabla ya kuingia `DEGRADED` - **Kiwango cha Hitilafu** — Hitilafu mfululizo za mtoa huduma kabla ya kuingia `OPEN` - **Muda wa Kuweka Upya** — Kipindi kabla ya mtoa huduma kujaribiwa tena - **CLOSED** (Salama) — Maombi hupita kama kawaida - **DEGRADED** — Maombi yanaendelea kupita huku ongezeko la hitilafu likifuatiliwa - **OPEN** — Mtoa huduma huzuiwa kwa muda baada ya hitilafu zinazojirudia - **HALF_OPEN** — Hujaribu kama mtoa huduma amerejea katika hali nzuri Vikomo vya kasi vya `429` vinavyohusu muunganisho hubaki katika **Kipindi cha Kusubiri cha Muunganisho** na havihesabiwi na kivunja saketi cha mtoa huduma. Hali ya wakati wa utekelezaji ya kivunja saketi cha mtoa huduma huonyeshwa kwenye **Dashibodi → Hali** pekee. 4. **Subiri Kipindi cha Kusubiri** — Ikiwa miunganisho yote inayoweza kuchaguliwa tayari ipo katika kipindi cha kusubiri, OmniRoute inaweza kusubiri hadi kipindi cha kwanza kiishe na kujaribu tena ombi lilelile la mteja kiotomatiki. 5. **Utambuzi Otomatiki wa Kikomo cha Kasi** — Watoa huduma wa juu wanaporejesha vipindi dhahiri vya kusubiri, vidokezo hivyo hupuuza kipindi cha ndani cha kusubiri cha muunganisho ikiwa mpangilio huu umewezeshwa. **Kidokezo cha Kitaalamu:** Tumia ukurasa wa **Hali** kukagua na kuweka upya vivunja saketi hai vya watoa huduma baada ya kukatika kwa huduma. Ukurasa wa Ustahimilivu hubadilisha usanidi pekee. --- ### Hamisha / Leta Hifadhidata Dhibiti nakala rudufu za hifadhidata katika **Dashibodi → Mipangilio → Mfumo na Hifadhi**. | Kitendo | Maelezo | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Hamisha Hifadhidata** | Hupakua hifadhidata ya sasa ya SQLite kama faili la `.sqlite` | | **Hamisha Zote (.tar.gz)** | Hupakua jalada kamili la nakala rudufu likijumuisha: hifadhidata, mipangilio, michanganyiko, miunganisho ya watoa huduma (bila vitambulisho), metadata ya funguo za API | | **Leta Hifadhidata** | Hupakia faili la `.sqlite` ili kuchukua nafasi ya hifadhidata ya sasa. Nakala rudufu ya kabla ya uletaji huundwa kiotomatiki isipokuwa `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Hamisha hifadhidata curl -o backup.sqlite http://localhost:20128/api/db-backups/export # API: Hamisha zote (jalada kamili) curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll # API: Leta hifadhidata curl -X POST http://localhost:20128/api/db-backups/import \ -F "file=@backup.sqlite" ``` **Uthibitishaji wa Uletaji:** Faili lililoletwa hukaguliwa ili kuthibitisha uadilifu wake (ukaguzi wa pragma wa SQLite), majedwali yanayohitajika (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), na ukubwa (kiwango cha juu ni 100MB). **Matumizi:** - Hamisha OmniRoute kati ya mashine - Unda nakala rudufu za nje kwa ajili ya urejeshaji baada ya janga - Shiriki usanidi kati ya washiriki wa timu (hamisha zote → shiriki jalada) --- ### Dashibodi ya Mipangilio Ukurasa wa mipangilio umepangwa katika **vichupo 7** ili kurahisisha uelekezaji: | Kichupo | Yaliyomo | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Jumla** | Zana za hifadhi ya mfumo, tabia chaguomsingi, mwonekano wa handaki la endpoint | | **Mwonekano** | Vidhibiti vya mandhari (angavu/giza/mfumo), mwonekano wa utepe wa pembeni, vibadilishaji vya paneli za kadi za handaki za Cloudflare/Tailscale/ngrok | | **AI** | Bajeti ya kufikiri (pitisha moja kwa moja / ondoa kiotomatiki / maalum / inayobadilika — angalia [THINKING_BUDGET.md](./THINKING_BUDGET.md)), prompt ya mfumo mzima, takwimu za akiba ya prompt | | **Usalama** | Mipangilio ya kuingia/Nenosiri, Udhibiti wa Ufikiaji wa IP, uthibitishaji wa API kwa `/models`, Kuzuia Watoa Huduma, ulinzi dhidi ya uingizaji wa prompt | | **Uelekezaji** | Mkakati wa jumla wa uelekezaji (Jaza Kwanza / Zamu kwa Zamu / P2C / Nasibu / Iliyotumika Kidogo Zaidi / Iliyoboreshwa kwa Gharama), lakabu za modeli zenye wildcard, misururu ya fallback, chaguomsingi za michanganyiko | | **Ustahimilivu** | Foleni ya maombi, kipindi cha kusubiri cha muunganisho, usanidi wa kikata mzunguko cha mtoa huduma, na tabia ya kusubiri hadi kipindi cha kusubiri kiishe | | **Mahiri** | Usanidi wa proksi wa mfumo mzima (HTTP/SOCKS5), ubatilishaji wa proksi kwa kila mtoa huduma | Sehemu ya Jumla hairudii tena madokezo ya kumbukumbu na akiba ambayo ni ya kusoma tu. Mipangilio ya muda wa kuhifadhi hifadhidata na uboreshaji huhifadhiwa kupitia `/api/settings/database`; ufutaji wa akiba kwa mikono hutumia `DELETE /api/cache`. Vikomo vya idadi ya safu za kumbukumbu za maombi na proksi hudhibitiwa na `CALL_LOGS_TABLE_MAX_ROWS` na `PROXY_LOGS_TABLE_MAX_ROWS`. --- ### Usimamizi wa Gharama na Bajeti Fikia kupitia **Dashibodi → Gharama**. | Kichupo | Kusudi | | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | **Bajeti** | Weka vikomo vya matumizi kwa kila funguo ya API kwa bajeti za kila siku/kila wiki/kila mwezi na ufuatiliaji wa wakati halisi | | **Bei** | Tazama na uhariri maingizo ya bei za modeli — gharama kwa kila tokeni 1K za ingizo/tokeo kwa kila mtoa huduma | ```bash # API: Weka bajeti curl -X POST http://localhost:20128/api/usage/budget \ -H "Content-Type: application/json" \ -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}' # API: Pata hali ya sasa ya bajeti curl http://localhost:20128/api/usage/budget ``` **Ufuatiliaji wa Gharama:** Kila ombi hurekodi matumizi ya tokeni na kukokotoa gharama kwa kutumia jedwali la bei. Tazama uchanganuzi katika **Dashibodi → Matumizi** kwa mtoa huduma, modeli, na funguo ya API. --- ### Unukuzi wa Sauti OmniRoute inasaidia unukuzi wa sauti kupitia endpoint inayooana na OpenAI: ```bash POST /v1/audio/transcriptions Authorization: Bearer your-api-key Content-Type: multipart/form-data # Mfano kwa kutumia curl curl -X POST http://localhost:20128/v1/audio/transcriptions \ -H "Authorization: Bearer your-api-key" \ -F "file=@audio.mp3" \ -F "model=openai/whisper-1" ``` `deepgram/nova-3` ni njia asilia ya Deepgram na inahitaji funguo ya API ya Deepgram. Ikiwa OpenRouter pekee ndiyo imesanidiwa, tumia `openrouter/deepgram/nova-3`. Watoa huduma wa **Kubadilisha Sauti kuwa Maandishi (unukuzi)**: - `openai/` (inaoana na whisper) - `groq/` (Groq Whisper Turbo) - `deepgram/` (familia ya Nova) - `assemblyai/` - `nvidia/` (Parakeet, Canary) - `huggingface/` (aina za whisper) - `qwen/` Watoa huduma wa **Kubadilisha Maandishi kuwa Sauti (`POST /v1/audio/speech`)**: - `openai/` (tts-1, tts-1-hd) - `hyperbolic/` - `deepgram/` (Aura) - `nvidia/` (Magpie TTS) - `elevenlabs/` - `huggingface/` - `inworld/` - `cartesia/` - `playht/` - `kie/` - `aws-polly/` - `xiaomi-mimo/` - `coqui/`, `tortoise/` - `qwen/` Miundo ya sauti inayotumika kwa unukuzi: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. Miundo ya matokeo ya TTS hutegemea mtoa huduma (mp3, wav, opus, pcm, mulaw). --- ### Mikakati ya Kusawazisha Michanganyiko Sanidi usawazishaji kwa kila mchanganyiko katika **Dashibodi → Michanganyiko → Unda/Hariri → Mkakati**. | Mkakati | Maelezo | | ---------------------------- | ------------------------------------------------------------------------------------------------------ | | **Mzunguko** | Huzunguka kwenye modeli kwa mpangilio | | **Kipaumbele** | Hujaribu modeli ya kwanza kila wakati; hutumia mbadala iwapo tu kuna hitilafu | | **Nasibu** | Huchagua modeli nasibu kutoka kwenye mchanganyiko kwa kila ombi | | **Uzani** | Huelekeza kwa uwiano kulingana na uzani uliowekwa kwa kila modeli | | **Iliyotumika Kidogo Zaidi** | Huelekeza kwenye modeli yenye maombi machache zaidi ya hivi karibuni (hutumia vipimo vya mchanganyiko) | | **Uboreshaji wa Gharama** | Huelekeza kwenye modeli ya bei nafuu zaidi inayopatikana (hutumia jedwali la bei) | Chaguo-msingi za jumla za mchanganyiko zinaweza kuwekwa katika **Dashibodi → Mipangilio → Uelekezaji → Chaguo-msingi za Mchanganyiko**. Kwa chaguo-msingi, muda wa kuisha wa malengo ya mchanganyiko hurithi muda wa kuisha wa ombi la sasa. Tumia **Muda wa kuisha wa lengo (sekunde)** katika chaguo-msingi za mchanganyiko au mchanganyiko mahususi pale tu ambapo kikomo kifupi kwa kila lengo kinapaswa kuanzisha matumizi ya mbadala kwa haraka zaidi. Uboreshaji wa mchanganyiko usio na ukawivu lazima uchaguliwe kwa hiari. Acha **Uboreshaji usio na ukawivu** ukiwa umezimwa ili kuzuia vipengele hivi vya ukawivu kushindanisha malengo mbadala, kuruka malengo kulingana na historia ya TTFT, au kubana maombi mbadala; kuuwezesha huruhusu uwekaji sambamba uliosanidiwa, urukaji wa kubashiri wa TTFT, na ubanaji wa mapema wa mbadala kubadilishana uaminifu wa uelekezaji/ombi kwa ukawivu mdogo wa hali mbaya zaidi. Zima **Akiba ya tokeni za u reasoning** wakati watoa huduma wa juu wanahitaji vikomo vikali vya `max_tokens` / `maxOutputTokens`. Ikiwashwa, uelekezaji wa mchanganyiko huongeza nafasi ya ziada ya modeli za u reasoning kwa modeli zilizo na kikomo cha matokeo kinachojulikana pekee na huacha kikomo cha tokeni cha mteja bila kubadilishwa wakati thamani salama yenye akiba ingezidi kikomo hicho. Ikiwa kikomo cha mteja tayari kiko juu ya kikomo kinachojulikana, OmniRoute hukipunguza hadi kwenye kikomo hicho kabla ya kutuma ombi kwa mtoa huduma wa juu. --- ### Dashibodi ya Afya Fikia kupitia **Dashibodi → Afya**. Muhtasari wa afya ya mfumo wa wakati halisi wenye kadi 6: | Kadi | Inachoonyesha | | ------------------------- | -------------------------------------------------------------------------------------------- | | **Hali ya Mfumo** | Muda wa kufanya kazi, toleo, matumizi ya kumbukumbu, saraka ya data | | **Afya ya Mtoa Huduma** | Hali ya wakati wa utekelezaji ya kivunja saketi cha kimataifa cha mtoa huduma | | **Vikomo vya Kasi** | Vipindi vinavyotumika vya kusubiri kwa miunganisho kwa kila akaunti pamoja na muda uliosalia | | **Vizuizi Vinavyotumika** | Vizuizi vinavyotumika vinavyohusu modeli na uondoaji wa muda | | **Akiba ya Sahihi** | Takwimu za akiba ya uondoaji wa nakala (funguo zinazotumika, kiwango cha mafanikio) | | **Telemetria ya Ukawivu** | Ujumlishaji wa ukawivu wa p50/p95/p99 kwa kila mtoa huduma | **Kidokezo cha Kitaalamu:** Ukurasa wa Afya hujisasisha kiotomatiki kila baada ya sekunde 10. Tumia kadi ya kivunja saketi kutambua watoa huduma wanaokumbana na matatizo. --- ## 🤖 Uelekezaji Otomatiki (Usanidi-sifuri) OmniRoute huja na **kielekezaji otomatiki kinachoendeshwa na alama** ambacho huchagua modeli bora kwa kila ombi katika kila mtoa huduma aliyeunganishwa — hakuna mchanganyiko wa kudumisha. Tuma tu ombi ukitumia mojawapo ya viambishi awali vya `auto/*`, na OmniRoute itaunda mchanganyiko pepe papo hapo, huku ikiwapa watahiniwa alama kulingana na muda wa kusubiri, gharama, kiwango cha mafanikio, kufaa kwa muktadha, ufaafu wa modeli kwa kazi, kushindwa kwa hivi karibuni, mgao, na hali ya kivunja mzunguko. | Kiambishi awali | Huboresha kwa ajili ya | | --------------- | -------------------------------------------------------------------------------------------------------------------- | | `auto` | Chaguo-msingi lenye uwiano (muda wa kusubiri × gharama × kiwango cha mafanikio) | | `auto/coding` | Kazi za uandishi wa msimbo: hupendelea Claude, GPT-5, GLM, Kimi, Qwen Coder, DeepSeek coders | | `auto/cheap` | $/token ya chini zaidi, hukubali muda mrefu zaidi wa kusubiri | | `auto/fast` | Muda mfupi zaidi wa kusubiri, hupuuza gharama | | `auto/offline` | Watoa huduma wa ndani pekee (Ollama, vLLM, llama.cpp) — muhimu kwa usanidi usio na mtandao | | `auto/smart` | Ubora wa kufikiri kwanza (Opus, GPT-5 xhigh, R1, GLM 5.1 reasoning) | | `auto/lkgp` | "Mtoa Huduma Mzuri wa Mwisho Kujulikana" — humfungamanisha mtoa huduma aliyefaulu mwisho, kisha hurudi kwenye kanuni | Mfano: ```bash curl -X POST http://localhost:20128/v1/chat/completions \ -H "Authorization: Bearer $OMNIROUTE_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "auto/coding", "messages": [{ "role": "user", "content": "Panga upya kitendakazi hiki cha Python" }], "stream": true }' ``` Kielekezaji otomatiki kimefafanuliwa kikamilifu katika [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — ikijumuisha jinsi ya kurekebisha uzito wa alama, kuweka watoa huduma kwenye orodha nyeusi, na kukagua maamuzi ya uelekezaji katika **Dashibodi → Mchanganyiko Otomatiki**. --- ## 🔌 Muunganisho wa MCP na A2A OmniRoute ni **seva ya MCP** (Itifaki ya Muktadha wa Modeli) na pia **seva ya A2A** (JSON-RPC 2.0 ya Wakala-kwa-Wakala). IDE yoyote inayooana na MCP au kipangishi cha wakala kinaweza kuita zana za OmniRoute moja kwa moja — hakuna kifungashio cha ziada kinachohitajika. ### Njia za usafirishaji za MCP - **SSE**: `http://localhost:20128/api/mcp/sse` - **HTTP inayoweza kutiririshwa**: `http://localhost:20128/api/mcp/stream` - **stdio**: `omniroute --mcp` (kwa programu-jalizi za IDE zinazopendelea stdio) ### Unganisha Claude Desktop Hariri `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) au faili inayolingana kwenye Windows/Linux: ```json { "mcpServers": { "omniroute": { "command": "omniroute", "args": ["--mcp"] } } } ``` ### Unganisha Cursor / Continue / VS Code MCP Tumia URL ya SSE `http://localhost:20128/api/mcp/sse` na ufunguo wa API wa Bearer uliozalishwa katika **Dashibodi → Funguo za API**. ### Mawanda Kwa sasa MCP inafafanua mawanda 32 yenye majina. Kila ufunguo wa Bearer unaweza kuwekewa kikomo cha mawanda mahususi — angalia [MCP-SERVER.md](../frameworks/MCP-SERVER.md) kwa orodha rasmi ya mawanda na zana, na [A2A-SERVER.md](../frameworks/A2A-SERVER.md) kwa skema ya JSON-RPC. --- ## 🧠 Mfumo wa Ujuzi OmniRoute hutoa **mfumo wa ujuzi** unaoweza kupanuliwa (`src/lib/skills/`) ili mawakala na endpoint ya A2A ziweze kuendesha taratibu maalum za nyanja mbalimbali (k.m. `code-review`, `summarize`, `extract-facts`, `web-research`). - **Kiolesura cha Marketplace** — Vinjari na usakinishe ujuzi kupitia **Dashboard → Skills** - **Mawanda kwa kila ufunguo** — Dhibiti ni funguo zipi za API zinazoweza kuitisha ujuzi upi - **Ujuzi maalum** — Weka faili ya TypeScript katika `src/lib/a2a/skills/`, isajili, na mara moja itaweza kuitishwa kupitia A2A Rejeleo kamili: [SKILLS.md](../frameworks/SKILLS.md). --- ## 💾 Mfumo wa Kumbukumbu OmniRoute huhifadhi **kumbukumbu ya muda mrefu ya mazungumzo** kwa kutumia urejeshaji mseto: - **SQLite FTS5** kwa utafutaji wa maneno muhimu katika zamu zilizopita - **Hifadhi ya vekta ya Qdrant** (ya hiari) kwa ukumbukaji wa kisemantiki - **Uchimbaji wa taarifa kiotomatiki** — huluki, mapendeleo na maamuzi hufupishwa baada ya kila kipindi na kuhifadhiwa katika jedwali la `memory_facts` - Kumbukumbu hutenganishwa kwa kila ufunguo wa API na kwa kila kipindi Dhibiti kumbukumbu katika **Dashboard → Memory** (tafuta, hariri, hamisha, futa kabisa). Kiolesura cha HTTP (`/api/memory/*`) huruhusu mawakala kutuma na kuuliza taarifa kwa njia ya kiprogramu — tazama [MEMORY.md](../frameworks/MEMORY.md). --- ## 🔔 Webhooks Jisajili kupokea matukio ya OmniRoute kwa ufuatiliaji na uendeshaji otomatiki wa wakati halisi. - Unda webhook katika **Dashboard → Webhooks** ukiwa na URL lengwa na siri ya kutia sahihi ya HMAC - Matukio yanayopatikana: `request.completed`, `request.failed`, `provider.unavailable`, `budget.exceeded`, `combo.switched`, `circuit_breaker.opened`, `circuit_breaker.closed` - Kila payload inajumuisha `X-OmniRoute-Signature` (HMAC-SHA256) kwa ajili ya uthibitishaji - Majaribio ya kurudia: majaribio 3 yenye muda wa kusubiri unaoongezeka kwa kasi, kisha foleni ya ujumbe ulioshindikana Schema kamili katika [WEBHOOKS.md](../frameworks/WEBHOOKS.md). --- ## ☁️ Mawakala wa Wingu OmniRoute huunganishwa na mawakala wa uandishi wa msimbo wa wingu (**OpenAI Codex Cloud**, **Devin**, **Jules**, **Antigravity**) ili uweze kutuma kazi za muda mrefu kutoka kwenye dashboard ileile inayoshughulikia uratibu wako wa ndani. - Unda kazi katika **Dashboard → Cloud Agents** au kupitia `POST /api/v1/agents/tasks` - Fuatilia hali, kumbukumbu za matukio na vizalishwa kwa kila kazi - Tumia ufunguo wako mwenyewe wa API kwa kila mtoa huduma — vitambulisho haviondoki kamwe kwenye instance ya OmniRoute Rejeleo kamili: [CLOUD_AGENT.md](../frameworks/CLOUD_AGENT.md). --- ## 🛠️ Usimamizi wa Kiprogramu Unaweza kudhibiti kila rasilimali ya OmniRoute (watoa huduma, combos, funguo, mipangilio) kupitia HTTP ukitumia **ufunguo wa Bearer wenye wigo wa `manage`**. Tengeneza ufunguo katika **Dashboard → API Keys → New Key → Scope: manage**, kisha: ```bash # Orodhesha watoa huduma curl http://localhost:20128/api/providers \ -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" # Ongeza muunganisho wa mtoa huduma curl -X POST http://localhost:20128/api/providers \ -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \ -H "Content-Type: application/json" \ -d '{ "provider": "openai", "apiKey": "sk-...", "name": "main" }' # Unda combo curl -X POST http://localhost:20128/api/combos \ -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "premium", "strategy": "priority", "models": [{ "model": "cc/claude-opus-4-7" }, { "model": "glm/glm-5.1" }] }' # Orodhesha/unda funguo za API curl http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" curl -X POST http://localhost:20128/api/keys -H "Authorization: Bearer $OMNIROUTE_MANAGE_KEY" \ -d '{ "name": "ci-bot", "scopes": ["chat"] }' ``` Tazama [API_REFERENCE.md](../reference/API_REFERENCE.md) kwa orodha kamili ya endpoints na schema za maombi/majibu. --- ## 💻 CLI ya Ndani OmniRoute huja na CLI ya ndani (`omniroute …`) kwa ajili ya usanidi, uchunguzi na udhibiti wakati wa utekelezaji. Hii ni **tofauti na ukurasa wa "Zana za CLI" kwenye dashibodi**, ambao husanidi CLI za wahusika wengine (Claude Code, Cursor, Codex, Cline, …) ili ziweze kuwasiliana na OmniRoute. ```bash omniroute setup # Mchawi shirikishi (nenosiri, watoa huduma, michanganyiko) omniroute setup --non-interactive # Inafaa kwa CI omniroute doctor # Uchunguzi wa afya (saraka ya data, DB, watoa huduma, porti) omniroute providers available # Orodhesha watoa huduma wanaotumika omniroute providers list # Orodhesha miunganisho iliyosanidiwa omniroute providers test # Jaribu moja kwa moja muunganisho wa mtoa huduma omniroute combos list # Orodhesha michanganyiko omniroute combos switch # Weka mchanganyiko chaguo-msingi omniroute models # Orodhesha modeli zinazopatikana (--json, --search) omniroute keys add | list | remove # Dhibiti funguo za API kutoka kwenye terminali omniroute backup # Hifadhi picha ya muda ya usanidi + DB omniroute restore [] # Rejesha kutoka kwenye picha ya muda omniroute health # Afya ya kina (vikataji, akiba, kumbukumbu) omniroute quota # Matumizi ya kiwango cha mtoa huduma omniroute mcp status # Hali ya seva ya MCP omniroute a2a status # Hali ya seva ya A2A omniroute tunnel list|create|stop # Vichuguu vya Cloudflare/Tailscale/ngrok omniroute reset-password # Weka upya nenosiri la msimamizi omniroute --mcp # Anzisha seva ya MCP kupitia stdio omniroute --port 3000 # Anzisha seva kwenye porti maalum ``` Kidokezo: unganisha `omniroute doctor --json` na zana yako ya ufuatiliaji ili kutoa arifa kuhusu miunganisho ya watoa huduma isiyo na afya. --- ## 🖥️ Programu ya Eneo-kazi (Electron) OmniRoute inapatikana kama programu asilia ya eneo-kazi kwa Windows, macOS na Linux. ### Usakinishaji ```bash # Kutoka kwenye saraka ya electron: cd electron npm install # Hali ya uundaji (unganisha kwenye seva ya uundaji ya Next.js inayoendelea kufanya kazi): npm run dev # Hali ya uzalishaji (hutumia toleo linalojitegemea): npm start ``` ### Kuunda Visakinishaji ```bash cd electron npm run build # Mfumo wa sasa npm run build:win # Windows (.exe NSIS) npm run build:mac # macOS (.dmg universal) npm run build:linux # Linux (.AppImage) ``` Matokeo → `electron/dist-electron/` ### Vipengele Muhimu | Kipengele | Maelezo | | ------------------------------ | ----------------------------------------------------------------------- | | **Utayari wa Seva** | Hukagua seva kabla ya kuonyesha dirisha (hakuna skrini tupu) | | **Trei ya Mfumo** | Punguza hadi kwenye trei, badilisha porti, funga kupitia menyu ya trei | | **Usimamizi wa Porti** | Badilisha porti ya seva kupitia trei (seva huanzishwa upya kiotomatiki) | | **Sera ya Usalama wa Maudhui** | CSP yenye vizuizi kupitia vichwa vya kipindi | | **Nakala Moja** | Ni nakala moja tu ya programu inayoweza kufanya kazi kwa wakati mmoja | | **Hali ya Nje ya Mtandao** | Seva iliyojumuishwa ya Next.js hufanya kazi bila intaneti | ### Vigeu vya Mazingira | Kigeu | Chaguo-msingi | Maelezo | | --------------------- | ------------- | ----------------------------------------- | | `OMNIROUTE_PORT` | `20128` | Porti ya seva | | `OMNIROUTE_MEMORY_MB` | `512` | Kikomo cha heap cha Node.js (64–16384 MB) | 📖 Nyaraka kamili: [`electron/README.md`](../../electron/README.md)