Verzija 1.0.0-alpha.1najnovije
Poglavlje 2.14
Pružatelji i modeli AI-ja
Kako usmjerivač pružatelja umjetne inteligencije (AI) bira model iz vlastitog skupa ključeva organizacije te kako skripte i alati AI-ja pristupaju sustavu Nexus izvana.
Ovu je stranicu s engleskog izvornika preveo AI. Ako je išta nejasno, mjerodavna je stranica na engleskom jeziku. Pročitajte ovu stranicu na engleskom jeziku

Harrow Port Authority koristi dvije instalacije. Ona na njezinoj fizički izoliranoj operativnoj mreži (poglavlje 2.10, Fizički izolirana instalacija) uopće nema hostiranog pružatelja usluga. Na povezanoj korporativnoj instalaciji, koju ovo poglavlje prati, na većinu pitanja odgovara model koji se izvodi na dva čvora grafičke procesorske jedinice (GPU) u vlastitoj serverskoj sobi luke. Ključ za Google Gemini, koji plaća Harrow, preuzima višak prometa kada je lokalni model zauzet, a Aoife Brennan zaključala je promet umjetne inteligencije (AI) organizacije na EU. Nitko u organizaciji Harrow nije konfigurirao model unutar usluge ili dodatka. Jednoj su komponenti rekli što Harrow posjeduje, a ta komponenta odlučuje o svakom pozivu.
Ovo poglavlje obrađuje tu komponentu, AI Provider Router, koju 1. dio i konzola nazivaju AI centralom, te skup ključeva koje ona koristi. Završava načinima na koje skripte i AI alati pristupaju sustavu Nexus izvana: ključevima za skripte, aplikacijskim programskim sučeljem (API) za prijenos reprezentativnog stanja (REST) i protokolom konteksta modela (MCP).
Usmjerivač pružatelja AI-ja
Usmjerivač se izvodi unutar pristupnika, nexus-gateway. To je jedina usluga koja čuva vjerodajnice modela organizacije i donosi konačnu odluku o tome koji pružatelj usluga i koji model odgovaraju na pojedini zahtjev. Svaki drugi dio sustava Nexus upućuje upite njemu. Korak radnog tijeka kaže što bi želio, a usmjerivač odlučuje.
Samo nekoliko usluga smije postaviti upit, a svaki je popis fiksno određen Helm chartom:
| Što se traži | Tko smije tražiti |
|---|---|
Dovršavanje (/internal/ai/chat i njegov tok) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Pozivi alata i ostale interne AI rute | nexus-orchestrator, nexus-workflows |
| Ugradnje i ponovno rangiranje | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Svaka interna ruta redom provjerava dvije stvari: interni ključ usluge pozivatelja i identitet pozivatelja prema gornjem popisu. Zahtjev bez ključa odbija se s MISSING_SERVICE_KEY (401), pogrešan ključ s INVALID_SERVICE_KEY (403), zahtjev koji ne navodi tko poziva s MISSING_CALLER_IDENTITY (403), a pozivatelj izvan popisa s UNAUTHORIZED_CALLER (403). Ništa od navedenog ne pokušava se ponovno jer ništa od toga nije prolazna pogreška.
Aplikacije i dodaci nikada se ne pojavljuju na tom popisu. Dodatak deklarira svoje želje na vještinama koje registrira te ih šalje kroz UNO, pogon radnog tijeka. Orkestrator zatim postavlja upit usmjerivaču u ime dodatka. Zbog toga jedna procurjela tajna dodatka može djelovati kao taj dodatak, ali ne može trošiti ničiji proračun za modele.
Skup ključeva organizacije
Ključevi modela pripadaju organizaciji. Svaka organizacija donosi vlastiti račun pružatelja usluga i plaća vlastiti račun, a ključ se nalazi u skupu organizacije, šifriran u usluzi nexus-auth. Ne postoji dijeljeni platformski ključ iza organizacije, tako da nijedna organizacija nikada ne troši proračun druge. Cijena tog pravila je jasna: organizacija bez ključa u svom skupu ne dobiva AI odgovore. Asistent prikazuje MODEL_NOT_CONNECTED (503) i navodi tko ga može povezati.
Ključ se u skup može dodati za četiri pružatelja usluga:
| ID pružatelja usluga | Prikazano kao |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Vlastiti poslužitelj modela
Organizacija također može koristiti bilo koji poslužitelj kojim upravlja, a koji koristi API kompatibilan sa sustavom OpenAI, kao što je model na GPU čvorovima organizacije Harrow. Instalacijski program imenuje ga u datoteci vrijednosti:
# 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 usmjerava adapter pristupnika kompatibilan sa sustavom OpenAI na vaš poslužitelj. Na instalaciji, utor scaleway iz skupa pristupa tom poslužitelju, tako da je ključ koji dodate za scaleway onaj ključ koji vaš vlastiti poslužitelj očekuje.
ai.installationHosts navodi nazive hostova koji se nalaze unutar instalacije, uz vlastitu domenu usluge izdanja i tri javna hosta. Svaki unos je naziv hosta, .suffix, IP adresa ili raspon IPv4 besklasnog međudomenskog usmjeravanja (CIDR). Usmjerivač koristi taj popis kako bi razlikovao poziv koji ostaje na lokaciji od onoga koji je napušta, o čemu izvještava provjera „Ništa ne napušta ovu lokaciju” na stranici Povežite model na vlastitom hardveru.
Mrežna pravila jednako su važna kao i usmjerivač. Imenski prostor prema zadanim postavkama zabranjuje sav izlazni promet, pa pristupnik može dosegnuti poslužitelj modela izvan imenskog prostora samo kada je njegov raspon u networkPolicy.externalEgressCIDRs. Isto vrijedi i za hostiranog pružatelja usluga: ako Harrow želi da njegov Gemini ključ odgovara, rasponi adresa pružatelja usluga također moraju biti navedeni tamo, inače poziv nikada ne napušta klaster. Poglavlje 2.16, Sigurnost i umrežavanje, u potpunosti obrađuje ta pravila.
Dodavanje i povlačenje ključeva
Vlasnici i administratori organizacije održavaju njezin skup. Nitko drugi ne može vidjeti ključeve niti ih mijenjati, a njihov se zahtjev odbija s AUTHORITY_EXCEEDED.
U konzoli
U izdanju Enterprise skup se čuva u AI centrali, pod pogonima. U izdanju Community isti se ključevi čuvaju u odjeljku Postavke, AI modeli. Ta je stranica osnovni usmjerivač, gdje dodajete ključeve i adresu lokalnog modela te birate koji model obavlja koji posao. Oboje prikazuje svaki ključ prema tome tko ga je postavio i kada („Postavila Aoife, 3. rujna”) te prema maskiranom prikazu njegovih najviše posljednjih četiriju znakova, kao što je ••••7f2q. Sam ključ više se nikada ne prikazuje nakon što ga dodate.
Putem BFF API-ja
Pozadinski sustav za korisničko sučelje (BFF) konzole poslužuje tri rute za skup. Pozovite ih vlastitim pristupnim tokenom osobe: organizacija dolazi iz tokena, nikada iz zahtjeva.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET vraća pružatelje usluga u skupu, podatak može li svaki od njih odgovarati, svaki ključ prema njegovom maskiranom prikazu te pružatelje usluga za koje se ključ može dodati. Dodavanje ključa prima JSON tijelo s dva obvezna polja i jednim neobveznim:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }Ključ putuje jednom. Usluga nexus-auth ga šifrira i obavještava usmjerivač, a odgovor nosi samo maskirani prikaz. Odgovor je 201 s ID-jem novog ključa i njegovim retkom: „Dodano. Ključ za Google Gemini ••••7f2q nalazi se u AI skupu organizacije i AI Provider Router sada može usmjeravati prema njemu.” Oznaka ima najviše 100 znakova, a ključ je jedan niz znakova bez razmaka od najviše 4096 znakova. Svako drugo polje u tijelu, ili polje koje imenuje organizaciju ili osobu, odbija se.
Povlačenje prima prazno tijelo. Usmjerivač odmah prestaje usmjeravati prema ključu, a nexus-auth ga zadržava, navedenog kao povučenog, tako da njegova povijest ostaje. Ništa u skupu nikada se ne briše.
| Odbijanje | HTTP | Kada |
|---|---|---|
VALIDATION_FAILED |
400 | Tijelo koje nije {provider, api_key, label?}, nepoznati pružatelj usluga ili vlastita pretplata osobe ponuđena kao ključ organizacije |
AUTHORITY_EXCEEDED |
403 | Pozivatelj nije vlasnik ili administrator organizacije |
RECORD_NOT_FOUND |
404 | U skupu organizacije nema ključa s tim ID-jem |
TRANSITION_NOT_PERMITTED |
409 | Ključ je već povučen |
TENANT_NOT_A_PARAMETER |
403 | Tijelo ili upit imenovali su organizaciju |
Stanja ključeva
Svaki ključ u skupu nalazi se u jednom od šest stanja. Samo ključ u upotrebi odgovara na razgovor.
| Stanje | Što to znači |
|---|---|
in_use |
Ključ odgovara do svog datuma isteka, ako ga ima. |
resting |
Usmjerivač ga je stavio u mirovanje nakon pogrešaka, do određenog vremena. Zahtjevi u međuvremenu idu na sljedeći ključ. |
exhausted |
Iskoristio je svoje ograničenje kod pružatelja usluga. |
invalid |
Pružatelj usluga ga više ne prihvaća. |
expired |
Istekao je na svoj datum isteka. |
withdrawn |
Administrator ga je povukao. Ostaje naveden u povijesti. |
Ključ koji zakaže miruje 60 sekundi. Nakon 5 uzastopnih pogrešaka usmjerivač ga isključuje, prebacuje njegov udio na ostale ključeve i bilježi obavijest PROVIDER_KEY_SWITCHED_OFF. Nitko nije odbijen dok drugi ključ može odgovoriti.
Kada pružatelj usluga nema ključ u upotrebi, skup navodi zašto ("Nema ključa u upotrebi: 1 povučen, 1 istekao"). Kada nijedan pružatelj usluga u skupu nema ključ u upotrebi, razgovor se odbija uz NO_PROVIDER_FOR_ROLE (422) i rješenje: vlasnik ili administrator dodaje organizacijski ključ. To je stanje konfiguracije i ostaje na zaslonu dok ga netko ne popravi.
Uloge, pravila i želje
Usmjerivač razmišlja u ulogama. Svaki je zahtjev namijenjen jednoj od pet: default, fast, reasoning, code ili long_context. Svaki je model također u razini, frontier, standard ili fast, a viša se razina preferira kada to uloga dopušta. Organizacija odlučuje koji pružatelj usluga opslužuje svaku ulogu (njezine dodjele uloga) i kojim se redoslijedom prebacuje na pričuvu kada pružatelj usluga zakaže (njezina ljestvica pravila usmjeravanja). Administratori postavljaju oboje u AI centrali. nexus-auth ih također poslužuje na /auth/org/<organisation-id>/settings/ai-provider/role-assignments i /auth/org/<organisation-id>/settings/ai-provider/routing-policy za administratorski ključ koji drži ai_provider:manage.
Pozivatelji mogu izraziti što žele. Redak vještine može sadržavati željenog pružatelja usluga i željeni model, uz profil sposobnosti. Usmjerivač svaki od njih tretira drugačije:
- Željeni pružatelj usluga uvažava se samo kada organizacija ima omogućenog tog pružatelja usluga i ima ključ za njega. U suprotnom, usmjerivač pronalazi zamjenu.
- Željeni model uvažava se kada se nalazi u katalogu tog pružatelja usluga i odgovara profilu.
- Profil sposobnosti filtar je koji nikada ne odabire. Može tražiti minimalni kontekstni prozor, upotrebu alata, vid, ugradnje, dugi kontekst ili rezidentnost podataka. Sve što ne zadovolji te uvjete nije prihvatljivo.
Usmjerivač odabire fiksnim redoslijedom. Uvažava želju kada može, zatim pokušava s drugim modelom istog pružatelja usluga, a potom s dodjelom uloge i bilo kojim drugim pružateljem usluga s ključem čiji katalog odgovara. Ako je zadan profil i nijedan mu katalog ne odgovara, zahtjev se odbija uz MODEL_CAPABILITY_UNAVAILABLE (422). Ako ništa nije dodijeljeno i ništa se ne podudara, rezultat je NO_PROVIDER_FOR_ROLE (422). Ne postoji zadani model krajnje nužde. Uloga koju niste konfigurirali glasno zakazuje, pri čemu usmjerivač vlastitim riječima navodi što treba postaviti.
Rezidentnost podataka jedino je ograničenje koje se ne može zaobići zamjenom. Profil s eu_only opslužuje pružatelj usluga iz EU-a ili se odbija. Harrow postavlja ovu blokadu za cijelu organizaciju, a centrala prikazuje drugog hostiranog pružatelja usluga, koji se nalazi u regiji SAD-a, kao isključenog.
Vještina također može fiksirati jedan točan model kada je vještini potreban taj model za rad. Čak i tada usmjerivač koristi vlastiti ključ organizacije za njega, a bez ključa ništa ne odgovara. Pozivatelj nikada ne može natjerati Nexus da koristi pružatelja usluga kojeg organizacija nije konfigurirala.
Nakon što je pružatelj usluga odabran, prebacivanje u slučaju kvara zasebno je pitanje. Pogreška 429, 5xx ili mrežna pogreška pomiče zahtjev niz ljestvicu do sljedećeg pružatelja usluga. Pogreška 400, 401, 403 ili 404 odmah zaustavlja proces, jer se vjerodajnice i oblici zahtjeva ne prenose između pružatelja usluga te bi ponovni pokušaj potrošio kvotu samo da bi došao do iste pogreške.
Da biste vidjeli što bi usmjerivač odabrao prije nego što itko postavi pitanje, očitajte GET /api/ai/routing-policy/effective na pristupniku s vlastitim tokenom osobe. On odgovara s modelom za prijavljenu organizaciju, ili s odbijenicom usmjerivača u riječima kada modela nema, te ne šalje nikakav zahtjev modelu.
Nadzor usmjerivača
Traka s brojkama na dnu svake stranice prikazuje model u upotrebi ("Model: lokalni"). Na izdanju Enterprise, AI centrala, uživo iscrtava promet usmjerivača dok se odvija: zahtjeve asistenta, poslove i aplikacije kako teku kroz uloge do pružatelja usluga i ključeva, ključ u svom 60-sekundnom mirovanju iscrtan sivom bojom, isključeni ključ iscrtan crvenom bojom, te prebacivanje na pričuvnog hostiranog pružatelja usluga kada je lokalni model zauzet. Uz taj tok prikazuje grafikon opterećenja po pružatelju usluga, zahtjeve u sekundi i vrijeme čekanja. Tomás ga drži otvorenim tijekom prvog tjedna nakon bilo kakve promjene pravila usmjeravanja, jer se pogrešna dodjela uloge tamo pokaže u roku od nekoliko minuta kao promet koji ide nekamo kamo nitko nije namjeravao.
Na izdanju Community, stranica AI modeli ima gumb Testiraj svaki model koji provjerava svaki konfigurirani model i označava odgovara li. To je najbrži način da dokažete da novi ključ radi prije nego što se itko osloni na njega.
Vektorske ugradnje (embeddings)
Pretraživanje i graf znanja pretvaraju tekst u vektore. Prema zadanim postavkama instalacija to radi pomoću modela za ugradnje koji se izvodi unutar klastera na procesoru, tako da nikakav tekst ne napušta lokaciju radi ugradnje i organizaciji za to nije potreban ključ. Korištenje hostiranog pružatelja usluga za ugradnje izbor je koji donosi organizacija; tada to prolazi kroz isti skup i ista pravila.
Samo tri servisa smiju od usmjerivača tražiti ugradnje ili ponovno rangiranje: nexus-graphrag, nexus-skills-engine i nexus-workflows. GraphRAG izrađuje ugradnje u ime organizacije čiji je to sadržaj, s postavkama te organizacije, i ne drži vlastiti ključ pružatelja usluga. Kada organizacija promijeni svoj model za ugradnje, nexus-workflows pokreće posao ponovne ugradnje za spremišta te organizacije.
Osobne vjerodajnice ostaju osobne
Neke vjerodajnice pripadaju jednoj osobi. Pretplata na Claude Max, prijavljena putem vlastitog računa te osobe, uobičajen je slučaj. Takva vjerodajnica nikada nije organizacijski ključ: skup je odbija uz VALIDATION_FAILED, nikada se ne navodi u tablici ključeva organizacije i nijedan zaslon druge osobe je ne prikazuje.
Ključevi modela također nikada ne idu nikamo drugamo. Stranica Ključevi vanjskih podataka, koja drži ključeve za vanjske izvore podataka, odbija sve što izgleda kao ključ AI modela uz AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Ako čitač datoteka pronađe ključeve modela unutar dokumenta ili konfiguracije gdje ne pripadaju, bilježi CREDENTIALS_IN_WRONG_PLACE, a administrator ih uklanja i zamjenjuje.
Skripte, REST i MCP
Nexus ima tri javna poslužitelja. U organizaciji Harrow to su console.harrow.example za konzolu, api.harrow.example za pristupnik i auth.harrow.example za prijavu. Skripte i alati koriste drugi i treći.
Ključevi za skripte
Skripta se prijavljuje pomoću ključa izrađenog u Postavke, Ključevi za skripte. Svaki ključ ima naziv, doseg (na primjer, "Samo pokretanje brojanja dronovima u dvorištu"), osobu koja ga je izradila i datum završetka; organizacija može zaključati najdulji vijek trajanja koji ključ smije imati. Tajna se prikazuje jednom prilikom izrade ključa. Kopirajte je u spremište tajni skripte, jer Nexus čuva samo njezina posljednja četiri znaka. Ključ se povlači, nikada ne uklanja: odmah prestaje raditi i ostaje naveden sa svakim pozivom koji je uputio. Rotiranje daje ključu novu tajnu i prikazuje je jednom.
Svaki ključ ima vlastitu stranicu s pozivima po danu, pozivima po servisu i dnevnikom aktivnosti koji sadrži vrijeme, adresu, servis i rezultat. Poziv izvan dosega ključa se odbija i prikazuje u dnevniku.
nexus-auth poslužuje iste ključeve prijavljenoj osobi na https://auth.harrow.example/api-keys: izradite i izlistajte, a zatim očitajte, promijenite, opozovite ili rotirajte jedan ključ prema njegovom id-u.
REST putem pristupnika
Šaljite REST pozive na https://api.harrow.example uz Authorization: Bearer <token-or-key>. Svaki ključ mora pripadati organizaciji. Ključ koji ne pripada nijednoj odbija se uz TOKEN_ORG_MISSING (403) od strane svakog servisa koji provjerava ključeve putem servisa nexus-auth.
Pozivatelj koji postavlja zahtjeve prečesto dobiva odgovor 429 uz RATE_LIMITED, zaglavlje Retry-After, te ograničenje i vremenski prozor u tijelu poruke. Pričekajte onoliko sekundi koliko je navedeno. Na izdanju Enterprise, administratori postavljaju ograničenja po ključu, po aplikaciji i po jedinici u Postavke, Ograničenja brzine (pogledajte poglavlje 2.16, Sigurnost i umrežavanje).
MCP za AI alate
AI alati koji koriste Model Context Protocol povezuju se na https://api.harrow.example/mcp. Prijavljuju se putem poslužitelja OAuth 2.1 (OAuth je otvoreni standard za delegiranu autorizaciju) na https://auth.harrow.example, koji podržava registraciju klijenta od strane samog alata, tako da se alat kao što je Claude Code ili Cursor sam registrira i otvara preglednik osobe za prijavu. Veza tada djeluje u ime te jedne osobe, s pravima te osobe i ničim više. Prijavljena osoba može dohvatiti gotovu konfiguraciju za alat naredbenog retka s https://auth.harrow.example/api/v1/mcp/cli-config.
Pozivi alata kojima je potreban model prolaze kroz usmjerivač kao i sve ostalo, pod organizacijom te osobe.




