# 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 ## Auto-Routing Marar Saiti (gabanin `auto/`) > **SABO:** Ba a buƙatar ƙirƙirar combo. Yi amfani da gabanin `auto/` kai tsaye a kowane client. ### Misalai Masu Sauri | ID na Samfuri | Nau'i | Halayya | | -------------- | ------- | ---------------------------------------------------------------------- | | `auto` | default | Duk providers da aka haɗa, dabarar LKGP, daidaitattun nauyi | | `auto/coding` | coding | Nauyin da ya fifita inganci, ya dace da samar da code | | `auto/fast` | fast | Zaɓi mai nauyi wanda ke da ƙarancin latency | | `auto/cheap` | cheap | Routing da aka inganta don farashi (mafi ƙarancin farashi da farko) | | `auto/offline` | offline | Yana fifita providers masu mafi yawan quota da ake da shi | | `auto/smart` | smart | Fifita inganci + ƙarin adadin bincike (10%) don gano samfura mafi kyau | | `auto/lkgp` | lkgp | LKGP a bayyane (daidai da tsohon `auto`) | | `auto/chaos` | chaos | Nauyin saka matsala don gwajin juriya (chaos engineering) | ### Haɗin Rukuni × Mataki (`auto/:`) Ƙarewar rubutu irin ta OpenRouter tana raba **irin hanyar da ake so** (rukuni) daga **yadda za a inganta ta** (mataki), don haka za ku iya haɗa su yadda kuke so (#4235 Phase B, `open-sse/services/autoCombo/suffixComposition.ts`): - **Rukunoni** (tace rukunin candidates bisa ƙwarewa): `coding` · `reasoning` · `vision` · `chat` · `multimodal`. `vision`/`multimodal` suna barin samfuran da ke iya vision; `reasoning` yana barin samfuran reasoning/thinking. - **Matakai** (zaɓi nauyin kimantawa / tace rukunin): `fast` (a tura cikin sauri) · `cheap` (laƙabi `floor`, mai rage kuɗi) · `reliable` (lafiyar circuit-breaker + daidaiton latency) · `free` / `pro` (tace rukunin bisa matakin samfuri ta hanyar `classifyTier` — matakin kyauta da na premium). | Misali | Yana warwarewa zuwa | | ---------------------- | -------------------------------------------------------------------------- | | `auto/coding:fast` | rukunin coding, nauyin ƙarancin latency | | `auto/coding:cheap` | rukunin coding, wanda aka inganta don farashi (laƙabi `auto/coding:floor`) | | `auto/reasoning:pro` | samfuran reasoning/thinking kawai, matakin premium | | `auto/vision` | samfuran da ke iya vision (babu mataki → daidaitattun nauyi) | | `auto/multimodal:free` | samfuran da ke iya multimodal, matakin kyauta kawai | Kowane ingantaccen `auto/[:]` yana warwarewa lokacin da ake buƙata; ana tallata zaɓaɓɓun kaɗan a cikin `/v1/models` da dashboard (`AUTO_SUFFIX_VARIANTS` a cikin `open-sse/services/autoCombo/builtinCatalog.ts`). Tacewar **fail-open** ce — idan wani ƙa’ida bai dace da ko ɗaya daga cikin samfuran da aka haɗa ba, za a yi amfani da cikakken rukuni domin kada routing ya taɓa lalacewa. Ba a canza babban mai ƙididdigewa (`combo.ts`) ba; ana amfani da matatar rukuni/mataki a cikin `buildAutoCandidates`. > **Bayanan samfuri kai-tsaye:** dacewar auto-routing tana samun bayanai daga jerin **Arena ELO** kai-tsaye + bayanan mataki na **models.dev** lokacin da aka kunna tutar `ARENA_ELO_SYNC_ENABLED` (idan ba haka ba, sai a koma ga tsayayyen taswirar dacewa). **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 ɗinku, saita model zuwa: model: "auto" # daidaitaccen tsohon zaɓi model: "auto/coding" # mafi dacewa da ayyukan coding model: "auto/fast" # mafi saurin wanda ake da shi model: "auto/cheap" # mafi arha ga kowane token ``` **Abin da ke faruwa:** 1. OmniRoute yana gano gabanin `auto/` a cikin `src/sse/handlers/chat.ts` 2. Yana tambayar duk **haɗin providers masu aiki** daga database 3. Yana tace su zuwa waɗanda ke da ingantattun credentials (API key ko OAuth token) 4. Yana tantance model na 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 yin routing ta amfani da tsarin nauyin nau'in da aka zaɓa + dabarar LKGP **Muhimman siffofi:** - ✅ **Kullum a kunne:** Babu toggle, babu ƙirƙirar combo, babu buƙatar configuration - ✅ **Mai canzawa:** Yana nuna providers da aka haɗa a halin yanzu ta atomatik - ✅ **Mannewar session:** LKGP yana tabbatar da cewa an fifita provider na ƙarshe da ya yi nasara - ✅ **Yana fahimtar asusu da yawa:** Kowane connection na provider yana zama candidate dabam - ✅ **Babu rubutu zuwa DB:** Virtual combo yana wanzuwa ne kawai don request ɗin, ba shi da wani nauyin persistence ### Sarrafa candidate ga kowane key (#7819, Mataki na 1+2) `GET /v1/auto-combo/{channel}/candidates` (`{channel}` = suffix bayan `auto/`, ko ainihin `auto` don babban channel) endpoint ne na **karantawa kawai** wanda ke lissafa rukunin candidates na yanzu na channel ɗin `auto/*`, tare da bayanan samuwa kai-tsaye, ta sake amfani da karatun resilience da ake da shi (ba taɓa amfani da ɗanyen `state` na breaker ba): - circuit breaker na provider — `getCircuitBreaker(provider).getStatus()` / `.canExecute()` - cooldown na connection — `rateLimitedUntil` / `testStatus` a kan row ɗin `provider_connections` da aka warware - kulle model — `isModelLocked(provider, connectionId, model)` Kowane ɗan takara kuma yana ɗauke da tutar `excluded` ta wannan maɓallin API. Ana adana keɓancewa ga kowane maɓallin API (`auto_candidate_overrides` table, migration `128`) — OmniRoute tsari ne na mai haya guda ɗaya wanda ba shi da `users` table, don haka `apiKeyId` shi ne ainihin shaida mafi kusa ta kowane mai kira — kuma ana tilasta ta a maƙurar tafkin 'yan takara da ke `open-sse/services/autoCombo/virtualFactory.ts` ta hanyar tsantsar aikin da aka gwada da unit test `filterExcludedCandidates()` (`open-sse/services/autoCombo/candidateOverrides.ts`). Tacewar tana da halin **fail-open**: apiKeyId/channel da ba a saita ba ko gazawar binciken DB dukansu suna barin tafkin ba tare da tacewa ba, don haka ma'aikacin da ba shi da overrides da aka saita zai ga routing mai daidaita byte-da-byte da yadda yake kafin wannan fasalin. **An ɗage zuwa wata issue ta gaba:** weights na kowane ɗan takara + bayyanannen ordering (Level 3 — yana shiga cikin hanyoyin dabarun weighted/priority da ake da su) da kuma pinning takamaiman dabarar `combo.ts` ga kowane channel na `auto/*` (Level 4). Duba shirin #7819 don buɗaɗɗiyar tambaya kan ko overrides su ci gaba da kasancewa na kowane maɓallin API ko su zama global bisa la'akari da tsarin mai haya guda ɗaya. **Abin da ke faruwa a bayan fage:** ```txt Buƙata: { model: "auto/coding" } ↓ src/sse/handlers/chat.ts yana gano prefix ↓ createVirtualAutoCombo('coding') → candidatePool daga active connections ↓ handleComboChat (engine ɗaya da persisted combos) ↓ Auto-scoring yana zaɓar mafi kyawun provider/model 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 virtual | | `open-sse/services/autoCombo/providerRegistryAccessor.ts` | Test hook don mocking provider registry | | `src/sse/handlers/chat.ts` | Haɗawa: auto prefix short-circuit | | `src/shared/constants/providers.ts` | System entry na `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 | **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. ## Kunshin Yanayi Akwai bayanan martabar nauyi 6 da aka riga aka ayyana a cikin `open-sse/services/autoCombo/modePacks.ts`. Kowane kunshi yana maye gurbin tsoffin nauyoyi gaba ɗaya domin karkatar da zaɓi zuwa ga manufa guda. Jimillar kowane kunshi ta riga ta kai `1.0` (`0.9999` kamar yadda aka nuna da lambobi huɗu bayan digo), saboda haka `normalizeScoringWeights()` ba shi da wani gyara mai ma'ana da zai yi lokacin da kunshi yake aiki — ƙimomin da ke ƙasa su ne, bayan zagaye, 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: - **Kunshin 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 nauyi gaba ɗaya (`weights = pack`, ba haɗewa 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 kunshi yake amfani da ƙimomin kunshin da ke sama. A wurin haɗi mai sanyi (ba a sami abubuwan lura ba tukuna, don haka `quality 0.5` da `reliability 1`) waɗannan ma'aunai biyu suna ƙara `+0.04` a ƙarƙashin kunshi 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 kunshi. - Abin da kowane kunshi 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 masu ƙoshin lafiya) - **cost-saver** → costInv 0.3324 (tokens mafi arha ne suke yin nasara) - **quality-first** → taskFit 0.3524 + stability 0.1429 + quality 0.03, mafi girma a cikin dukkan kunshin (samfurin da ya fi dacewa da aikin, mai daidaito) - **offline-friendly** → quota 0.3324 + health 0.2667 (mafi girman sararin aiki 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 kunshin (mafi ƙarancin abubuwan bazata) - **chaos-mode** → health 0.4000 + taskFit 0.1905 (bayanan martabar gwajin shigar da matsala) ### Sarrafawar Kowane 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 canza saitunan haɗin da aka adana ba. Waɗannan suna aiki ne kawai ga dabarar `auto` kuma kawai ga buƙatar da ke ɗauke da su; ana amfani da `modePack`/`budgetCap`/`budgetFallback` da aka adana na haɗin idan babu header. | Header | Abubuwan da yake karɓa | Tasiri | | :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-OmniRoute-Mode` | laƙabin saitin da aka riga aka tanada (`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 maki na wannan buƙata. `balanced`/`default` suna tilasta amfani da ma'aunan tsoho (babu pack). Ana yin watsi da ƙimomin da ba a sani ba (ana kiyaye saitunan). | | `X-OmniRoute-Budget` | lamba mai kyau (matsakaicin USD ga kowace buƙata) | Ƙaƙƙarfan iyakar kuɗi: ana tace 'yan takarar da kiyasin kuɗinsu ya zarce ta kafin zaɓe. Abin da zai faru idan **duk** 'yan takara sun zarce ta yana ƙarƙashin ikon `X-OmniRoute-Budget-Fallback` da ke ƙasa. | | `X-OmniRoute-Budget-Fallback` | `cheapest` (tsoho, laƙabai: `cheapest-viable`, `soft`) ko `strict` (laƙabai: `block`, `hard`) | `cheapest`: yana koma wa ɗan takara mafi arha gaba ɗaya duk da cewa har yanzu ya zarce 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 ba tare da sanarwa ba. Ana yin watsi da ƙimomin da ba a sani ba. | | `X-OmniRoute-Effort` | `auto` (an tanadi sauran ƙimomi) | Kasafin tunani mai daidaitawa: idan buƙatar ba ta ɗauke da **wani** filin yin tunani na kowace siga ba (`reasoning_effort`, `reasoning`, `thinking`), gateway yana warware `auto` zuwa `low`/`medium`/`high` daga tabbatattun alamomin tsarin buƙata (tsawon saƙon mai amfani na ƙarshe, girman mahalli har zuwa saƙon mai amfani na ƙarshe, sakamakon kayan aiki na baya, zurfin madaukin kayan aiki). Alamomin sun keɓanta ga zagayen yanzu — ana yin watsi da duk abin da ke bayan saƙon mai amfani na ƙarshe — don haka kowace buƙata a cikin madaukin kayan aiki tana warwarewa zuwa mataki ɗaya (daidaitaccen mataki marar yanayin zaman ga kowane zagaye, babu yanayin zaman, babu ƙara mataki a tsakiyar madauki wanda zai lalata prefixes na prompt-cache na upstream). Filin yin tunani da client ya bayyana a sarari koyaushe shi ne yake da rinjaye. Wannan ya keɓanta ga buƙatun da upstream dispatch ɗinsu ya warware zuwa tsarin OpenAI Chat Completions (`targetFormat === FORMATS.OPENAI`) — `reasoning_effort` fili ne mai tsarin OpenAI, don haka header ɗin ba ya yin komai a kan buƙatar da aka nufa ga Claude ko Gemini (duba `open-sse/handlers/chatCore/adaptiveEffortWiring.ts`). | ```bash # Tilasta amfani da mafi saurin profile, iyakance wannan buƙatar zuwa $0.05, sannan a toshe ta gaba ɗaya maimakon wuce kasafin kuɗi 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 pure function ce (`open-sse/services/autoCombo/requestControls.ts`); ƙimomin da aka warware suna shiga abubuwan shigarwa na engine ɗin da suke akwai, wato `config.modePack` / `config.budgetCap` / `config.budgetFallback`. `config.budgetFallback` da aka adana na combo ("strict" | "cheapest") yana saita manufofin dindindin; header ɗin yana maye gurbinsa don buƙata guda ɗaya. ## Duk Dabarun Sarrafa Hanya Injin haɗin OmniRoute yana goyon bayan **dabarun sarrafa hanya guda 19** (an ayyana su a cikin `src/shared/constants/routingStrategies.ts` → `ROUTING_STRATEGY_VALUES`). Ana samar da injin Auto Combo kansa ƙarƙashin dabarar `auto`; sauran kuma suna samuwa ga haɗe-haɗen da aka adana. | Dabara | Bayani | | :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `priority` | Jerin manufa na farko da aka tsara tare da fifiko bayyananne | | `weighted` | Zaɓin bazuwar mai nauyi bisa nauyin kowace manufa | | `round-robin` | Bi ta cikin manufofi ɗaya bayan ɗaya bisa jeri | | `context-relay` | Miƙa mahallin tattaunawa tsakanin manufofi (dogayen tattaunawa) | | `fill-first` | Cika ƙason kowace manufa kafin a matsa zuwa ta gaba | | `p2c` | Daidaita nauyi ta zaɓin bazuwar daga zaɓuɓɓuka 2 | | `random` | Zaɓin bazuwar bai-ɗaya | | `least-used` | Zaɓi manufa mai mafi ƙarancin nauyin aiki na yanzu | | `cost-optimized` | Rage $ na kowace buƙata bisa farashin kundin bayanai | | `reset-aware` ⭐ | Ba da fifiko bisa lokacin sake saita ƙaso — tagogin sake saiti masu gajarta suna samun matsayi mafi girma | | `reset-window` | Fi son manufofin da tagar ƙasonsu za ta sake saitawa mafi kusa | | `headroom` | Zaɓi manufa mai mafi yawan sararin ƙaso da ya rage | | `strict-random` | Zaɓin bazuwar ba tare da cire maimaitawa ba | | `auto` | Yi amfani da kimantawar Auto Combo (abubuwa 16) — **ana 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 ya gaza) | | `context-optimized` | Zaɓi manufa mafi dacewa da girman mahallin yanzu | | `cache-optimized` | Sake tsara manufofi bisa dacewar ma’ajiyar prompt — za a fara gwada haɗin da aka fi tsammanin yana riƙe da prefix ɗin wannan buƙata a ma’ajiyarsa (`open-sse/services/combo/promptCacheAffinity.ts`, #8008) | | `fusion` 🧬 | Aika buƙata zuwa rukunin samfura a lokaci guda, sannan mai hukunci ya haɗa amsa guda (duba ƙasa) | | `pipeline` | Gudanar da manufofi bi da bi, tare da sanya fitarwar 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 da ya dace da gwargwado ne ga kowace buƙata** (`open-sse/services/combo/targetSorters.ts` → `selectWeightedTarget`), ba mai daidaita rabon amfani ba ne: - Kowace buƙata tana zaɓar mataki **guda ɗaya** da yiwuwar `weight / totalWeight`; sauran matakan ana tsara su bisa saukowar nauyi a matsayin jerin madadin wannan buƙatar. - Matakin da nauyinsa yake `0` (ko babu) **ba a taɓa zaɓarsa ba** muddin wani mataki yana da nauyi > 0 — zai iya zama madadin ne kawai bayan matakin da aka zaɓa ya gaza. Sai idan nauyuka **duka** suka zama 0 ne zaɓin zai zama bai-ɗaya. - Ana cire matakan da duk manufofinsu ba sa samuwa — provider circuit breaker `OPEN`, lokacin jiran haɗi, kulle samfur — daga zaɓin kafin a gudanar da shi (`open-sse/services/combo/targetResolution.ts`), don haka mataki lafiyayye guda ɗaya zai iya cin nasarar kowace buƙata na ɗan lokaci. - `stickyWeightedLimit` (tsarin combo, tsohon ƙima `1` = a kashe) yana manne wa matakin da aka zaɓa har tsawon nasarori masu jere daidai wannan adadin kafin a sake yin zaɓi. Don juyawa mai tsauri, yi amfani da `round-robin`; nauyuka daidai a `weighted` suna samar da daidaito na ƙididdiga — ba mai tsauri ba. ## 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ɓantaccen endpoint na `POST /api/combos/auto`** — ana amfani da Auto-Combo ta hanyoyi biyu: 1. **Ba tare da saiti ba (ana ba da shawara):** Aika kowace chat completion request tare da `model: "auto"` ko `model: "auto/"`. Virtual factory yana gina combo ga kowace request — babu adanawa, kuma ba a buƙatar kiran API. 2. **Combo da aka adana mai `strategy: "auto"`:** Ƙirƙiri combo na yau da kullum ta hanyar `POST /api/combos` sannan ka saita `strategy: "auto"` tare da `config.auto.weights` / `config.auto.candidatePool`. Ana amfani da injin ƙididdige maki iri ɗaya; ana adana combo ɗin a cikin `combos` kuma ana iya sake amfani da shi ta ID. Domin ganowa, `GET /api/combos/auto` yana jera kowane variant tare da candidate pool da aka warware, haɗe da `context_length` / `max_output_tokens` — wato MAX a dukkan windows na candidate pool. Clients (misali opencode plugin) dole ne su sanar da waɗannan ƙimomi maimakon `0`: context mai sifili yana kashe auto-compaction na opencode gaba ɗaya, yana barin sessions su ci gaba da girma har sai history purge na gateway ya lalata context. Sanar da MAX ba shi da haɗari saboda context pre-filter na auto-combo yana tura requests masu girma fiye da kima zuwa candidates masu manyan windows. ```bash # Amfani ba tare da saiti ba (ba a ƙirƙiri combo ba) 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 endpoint na combos na 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 Combos da aka adana masu `strategy: "auto"` za su iya saita `config.routerStrategy` (ko tsohon `config.auto.routerStrategy`) zuwa ɗaya daga cikin: - `rules` — ƙididdige maki mai nauyi na asali - `score` — yana zaɓar mafi girman configured weighted score. Daidaitattun maki gaba ɗaya suna kiyaye configured candidate order; `explorationRate` da ke akwai yana ɗaukar samfur daga cikakken ranked pool. - `cost` / `eco` — provider mafi arha da ke cikin koshin lafiya - `latency` / `fast` — p95 latency mafi ƙanƙanta tare da reliability penalty - `sla-aware` / `sla` — fifita candidates waɗanda suka cika p95 latency, error-rate, da optional cost SLOs - `lkgp` — provider na ƙarshe da aka san yana aiki da kyau da farko ### Cikakken bayani kan dabarun router Injin auto-combo yana samar da aiwatarwar **RouterStrategy** guda 6 masu sauƙin musanyawa waɗanda za ka iya sauyawa ta hanyar `config.routerStrategy` (ko tsohon `config.auto.routerStrategy`). Kowace dabara tana zaɓar provider guda ɗaya daga candidate pool, bisa wani `RoutingContext` (nau'in task, alamun tool/vision, kiyasin token, optional SLA policy, optional provider na ƙarshe da aka san yana aiki da kyau). #### 1. `rules` (na asali) — ƙididdige maki mai nauyi na abubuwa 16 Yana naɗe injin ƙididdige maki da ake da shi. Yana tace candidates masu circuit-breaker `OPEN`, sannan yana gudanar da `scorePool()` tare da nau'in task na yanzu da `getTaskFitness()`, yana zaɓar provider mai maki mafi girma. ```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**: Na asali. Yi amfani da shi idan kana son daidaitaccen musaya tsakanin dukkan signals. **Alias**: `rules` (babu alias) --- #### 2. `cost` / `eco` — provider mafi arha da ke cikin koshin lafiya Yana tsara candidate pool bisa `costPer1MTokens` (daga ƙarami zuwa babba) sannan ya zaɓi mafi arha. Da farko yana cire candidates masu `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**: Workloads masu la'akari da tsada, batch processing, ko ayyukan baya. **Aliases**: `cost`, `eco` --- #### 3. `latency` / `fast` — p95 latency mafi ƙanƙanta tare da reliability penalty Ana jerantawa bisa `p95LatencyMs + (errorRate * 1000)`. Hukuncin ƙimar kuskure yana tabbatar da cewa ana sanya masu samar da sabis marasa dogaro a ƙasa ko da kuwa latency ɗinsu 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 latency ke da matuƙar muhimmanci kamar hira ta ainihin lokaci, cika rubutu ta atomatik, ko mataimakan rubuta lamba masu mu'amala. **Sunaye na madadi**: `latency`, `fast` --- #### 4. `sla-aware` / `sla` — bin ƙa'idodin SLO na latency/kuskure/kuɗi Yana ba kowane ɗan takara maki bisa yadda yake cika manufar SLO da aka saita: | Ma'auni | Nauyi | Tsari | | ----------------------- | ----- | --------------------------------------------------- | | Makin latency | 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 karkatar daidaitacciyar latency | Lokacin da `hardConstraints: true`, ana fara jeranta 'yan takara ne bisa **maki na karya ƙa'ida** (gwargwadon yadda suka wuce kowane SLO), sannan bisa jimillar maki. In ba haka ba, kawai ana amfani da jimillar maki. ```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 manufar: { targetP95Ms, maxErrorRate, maxCostPer1MTokens, hardConstraints } } } ``` **Filayen SLA** (ana saita su a kan tsarin haɗin): ```json { "strategy": "auto", "config": { "routerStrategy": "sla-aware", "slaTargetP95Ms": 1500, "slaMaxErrorRate": 0.05, "slaMaxCostPer1MTokens": 5, "slaHardConstraints": true } } ``` **Lokacin amfani**: Ayyukan samarwa masu tsauraran iyakokin latency, ƙimar kuskure, ko kuɗi. **Sunaye na madadi**: `sla-aware`, `sla` --- #### 5. `lkgp` — fara da mai samar da sabis na ƙarshe da aka tabbatar yana aiki Yana fara gwada **mai samar da sabis na ƙarshe da aka tabbatar yana aiki** (idan an saita shi), sannan ya koma kan dabarar `rules`. Yana da amfani wajen manne zaman aiki — mai samar da sabis ɗaya ne yake sarrafa buƙatun ci gaba 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 /* ... */ }; } } // Komawa kan dabarar rules return getStrategy("rules").select(pool, context); } } ``` **Lokacin amfani**: Tattaunawa mai zagaye da yawa inda ake son mai samar da sabis ɗaya ya sarrafa buƙatun ci gaba (misali, don caching, ci gaban mahallin bayani, ko daidaiton farashi). **Sunan madadi**: `lkgp` (babu wani sunan madadi) --- ### Dabarun na'ura mai ba da hanya na musamman Za ka iya yin rajistar aiwatarwar `RouterStrategy` taka 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) { // Sanya dabararka ta bayar da hanya 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ɓen dabarar na'ura mai ba da hanya | Yanayin amfani | Dabara | Dalili | | ----------------------- | ----------- | --------------------------------------------------------- | | Aiki mai daidaito | `rules` | Tsoho — yana la'akari da dukkan ma'aunai | | Rage kuɗi | `cost` | Koyaushe yana zaɓar mafi arha | | Rage latency | `latency` | Yana zaɓar mai samar da sabis mafi sauri kuma abin dogaro | | Tsauraran SLO | `sla-aware` | Yana tacewa bisa iyakokin p95/kuskure/kuɗi | | Hira mai zagaye da yawa | `lkgp` | Manne zaman aiki | Filayen da ke la'akari da SLA: ```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 Suke Shiga Cikin Auto-Combo Aikin ƙididdiga mai abubuwa 16 (`open-sse/services/autoCombo/scoring.ts`) yana ɗaukar kasancewa a tier a matsayin sigina biyu: `tierPriority` (0.0476) da `tierAffinity` (0.0476). Duba [teburin abubuwan ƙididdiga](#how-it-works-persisted-auto-combos) na asali da ke sama don cikakken saitin `DEFAULT_WEIGHTS` — an jera keɓantattun sauye-sauyen kowane pack (ship-fast/cost-saver/quality-first/ offline-friendly) a cikin 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 jerin tier, yi amfani da dabarar combo ta `priority` sannan a tsara providers bisa tier. Don fifita Tier 1 (subscription) sosai, ƙara nauyin `tierPriority`: ```json { "strategy": "auto", "config": { "auto": { "weights": { "tierPriority": 0.3, "costInv": 0.05 } } } } ``` Duba `docs/marketing/TIERS.md` don ma'anonin tier da rarraba providers. ## 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 ƙididdiga mai abubuwa 16, `DEFAULT_WEIGHTS`, daidaita pool | | `open-sse/services/autoCombo/taskFitness.ts` | Binciken dacewar model × aiki | | `open-sse/services/autoCombo/engine.ts` | Dabarar zaɓi, bandit, iyakar kasafin kuɗi | | `open-sse/services/autoCombo/selfHealing.ts` | Warewa, gwaje-gwajen bincike, yanayin aukuwar matsala | | `open-sse/services/autoCombo/modePacks.ts` | Bayanan martabar nauyi 6 (ship-fast, cost-saver, quality-first, offline-friendly, reliability-first, chaos-mode) | | `open-sse/services/autoCombo/autoPrefix.ts` | Mai fassara prefix na `auto/` + nau'o'i 6 | | `open-sse/services/autoCombo/virtualFactory.ts` | Yana gina `AutoComboConfig` na cikin ƙwaƙwalwa daga haɗin kai masu aiki | | `open-sse/services/autoCombo/providerRegistryAccessor.ts` | Mahaɗin gwaji don kwaikwayon rajistar mai samarwa | | `src/shared/constants/routingStrategies.ts` | `ROUTING_STRATEGY_VALUES` (dabaru 19) | | `src/sse/handlers/chat.ts` | Haɗawa: gajeriyar hanyar auto-prefix |