Različica 1.0.0-alpha.1najnovejša
Poglavje 2.14
Ponudniki in modeli UI
Kako usmerjevalnik ponudnikov umetne inteligence (UI) izbere model iz organizacijskega nabora ključev ter kako skripti in orodja UI dostopajo do sistema Nexus od zunaj.
To stran je iz angleškega izvirnika prevedla UI. Če je karkoli nejasno, je referenca angleška stran. Preberite to stran v angleščini

Harrow Port Authority upravlja dve namestitvi. Tista v njihovem fizično ločenem (air-gapped) operativnem omrežju (poglavje 2.10, Fizično ločena namestitev) nima nobenega gostovanega ponudnika. V povezani korporativni namestitvi, ki jo spremlja to poglavje, na večino vprašanj odgovori model, ki teče na dveh vozliščih z grafičnimi procesnimi enotami (GPU) v lastni strežniški sobi pristanišča. Ključ za Google Gemini, ki ga plačuje Harrow, prevzame presežek, ko je lokalni model zaseden, Aoife Brennan pa je promet umetne inteligence (UI) organizacije zaklenila na EU. Nihče v podjetju Harrow ni konfiguriral modela znotraj storitve ali vtičnika. Eni komponenti so povedali, kaj je v lasti podjetja Harrow, in ta komponenta odloča o vsakem klicu.
To poglavje obravnava to komponento, AI Provider Router, ki jo 1. del in konzola imenujeta stikalna plošča UI, ter nabor ključev, iz katerega črpa. Zaključi se z načini, kako skripti in orodja UI dosežejo Nexus od zunaj: ključi za skripte, aplikacijski programski vmesnik (API) REST (prenos reprezentacijskega stanja) in Model Context Protocol (MCP).
Usmerjevalnik ponudnikov UI
Usmerjevalnik teče znotraj prehoda, nexus-gateway. Je edina storitev, ki hrani poverilnice modelov organizacije, in sprejema končno odločitev o tem, kateri ponudnik in kateri model odgovorita na posamezno zahtevo. Vsi drugi deli sistema Nexus vprašajo njega. Korak delovnega toka pove, kaj bi želel, usmerjevalnik pa odloči.
Samo nekaj storitev sme vprašati, vsak seznam pa je določen s paketom Helm chart:
| Kaj je zahtevano | Kdo sme vprašati |
|---|---|
Dopolnitev (/internal/ai/chat in njen tok) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Klici orodij in druge interne poti UI | nexus-orchestrator, nexus-workflows |
| Vdelave in ponovno razvrščanje | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Vsaka interna pot zaporedoma preveri dve stvari: interni storitveni ključ klicatelja in identiteto klicatelja glede na zgornji seznam. Zahteva brez ključa je zavrnjena z MISSING_SERVICE_KEY (401), napačen ključ z INVALID_SERVICE_KEY (403), zahteva, ki ne pove, kdo kliče, z MISSING_CALLER_IDENTITY (403), in klicatelj izven seznama z UNAUTHORIZED_CALLER (403). Nobena od teh zahtev se ne ponovi, ker nobena od njih ni prehodna napaka.
Aplikacije in vtičniki se nikoli ne pojavijo na tem seznamu. Vtičnik izrazi svoje želje pri veščinah, ki jih registrira, in jih razpošlje prek UNO, pogona delovnih tokov. Orkestrator nato v imenu vtičnika vpraša usmerjevalnik. Zato lahko ena razkrita skrivnost vtičnika deluje kot ta vtičnik, ne more pa porabiti proračuna za modele kogarkoli drugega.
Organizacijski nabor ključev
Ključi modelov pripadajo organizaciji. Vsaka organizacija prinese svoj račun ponudnika in plačuje svoj račun, ključ pa se nahaja v naboru organizacije, šifriran v storitvi nexus-auth. V ozadju organizacije ni nobenega deljenega ključa platforme, zato nobena organizacija nikoli ne porablja proračuna druge. Cena tega pravila je jasna: organizacija brez ključa v svojem naboru ne dobi nobenih odgovorov UI. Pomočnik prikaže MODEL_NOT_CONNECTED (503) in pove, kdo ga lahko poveže.
Ključ je mogoče dodati v nabor za štiri ponudnike:
| ID ponudnika | Prikazan kot |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Vaš lastni strežnik modela
Organizacija lahko uporabi tudi katerikoli strežnik, ki ga upravlja in ki govori API, združljiv z OpenAI, kot je model na vozliščih GPU podjetja Harrow. Namestitveni program ga poimenuje v datoteki z vrednostmi:
# harrow-values.yaml (Helm values): the AI part
ai:
localProvider:
baseUrl: "https://models.harrow.example/v1"
installationHosts:
- models.harrow.example
- 10.40.20.0/24
networkPolicy:
externalEgressCIDRs:
- 10.40.20.0/24ai.localProvider.baseUrl usmeri vmesnik prehoda, združljiv z OpenAI, na vaš strežnik. V namestitvi mesto scaleway v naboru doseže ta strežnik, tako da je ključ, ki ga dodate za scaleway, tisti ključ, ki ga pričakuje vaš lastni strežnik.
ai.installationHosts navaja imena gostiteljev, ki so znotraj namestitve, poleg lastne storitvene domene izdaje in treh javnih gostiteljev. Vsak vnos je ime gostitelja, .suffix, naslov IP ali obseg IPv4 brezrazrednega meddomenskega usmerjanja (CIDR). Usmerjevalnik uporablja ta seznam, da loči klic, ki ostane na lokaciji, od tistega, ki jo zapusti, kar poroča preverjanje »Nič ne zapusti te lokacije« na strani Povežite model na lastni strojni opremi.
Omrežni pravilnik je prav tako pomemben kot usmerjevalnik. Imenski prostor privzeto zavrača ves izhodni promet, zato lahko prehod doseže strežnik modela izven imenskega prostora le, če je njegov obseg v networkPolicy.externalEgressCIDRs. Enako velja za gostovanega ponudnika: če Harrow želi, da njegov ključ Gemini odgovarja, morajo biti tam navedeni tudi obsegi naslovov ponudnika, sicer klic nikoli ne zapusti gruče. Poglavje 2.16, Varnost in omrežje, v celoti obravnava ta pravilnik.
Dodajanje in umik ključev
Lastniki in skrbniki organizacije upravljajo njen nabor. Nihče drug ne more videti ključev in jih ne more spreminjati, zahteva z njihove strani pa je zavrnjena z AUTHORITY_EXCEEDED.
V konzoli
V izdaji Enterprise se nabor hrani v stikalni plošči UI, pod pogoni. V izdaji Community se isti ključi hranijo v Nastavitve, Modeli UI. Ta stran je osnovni usmerjevalnik, kjer dodate ključe in naslov lokalnega modela ter izberete, kateri model opravlja katero delo. Obe prikažeta vsak ključ glede na to, kdo ga je nastavil in kdaj (»Nastavila Aoife, 3. sept.«), ter z zakritim namigom največ zadnjih štirih znakov, kot je ••••7f2q. Sam ključ po tem, ko ga dodate, ni nikoli več prikazan.
Prek BFF API-ja
Zaledje za čelni del (BFF) konzole streže tri poti za nabor. Kličite jih z lastnim žetonom za dostop osebe: organizacija izhaja iz žetona, nikoli iz zahteve.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET vrne ponudnike v naboru, ali vsak lahko odgovarja, vsak ključ po njegovem namigu in ponudnike, za katere je mogoče dodati ključ. Dodajanje ključa sprejme telo JSON z dvema obveznima poljema in enim izbirnim:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }Ključ potuje enkrat. nexus-auth ga šifrira in obvesti usmerjevalnik, odgovor pa nosi le namig. Odgovor je 201 z ID-jem novega ključa in njegovo vrstico: »Dodano. Ključ Google Gemini ••••7f2q je v naboru UI organizacije in AI Provider Router lahko zdaj usmerja nanj.« Oznaka ima največ 100 znakov, ključ pa je en niz brez presledkov z največ 4.096 znaki. Katerokoli drugo polje v telesu ali polje, ki imenuje organizacijo ali osebo, je zavrnjeno.
Umik sprejme prazno telo. Usmerjevalnik takoj preneha usmerjati na ključ, nexus-auth pa ga obdrži, navedenega kot umaknjenega, tako da njegova zgodovina ostane. Nič v naboru se nikoli ne izbriše.
| Zavrnitev | HTTP | Kdaj |
|---|---|---|
VALIDATION_FAILED |
400 | Telo, ki ni {provider, api_key, label?}, neznan ponudnik ali lastna naročnina osebe, ponujena kot ključ organizacije |
AUTHORITY_EXCEEDED |
403 | Klicatelj ni lastnik ali skrbnik organizacije |
RECORD_NOT_FOUND |
404 | V naboru organizacije ni ključa s tem ID-jem |
TRANSITION_NOT_PERMITTED |
409 | Ključ je že umaknjen |
TENANT_NOT_A_PARAMETER |
403 | Telo ali poizvedba je imenovala organizacijo |
Stanja ključev
Vsak ključ v naboru je v enem od šestih stanj. Samo ključ v uporabi odgovarja na klepet.
| Stanje | Kaj pomeni |
|---|---|
in_use |
Ključ odgovarja do datuma poteka veljavnosti, če ga ima. |
resting |
Usmerjevalnik ga je po napakah poslal na počitek do določenega časa. Zahteve medtem gredo na naslednji ključ. |
exhausted |
Porabil je svojo omejitev pri ponudniku. |
invalid |
Ponudnik ga ne sprejema več. |
expired |
Potekel je na datum poteka veljavnosti. |
withdrawn |
Skrbnik ga je umaknil. Ostane naveden kot zgodovina. |
Ključ, ki odpove, počiva 60 sekund. Po 5 zaporednih napakah ga usmerjevalnik izklopi, njegov delež prenese na druge ključe in zabeleži obvestilo PROVIDER_KEY_SWITCHED_OFF. Nihče ni zavrnjen, dokler lahko odgovarja drug ključ.
Ko ponudnik nima ključa v uporabi, nabor pove zakaj (»Noben ključ v uporabi: 1 umaknjen, 1 potekel«). Ko noben ponudnik v naboru nima ključa v uporabi, je klepet zavrnjen z NO_PROVIDER_FOR_ROLE (422) in rešitvijo: lastnik ali skrbnik doda ključ organizacije. To je stanje konfiguracije in ostane na zaslonu, dokler ga nekdo ne popravi.
Vloge, pravilniki in želje
Usmerjevalnik razmišlja v vlogah. Vsaka zahteva je namenjena eni od petih: default, fast, reasoning, code ali long_context. Vsak model je tudi v ravni, frontier, standard ali fast, višja raven pa ima prednost, ko vloga to dopušča. Organizacija se odloči, kateri ponudnik služi posamezni vlogi (njene dodelitve vlog) in v kakšnem vrstnem redu se preklopi na rezervo, ko ponudnik odpove (njena lestvica pravilnika usmerjanja). Skrbniki nastavijo oboje v stikalni plošči UI. nexus-auth ju streže tudi na /auth/org/<organisation-id>/settings/ai-provider/role-assignments in /auth/org/<organisation-id>/settings/ai-provider/routing-policy za skrbniški ključ, ki ima ai_provider:manage.
Klicatelji lahko povedo, kaj bi želeli. Vrstica veščine ima lahko prednostnega ponudnika in prednostni model ter profil zmogljivosti. Usmerjevalnik vsakega obravnava drugače:
- Prednostni ponudnik se upošteva le, ko ima organizacija tega ponudnika omogočenega in ima ključ zanj. Sicer usmerjevalnik uporabi nadomestilo.
- Prednostni model se upošteva, ko je v katalogu tega ponudnika in ustreza profilu.
- Profil zmogljivosti je filter, ki nikoli ne izbira. Zahteva lahko najmanjše kontekstno okno, uporabo orodij, vid, vdelave, dolg kontekst ali rezidenčnost podatkov. Karkoli temu ne ustreza, ni primerno.
Usmerjevalnik izbira v določenem vrstnem redu. Upošteva željo, ko lahko, nato poskusi drug model istega ponudnika, nato dodelitev vloge in kateregakoli drugega ponudnika s ključem, čigar katalog ustreza. Če je bil podan profil in mu ne ustreza noben katalog, je zahteva zavrnjena z MODEL_CAPABILITY_UNAVAILABLE (422). Če ni nič dodeljeno in nič ne ustreza, je NO_PROVIDER_FOR_ROLE (422). Ni privzetega modela v skrajni sili. Vloga, ki je niste konfigurirali, glasno odpove, pri čemer usmerjevalnik s svojimi besedami pove, kaj je treba nastaviti.
Rezidenčnost podatkov je edina omejitev, ki je ni mogoče zaobiti z nadomestilom. Profil z eu_only postreže ponudnik iz EU ali pa je zavrnjen. Harrow nastavi to zaklepanje za celotno organizacijo, stikalna plošča pa drugega gostovanega ponudnika, ki se nahaja v regiji ZDA, izriše kot izklopljenega.
Veščina lahko tudi pripne en točno določen model, ko veščina potrebuje ta model za delovanje. Tudi takrat usmerjevalnik zanj uporabi lastni ključ organizacije, in brez njega nič ne odgovori. Klicatelj nikoli ne more pripraviti sistema Nexus do uporabe ponudnika, ki ga organizacija ni konfigurirala.
Ko je ponudnik izbran, je samodejni preklop ob izpadu ločena zadeva. Napaka 429, 5xx ali napaka omrežja premakne zahtevo po lestvici navzdol do naslednjega ponudnika. Napaka 400, 401, 403 ali 404 se ustavi takoj, ker se poverilnice in oblike zahtev ne prenašajo med ponudniki in bi ponovni poskus porabil kvoto, da bi dosegel isto napako.
Če želite videti, kaj bi usmerjevalnik izbral, preden kdorkoli postavi vprašanje, preberite GET /api/ai/routing-policy/effective na prehodu z lastnim žetonom osebe. Odgovori z modelom za prijavljeno organizacijo ali z ubesedeno zavrnitvijo usmerjevalnika, ko modela ni, in ne pošlje nobene zahteve modelu.
Spremljanje usmerjevalnika
Pas s številkami na dnu vsake strani prikazuje model v uporabi (»Model: lokalni«). V izdaji Enterprise pogled Stikalna plošča UI, v živo izrisuje promet usmerjevalnika med njegovim dogajanjem: zahteve pomočnika, opravil in aplikacij, ki tečejo skozi vloge do ponudnikov in ključev, ključ v svojem 60-sekundnem počitku izrisan sivo, izklopljen ključ izrisan rdeče in preklop na gostovanega ponudnika, ko je lokalni model zaseden. Poleg toka izrisuje graf obremenitve na ponudnika, zahtev na sekundo in čakalnega časa. Tomás ga ima odprtega v prvem tednu po vsaki spremembi pravilnika usmerjanja, ker se napačna dodelitev vloge tam pokaže v nekaj minutah kot promet, ki gre nekam, kamor nihče ni nameraval.
V izdaji Community ima stran Modeli UI gumb Preizkusi vsak model, ki preveri vsak konfiguriran model in označi, ali odgovarja. To je najhitrejši način za dokazovanje, da nov ključ deluje, preden se nanj kdorkoli zanese.
Vdelave (Embeddings)
Iskanje in graf znanja pretvarjata besedilo v vektorje. Namestitev to privzeto počne z modelom za vdelave, ki teče znotraj gruče na procesorju, tako da nobeno besedilo ne zapusti lokacije za vdelavo in organizacija za to ne potrebuje ključa. Uporaba gostovanega ponudnika za vdelave je izbira, ki jo sprejme organizacija; nato gre skozi isti nabor in ista pravila.
Samo tri storitve smejo prositi usmerjevalnik za vdelave ali ponovno razvrščanje: nexus-graphrag, nexus-skills-engine in nexus-workflows. GraphRAG vdeluje kot organizacija, katere vsebina to je, z nastavitvami te organizacije, in nima nobenega lastnega ključa ponudnika. Ko organizacija spremeni svoj model za vdelave, nexus-workflows zažene opravilo ponovne vdelave za shrambe te organizacije.
Osebne poverilnice ostanejo osebne
Nekatere poverilnice pripadajo eni osebi. Naročnina Claude Max, prijavljena prek lastnega računa te osebe, je pogost primer. Takšna poverilnica ni nikoli ključ organizacije: nabor jo zavrne z VALIDATION_FAILED, nikoli ni navedena v tabeli ključev organizacije in noben zaslon druge osebe je ne prikaže.
Ključi modelov prav tako nikoli ne gredo nikamor drugam. Stran Ključi zunanjih podatkov, ki hrani ključe za zunanje podatkovne vire, zavrne vse, kar je videti kot ključ modela UI, z AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Če bralnik datotek najde ključe modelov znotraj dokumenta ali konfiguracije, kamor ne sodijo, zabeleži CREDENTIALS_IN_WRONG_PLACE, skrbnik pa jih odstrani in zamenja.
Skripti, REST in MCP
Nexus ima tri javne gostitelje. V podjetju Harrow so to console.harrow.example za konzolo, api.harrow.example za prehod in auth.harrow.example za prijavo. Skripti in orodja uporabljajo drugega in tretjega.
Ključi za skripte
Skript se prijavi s ključem, ustvarjenim v Nastavitve, Ključi za skripte. Vsak ključ ima ime, doseg (na primer »Samo zaženi štetje na dvorišču z droni«), osebo, ki ga je ustvarila, in končni datum; organizacija lahko zaklene najdaljšo življenjsko dobo, ki jo ključ sme imeti. Skrivnost je prikazana enkrat ob izdelavi ključa. Kopirajte jo v shrambo skrivnosti skripta, saj Nexus hrani le njene zadnje štiri znake. Ključ se umakne, nikoli odstrani: ustavi se takoj in ostane naveden z vsakim klicem, ki ga je opravil. Rotacija da ključu novo skrivnost in jo prikaže enkrat.
Vsak ključ ima svojo stran s klici na dan, klici po storitvah in dnevnikom dejavnosti s časom, naslovom, storitvijo in rezultatom. Klic izven dosega ključa je zavrnjen in se prikaže v dnevniku.
nexus-auth streže iste ključe prijavljeni osebi na https://auth.harrow.example/api-keys: ustvarite in izpišite seznam, nato preberite, spremenite, prekličite ali rotirajte en ključ po njegovem ID-ju.
REST prek prehoda
Pošljite klice REST na https://api.harrow.example z Authorization: Bearer <token-or-key>. Vsak ključ mora pripadati organizaciji. Ključ brez nje zavrne z TOKEN_ORG_MISSING (403) vsaka storitev, ki preverja ključe prek nexus-auth.
Klicatelj, ki sprašuje prepogosto, dobi odgovor 429 z RATE_LIMITED, glavo Retry-After ter omejitvijo in oknom v telesu. Počakajte toliko sekund, kolikor navede. V izdaji Enterprise skrbniki nastavijo omejitve na ključ, na aplikacijo in na enoto v Nastavitve, Omejitve hitrosti (glejte poglavje 2.16, Varnost in omrežje).
MCP za orodja UI
Orodja UI, ki govorijo Model Context Protocol, se povežejo na https://api.harrow.example/mcp. Prijavijo se prek strežnika OAuth 2.1 (OAuth je odprti standard za delegirano avtorizacijo) na https://auth.harrow.example, ki podpira registracijo odjemalca s strani samega orodja, tako da se orodje, kot je Claude Code ali Cursor, registrira samo in odpre brskalnik osebe za prijavo. Povezava nato deluje za to eno osebo, s pravicami te osebe in nič več. Prijavljena oseba lahko pridobi pripravljeno konfiguracijo za orodje ukazne vrstice iz https://auth.harrow.example/api/v1/mcp/cli-config.
Klici orodij, ki potrebujejo model, gredo skozi usmerjevalnik kot vse drugo, pod organizacijo te osebe.




