Verzija 1.0.0-alpha.1najnovije
Poglavlje 2.14
AI provajderi i modeli
Kako ruter dobavljača veštačke inteligencije (AI) bira model iz sopstvenog skupa ključeva organizacije i kako skripte i AI alatke pristupaju sistemu Nexus spolja.
Ovu stranicu je sa engleskog originala prevela AI tehnologija. Ako nešto nije jasno, merodavna je stranica na engleskom. Pročitajte ovu stranicu na engleskom

Harrow Port Authority ima dve instalacije. Ona na njegovoj izolovanoj operativnoj mreži (poglavlje 2.10, Instalacija u izolovanom okruženju) uopšte nema hostovanog dobavljača. Na povezanoj korporativnoj instalaciji, koju ovo poglavlje prati, na većinu pitanja odgovara model koji radi na dva čvora sa grafičkim procesorima (GPU) u sopstvenoj serverskoj sali luke. Google Gemini ključ, koji plaća Harrow, preuzima višak zahteva kada je lokalni model zauzet, a Aoife Brennan je ograničila saobraćaj veštačke inteligencije (AI) organizacije na EU. Niko u Harrow-u nije konfigurisao model unutar servisa ili dodatka. Jednoj komponenti su rekli šta Harrow poseduje, i ta komponenta odlučuje o svakom pozivu.
Ovo poglavlje obrađuje tu komponentu, AI Provider Router, koju Deo 1 i konzola nazivaju AI komutatorom, kao i skup ključeva iz kojeg ona crpi. Završava se načinima na koje skripte i AI alati pristupaju Nexus-u spolja: ključevima za skripte, REST (representational state transfer) interfejsom za programiranje aplikacija (API) i protokolom Model Context Protocol (MCP).
AI Provider Router
Ruter radi unutar mrežnog prolaza, nexus-gateway. To je jedini servis koji čuva akreditive modela organizacije i donosi konačnu odluku o tome koji dobavljač i koji model odgovaraju na svaki zahtev. Svi ostali delovi Nexus-a pitaju njega. Korak radnog toka kaže šta bi želeo, a ruter odlučuje.
Samo nekoliko servisa sme da pita, a svaku listu utvrđuje chart:
| Šta se traži | Ko sme da traži |
|---|---|
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 |
| Ugrađivanja (embeddings) i ponovno rangiranje | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Svaka interna ruta proverava dve stvari redom: interni servisni ključ pozivaoca i identitet pozivaoca prema gornjoj listi. Zahtev bez ključa odbija se sa MISSING_SERVICE_KEY (401), pogrešan ključ sa INVALID_SERVICE_KEY (403), zahtev koji ne navodi ko poziva sa MISSING_CALLER_IDENTITY (403), a pozivalac van liste sa UNAUTHORIZED_CALLER (403). Nijedan od njih se ne ponavlja, jer nijedan nije prolazna greška.
Aplikacije i dodaci se nikada ne pojavljuju na toj listi. Dodatak navodi svoje želje na veštinama koje registruje i šalje ih preko UNO-a, mehanizma radnih tokova. Orkestrator zatim pita ruter u ime dodatka. Zato jedna procurela tajna dodatka može da deluje kao taj dodatak, ali ne može da troši ničiji budžet za modele.
Fond ključeva organizacije
Ključevi modela pripadaju organizaciji. Svaka organizacija donosi sopstveni nalog kod dobavljača i plaća sopstveni račun, a ključ se čuva u skupu organizacije, šifrovan u nexus-auth. Iza organizacije ne postoji zajednički ključ platforme, tako da nijedna organizacija nikada ne troši budžet druge. Cena tog pravila je jasna: organizacija bez ključa u svom skupu ne dobija AI odgovore. Asistent prikazuje MODEL_NOT_CONNECTED (503) i navodi ko može da poveže ključ.
Ključ se može dodati u skup za četiri dobavljača:
| ID dobavljača | Prikazuje se kao |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Sopstveni server modela
Organizacija može da koristi i bilo koji server koji pokreće, a koji podržava API kompatibilan sa OpenAI, kao što je model na Harrow-ovim GPU čvorovima. Instalater ga navodi u datoteci vrednosti:
# 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 usmerava adapter mrežnog prolaza kompatibilan sa OpenAI na Vaš server. Na instalaciji, mesto scaleway u skupu dopire do tog servera, tako da je ključ koji dodate za scaleway onaj ključ koji Vaš sopstveni server očekuje.
ai.installationHosts navodi nazive hostova koji se nalaze unutar instalacije, pored sopstvenog servisnog domena izdanja i tri javna hosta. Svaka stavka je naziv hosta, .suffix, IP adresa ili IPv4 opseg u notaciji Classless Inter-Domain Routing (CIDR). Ruter koristi listu da razlikuje poziv koji ostaje na lokaciji od poziva koji je napušta, što je ono što prijavljuje provera „Ništa ne napušta ovu lokaciju“ na stranici Povežite model na sopstvenom hardveru.
Mrežna politika je podjednako važna kao i ruter. Namespace podrazumevano zabranjuje sav izlazni saobraćaj, tako da mrežni prolaz može da dosegne server modela izvan namespace-a samo kada je njegov opseg naveden u networkPolicy.externalEgressCIDRs. Isto važi i za hostovanog dobavljača: ako Harrow želi da njegov Gemini ključ odgovara, i opsezi adresa dobavljača moraju biti tamo navedeni, inače poziv nikada ne napušta klaster. Poglavlje 2.16, Bezbednost i umrežavanje, detaljno obrađuje ovu politiku.
Dodavanje i povlačenje ključeva
Vlasnici i administratori organizacije upravljaju njenim skupom. Niko drugi ne može da vidi ključeve niti da ih menja, a njihov zahtev se odbija sa AUTHORITY_EXCEEDED.
U konzoli
Na Enterprise izdanju skup se vodi u AI komutatoru, u okviru mehanizama. Na Community izdanju isti ključevi se vode u Podešavanja, AI modeli. Ta stranica je osnovni ruter, gde dodajete ključeve i adresu lokalnog modela i birate koji model obavlja koji posao. Obe prikazuju svaki ključ prema tome ko ga je postavio i kada („Postavila Aoife, 3. sept.“) i prema maskiranom nagoveštaju od najviše poslednja četiri znaka, kao što je ••••7f2q. Sam ključ se nakon dodavanja više nikada ne prikazuje.
Preko BFF API-ja
Pozadinski sloj konzole za prednji sloj (BFF) pruža tri rute za skup. Pozivajte ih sopstvenim pristupnim tokenom osobe: organizacija se određuje iz tokena, nikada iz zahteva.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET vraća dobavljače u skupu, da li svaki može da odgovara, svaki ključ prema njegovom nagoveštaju i dobavljače za koje se ključ može dodati. Dodavanje ključa zahteva JSON telo sa dva obavezna polja i jednim opcionim:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }Ključ se prenosi jednom. nexus-auth ga šifruje i obaveštava ruter, a odgovor sadrži samo nagoveštaj. Odgovor je 201 sa ID-jem novog ključa i njegovim redom: „Dodato. Google Gemini ključ ••••7f2q nalazi se u AI skupu organizacije i AI Provider Router sada može da usmerava na njega.“ Oznaka ima najviše 100 znakova, a ključ je jedan niz bez razmaka od najviše 4.096 znakova. Bilo koje drugo polje u telu, ili polje koje navodi organizaciju ili osobu, odbija se.
Povlačenje zahteva prazno telo. Ruter odmah prestaje da usmerava na ključ, a nexus-auth ga zadržava, naveden kao povučen, tako da njegova istorija ostaje. Ništa u skupu se nikada ne briše.
| Odbijanje | HTTP | Kada |
|---|---|---|
VALIDATION_FAILED |
400 | Telo koje nije {provider, api_key, label?}, nepoznat dobavljač ili lična pretplata osobe ponuđena kao ključ organizacije |
AUTHORITY_EXCEEDED |
403 | Pozivalac nije vlasnik ili administrator organizacije |
RECORD_NOT_FOUND |
404 | U skupu organizacije nema ključa sa tim ID-jem |
TRANSITION_NOT_PERMITTED |
409 | Ključ je već povučen |
TENANT_NOT_A_PARAMETER |
403 | Telo ili upit je naveo organizaciju |
Stanja ključeva
Svaki ključ u skupu nalazi se u jednom od šest stanja. Samo ključ u upotrebi odgovara na razgovor.
| Stanje | Šta znači |
|---|---|
in_use |
Ključ odgovara, do datuma isteka ako ga ima. |
resting |
Ruter ga je stavio u mirovanje nakon grešaka, do određenog vremena. Zahtevi u međuvremenu idu sledećem ključu. |
exhausted |
Iskoristio je svoje ograničenje kod dobavljača. |
invalid |
Dobavljač ga više ne prihvata. |
expired |
Istekao je na datum isteka. |
withdrawn |
Administrator ga je povukao. Ostaje naveden kao istorija. |
Ključ koji ne uspe miruje 60 sekundi. Nakon 5 uzastopnih grešaka ruter ga isključuje, prenosi njegov udeo na ostale ključeve i beleži obaveštenje PROVIDER_KEY_SWITCHED_OFF. Niko nije odbijen dok neki drugi ključ može da odgovori.
Kada dobavljač nema ključ u upotrebi, skup navodi razlog („Nema ključa u upotrebi: 1 povučen, 1 istekao“). Kada nijedan dobavljač u skupu nema ključ u upotrebi, razgovor se odbija sa NO_PROVIDER_FOR_ROLE (422) i rešenjem: vlasnik ili administrator dodaje ključ organizacije. To je stanje konfiguracije i ostaje na ekranu dok ga neko ne ispravi.
Uloge, politike i želje
Ruter razmišlja u ulogama. Svaki zahtev je za jednu od pet: default, fast, reasoning, code ili long_context. Svaki model je takođe u jednom nivou, frontier, standard ili fast, a viši nivo ima prednost kada uloga to dozvoljava. Organizacija odlučuje koji dobavljač opslužuje koju ulogu (njene dodele uloga) i redosled prelaska na rezervu kada dobavljač ne uspe (njena lestvica politike usmeravanja). Administratori podešavaju oboje u AI komutatoru. nexus-auth ih takođe pruža na /auth/org/<organisation-id>/settings/ai-provider/role-assignments i /auth/org/<organisation-id>/settings/ai-provider/routing-policy za administratorski ključ koji ima ai_provider:manage.
Pozivaoci mogu da navedu šta bi želeli. Red veštine može da sadrži željenog dobavljača i željeni model, kao i profil mogućnosti. Ruter svaki tretira drugačije:
- Željeni dobavljač se uvažava samo kada organizacija ima tog dobavljača omogućenog i ima ključ za njega. U suprotnom ruter vrši zamenu.
- Željeni model se uvažava kada se nalazi u katalogu tog dobavljača i odgovara profilu.
- Profil mogućnosti je filter koji nikada ne bira. Može da zahteva minimalni kontekstni prozor, korišćenje alata, vid, ugrađivanja, dugačak kontekst ili lokaciju čuvanja podataka. Ono što ga ne zadovolji nije prihvatljivo.
Ruter bira utvrđenim redosledom. Uvažava želju kada može, zatim pokušava drugi model istog dobavljača, zatim dodelu uloge i bilo kog drugog dobavljača sa ključem čiji katalog odgovara. Ako je profil zadat, a nijedan katalog mu ne odgovara, zahtev se odbija sa MODEL_CAPABILITY_UNAVAILABLE (422). Ako ništa nije dodeljeno i ništa ne odgovara, to je NO_PROVIDER_FOR_ROLE (422). Ne postoji podrazumevani model kao poslednje rešenje. Uloga koju niste konfigurisali ne uspeva jasno, a ruter sopstvenim rečima navodi šta treba podesiti.
Lokacija čuvanja podataka je jedino ograničenje koje se ne može zaobići zamenom. Profil sa eu_only opslužuje dobavljač iz EU ili se odbija. Harrow postavlja ovo zaključavanje za celu organizaciju, a komutator prikazuje drugog hostovanog dobavljača, koji se nalazi u američkom regionu, kao isključenog.
Veština može i da fiksira jedan tačno određen model kada joj je taj model potreban za rad. Čak i tada ruter za njega koristi sopstveni ključ organizacije, a bez njega ništa ne odgovara. Pozivalac nikada ne može da natera Nexus da koristi dobavljača kojeg organizacija nije konfigurisala.
Kada je dobavljač izabran, prelazak na rezervu je posebno pitanje. Greška 429, 5xx ili mrežna greška pomera zahtev niz lestvicu do sledećeg dobavljača. Greška 400, 401, 403 ili 404 se odmah zaustavlja, jer se akreditivi i oblici zahteva ne prenose između dobavljača, a ponovni pokušaj bi potrošio kvotu da bi došao do iste greške.
Da biste videli šta bi ruter izabrao pre nego što iko postavi pitanje, pročitajte GET /api/ai/routing-policy/effective na mrežnom prolazu sopstvenim tokenom osobe. Vraća model za prijavljenu organizaciju, ili odbijanje rutera rečima kada modela nema, i ne šalje nijedan zahtev modelu.
Nadgledanje rutera
Traka sa pokazateljima na dnu svake stranice prikazuje model u upotrebi („Model: lokalni“). Na Enterprise izdanju, AI komutator uživo prikazuje saobraćaj rutera u realnom vremenu: zahteve od asistenta, poslova i aplikacija koji teku kroz uloge do dobavljača i ključeva, ključ u svom 60-sekundnom mirovanju prikazan sivo, isključen ključ prikazan crveno i prelazak na hostovanog dobavljača kada je lokalni model zauzet. Pored toka prikazuje opterećenje po dobavljaču, broj zahteva u sekundi i vreme čekanja. Tomás ga drži otvorenim tokom prve nedelje nakon svake promene politike usmeravanja, jer se pogrešna dodela uloge tamo pojavi u roku od nekoliko minuta kao saobraćaj koji ide tamo gde niko nije nameravao.
Na Community izdanju, stranica AI modeli ima dugme Testiraj svaki model koje proverava svaki konfigurisani model i označava da li odgovara. To je najbrži način da potvrdite da novi ključ radi pre nego što se iko osloni na njega.
Vektorske reprezentacije (embeddings)
Pretraga i graf znanja pretvaraju tekst u vektore. Podrazumevano, instalacija to radi pomoću modela za ugrađivanje koji radi unutar klastera na procesoru, tako da nijedan tekst ne napušta lokaciju radi ugrađivanja i organizaciji za to nije potreban ključ. Korišćenje hostovanog dobavljača za ugrađivanja je izbor koji organizacija donosi; tada ono prolazi kroz isti skup i ista pravila.
Samo tri servisa mogu da traže od rutera ugrađivanja (embeddings) ili ponovno rangiranje: nexus-graphrag, nexus-skills-engine i nexus-workflows. GraphRAG ugrađuje sadržaj u ime organizacije kojoj taj sadržaj pripada, sa podešavanjima te organizacije, i nema sopstveni ključ dobavljača. Kada organizacija promeni svoj model za ugrađivanje, nexus-workflows pokreće posao ponovnog ugrađivanja za skladišta te organizacije.
Lični akreditivi pojedinca ostaju lični
Neki akreditivi pripadaju jednoj osobi. Pretplata Claude Max, prijavljena preko sopstvenog naloga te osobe, uobičajen je slučaj. Takav akreditiv nikada nije ključ organizacije: skup ga odbija sa VALIDATION_FAILED, nikada se ne navodi u tabeli ključeva organizacije i ne prikazuje ga nijedan ekran druge osobe.
Ključevi modela takođe nikada ne idu nigde drugde. Stranica Ključevi za spoljne podatke, koja sadrži ključeve za spoljne izvore podataka, odbija sve što liči na ključ AI modela sa AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Ako čitač datoteka pronađe ključeve modela unutar dokumenta ili konfiguracije gde im nije mesto, beleži CREDENTIALS_IN_WRONG_PLACE, a administrator ih uklanja i zamenjuje.
Skripte, REST i MCP
Nexus ima tri javna hosta. U Harrow to su console.harrow.example za konzolu, api.harrow.example za gateway i auth.harrow.example za prijavu. Skripte i alati koriste drugi i treći.
Ključevi za skripte
Skripta se prijavljuje ključem napravljenim u Podešavanja, Ključevi za skripte. Svaki ključ ima naziv, domet (na primer, „Samo pokretanje brojanja u Drone dvorištu”), osobu koja ga je napravila i datum isteka; organizacija može da ograniči najduži vek trajanja ključa. Tajna se prikazuje jednom, kada se ključ napravi. Kopirajte je u skladište tajni skripte, jer Nexus čuva samo njena poslednja četiri znaka. Ključ se povlači, nikada ne uklanja: odmah prestaje da radi i ostaje naveden sa svim pozivima koje je uputio. Rotacija daje ključu novu tajnu i prikazuje je jednom.
Svaki ključ ima sopstvenu stranicu sa pozivima po danu, pozivima po servisu i dnevnikom aktivnosti sa vremenom, adresom, servisom i rezultatom. Poziv izvan dometa ključa se odbija i prikazuje u dnevniku.
nexus-auth pruža iste ključeve prijavljenoj osobi na https://auth.harrow.example/api-keys: kreiranje i prikaz liste, a zatim čitanje, izmenu, opoziv ili rotaciju jednog ključa prema njegovom id.
REST preko gateway-a
Šaljite REST pozive na https://api.harrow.example sa Authorization: Bearer <token-or-key>. Svaki ključ mora pripadati nekoj organizaciji. Ključ bez organizacije odbija se sa TOKEN_ORG_MISSING (403) u svakom servisu koji proverava ključeve preko nexus-auth.
Pozivaocu koji šalje previše zahteva odgovara se sa 429 uz RATE_LIMITED, zaglavlje Retry-After i ograničenje i vremenski prozor u telu odgovora. Sačekajte broj sekundi koji je naveden. Na Enterprise planu administratori postavljaju ograničenja po ključu, po aplikaciji i po jedinici u Podešavanja, Ograničenja učestalosti (videti poglavlje 2.16, Bezbednost i umrežavanje).
MCP za AI alate
AI alati koji koriste Model Context Protocol povezuju se na https://api.harrow.example/mcp. Prijavljuju se preko OAuth 2.1 servera (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 registruje i otvara pregledač osobe radi prijave. Veza tada deluje u ime te jedne osobe, sa pravima te osobe i ničim više. Prijavljena osoba može da preuzme gotovu konfiguraciju za alat komandne linije sa https://auth.harrow.example/api/v1/mcp/cli-config.
Pozivi alata kojima je potreban model prolaze kroz ruter kao i sve ostalo, u okviru organizacije te osobe.




