PrijavaRezervirajte prezentaciju

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

16 min čitanja

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.

Lijevo: tri okvira složena jedan na drugi, "Asistent", "Korak tijeka rada", "Vještina", svaki sa strelicom koja vodi u okvir "UNO otprema (nexus-orchestrator)". Strelica označena s "želje: željeni pružatelj usluga, željeni model, profil sposobnosti" ide desno u veliki okvir "Usmjerivač pružatelja AI usluga (nexus-gateway)". Unutar okvira usmjerivača nalaze se tri mala okvira u nizu: "Uloga", "Skup organizacije", "Pravila usmjeravanja". Iz usmjerivača tri strelice idu desno prema "Lokalni model (ai.localProvider.baseUrl)", "Ključ hostiranog pružatelja usluga A", "Ključ hostiranog pružatelja usluga B". Ispod usmjerivača nalazi se zaseban okvir "nexus-auth: skup ključeva organizacije (šifrirano)" s isprekidanom strelicom prema gore u usmjerivač označenom s "ključevi, razriješeni po pozivu".
Kako zahtjev stiže do modela.

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

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

Povežite model na vlastitom hardveru
Povežite model na vlastitom hardveru
Povezivanje modela na vlastitom hardveru. Stranica navodi modele koje poslužitelj prijavljuje, ulogu koju svaki od njih ima te potvrđuje da ništa ne napušta lokaciju.

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.

AI centrala
AI centrala
AI centrala navodi svakog pružatelja usluga uz podatak o tome tko je postavio njegov ključ i koje poslove obavlja. Jedan ključ miruje nakon pogrešaka, drugi je isključen, a stranica navodi kamo podaci smiju ići.
AI modeli
AI modeli
Osnovni usmjerivač u izdanju Community: ključ organizacije, lokalni model na vlastitom stroju organizacije i koji model obavlja koji posao.

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.

AI centrala, uživo
AI centrala, uživo
Usmjerivač uživo. Promet teče od asistenta i poslova kroz uloge do lokalnog modela i hostiranih ključeva; jedan ključ miruje, jedan je isključen, a zlatne točkice pokazuju prebacivanje na pričuvu dok je lokalni model zauzet.

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.

Jedan ključ za skripte
Jedan ključ za skripte
Jedan ključ za skripte. Stranica prikazuje doseg ključa, tko ga je izradio, njegov datum završetka, pozive po danu i po servisu te rezultat svakog poziva; tajna završava s …7QK2 i nikada se više ne prikazuje.

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.