# OmniRoute Auto-Combo Engine (Hausa) 🌐 **Languages:** 🇺🇸 [English](../../../../routing/AUTO-COMBO.md) · 🇪🇹 [am](../../../am/docs/routing/AUTO-COMBO.md) · 🇸🇦 [ar](../../../ar/docs/routing/AUTO-COMBO.md) · 🇦🇿 [az](../../../az/docs/routing/AUTO-COMBO.md) · 🇧🇬 [bg](../../../bg/docs/routing/AUTO-COMBO.md) · 🇧🇩 [bn](../../../bn/docs/routing/AUTO-COMBO.md) · 🇧🇦 [bs](../../../bs/docs/routing/AUTO-COMBO.md) · 🇨🇿 [cs](../../../cs/docs/routing/AUTO-COMBO.md) · 🇩🇰 [da](../../../da/docs/routing/AUTO-COMBO.md) · 🇩🇪 [de](../../../de/docs/routing/AUTO-COMBO.md) · 🇬🇷 [el](../../../el/docs/routing/AUTO-COMBO.md) · 🇪🇸 [es](../../../es/docs/routing/AUTO-COMBO.md) · 🇪🇪 [et](../../../et/docs/routing/AUTO-COMBO.md) · 🇮🇷 [fa](../../../fa/docs/routing/AUTO-COMBO.md) · 🇫🇮 [fi](../../../fi/docs/routing/AUTO-COMBO.md) · 🇫🇷 [fr](../../../fr/docs/routing/AUTO-COMBO.md) · 🇮🇪 [ga](../../../ga/docs/routing/AUTO-COMBO.md) · 🇮🇳 [gu](../../../gu/docs/routing/AUTO-COMBO.md) · 🇮🇱 [he](../../../he/docs/routing/AUTO-COMBO.md) · 🇮🇳 [hi](../../../hi/docs/routing/AUTO-COMBO.md) · 🇭🇷 [hr](../../../hr/docs/routing/AUTO-COMBO.md) · 🇭🇺 [hu](../../../hu/docs/routing/AUTO-COMBO.md) · 🇦🇲 [hy](../../../hy/docs/routing/AUTO-COMBO.md) · 🇮🇩 [id](../../../id/docs/routing/AUTO-COMBO.md) · 🇳🇬 [ig](../../../ig/docs/routing/AUTO-COMBO.md) · 🇮🇹 [it](../../../it/docs/routing/AUTO-COMBO.md) · 🇯🇵 [ja](../../../ja/docs/routing/AUTO-COMBO.md) · 🇬🇪 [ka](../../../ka/docs/routing/AUTO-COMBO.md) · 🇰🇭 [km](../../../km/docs/routing/AUTO-COMBO.md) · 🇮🇳 [kn](../../../kn/docs/routing/AUTO-COMBO.md) · 🇰🇷 [ko](../../../ko/docs/routing/AUTO-COMBO.md) · 🇱🇹 [lt](../../../lt/docs/routing/AUTO-COMBO.md) · 🇱🇻 [lv](../../../lv/docs/routing/AUTO-COMBO.md) · 🇮🇳 [ml](../../../ml/docs/routing/AUTO-COMBO.md) · 🇮🇳 [mr](../../../mr/docs/routing/AUTO-COMBO.md) · 🇲🇾 [ms](../../../ms/docs/routing/AUTO-COMBO.md) · 🇲🇹 [mt](../../../mt/docs/routing/AUTO-COMBO.md) · 🇲🇲 [my](../../../my/docs/routing/AUTO-COMBO.md) · 🇳🇵 [ne](../../../ne/docs/routing/AUTO-COMBO.md) · 🇳🇱 [nl](../../../nl/docs/routing/AUTO-COMBO.md) · 🇳🇴 [no](../../../no/docs/routing/AUTO-COMBO.md) · 🇮🇳 [or](../../../or/docs/routing/AUTO-COMBO.md) · 🇮🇳 [pa](../../../pa/docs/routing/AUTO-COMBO.md) · 🇵🇭 [phi](../../../phi/docs/routing/AUTO-COMBO.md) · 🇵🇱 [pl](../../../pl/docs/routing/AUTO-COMBO.md) · 🇵🇹 [pt](../../../pt/docs/routing/AUTO-COMBO.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/routing/AUTO-COMBO.md) · 🇷🇴 [ro](../../../ro/docs/routing/AUTO-COMBO.md) · 🇷🇺 [ru](../../../ru/docs/routing/AUTO-COMBO.md) · 🇱🇰 [si](../../../si/docs/routing/AUTO-COMBO.md) · 🇸🇰 [sk](../../../sk/docs/routing/AUTO-COMBO.md) · 🇸🇮 [sl](../../../sl/docs/routing/AUTO-COMBO.md) · 🇷🇸 [sr](../../../sr/docs/routing/AUTO-COMBO.md) · 🇸🇪 [sv](../../../sv/docs/routing/AUTO-COMBO.md) · 🇰🇪 [sw](../../../sw/docs/routing/AUTO-COMBO.md) · 🇮🇳 [ta](../../../ta/docs/routing/AUTO-COMBO.md) · 🇮🇳 [te](../../../te/docs/routing/AUTO-COMBO.md) · 🇹🇭 [th](../../../th/docs/routing/AUTO-COMBO.md) · 🇹🇷 [tr](../../../tr/docs/routing/AUTO-COMBO.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/routing/AUTO-COMBO.md) · 🇵🇰 [ur](../../../ur/docs/routing/AUTO-COMBO.md) · 🇺🇿 [uz](../../../uz/docs/routing/AUTO-COMBO.md) · 🇻🇳 [vi](../../../vi/docs/routing/AUTO-COMBO.md) · 🇳🇬 [yo](../../../yo/docs/routing/AUTO-COMBO.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/routing/AUTO-COMBO.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/routing/AUTO-COMBO.md) --- > **Ga Masu Amfani**: Kuna neman hanyar farawa cikin sauri? Duba [Jagorar Mai Amfani da Auto-Combo](../getting-started/AUTO-COMBO-GUIDE.md) don bayani da misalai masu sauƙi. > Jerin samfura masu sarrafa kansu tare da kimantawa mai daidaituwa + tura buƙatu ta atomatik ba tare da saiti ba ## Tura-Hanya ta Atomatik Ba Tare da Saitawa Ba (prefix na `auto/`) > **SABO:** Ba a buƙatar ƙirƙirar combo. Yi amfani da prefix na `auto/` kai tsaye a kowace client. ### Misalai Masu Sauri | ID na Model | Nau'i | Halayya | | -------------- | ------- | ------------------------------------------------------------------------------ | | `auto` | default | Duk providers da aka haɗa, dabarar LKGP, daidaitattun nauyi | | `auto/coding` | coding | Nauyin da ke fifita inganci, ya dace da samar da code | | `auto/fast` | fast | Zaɓi mai nauyi wanda ke da ƙarancin jinkiri | | `auto/cheap` | cheap | Tura-hanya da aka inganta don rage kuɗi (mafi ƙarancin kuɗi da farko) | | `auto/offline` | offline | Yana fifita providers masu mafi yawan wadatar quota | | `auto/smart` | smart | Fifita inganci + ƙarin adadin bincike (10%) don gano ingantattun models | | `auto/lkgp` | lkgp | LKGP kai tsaye (daidai da default `auto`) | | `auto/chaos` | chaos | Rarrabawa a layi ɗaya, model ɗaya ga kowane provider (ba shigar da matsala ba) | ### Haɗin Category × Tier (`auto/:`) Suffixes irin na OpenRouter suna ware **irin hanyar da ake so** (category) daga **yadda za a inganta ta** (tier), saboda haka za ka iya haɗa su yadda kake so (#4235 Phase B, `open-sse/services/autoCombo/suffixComposition.ts`): - **Categories** (tace tarin candidates bisa capability): `coding` · `reasoning` · `vision` · `chat` · `multimodal`. `vision`/`multimodal` suna barin models masu capability na vision; `reasoning` yana barin models na reasoning/thinking. - **Tiers** (zaɓi nauyin ƙididdiga / tace tarin): `fast` (ship-fast) · `cheap` (alias `floor`, mai rage kuɗi) · `reliable` (lafiyar circuit-breaker + daidaiton latency) · `free` / `pro` (tace tarin bisa tier na model ta hanyar `classifyTier` — free-tier da premium). | Misali | Yana warwarewa zuwa | | ---------------------- | ------------------------------------------------------------------ | | `auto/coding:fast` | tarin coding, nauyin ƙarancin latency | | `auto/coding:cheap` | tarin coding, ingantacce don rage kuɗi (alias `auto/coding:floor`) | | `auto/reasoning:pro` | models na reasoning/thinking kawai, tier na premium | | `auto/vision` | models masu capability na vision (babu tier → daidaitattun nauyi) | | `auto/multimodal:free` | models masu capability na multimodal, free tier kawai | Duk wani ingantaccen `auto/[:]` ana warware shi lokacin da ake buƙata; ana tallata zaɓaɓɓun nau'uka a `/v1/models` da dashboard (`AUTO_SUFFIX_VARIANTS` a cikin `open-sse/services/autoCombo/builtinCatalog.ts`). Tacewar tana da tsarin **fail-open** — idan wani sharadi bai dace da ko ɗaya daga cikin models da aka haɗa ba, za a yi amfani da cikakken tarin domin kada tura-hanya ta taɓa lalacewa. Babban scorer (`combo.ts`) bai canza ba; ana amfani da tacewar category/tier a cikin `buildAutoCandidates`. > **Bayanan model kai tsaye:** dacewar tura-hanya ta atomatik tana amfani da matsayi na **Arena ELO** kai tsaye + bayanan tier na **models.dev** lokacin da aka kunna flag na `ARENA_ELO_SYNC_ENABLED` (idan ba haka ba, tana komawa ga static fitness map). **Yadda ake amfani da shi:** ```bash # Duk wani IDE ko kayan aikin CLI da ke goyon bayan tsarin OpenAI Base URL: http://localhost:20128/v1 API Key: # A cikin code/config ɗinka, saita model zuwa: model: "auto" # daidaitaccen default model: "auto/coding" # mafi dacewa da ayyukan coding model: "auto/fast" # mafi sauri da ake da shi model: "auto/cheap" # mafi arha ga kowane token ``` **Abin da ke faruwa:** 1. OmniRoute yana gano prefix na `auto/` a cikin `src/sse/handlers/chat.ts` 2. Yana tambayar duk **active provider connections** daga database 3. Yana tace su zuwa waɗanda ke da ingantattun credentials (API key ko OAuth token) 4. Yana tantance model ga kowane connection (`connection.defaultModel` ko model na farko na provider) 5. Yana gina **virtual combo** a cikin memory (ba a adana shi a DB) 6. Yana tura hanya ta amfani da weight profile na variant da aka zaɓa + dabarar LKGP **Muhimman siffofi:** - ✅ **Kullum a kunne:** Ba a buƙatar toggle, ƙirƙirar combo, ko configuration - ✅ **Mai sauyawa:** Yana nuna providers da aka haɗa a halin yanzu ta atomatik - ✅ **Mannewar session:** LKGP yana tabbatar da cewa ana fifita provider na ƙarshe da ya yi nasara - ✅ **Yana gane asusu da yawa:** Kowane provider connection yana zama candidate daban - ✅ **Babu rubutu a DB:** Virtual combo yana wanzuwa ne kawai don request ɗin, babu ƙarin nauyin persistence ### Sarrafa candidate ga kowane key (#7819, Level 1+2) `GET /v1/auto-combo/{channel}/candidates` (`{channel}` = suffix da ke bayan `auto/`, ko ainihin `auto` don base channel) endpoint ne na **read-only** wanda ke jera tarin candidates na yanzu na channel na `auto/*`, tare da bayanan reachability kai tsaye, yana sake amfani da resilience reads da ke akwai (ba ya taɓa amfani da raw breaker `state`): - circuit breaker na provider — `getCircuitBreaker(provider).getStatus()` / `.canExecute()` - cooldown na connection — `rateLimitedUntil` / `testStatus` a kan row na `provider_connections` da aka warware - kulle model — `isModelLocked(provider, connectionId, model)` Kowane candidate kuma yana ɗauke da flag na `excluded` na wannan API key. Ana adana exclusions bisa kowane API key (`auto_candidate_overrides` table, migration `128`) — OmniRoute tsari ne na single-tenant ba tare da `users` table ba, don haka `apiKeyId` shi ne ainihin shaida mafi kusa ta kowane caller — kuma ana tilasta su a mashigar candidate-pool a cikin `open-sse/services/autoCombo/virtualFactory.ts` ta hanyar `filterExcludedCandidates()` mai tsabta kuma wanda aka yi wa unit test (`open-sse/services/autoCombo/candidateOverrides.ts`). Tacewar tana da tsarin **fail-open**: apiKeyId/channel da ba a saita ba ko gazawar duba DB duka suna barin tarin ba tare da tacewa ba, saboda haka operator wanda ba shi da overrides da aka saita yana ganin tura-hanya mai bytes daidai da yadda take kafin wannan fasalin. **An ɗage zuwa batun da za a biyo baya:** nauyin kowane ɗan takara + fayyace jerantawa (Mataki na 3 — yana shiga cikin hanyoyin dabarun nauyi/fifiko da ake da su) da kuma ɗaure takamaiman dabarar `combo.ts` ga kowane tashar `auto/*` (Mataki na 4). Duba shirin #7819 don tambayar da har yanzu ba a warware ba kan ko ya kamata keɓancewar saituna su ci gaba da kasancewa na kowane API-key ko kuma su zama na gama-gari bisa la’akari da samfurin mai haya guda ɗaya. **A bayan fage:** ```txt Buƙata: { model: "auto/coding" } ↓ src/sse/handlers/chat.ts yana gano prefix ↓ createVirtualAutoCombo('coding') → tarin ƴan takara daga haɗin da ke aiki ↓ handleComboChat (inji iri ɗaya da na combo da aka adana) ↓ Ƙididdigar atomatik tana zaɓar mafi kyawun mai samarwa/samfuri ga kowace buƙata ``` **Fayilolin aiwatarwa:** | Fayil | Manufa | | --------------------------------------------------------- | -------------------------------------------------------- | | `open-sse/services/autoCombo/autoPrefix.ts` | Mai fassara prefix (`parseAutoPrefix`) | | `open-sse/services/autoCombo/virtualFactory.ts` | Yana ƙirƙirar abubuwan `AutoComboConfig` na kama-da-wane | | `open-sse/services/autoCombo/providerRegistryAccessor.ts` | Hanyar gwaji don kwaikwayon rajistar masu samarwa | | `src/sse/handlers/chat.ts` | Haɗawa: gajeriyar hanyar prefix na atomatik | | `src/shared/constants/providers.ts` | Shigarwar tsarin `SYSTEM_PROVIDERS.auto` | ## Sunayen Combo Masu Daidai da Ainihin Model Id Combo wanda `name` ɗinsa yake daidai da ainihin model id kai tsaye (misali, combo mai suna `gpt-5.5`) wani **tsari ne da aka yi da gangan kuma ake tallafawa**, ba bug ba ne: shi ne hanyar komawa ga wani provider daban bisa kowane model id da aka rubuta a [#6940](https://github.com/diegosouzapw/OmniRoute/issues/6940). Saboda ana duba warware combo kafin warware model id kai tsaye (`getComboForModel()` a cikin `src/sse/services/model.ts`), buƙatar ainihin id `gpt-5.5` za ta bi ta cikin targets na combo (misali, `acme-responses/gpt-5.5`, `backup-responses/gpt-5.5`) maimakon a tura ta kai tsaye zuwa provider guda ɗaya — wannan yana sake amfani da fifikon combo-kafin-rewrite da aka gina domin [#3227/#3233](https://github.com/diegosouzapw/OmniRoute/issues/3227), kuma ana yi masa gwajin regression ta `tests/unit/responses-combo-resolution-3227.test.ts` da `tests/unit/combo-name-codex-responses-rewrite.test.ts`. Ƙirƙira ko sake sanya wa combo suna wanda zai rufe ainihin model id **ba a taɓa ƙin yarda da shi** — yin hakan zai karya wannan tsarin aiki da aka rubuta. A maimakon haka (#8530), `POST /api/combos` da `PUT /api/combos/[id]` suna haɗa filin `warning` wanda ba ya hana aiki cikin response idan (sabon) sunan ya yi karo da ainihin model id: ```json { "warning": { "code": "COMBO_NAME_SHADOWS_MODEL", "modelId": "gpt-5.5", "providerId": "openai" } } ``` A lokacin farawa, `scanComboModelNameCollisionsAtBoot()` (`src/instrumentation-node.ts`) yana kuma rubuta gargaɗin `[STARTUP]` na layi guda wanda ke jera duk combo da ke rufe model id, domin masu gudanarwa waɗanda suka ci karo da wannan bisa kuskure (maimakon da gangan, bisa #6940) su sami sanarwa. Helper na ganowa yana cikin `src/lib/combos/modelNameCollision.ts`. ## Kiran Custom Combo Daga Client Persisted combos (Saituna → Combos) ana amfani da su ne kawai idan client ya aika da **ainihin sunan** combo a cikin filin `model` — babu fuzzy ko partial matching na sunan combo, kuma ba a amfani da prefix na `auto/`. Jerin warwarewa (`getComboForModel()` a cikin `src/sse/services/model.ts`): 1. daidaituwar ainihin sunan combo (`model: "my-combo"`), 2. prefix na `combo/` (`model: "combo/my-combo"`), 3. glob mappings na model→combo (`/api/model-combo-mappings`). ```bash curl -X POST http://localhost:20128/v1/chat/completions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"model":"my-combo","messages":[{"role":"user","content":"Hello"}]}' ``` Kurakurai biyu da aka fi yi: - **`auto` ba ya amfani da combos ɗinka.** `auto`/`auto/*` yana gina nasa candidate pool na zero-config kuma yana duba persisted combos ne kawai idan akwai combo da ainihin sunansa yake `auto` (ba a ba da shawarar hakan). Domin a yi routing ta combo, aika ainihin sunansa — ba `auto` ba. - **`openrouter/auto` ainihin samfurin OpenRouter ne mai kuɗi** ("Auto Best Available"), ba alias na OmniRoute ba ne. Shi ne model entry guda ɗaya tak na OpenRouter registry (`open-sse/config/providers/registry/openrouter/index.ts`) kuma ana cajinsa daban. Yi amfani da Saituna → Routing → Ɓoye models masu kuɗi domin cire shi daga `auto` pools. Duba [#7992](https://github.com/diegosouzapw/OmniRoute/issues/7992) da [#7111](https://github.com/diegosouzapw/OmniRoute/issues/7111) domin ruɗanin farko da wannan rubutun ke fayyacewa. ## Yadda Yake Aiki (Auto-Combos Masu Dorewa) Injin Auto-Combo yana zaɓar mafi kyawun mai samarwa/samfuri a kai a kai ga kowace buƙata ta amfani da **aikin ƙididdiga mai ma'auni 16** (wanda aka ayyana a `open-sse/services/autoCombo/scoring.ts` → `DEFAULT_WEIGHTS`). Jimillar tsoffin nauye-nauyen ita ce `1.0`; ana sake daidaita nauye-nauyen da aka keɓance ta hanyar `normalizeScoringWeights()`. Biyu daga cikin goma sha shida ɗin — `cacheAffinity` da `resetWindowAffinity` — suna da tsohon nauyi na `0`; `reliability` yana da `0` a cikin `DEFAULT_WEIGHTS` amma `0.03` a cikin fakiti na gama-gari da `0.04` a cikin `reliability-first`, sannan `quality` yana da `0.02` a cikin fakiti (`0.03` a cikin `quality-first`): duk da haka ana ƙididdige su ga kowane ɗan takara, kuma `cacheAffinity` yana sarrafa cire maimaituwar prompt-cache a wajen makin, don haka abubuwan da tsohon nauyinsu sifili ne kawai ba sa bayar da tasiri ta tsohuwa, yayin da fakiti suke yi. ![Ƙididdigar Auto-Combo mai ma'auni 16](../diagrams/exported/auto-combo-scoring.svg) > Tushe: [diagrams/auto-combo-scoring.mmd](../diagrams/auto-combo-scoring.mmd) (sake samarwa ta hanyar `npm run docs:render-diagrams`). Sunan fayil ɗin na tarihi ne; tushen da zanen da aka samar suna nuna dukkan ma'aunai 16 da aka ayyana a cikin `DEFAULT_WEIGHTS`. | Ma'auni | Tsohon Nauyi | Bayani | | :-------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `quota` | 0.1429 | Ragowar kaso / sararin iyakar ƙimar amfani [0..1] | | `health` | 0.1605 | Makin lafiya daga circuit breaker (CLOSED=1.0, HALF_OPEN=0.5, OPEN=0.0) | | `costInv` | 0.1429 | Akasin kuɗin da aka **haɗa** (60% farashin token na shigarwa + 40% farashin token na fitarwa, an daidaita) — mafi arha = mafi girman maki | | `latencyInv` | 0.1143 | Akasin jinkirin p95 da aka daidaita da rukunin — mafi sauri = mafi girman maki | | `taskFit` | 0.0762 | Dacewa da nau'in aiki (rubuta lamba, bita, tsarawa, nazari, gyaran kurakurai, takardu) | | `stability` | 0.0476 | Kwanciyar hankali bisa bambanci daga daidaitaccen karkatar jinkiri — ɗan takarar da lokacin amsawarsa ke yawan canzawa yana samun ƙaramin maki | | `tierPriority` | 0.0476 | Fifikon matakin asusu — Ultra=1.0, Pro=0.67, Standard=0.33, Free=0.0 | | `tierAffinity` | 0.0476 | Dacewa tsakanin matakin ɗan takara da matakin da manifest ya ba da shawara | | `specificityMatch` | 0.0476 | Daidaituwa tsakanin takamaiman buƙatar (alamu daga manifest) da matakin samfurin | | `contextAffinity` | 0.0476 | Dacewa tsakanin buƙatar girman taga mahallin da tagar mahallin samfurin | | `sessionAvailability` | 0.0476 | Samuwar zaman OAuth na haɗin ɗan takara ga wannan zaman (`getOAuthSessionAvailability()`; haɗe-haɗen da ba na OAuth ba suna samun maki 1.0) | | `connectionDensity` | 0.0476 | Yana rarraba nauyi tsakanin haɗe-haɗen mai samarwa ɗaya (hana taruwa a wuri guda) | | `cacheAffinity` | 0.00 | Dacewar rendezvous-hash zuwa haɗin da ya fi yiwuwa ya riga ya riƙe prefix na prompt-cache na wannan buƙatar (`open-sse/services/combo/promptCacheAffinity.ts`); a kashe yake ta tsohuwa (#8008) | | `resetWindowAffinity` | 0.00 | Nuna fifiko ga haɗe-haɗen da tagar sake saita kasonsu ta fi dacewa (a kashe yake ta tsohuwa) | | `quality` | 0.03 | Alamar ingancin fitarwa bisa ra'ayoyin masu amfani daga mai bin diddigin ingancin routing-event; 'yan takarar da ba su da bayanan lura suna karɓar matsakaicin 0.5 | | `reliability` | 0.00 | Adadin nasarar da aka lura, `1 - failureRate`, daga tarihin amfani na awa 24 bayan cika mafi ƙarancin samfura goma (in ba haka ba ana amfani da ma'aunin ainihin lokaci); 'yan takarar da ba su da bayanan lura ana ɗaukarsu a matsayin 1.0. A kashe yake ta tsohuwa | `quality` (`open-sse/services/routing/quality.ts`): `cold restart → ∅`; `observations = 0 → score 0.5`. **Jimilla:** `0.1429 + 0.1605 + 0.1429 + 0.1143 + 0.0762 + (7 × 0.0476) + 0.00 + 0.00 + 0.03 + 0.00 = 1.0` kamar yadda aka ayyana a cikin `DEFAULT_WEIGHTS`; ana sake daidaita nauye-nauyen da mai amfani ya saita zuwa rabon ƙididdiga ta hanyar `normalizeScoringWeights()` kafin a ƙididdige maki. ## Fakitin Yanayi Akwai bayanan ma'auni guda 6 da aka riga aka ayyana a cikin `open-sse/services/autoCombo/modePacks.ts`. Kowanne fakiti yana maye gurbin tsoffin ma'aunai gaba ɗaya domin karkatar da zaɓi zuwa ga manufa guda. Jimillar kowane fakiti ta riga ta kai `1.0` (`0.9999` idan aka nuna zuwa guraben adadi huɗu), don haka `normalizeScoringWeights()` ba shi da wani abu mai ma'ana da zai gyara lokacin da fakiti yake aiki — ƙimomin da ke ƙasa, bayan zagaye, su ne waɗanda mai ƙididdigar maki yake amfani da su. | Ma'auni | ship-fast | cost-saver | quality-first | offline-friendly | reliability-first | chaos-mode | | :-------------------- | :--------- | :--------- | :------------ | :--------------- | :---------------- | :--------- | | `quota` | 0.1133 | 0.1133 | 0.0752 | **0.3324** | 0.1133 | 0.0376 | | `health` | 0.2667 | 0.1810 | 0.1714 | 0.2667 | **0.3524** | **0.4000** | | `costInv` | 0.0276 | **0.3324** | 0.0276 | 0.0752 | 0.0181 | 0.0140 | | `latencyInv` | **0.3048** | 0.0476 | 0.0476 | 0.0476 | 0.0476 | 0.0186 | | `taskFit` | 0.0952 | 0.0952 | **0.3524** | 0.0000 | 0.0952 | 0.1905 | | `stability` | 0.0000 | 0.0476 | 0.1429 | 0.0952 | 0.1905 | 0.1714 | | `tierPriority` | 0.0376 | 0.0376 | 0.0276 | 0.0376 | 0.0276 | 0.0040 | | `tierAffinity` | 0.0000 | 0.0000 | 0.0000 | 0.0000 | 0.0000 | 0.0000 | | `specificityMatch` | 0.0000 | 0.0000 | 0.0000 | 0.0000 | 0.0000 | 0.0000 | | `contextAffinity` | 0.0095 | 0.0000 | 0.0000 | 0.0000 | 0.0000 | 0.0186 | | `sessionAvailability` | 0.0476 | 0.0476 | 0.0476 | 0.0476 | 0.0476 | 0.0476 | | `resetWindowAffinity` | 0.0000 | 0.0000 | 0.0000 | 0.0000 | 0.0000 | 0.0000 | | `connectionDensity` | 0.0476 | 0.0476 | 0.0476 | 0.0476 | 0.0476 | 0.0476 | | `quality` | 0.02 | 0.02 | **0.03** | 0.02 | 0.02 | 0.02 | | `reliability` | 0.03 | 0.03 | 0.03 | 0.03 | **0.04** | 0.03 | Bayanan kula: - **Fakitoci suna ɗauke da `quality` da `reliability`** (`quality 0.02`, `quality-first 0.03`; `reliability 0.03`, `reliability-first 0.04`) kuma suna maye gurbin taswirar ma'auni gaba ɗaya (`weights = pack`, ba haɗawa ba). `DEFAULT_WEIGHTS` yana ɗauke da `quality 0.03 / reliability 0`; zaɓin `balanced`/`default` yana riƙe waɗannan tsoffin ƙimomi, yayin da zaɓin fakiti ke amfani da ƙimomin fakitin da ke sama. A kan tafki mai sanyi (ba a samu abubuwan lura ba tukuna, don haka `quality 0.5` da `reliability 1`) waɗannan ma'aunai biyu suna ƙara `+0.04` a ƙarƙashin fakiti na gama-gari (`0.03 + 0.01`), `+0.045` a ƙarƙashin `quality-first`, da `+0.05` a ƙarƙashin `reliability-first`. - `tierAffinity`, `specificityMatch` da `resetWindowAffinity` an saita su a sarari zuwa `0` a cikin kowane fakiti. - Abin da kowane fakiti ya fi mayar da hankali a kai a taƙaice: - **ship-fast** → latencyInv 0.3048 + health 0.2667 (haɗe-haɗe masu ƙarancin jinkiri kuma lafiyayyu) - **cost-saver** → costInv 0.3324 (alamu mafi arha ne suke yin nasara) - **quality-first** → taskFit 0.3524 + stability 0.1429 + quality 0.03, mafi girma a cikin dukkan fakitoci (samfurin da ya fi dacewa da aikin, mai daidaito) - **offline-friendly** → quota 0.3324 + health 0.2667 (mafi girman sararin ajiya ba tare da la'akari da sauri/farashi ba) - **reliability-first** → health 0.3524 + stability 0.1905 + reliability 0.04, mafi girma a cikin dukkan fakitoci (mafi ƙarancin abubuwan ba-zata) - **chaos-mode** → health 0.4000 + taskFit 0.1905 (fakitin ma'aunin da `auto/chaos` ke sanya wa mambobin rukuninsa; yaɗawa a layi ɗaya ba ya karanta waɗannan ma'aunai, kuma wannan ba bayanin martabar shigar da matsala ba ne, duba [CHAOS-MODE.md](../guides/CHAOS-MODE.md#autochaos-parallel-fan-out)) ### Sarrafawar Kowace Buƙata (headers) — #6023 / #6024 / #6025 / #3470 Ana iya jagorantar haɗin `auto` **ga kowace buƙata** ta hanyar headers guda uku, ba tare da sauya saitunan haɗin da aka adana ba. Waɗannan suna aiki ne kawai ga dabarar `auto`, kuma ga buƙatar da ke ɗauke da su kawai; ana amfani da `modePack`/`budgetCap`/`budgetFallback` da aka adana na haɗin idan header ɗin ba ya nan. | Kanun Bayani | Abubuwan da yake karɓa | Tasiri | | :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-OmniRoute-Mode` | sunan laƙabi da aka riga aka saita (`fast`, `balanced`, `quality`, `cheap`, `reliable`, `offline`) ko ɗanyen sunan pack (`ship-fast`, `cost-saver`, `quality-first`, `offline-friendly`, `reliability-first`) | Yana maye gurbin ma'aunin makin wannan buƙatar. `balanced`/`default` suna tilasta amfani da tsoffin ma'aunai (babu pack). Ana yin watsi da ƙimomin da ba a sani ba (ana kiyaye saitunan). | | `X-OmniRoute-Budget` | lamba mai kyau (iyakar USD ga kowace buƙata) | Tsayayyen iyakar kuɗi: ana tace 'yan takarar da ƙiyasin kuɗinsu ya wuce ta kafin zaɓe. Abin da zai faru idan **duk** 'yan takara sun wuce ta yana ƙarƙashin ikon `X-OmniRoute-Budget-Fallback` da ke ƙasa. | | `X-OmniRoute-Budget-Fallback` | `cheapest` (tsoho, sunayen laƙabi: `cheapest-viable`, `soft`) ko `strict` (sunayen laƙabi: `block`, `hard`) | `cheapest`: yana koma wa ɗan takara mafi arha gaba ɗaya duk da cewa har yanzu ya wuce iyakar (tsohuwar ɗabi'a). `strict`: yana ƙin yin zaɓi — buƙatar tana gaza nan take tare da `HTTP 402` maimakon kashe kuɗi fiye da kima a ɓoye. Ana yin watsi da ƙimomin da ba a sani ba. | | `X-OmniRoute-Effort` | `auto` (an keɓe sauran ƙimomi) | Kasafin tunani mai daidaitawa: idan buƙatar ba ta ƙunshi **kowane** filin tunani na kowace siga ba (`reasoning_effort`, `reasoning`, `thinking`), gateway zai fassara `auto` zuwa `low`/`medium`/`high` bisa ƙayyadaddun alamomin tsarin buƙata (tsawon saƙon mai amfani na ƙarshe, girman mahallin har zuwa saƙon mai amfani na ƙarshe, sakamakon kayan aiki na baya, zurfin madaukin kayan aiki). Alamomin sun taƙaita ga zagayen yanzu — ana watsi da duk abin da ke bayan saƙon mai amfani na ƙarshe — don haka kowace buƙata a cikin madaukin kayan aiki tana samun mataki iri ɗaya (ɗaurewar mataki marar yanayin zaman da aka keɓe ga kowane zagaye, babu yanayin zaman, babu ƙarin mataki a tsakiyar madauki wanda zai karya prefixes na prompt-cache na upstream). Filin tunani da abokin ciniki ya fayyace a sarari koyaushe shi ke da fifiko. Wannan ya taƙaita ga buƙatun da turawar upstream ɗinsu ta koma tsarin OpenAI Chat Completions (`targetFormat === FORMATS.OPENAI`) — `reasoning_effort` fili ne mai tsarin OpenAI, don haka header ɗin ba ya yin komai kan buƙatar da aka nufa ga Claude ko Gemini (duba `open-sse/handlers/chatCore/adaptiveEffortWiring.ts`). | ```bash # Tilasta amfani da profile mafi sauri, iyakance wannan buƙatar zuwa $0.05, sannan a toshe ta gaba ɗaya maimakon wuce kasafin curl -sS http://localhost:20128/v1/chat/completions \ -H "Content-Type: application/json" \ -H "X-OmniRoute-Mode: fast" \ -H "X-OmniRoute-Budget: 0.05" \ -H "X-OmniRoute-Budget-Fallback: strict" \ -d '{"model":"auto","messages":[{"role":"user","content":"hi"}]}' ``` Warwarewar tsantsar aiki ce (`open-sse/services/autoCombo/requestControls.ts`); ƙimomin da aka warware suna shiga shigarwar `config.modePack` / `config.budgetCap` / `config.budgetFallback` da engine ɗin ke da su. `config.budgetFallback` da aka adana na combo ("strict" | "cheapest") yana saita manufofin dindindin; header ɗin yana soke shi don buƙata guda ɗaya. ## Dukkan Dabarun Turowa Injin haɗa-hadar OmniRoute yana goyon bayan **dabarun turowa guda 20** (waɗanda aka ayyana a cikin `src/shared/constants/routingStrategies.ts` → `ROUTING_STRATEGY_VALUES`). Ana samar da injin Auto Combo kansa ƙarƙashin dabarar `auto`; sauran kuwa suna samuwa ga haɗa-hadar da aka adana. | Dabara | Bayani | | :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `priority` | Jerin manufa na farko bisa tsari tare da fifiko bayyananne | | `weighted` | Zaɓin bazuwar mai nauyi bisa nauyin kowace manufa | | `round-robin` | Zagayawa ta cikin manufofi bisa tsari (rukuni-rukuni; duba ƙasa) | | `context-relay` | Miƙa mahalli tsakanin manufofi (dogayen tattaunawa) | | `fill-first` | Cika ƙa'idar kason kowace manufa kafin matsawa zuwa ta gaba | | `p2c` | Daidaita nauyi ta zaɓin bazuwar ƙarfi-na-zaɓuɓɓuka-2 | | `random` | Zaɓin bazuwar da ya yi daidai | | `least-used` | Zaɓi manufa mai mafi ƙarancin nauyin aiki na yanzu | | `cost-optimized` | Rage $ na kowace buƙata bisa farashin kundin | | `reset-aware` ⭐ | Ba da fifiko bisa lokacin sake saita ƙa'idar kaso — tagogin sake saiti gajeru suna samun matsayi mafi girma | | `reset-window` | Fi son manufofin da tagar ƙa'idar kasonsu za ta sake saitawa da wuri | | `headroom` | Zaɓi manufa mai mafi yawan sararin ƙa'idar kaso da ya rage | | `quota-weighted` | Tsallake asusun da ƙa'idar kasonsu ta ƙare, sannan zaɓi daga sauran gwargwadon ragowar ƙa'idar kaso da aka raba da nauyin buƙatun da ake sarrafawa; tattaunawar da ake da su za su ci gaba da kasancewa a manne | | `strict-random` | Bazuwar zaɓi ba tare da cire maimaituwa ba | | `auto` | Yi amfani da kimanta Auto Combo (abubuwa 16) — **an ba da shawara** | | `lkgp` | Hanyar Ƙarshe-da-Aka-San-Tana-Aiki (yana manne wa mai samarwa na ƙarshe da ya yi nasara, sannan ya koma ga ƙa'idoji idan hakan bai yiwu ba) | | `context-optimized` | Zaɓi manufa da ta fi dacewa da girman mahalli na yanzu | | `cache-optimized` | Sake tsara manufofi bisa kusanci da ma'ajiyar prompt — ana fara gwada haɗin da ya fi yiwuwa ya riga ya riƙe prefix ɗin wannan buƙata a ma'ajiyarsa (`open-sse/services/combo/promptCacheAffinity.ts`, #8008) | | `fusion` 🧬 | Aika zuwa rukunin samfura a lokaci guda, sannan wani mai hukunci ya haɗa amsa guda ɗaya (duba ƙasa) | | `pipeline` | Gudanar da manufofi ɗaya bayan ɗaya, ana shigar da sakamakon kowane mataki cikin shigarwar mataki na gaba; amsar ƙarshe kaɗai ake mayarwa (#6396) | ⭐ = Sabo a v3.8.0 · 🧬 = Sabo a v3.8.36 ### Ma'anar `weighted` `weighted` **zaɓin bazuwar gwargwado ne ga kowace buƙata** (`open-sse/services/combo/targetSorters.ts` → `selectWeightedTarget`), ba mai daidaitawa ba ne: - Kowace buƙata tana zaɓar mataki **guda ɗaya** da yiwuwar `weight / totalWeight`; ana tsara sauran matakan bisa nauyi daga mafi girma zuwa mafi ƙanƙanta a matsayin jerin komawa-baya na wannan buƙata. - Matakin da nauyinsa yake `0` (ko babu shi) **ba a taɓa zaɓarsa** muddin wani mataki yana da nauyi > 0 — zai iya zama hanyar komawa-baya ne kawai bayan matakin da aka zaɓa ya gaza. Sai idan nauyin **dukkan** matakan ya zama 0 ne zaɓin zai zama daidai. - Matakan da dukkan manufofinsu ba sa samuwa — circuit breaker na mai samarwa yana `OPEN`, haɗin yana cikin cooldown, ko samfurin yana cikin lockout — ana cire su daga zaɓin kafin a yi shi (`open-sse/services/combo/targetResolution.ts`), don haka mataki guda mai lafiya zai iya cin nasarar kowace buƙata na ɗan lokaci. - `stickyWeightedLimit` (daidaitawar combo, tsohon ƙimarsa `1` = a kashe) yana manne wa matakin da aka zaɓa har tsawon nasarori jere daidai wannan adadin kafin a sake zaɓe. Don juyawa mai tsauri yi amfani da `round-robin`; nauyi iri ɗaya a kan `weighted` yana ba da daidaito na ƙididdiga — ba mai tsauri ba. ### Yanayin bututun wakili Haɗin `pipeline` mai aƙalla samfura biyu zai iya kunna rabawar mai tsarawa/mai aiwatarwa ta hanyar `config.agenticOrchestration.enabled`. Manufa ta farko ce ke da alhakin tsarawa da amsoshin ƙarshe; manufa ta biyu tana fitar da kiran kayan aiki na asalin abokin ciniki. OmniRoute yana gano ci gaban sakamakon kayan aiki daga ƙa'idar buƙatar, yana tambayar mai tsarawa ko ana buƙatar wani zagayen kayan aiki, sannan a sauƙaƙe yana sanya ko dai mai aiwatarwa ko mai tsarawa ya zama matakin ƙarshe da abokin ciniki zai gani. Ƙarin samfuran da ke bayan manufa ta biyu ana jera su a matsayin madadin masu aiwatarwa. Amsar HTTP da ta gaza ko keɓantacciyar matsalar sufuri tana matsawa zuwa mai aiwatarwa na gaba, tare da ɗaukar shawarar mai tsarawa iri ɗaya da kayan aiki na asali, amma da umarnin matakin wannan mai aiwatarwar da haɗin da aka warware. Ana dawo da amsa ta farko da ta yi nasara ba tare da canji ba, ciki har da watsawar SSE; gazawar da ta faru bayan fara watsa bayanan da ya yi nasara ba za a iya sake gwadawa a nan ba. Idan duk masu aiwatarwa sun gaza, ana dawo da gazawa ta ƙarshe. Katsewar abokin ciniki yana dakatar da aikawa. ```json { "strategy": "pipeline", "models": [{ "model": "provider/planner" }, { "model": "provider/executor" }], "config": { "agenticOrchestration": { "enabled": true, "maxToolRounds": 8 } } } ``` Mai aiwatarwa na iya fitar da kiraye-kiraye masu zaman kansu da yawa a cikin amsa ɗaya. Kiraye-kirayen da suka dogara da juna ana sarrafa su a zagayen sakamakon kayan aiki na abokin ciniki na gaba, inda mai tsarawa yake duba kowane sakamako. `maxToolRounds` yana amfani da `8` a matsayin tsoho kuma yana karɓar `1`–`32`; da zarar an kai iyakar, dole ne mai tsarawa ya samar da mafi kyawun amsar ƙarshe da ake da ita. Ana ajiyar shawarwarin mai tsarawa na ciki, yayin da amsar da aka zaɓa don abokin ciniki take kiyaye zaɓin watsawa na asali. ### Rukunin manne na `round-robin` da faɗaɗa asusu Ana yin round-robin rukuni-rukuni, ba buƙata-ɗaya-a-kowane-mataki ba: - `stickyRoundRobinLimit` (saitin haɗi, sai `comboStickyRoundRobinLimit`, sai `settings.stickyRoundRobinLimit`, tsoho **3**) yana riƙe da manufa ɗaya na adadin nasarorin jere da aka saita kafin ya juya. Saita ƙetaren haɗin zuwa `1` don juyawa a kowane buƙata. Editan haɗi yana nuna ƙimar da ake amfani da ita da kuma matakin da ta fito daga gare shi. - `connectionAwareExpansion` (saitin haɗi, sai saituna, tsoho **false**) yana faɗaɗa kowane mataki na matakin mai samarwa zuwa manufofin kowane asusu kafin juyawa. Dabarun Rukuni-B (priority, weighted, round-robin, random, p2c, least-used, cost-optimized, lkgp, fill-first, strict-random, context-optimized, cache-optimized, context-relay, fusion, pipeline) suna ci gaba da amfani da hangen matakin mai samarwa har sai an kunna wannan. Editan haɗi yana bayar da gada / kunna / kashe; gada yana amfani da tsohon saitin duniya (a kashe). - Rabawar wurin ma'ajiyar umarni (`promptCacheAffinityEnabled`, tsoho **true**) tana sake tsara haɗe-haɗen da aka ƙure don maɓallan ma'ajiya masu dacewa su ci gaba da kasancewa a asusu ɗaya. Tana da fifiko a kan juyawar round-robin da weighted a tsakanin matakan kowane asusu da aka ƙure. Kashe ta a ƙarƙashin Settings → Combo defaults idan kana buƙatar juyawa mai tsauri. Babu ƙetaren kowane haɗi. Don juyawar asusu da yawa a kan samfuri ɗaya, fi son **matakin asusu mai sauyawa guda ɗaya** (`connectionId` mara komai, dukan rukunin) tare da iyakar manne `1`, maimakon `connectionId` guda uku da aka ƙure. Matakan da aka ƙure tare da kusanci suna haɗuwa zuwa asusu ɗaya ko da yayin da ƙirgar RR ke ƙaruwa. ## Dabarar Fusion `fusion` ita ce dabara guda ɗaya da **ba ta** zaɓar manufa guda. Tana aika buƙatar zuwa ga **kowace samfurin kwamiti a lokaci guda**, sannan wani **samfurin alƙali** da za a iya saita shi ya haɗa amsa ta ƙarshe guda ɗaya daga dukkan amsoshin kwamitin. An ɗauko ta daga `decolua/9router` na asali (tsarin Fusion na OpenRouter); aiwatarwa tana cikin `open-sse/services/fusion.ts`. Yadda take aiki: 0. **Tsallakewa ga buƙata mai kayan aiki** — buƙatar da ke ɗauke da jerin `tools` marar komai tare da `tool_choice` wanda ba a bayyana a sarari a matsayin `"none"` ba, tana tsallake kwamitin gaba ɗaya: ana tura ta kai tsaye zuwa samfuri guda ɗaya (alƙalin da aka saita, ko `panel[0]`) tare da `tools`/`tool_choice` ba tare da wani sauyi ba. Membobin kwamitin ba su da damar amfani da kayan aiki, kuma umarnin haɗawa na alƙali yana hana fitar da kiran kayan aiki, don haka abokan ciniki masu aiki ta kansu/masu kiran kayan aiki suna samun ainihin shawarar kiran kayan aiki maimakon rubutun da aka haɗa (#6771). 1. **Rarrabawa** (buƙatun da ba su ɗauke da kayan aiki kawai) — ana aika buƙatar zuwa kowane samfurin kwamiti a lokaci guda, tare da tilasta rashin yawo da cire kayan aiki (alƙali yana buƙatar cikakken rubutu don haɗawa). 2. **Tattara bisa adadin da ake buƙata tare da ƙarin lokaci** — da zarar amsoshi `minPanel` sun iso, wani ɗan gajeren ma'aunin ƙarin lokaci yana farawa domin masu jinkiri, sannan fusion ya ci gaba da duk abin da aka tattara. Wannan yana iyakance jinkirin samfurin da ya fi kowa jinkiri a ainihin lokacin jira, ƙarƙashin ƙayyadadden iyakar lokaci. 3. **Haɗawar alƙali** — ana ɓoye sunayen tushen amsoshin kwamiti (`Source 1`, `Source 2`, … — domin alƙali ya auna ingancin abun ciki, ba sunan samfurin ba), sannan a miƙa su ga alƙali, wanda ke nazarin yarjejeniya / saɓani / ɗaukar wani ɓangare kawai / fahimta ta musamman / wuraren da ba a lura da su ba, sannan ya rubuta amsa **guda ɗaya** mai cikakken iko. Kiran alƙali yana riƙe da asalin alamar `stream` ta abokin ciniki + kayan aiki, don haka yawo da amfani da kayan aiki daga baya har yanzu suna aiki. 4. **Raguwar aiki cikin tsari** — babu amsar kwamiti → `503`; idan mai tsira 1 ne tak → ana mayar da wannan amsar kai tsaye (babu abin da za a haɗa); kwamiti mai samfuri guda ɗaya yana amsawa kai tsaye. Memba na kwamiti kuma zai iya zama matakin `combo-ref` (`{kind: "combo-ref", comboName: "..."}`) mai nuni zuwa wani combo — ana warware shi a matsayin **murya guda ta kwamiti mai aiki kamar akwatin-baƙi** (cikakken turawa mai maimaitawa zuwa cikin combo ɗin da aka ambata, ba rarrabawa zuwa manufofin wannan combo ɗin ba), tare da kariyar zurfi/zagaye iri ɗaya da kowace dabara mai amfani da combo-ref take amfani da ita (#6764). ### Saituna Ana saita shi a cikin tarin `config` na combo (babu ƙaura ta schema — yana sake amfani da teburin `combos` da yake akwai): | Fili | Nau'i | Tsoho | Manufa | | :--------------------------------------- | :------- | :------------------------ | :------------------------------------------------------------------------------------------------------------- | | `config.judgeModel` | `string` | samfurin kwamiti na farko | Samfurin da ke haɗa amsa ta ƙarshe | | `config.fusionTuning.minPanel` | `number` | `2` | Amsoshi masu nasara da ake buƙata kafin ma'aunin ƙarin lokaci ya fara (ana iyakance shi zuwa `[2, panelSize]`) | | `config.fusionTuning.stragglerGraceMs` | `number` | `8000` | Tsawon lokacin jiran masu jinkiri bayan an kai adadin da ake buƙata | | `config.fusionTuning.panelHardTimeoutMs` | `number` | `90000` | Cikakkiyar iyaka domin samfuri guda da ya makale kada ya tsaida buƙatar | Tsoffin ƙimomi suna cikin `FUSION_DEFAULTS` (`open-sse/services/fusion.ts`). ### Misali ```bash curl -X POST http://localhost:20128/api/combos \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "fusion-panel", "strategy": "fusion", "targets": [ { "model": "cc/claude-opus-4-7" }, { "model": "cx/gpt-5.5" }, { "model": "glm/glm-5.1" } ], "config": { "judgeModel": "cc/claude-opus-4-7", "fusionTuning": { "minPanel": 2, "stragglerGraceMs": 8000, "panelHardTimeoutMs": 90000 } } }' ``` Sannan kira shi kamar kowane combo: `{"model":"fusion-panel","messages":[...]}`. ## Masana'antar Virtual Auto-Combo Injin Auto Combo ba ya buƙatar combos da aka riga aka ayyana. Maimakon haka, `open-sse/services/autoCombo/virtualFactory.ts` yana ƙirƙirar zaɓuɓɓuka nan take: 1. Yana ɗauko `getProviderConnections({ isActive: true })` (duk haɗin da aka kunna) 2. Yana tace waɗanda ke da ingantattun bayanan shaidar shiga (API key ko OAuth token wanda bai ƙare ba ta hanyar `hasUsableOAuthToken()`) 3. Yana kwatanta su da `getProviderRegistry()` don samuwar model + farashi 4. Ga kowane tuple `(provider, model, connection)`, yana ƙirƙirar `VirtualAutoComboCandidate` 5. Yana zaɓar `connection.defaultModel` (ko model na farko a registry) a matsayin makasudin aikawa 6. Yana ƙididdige maki ga kowane zaɓi ta amfani da `scorePool()` mai abubuwa 16 da kunshin nauyin variant ɗin 7. Yana dawo da `AutoComboConfig` da aka samar a cikin ƙwaƙwalwa don `handleComboChat()` — ba a taɓa adana shi a DB ba Wannan yana nufin **ƙara sabon provider wanda aka kunna masa `auto/*` zai faɗaɗa tarin zaɓuɓɓuka kai tsaye** — ba sai an gyara combo da hannu ba. Ana sake gina virtual combo ga kowace request, don haka sabbin haɗin da aka ƙara ko waɗanda suka dawo cikin koshin lafiya ana gano su nan take. ## Gyaran Kai Tsaye - **Warewa na ɗan lokaci**: Maki < 0.2 → a ware shi na minti 5 (backoff mai ƙaruwa, mafi yawa minti 30) - **Sanin yanayin circuit breaker**: OPEN → a ware shi kai tsaye; HALF_OPEN → probe requests - **Yanayin matsala**: >50% OPEN → a kashe exploration, a ƙara stability zuwa iyaka - **Farfadowa bayan cooldown**: Bayan warewa, request ta farko za ta kasance "probe" mai rage timeout ## Bandit Exploration Ana tura 5% na requests (ana iya saita adadin) zuwa providers na bazata domin exploration. Ana kashe wannan a yanayin matsala. ## API Babu **keɓantacciyar mashigar `POST /api/combos/auto`** — ana amfani da Auto-Combo ta hanyoyi biyu: 1. **Ba tare da saiti ba (ana ba da shawara):** Aika kowace buƙatar kammala tattaunawa tare da `model: "auto"` ko `model: "auto/"`. Masana'antar kama-da-wane tana gina combo ɗin ga kowace buƙata — ba a buƙatar adanawa ko kiran API. 2. **Combo da aka adana tare da `strategy: "auto"`:** Ƙirƙiri combo na yau da kullum ta hanyar `POST /api/combos`, sannan saita `strategy: "auto"` tare da `config.auto.weights` / `config.auto.candidatePool`. Ana amfani da injin ƙididdiga iri ɗaya; ana adana combo ɗin a cikin `combos` kuma za a iya sake amfani da shi ta ID. Don ganowa, `GET /api/combos/auto` yana jera kowane nau'i tare da tafkin 'yan takararsa da aka tantance, da kuma `context_length` / `max_output_tokens` — wato ƙimar MAX a dukkan tagogin tafkin 'yan takarar. Dole ne abokan hulɗa (misali, plugin na opencode) su tallata waɗannan ƙimomin maimakon `0`: mahallin sifili yana kashe matsewar atomatik ta opencode gaba ɗaya, yana barin zaman aiki ya ci gaba da girma har sai gogewar tarihin gateway ta lalata mahallin. Tallata MAX ba shi da haɗari saboda matatar mahalli ta auto-combo kafin routing tana tura buƙatun da suka wuce girman da aka yarda zuwa 'yan takara masu manyan tagogi. ```bash # Amfani ba tare da saiti ba (ba a ƙirƙiri combo) curl -X POST http://localhost:20128/v1/chat/completions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"model":"auto/coding","messages":[{"role":"user","content":"Hello"}]}' # Auto combo da aka adana ta hanyar mashigar combos ta yau da kullum curl -X POST http://localhost:20128/api/combos \ -H "Content-Type: application/json" \ -d '{"id":"my-auto","name":"Auto Coder","strategy":"auto","config":{"auto":{"candidatePool":["anthropic","google","openai"],"weights":{"quota":0.15,"health":0.3,"costInv":0.05,"latencyInv":0.35,"taskFit":0.1,"stability":0,"tierPriority":0.05}}}}' ``` ### Dabarun auto router Combo da aka adana mai `strategy: "auto"` zai iya saita `config.routerStrategy` (ko tsohon `config.auto.routerStrategy`) zuwa ɗaya daga cikin: - `rules` — ƙididdigar nauyi ta tsohuwa - `score` — yana zaɓar ƙimar nauyi mafi girma da aka saita. Idan ƙimomi sun yi daidai ƙwarai, ana kiyaye jerin 'yan takara da aka saita; `explorationRate` da ake da shi yana ɗaukar samfuri daga dukan tafkin da aka jera. - `cost` / `eco` — mai bayarwa mafi arha kuma lafiyayye - `latency` / `fast` — mafi ƙarancin jinkirin p95 tare da hukuncin rashin amintuwa - `sla-aware` / `sla` — fifita 'yan takarar da suka cika jinkirin p95, ƙimar kuskure, da SLO na kuɗi idan an saita - `lkgp` — fara da mai bayarwa na ƙarshe da aka sani yana aiki da kyau - `nadir` — tambayi API na yanke shawara na [Nadir](https://getnadir.com) wane model ne a cikin tafkin prompt ɗin yake buƙata; sai an zaɓi shiga, kuma idan ya gaza sai a koma `rules` ### Dabarun router dalla-dalla Injin auto-combo yana samar da aiwatarwa 7 na **RouterStrategy** masu iya sauyawa waɗanda za ka iya musanya ta hanyar `config.routerStrategy` (ko tsohon `config.auto.routerStrategy`). Kowace dabara tana zaɓar mai bayarwa guda ɗaya daga tafkin 'yan takara, bisa wani `RoutingContext` (nau'in aiki, alamomin kayan aiki/hoto, kimar token, manufofin SLA na zaɓi, da kuma mai bayarwa na ƙarshe da aka sani yana aiki da kyau idan akwai). #### 1. `rules` (tsoho) — ƙididdigar nauyi mai dalilai 16 Yana naɗe injin ƙididdigar da ake da shi. Yana tace 'yan takarar circuit-breaker masu matsayin `OPEN`, sannan ya gudanar da `scorePool()` tare da nau'in aiki na yanzu da `getTaskFitness()`, yana zaɓar mai bayarwa da ya fi kowa samun ƙima. ```ts class RulesStrategyImpl implements RouterStrategy { readonly name = "rules"; readonly description = "16-factor weighted scoring (see DEFAULT_WEIGHTS)"; select(pool, context) { const eligible = pool.filter((c) => c.circuitBreakerState !== "OPEN"); const ranked = scorePool( eligible.length > 0 ? eligible : pool, context.taskType, undefined, getTaskFitness ); return { provider: ranked[0].provider /* ... */ }; } } ``` **Lokacin amfani**: Tsoho. Yi amfani da shi idan kana son daidaitaccen sasanci tsakanin dukkan alamomi. **Sunan madadi**: `rules` (ba shi da sunan madadi) --- #### 2. `cost` / `eco` — mai bayarwa mafi arha kuma lafiyayye Yana tsara tafkin 'yan takara bisa `costPer1MTokens` (daga ƙarami zuwa babba), sannan ya zaɓi mafi arha. Yana fara da tace 'yan takara masu matsayin `OPEN`. ```ts class CostStrategyImpl implements RouterStrategy { readonly name = "cost"; readonly description = "Always selects cheapest available provider"; select(pool, context) { const healthy = pool.filter((c) => c.circuitBreakerState !== "OPEN"); const sorted = [...healthy].sort((a, b) => a.costPer1MTokens - b.costPer1MTokens); return { provider: sorted[0].provider /* ... */ }; } } ``` **Lokacin amfani**: Ayyukan da ke kula da tsada, sarrafa rukuni, ko ayyukan baya. **Sunayen madadi**: `cost`, `eco` --- #### 3. `latency` / `fast` — mafi ƙarancin jinkirin p95 tare da hukuncin rashin amintuwa Yana tsarawa bisa `p95LatencyMs + (errorRate * 1000)`. Hukuncin ƙimar kuskure yana tabbatar da cewa ana sanya marasa samar da ingantaccen aiki a ƙasa, ko da jinkirinsu na asali ya yi ƙasa. ```ts class LatencyStrategyImpl implements RouterStrategy { readonly name = "latency"; readonly description = "Prioritizes lowest p95 latency with reliability weighting"; select(pool, context) { const healthy = pool.filter((c) => c.circuitBreakerState !== "OPEN"); const sorted = [...healthy].sort( (a, b) => a.p95LatencyMs + a.errorRate * 1000 - (b.p95LatencyMs + b.errorRate * 1000) ); return { provider: sorted[0].provider /* ... */ }; } } ``` **Lokacin amfani**: Ayyukan da ke kula da jinkiri kamar tattaunawa ta ainihin lokaci, autocomplete, ko mataimakan rubuta lamba masu mu'amala. **Sunayen madadi**: `latency`, `fast` --- #### 4. `sla-aware` / `sla` — bin SLO na jinkiri/kuskure/kuɗi Yana ba kowane ɗan takara ƙima bisa yadda ya cika manufofin SLO da aka saita: | Ma'auni | Nauyi | Tsari | | ----------------------- | ----- | ------------------------------------------------- | | Makin jinkiri | 35% | `threshold / max(value, ε)` | | Makin kuskure | 35% | `threshold / max(value, ε)` | | Makin lafiya | 15% | `1.0` (CLOSED) / `0.5` (HALF_OPEN) / `0.0` (OPEN) | | Makin kuɗi | 10% | `threshold / max(value, ε)` ko daidaitaccen akasi | | Makin kwanciyar hankali | 5% | daidaitaccen akasin stddev na jinkiri | Lokacin da `hardConstraints: true`, ana jera 'yan takara da farko bisa **makin karya ƙa'ida** (yawan yadda suka zarce kowace SLO), sannan bisa haɗaɗɗen maki. In ba haka ba, haɗaɗɗen maki kawai ake amfani da shi. ```ts class SLAStrategyImpl implements RouterStrategy { readonly name = "sla-aware"; readonly description = "Selects the provider most likely to satisfy latency, error-rate, and cost SLOs"; select(pool, context) { // ... yana ba kowane ɗan takara maki bisa manufa: { targetP95Ms, maxErrorRate, maxCostPer1MTokens, hardConstraints } } } ``` **Filayen SLA** (ana saita su a kan saitin combo): ```json { "strategy": "auto", "config": { "routerStrategy": "sla-aware", "slaTargetP95Ms": 1500, "slaMaxErrorRate": 0.05, "slaMaxCostPer1MTokens": 5, "slaHardConstraints": true } } ``` **Lokacin amfani**: Ayyukan samarwa masu tsauraran iyakokin jinkiri, adadin kuskure, ko kuɗi. **Wasu sunaye**: `sla-aware`, `sla` --- #### 5. `lkgp` — mai samarwa na ƙarshe da aka san yana da kyau da farko Yana fara gwada **mai samarwa na ƙarshe da aka san yana da kyau** (idan an saita shi), sannan ya koma ga dabarar `rules`. Yana da amfani don manne zaman aiki — mai samarwa ɗaya ne yake gudanar da buƙatun biyo baya a cikin tattaunawa. ```ts class LKGPStrategyImpl implements RouterStrategy { readonly name = "lkgp"; readonly description = "Tries last known good provider first, then falls back to rules"; select(pool, context) { if (context.lkgpEnabled === false) { return getStrategy("rules").select(pool, context); } if (context.lastKnownGoodProvider) { const candidates = pool.filter( (c) => c.provider === context.lastKnownGoodProvider && c.circuitBreakerState !== "OPEN" ); if (candidates.length > 0) { return { provider: candidates[0].provider /* ... */ }; } } // Koma ga dabarar rules return getStrategy("rules").select(pool, context); } } ``` **Lokacin amfani**: Tattaunawa mai zagaye da yawa inda kake son mai samarwa ɗaya ya gudanar da buƙatun biyo baya (misali, don caching, ci gaban mahallin bayanai, ko daidaiton farashi). **Wani suna**: `lkgp` (ba shi da wani suna) --- #### 6. `nadir` — zaɓin samfuri bisa prompt ta hanyar Nadir Kowace dabara da ke sama tana jera 'yan takara ne bisa nata bayanan telemetry; babu wadda take karanta buƙatar. `nadir` yana aika saƙon mai amfani na ƙarshe tare da model ids na pool zuwa API na yanke shawara na [Nadir](https://getnadir.com) (`POST /v1/bucket`), sannan ya tura zuwa samfurin da Nadir ya zaɓa daga jerin (`simple` → samfuri mafi arha da ke da ƙwarewar da ake buƙata, `complex` → samfurin frontier). Har yanzu `rules` ne ke zaɓar haɗin da ke hidimar wannan samfurin, don haka quota, lafiya, da kuɗi suna ci gaba da tantance asusun da za a yi amfani da shi. ```json { "strategy": "auto", "config": { "routerStrategy": "nadir", "nadir": { "apiKey": "ndr_...", "baseUrl": "https://api.getnadir.com", "timeoutMs": 2000 } } } ``` `OMNIROUTE_NADIR_API_KEY` da `OMNIROUTE_NADIR_BASE_URL` su ne madadin env na waɗannan strings guda biyu. Ana buƙatar `baseUrl` ne kawai don Nadir da aka ɗora da kai (ana amincewa da `/v1` a ƙarshe). Kiran da ba shi da maɓalli yana shiga matakin Nadir na baƙi, wanda aka iyakance adadin kiransa ga kowane IP. Abin da ke fita daga tsarin: rubutun saƙon mai amfani na ƙarshe (haruffa 16k na farko), model ids na 'yan takara, da alamar channel ta `source: "omniroute"`. Ba a aika system prompt, tarihi, tools, ko headers. Halayen gazawa na fail-open ne: timeout (tsoho 2000 ms), martanin da ba 2xx ba, host da ba a iya kaiwa gare shi, gurɓataccen martani, ko zaɓin da ba ya cikin pool zai koma ga shawarar `rules`, kuma za a fara dalilin da `NadirStrategy: fallback (…)`. Bayan kiran da ya gaza, dabarar za ta tsallake network na tsawon 30 s, don haka katsewar sabis za ta jawo timeout guda ɗaya a kowane 30 s maimakon guda ɗaya ga kowace buƙata. Abubuwan da suka faru na routing suna bayar da rahoton `strategy: "nadir"` ne kawai lokacin da Nadir ya yi zaɓin da kansa. **Lokacin amfani**: zirga-zirgar buƙatu masu matakan wahala daban-daban a kan pool da ya ƙunshi matakan samfura (ƙarami, matsakaici, da frontier), inda kake son rage kuɗin amfani da frontier koyaushe. **Wani suna**: `nadir` (ba shi da wani suna) --- ### Dabarun router na musamman Za ka iya rajistar naka aiwatarwar `RouterStrategy` ta hanyar API na jama'a: ```ts import { registerStrategy, type RouterStrategy, } from "@omniroute/open-sse/services/autoCombo/routerStrategy"; class MyCustomStrategy implements RouterStrategy { readonly name = "my-custom"; readonly description = "My custom routing strategy"; select(pool, context) { // Dabararka ta routing a nan return { provider: pool[0].provider, model: pool[0].model, strategy: this.name, reason: "MyCustomStrategy: ...", candidatesConsidered: pool.length, finalScore: 1.0, }; } } registerStrategy("my-custom", new MyCustomStrategy()); ``` Sannan yi amfani da ita: ```json { "strategy": "auto", "config": { "routerStrategy": "my-custom" } } ``` --- ### Jagorar zaɓin dabarar router | Yanayin amfani | Dabara | Dalili | | ----------------------------- | ----------- | ------------------------------------------------ | | Aikin daidaitacce | `rules` | Tsoho — yana la'akari da dukkan ma'aunai | | Rage kuɗi | `cost` | Kullum yana zaɓar mafi arha | | Rage jinkiri | `latency` | Yana zaɓar mai samarwa mafi sauri kuma amintacce | | Tsauraran SLOs | `sla-aware` | Yana tacewa bisa iyakokin p95/kuskure/kuɗi | | Tattaunawa mai zagaye da yawa | `lkgp` | Manne zaman aiki | | Wahala iri-iri | `nadir` | Yana zaɓar matakin samfuri ga kowane prompt | Filayen SLA-aware: ```json { "strategy": "auto", "config": { "routerStrategy": "sla-aware", "slaTargetP95Ms": 1500, "slaMaxErrorRate": 0.05, "slaMaxCostPer1MTokens": 5, "slaHardConstraints": true } } ``` ## Dacewar Aiki An tantance samfura sama da 30 a nau'ikan ayyuka 6 (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Yana goyan bayan tsarin alamar wildcard (misali, `*-coder` → babban makin coding). ## Taƙaitaccen Bayanin Auto Variants Idan aka haɗa `auto` kai tsaye (tsoho) da ƙimomin `AutoVariant` guda 6 da aka ayyana a cikin `autoPrefix.ts`, akwai **ID na samfura guda 7 da za a iya kira**: `auto`, `auto/coding`, `auto/fast`, `auto/cheap`, `auto/offline`, `auto/smart`, `auto/lkgp` (`AutoVariant` kansa yana lissafa ƙimomi 6; zaɓi na 7 shi ne "babu variant" — `auto` kai tsaye — wanda `parseAutoPrefix()` ke sarrafawa a matsayin `variant: undefined`.) ## Yadda tiers ke dacewa da Auto-Combo Aikin ba da maki mai sigogi 16 (`open-sse/services/autoCombo/scoring.ts`) yana ɗaukar kasancewa cikin tier a matsayin sigina biyu: `tierPriority` (0.0476) da `tierAffinity` (0.0476). Duba [teburin sigogin ba da maki](#how-it-works-persisted-auto-combos) na asali da ke sama don cikakken saitin `DEFAULT_WEIGHTS` — an jera keɓantattun saitunan kowane pack (ship-fast/cost-saver/quality-first/ offline-friendly) a teburin "Weight profiles per pack". Tier shi kaɗai **ba ya** tilasta a fara da Tier 1 — idan jinkirin Tier 1 ya yi muni ko daidaiton farashi da inganci bai dace ba, Tier 2 ne zai yi nasara. Don tilasta bin tsarin tier, yi amfani da dabarar combo ta `priority` sannan ka tsara masu samarwa bisa tier. Don fifita Tier 1 (biyan kuɗin rajista) sosai, ƙara nauyin `tierPriority`: ```json { "strategy": "auto", "config": { "auto": { "weights": { "tierPriority": 0.3, "costInv": 0.05 } } } } ``` Duba [`docs/guides/TIERS.md`](../guides/TIERS.md) don ma’anonin tier da rarrabuwar masu samarwa. ## Gwaji da Faɗin Rufewa ### Matrix ɗin yanke shawarar routing mai tabbataccen sakamako (`npm run test:combo:matrix`) `tests/integration/combo-matrix/*.test.ts` yana tabbatar da **shawarar** routing ta dukkan dabarun jama'a guda 19 daga farko zuwa ƙarshe ta hanyar ainihin combo pipeline tare da upstream na kwaikwayo. Rufewar ta haɗa da: - Dukkan dabarun `ROUTING_STRATEGY_VALUES` guda 19 (ordered, weighted, cost, context, fusion, …). - `quota-share` (na ciki) daga farko zuwa ƙarshe: adalcin DRR + rage fifikon saturation ta hanyar ainihin mashigar `selectQuotaShareTarget` (`registerQuotaFetcher` / `setLKGP` / `__setHeadroomSaturationFetcherForTests`). - Rufewar universal-handoff ta `context-relay` a dukkan adadin targets. Wannan rukunin gwaje-gwaje yana gudana a CI (aikin `test:integration`) tare da `--test-concurrency=1` da `--test-force-exit` domin ya kasance mai tabbataccen sakamako kuma baya buƙatar live credentials. ### Gated live smoke (BA ya cikin CI — providers na gaske) | Command | Abin da yake yi | | :------------------------------------- | :----------------------------------------------------------------------------------------------------- | | `npm run test:combo:live` | Routing na gaske a cikin process tare da `RUN_COMBO_LIVE=1`; yana ɗaukar snapshot na live OmniRoute DB | | `npm run test:combo:live:vps` | Kiran HTTP zuwa live OmniRoute server (saita `COMBO_LIVE_BASE_URL`) | | `npm run test:combo:live:vps:failover` | Haka nan, tare da yanayin failover da aka shirya da gangan | Waɗannan smoke tests suna gwada ainihin wire path (combo → provider → completion). An cire su daga CI da gangan saboda suna buƙatar live credentials da damar shiga VPS. --- ## Fayiloli | Fayil | Manufa | | :-------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | | `open-sse/services/autoCombo/scoring.ts` | Aikin ƙididdigar ma'auni 16, `DEFAULT_WEIGHTS`, da daidaita rukunin | | `open-sse/services/autoCombo/taskFitness.ts` | Binciken dacewar samfuri × aiki | | `open-sse/services/autoCombo/engine.ts` | Dabarun zaɓi, bandit, da iyakar kasafin kuɗi | | `open-sse/services/autoCombo/selfHealing.ts` | Warewa, gwaje-gwajen bincike, da yanayin aukuwar matsala | | `open-sse/services/autoCombo/modePacks.ts` | Bayanan ma'auni guda 6 (ship-fast, cost-saver, quality-first, offline-friendly, reliability-first, chaos-mode) | | `open-sse/services/autoCombo/autoPrefix.ts` | Mai tantance prefix na `auto/` + nau'uka guda 6 | | `open-sse/services/autoCombo/virtualFactory.ts` | Yana gina `AutoComboConfig` na cikin ƙwaƙwalwa daga haɗin da ke aiki kai tsaye | | `open-sse/services/autoCombo/providerRegistryAccessor.ts` | Mahadar gwaji don kwaikwayon rajistar masu samarwa | | `src/shared/constants/routingStrategies.ts` | `ROUTING_STRATEGY_VALUES` (dabaru 20) | | `src/sse/handlers/chat.ts` | Haɗawa: dakatarwar gajeriyar hanya ta auto-prefix |