PrijavaZakažite brifing

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

16 min čitanja

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.

Levo: tri okvira jedan iznad drugog, „Asistent”, „Korak toka rada”, „Veština”, svaki sa strelicom ka okviru „UNO dispatch (nexus-orchestrator)”. Strelica sa oznakom „želje: željeni dobavljač, željeni model, profil mogućnosti” vodi desno ka velikom okviru „AI Provider Router (nexus-gateway)”. Unutar okvira rutera, tri mala okvira u nizu: „Uloga”, „Skup organizacije”, „Politika rutiranja”. Od rutera tri strelice vode desno ka „Lokalni model (ai.localProvider.baseUrl)”, „Ključ hostovanog dobavljača A”, „Ključ hostovanog dobavljača B”. Ispod rutera nalazi se zaseban okvir „nexus-auth: skup ključeva organizacije (šifrovan)” sa isprekidanom strelicom nagore ka ruteru, sa oznakom „ključevi, razrešeni po pozivu”.
Kako zahtev stiže do modela.

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/24

ai.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.

Povežite model na sopstvenom hardveru
Povežite model na sopstvenom hardveru
Povezivanje modela na sopstvenom hardveru. Stranica navodi modele koje server prijavljuje, ulogu koju svaki ima, i potvrđuje da ništa ne napušta lokaciju.

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.

AI centrala
AI centrala
AI komutator navodi svakog dobavljača sa podatkom ko je postavio njegov ključ i koje poslove obavlja. Jedan ključ miruje nakon grešaka, drugi je isključen, a stranica navodi gde podaci smeju da idu.
AI modeli
AI modeli
Osnovni ruter na Community izdanju: ključ organizacije, lokalni model na sopstvenoj mašini organizacije i koji model obavlja koji posao.

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.

AI komutator, uživo
AI komutator, uživo
Ruter uživo. Saobraćaj teče od asistenta i poslova kroz uloge do lokalnog modela i hostovanih ključeva; jedan ključ miruje, jedan je isključen, a zlatne tačke prikazuju prelazak na rezervu dok je lokalni model zauzet.

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.

Jedan ključ za skripte
Jedan ključ za skripte
Jedan ključ za skripte. Stranica prikazuje domet ključa, ko ga je napravio, datum isteka, pozive po danu i po servisu, kao i rezultat svakog poziva; tajna se završava sa …7QK2 i više se nikada ne prikazuje.

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.