Logg innBestill en gjennomgang

Kapittel 2.14

KI-leverandører og modeller

Hvordan leverandørruteren for kunstig intelligens (KI) velger en modell fra organisasjonens egen nøkkelpulje, og hvordan skript og KI-verktøy når Nexus utenfra.

Denne siden er oversatt med KI fra den engelske originalen. Hvis noe er uklart, er den engelske siden referansen. Les denne siden på engelsk

16 minutter å lese

Harrow Port Authority kjører to installasjoner. Den på det luftgap-sikrede driftsnettverket (kapittel 2.10, Luftgap-sikret installasjon) har ingen ekstern leverandør i det hele tatt. På den tilkoblede bedriftsinstallasjonen, som dette kapittelet følger, besvares de fleste spørsmål av en modell som kjører på to GPU-noder (grafikkprosessorer) i havnens eget serverrom. En nøkkel for Google Gemini, betalt av Harrow, tar unna overskuddet når den lokale modellen er opptatt, og Aoife Brennan har låst organisasjonens trafikk for kunstig intelligens (KI) til EU. Ingen hos Harrow har konfigurert en modell inne i en tjeneste eller et programtillegg. De har fortalt én komponent hva Harrow eier, og denne komponenten avgjør hvert eneste kall.

Dette kapittelet tar for seg denne komponenten, AI Provider Router, som del 1 og konsollen kaller KI-sentralbordet, samt puljen av nøkler den henter fra. Kapittelet avsluttes med måtene skript og KI-verktøy når Nexus på utenfra: nøkler for skript, programmeringsgrensesnittet (API) for REST (representational state transfer) og Model Context Protocol (MCP).

AI Provider Router

Ruteren kjører inne i gatewayen, nexus-gateway. Det er den eneste tjenesten som sitter på en organisasjons modell-legitimasjon, og den tar den endelige avgjørelsen om hvilken leverandør og hvilken modell som skal besvare hver forespørsel. Alle andre deler av Nexus spør denne. Et trinn i en arbeidsflyt sier hva det ønsker, og ruteren bestemmer.

Kun noen få tjenester får lov til å spørre, og hver liste er fastsatt av chartet:

Hva det spørres om Hvem som kan spørre
En fullføring (/internal/ai/chat og dens strøm) nexus-orchestrator, nexus-workflows, nexus-skills-engine
Verktøykall og de andre interne KI-rutene nexus-orchestrator, nexus-workflows
Innebygginger (embeddings) og omrangering (reranking) nexus-graphrag, nexus-skills-engine, nexus-workflows

Hver interne rute kontrollerer to ting etter tur: den som ringer sin interne tjenestenøkkel, og identiteten til den som ringer opp mot listen ovenfor. En forespørsel uten nøkkelen avvises med MISSING_SERVICE_KEY (401), en feil nøkkel med INVALID_SERVICE_KEY (403), en forespørsel som ikke oppgir hvem som ringer med MISSING_CALLER_IDENTITY (403), og en anroper utenfor listen med UNAUTHORIZED_CALLER (403). Ingen av disse forsøkes på nytt, fordi ingen av dem er en forbigående feil.

Apper og programtillegg står aldri på den listen. Et programtillegg erklærer sine ønsker på ferdighetene det registrerer, og sender dem gjennom UNO, arbeidsflytmotoren. Orkestratoren spør deretter ruteren på vegne av programtillegget. Dette er grunnen til at en lekket hemmelighet fra et programtillegg kan opptre som det programtillegget, men ikke kan bruke opp noens modellbudsjett.

Til venstre: tre bokser stablet, «Assistent», «Arbeidsflyttrinn», «Ferdighet», hver med en pil inn i en boks «UNO-utsendelse (nexus-orchestrator)». En pil merket «ønsker: foretrukket leverandør, foretrukket modell, kapasitetsprofil» går til høyre inn i en stor boks «AI Provider Router (nexus-gateway)». Inne i ruterboksen er det tre små bokser på rad: «Rolle», «Organisasjonspulje», «Rutingspolicy». Fra ruteren går tre piler til høyre til «Lokal modell (ai.localProvider.baseUrl)», «Ekstern leverandørnøkkel A», «Ekstern leverandørnøkkel B». Under ruteren er det en egen boks «nexus-auth: organisasjonens nøkkelpulje (kryptert)» med en stiplet pil opp inn i ruteren merket «nøkler, løst per kall».
Hvordan en forespørsel når en modell.

Organisasjonens nøkkelpulje

Modellnøkler tilhører organisasjonen. Hver organisasjon tar med sin egen leverandørkonto og betaler sin egen regning, og nøkkelen ligger i organisasjonens pulje, kryptert i nexus-auth. Det finnes ingen delt plattformnøkkel bak en organisasjon, så ingen organisasjon bruker noen gang en annens budsjett. Kostnaden ved denne regelen er enkel: En organisasjon uten nøkkel i puljen sin får ingen KI-svar. Assistenten viser MODEL_NOT_CONNECTED (503) og forteller hvem som kan koble til en.

En nøkkel kan legges til i puljen for fire leverandører:

Leverandør-ID Vises som
anthropic_api_key Anthropic
gemini Google Gemini
openrouter OpenRouter
scaleway Scaleway

En egen modellserver

En organisasjon kan også bruke en hvilken som helst server den selv drifter som snakker det OpenAI-kompatible API-et, slik som modellen på Harrows GPU-noder. Installasjonsprogrammet navngir den i verdifilen (values-filen):

# 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 peker gatewayens OpenAI-kompatible adapter mot serveren din. På en installasjon når puljens scaleway-plass den serveren, så nøkkelen du legger til for scaleway, er nøkkelen din egen server forventer.

ai.installationHosts lister opp vertsnavn som befinner seg inne i installasjonen, i tillegg til utgivelsens eget tjenestedomene og de tre offentlige vertene. Hver oppføring er et vertsnavn, en .suffix, en IP-adresse eller et IPv4 CIDR-område (Classless Inter-Domain Routing). Ruteren bruker listen til å skille et kall som forblir lokalt fra et som forlater stedet, og det er dette kontrollen «Ingenting forlater dette stedet» på siden Koble til en modell på egen maskinvare rapporterer.

Nettverkspolicyen er like viktig som ruteren. Navnerommet (namespace) nekter som standard all utgående trafikk (egress), så gatewayen kan kun nå en modellserver utenfor navnerommet når adresseområdet dens ligger i networkPolicy.externalEgressCIDRs. Det samme gjelder for en ekstern leverandør: Hvis Harrow vil at Gemini-nøkkelen deres skal svare, må leverandørens adresseområder også føres opp der, ellers forlater kallet aldri klyngen. Kapittel 2.16, Sikkerhet og nettverk, dekker policyen i sin helhet.

Koble til en modell på egen maskinvare
Koble til en modell på egen maskinvare
Tilkobling av en modell på egen maskinvare. Siden lister opp modellene serveren rapporterer, rollen hver enkelt spiller, og bekrefter at ingenting forlater stedet.

Legge til og trekke tilbake nøkler

Eiere og administratorer i en organisasjon forvalter puljen dens. Ingen andre kan se nøklene eller endre dem, og en forespørsel fra dem avvises med AUTHORITY_EXCEEDED.

I konsollen

På Enterprise holdes puljen i KI-sentralbordet, under motorene. På Community ligger de samme nøklene under Innstillinger, KI-modeller. Den siden er den grunnleggende ruteren, der du legger til nøkler og en lokal modelladresse, og velger hvilken modell som gjør hvilken jobb. Begge viser hver nøkkel med hvem som la den inn og når («Satt av Aoife, 3. sept.») og med et maskert hint på maksimalt de siste fire tegnene, slik som ••••7f2q. Selve nøkkelen vises aldri igjen etter at du har lagt den til.

KI-sentralbordet
KI-sentralbordet
KI-sentralbordet lister opp hver leverandør med hvem som la inn nøkkelen og hvilke jobber den utfører. Én nøkkel hviler etter feil, en annen er slått av, og siden viser hvor data kan sendes.
KI-modeller
KI-modeller
Den grunnleggende ruteren på Community: en organisasjonsnøkkel, en lokal modell på organisasjonens egen maskin, og hvilken modell som gjør hvilken jobb.

Gjennom BFF API-et

Konsollens backend for frontend (BFF) betjener tre ruter for puljen. Kall dem med en persons eget tilgangstoken: organisasjonen hentes fra tokenet, aldri fra forespørselen.

GET  /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw

GET returnerer leverandørene i puljen, hvorvidt hver enkelt kan svare, hver nøkkel ved hjelp av hintet sitt, og hvilke leverandører det kan legges til en nøkkel for. Å legge til en nøkkel krever en JSON-kropp med to obligatoriske felt og ett valgfritt:

{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }

Nøkkelen sendes kun én gang. nexus-auth krypterer den og varsler ruteren, og svaret inneholder kun hintet. Svaret er 201 med den nye nøkkelens ID og raden dens: «Lagt til. Google Gemini-nøkkelen ••••7f2q ligger i organisasjonens KI-pulje, og AI Provider Router kan rute til den nå.» En etikett er på maksimalt 100 tegn, og en nøkkel er én streng uten mellomrom på maksimalt 4 096 tegn. Ethvert annet felt i kroppen, eller et felt som navngir en organisasjon eller en person, blir avvist.

Tilbaketrekking krever en tom kropp. Ruteren slutter umiddelbart å rute til nøkkelen, og nexus-auth beholder den, oppført som trukket tilbake, slik at historikken bevares. Ingenting i puljen slettes noen gang.

Avvisning HTTP Når
VALIDATION_FAILED 400 En kropp som ikke er {provider, api_key, label?}, en ukjent leverandør, eller en persons eget abonnement tilbudt som en organisasjonsnøkkel
AUTHORITY_EXCEEDED 403 Anroperen er ikke en eier eller administrator i organisasjonen
RECORD_NOT_FOUND 404 Ingen nøkkel med den ID-en finnes i organisasjonens pulje
TRANSITION_NOT_PERMITTED 409 Nøkkelen er allerede trukket tilbake
TENANT_NOT_A_PARAMETER 403 Kroppen eller spørringen navnga en organisasjon

Nøkkeltilstander

Hver nøkkel i puljen er i én av seks tilstander. Kun en nøkkel som er i bruk, besvarer en samtale.

Tilstand Hva det betyr
in_use Nøkkelen svarer, frem til utløpsdatoen hvis den har en.
resting Ruteren lot den hvile etter feil, frem til et fastsatt tidspunkt. Forespørsler går til neste nøkkel i mellomtiden.
exhausted Den har brukt opp kvoten sin hos leverandøren.
invalid Leverandøren godtar den ikke lenger.
expired Den utløp på utløpsdatoen sin.
withdrawn En administrator trakk den tilbake. Den blir stående oppført som historikk.

En nøkkel som feiler, hviler i 60 sekunder. Etter 5 feil på rad slår ruteren den av, flytter andelen dens til de andre nøklene, og registrerer varselet PROVIDER_KEY_SWITCHED_OFF. Ingen blir avvist så lenge en annen nøkkel kan svare.

Når en leverandør ikke har noen nøkkel i bruk, oppgir puljen hvorfor («Ingen nøkkel i bruk: 1 trukket tilbake, 1 utløpt»). Når ingen leverandør i puljen har en nøkkel i bruk, avvises en samtale med NO_PROVIDER_FOR_ROLE (422) og løsningen: en eier eller administrator legger til en organisasjonsnøkkel. Dette er en konfigurasjonstilstand, og den blir stående på skjermen til noen retter den.

Roller, retningslinjer og ønsker

Ruteren tenker i roller. Hver forespørsel gjelder én av fem: default, fast, reasoning, code eller long_context. Hver modell tilhører også et nivå, frontier, standard eller fast, og et høyere nivå foretrekkes når rollen tillater det. Organisasjonen bestemmer hvilken leverandør som betjener hver rolle (rolletildelingene), og rekkefølgen det skal falles tilbake i når en leverandør feiler (rutingspolicy-stigen). Administratorer angir begge deler i KI-sentralbordet. nexus-auth betjener dem også på /auth/org/<organisation-id>/settings/ai-provider/role-assignments og /auth/org/<organisation-id>/settings/ai-provider/routing-policy for en administratornøkkel som har ai_provider:manage.

Anropere kan si hva de ønsker seg. En ferdighetsrad kan inneholde en foretrukket leverandør og en foretrukket modell, pluss en kapasitetsprofil. Ruteren behandler hver av disse ulikt:

  • En foretrukket leverandør innfris kun når organisasjonen har aktivert den aktuelle leverandøren og har en nøkkel for den. Ellers velger ruteren en erstatning.
  • En foretrukket modell innfris når den finnes i leverandørens katalog og passer til profilen.
  • En kapasitetsprofil er et filter som aldri velger. Den kan be om et minimum kontekstvindu, verktøybruk, syn (vision), innebygginger (embeddings), lang kontekst eller datalagringstilhørighet (data residency). Alt som ikke oppfyller kravene, er ikke kvalifisert.

Ruteren velger i en fast rekkefølge. Den innfrir ønsket når den kan, prøver deretter en annen modell fra samme leverandør, deretter rolletildelingen og enhver annen leverandør med en nøkkel hvis katalog passer. Hvis en profil ble oppgitt og ingen katalog passer til den, avvises forespørselen med MODEL_CAPABILITY_UNAVAILABLE (422). Hvis ingenting er tildelt og ingenting samsvarer, blir det NO_PROVIDER_FOR_ROLE (422). Det finnes ingen standardmodell som siste utvei. En rolle du ikke har konfigurert, feiler tydelig, der ruterens egne ord forteller hva som må angis.

Datalagringstilhørighet er den eneste begrensningen som ikke kan omgås ved å velge en erstatning. En profil med eu_only betjenes av en EU-leverandør eller blir avvist. Harrow setter denne låsen for hele organisasjonen, og sentralbordet viser den andre eksterne leverandøren, som ligger i en amerikansk region, som avslått.

En ferdighet kan også låse seg til én nøyaktig modell når ferdigheten trenger akkurat den modellen for å fungere. Selv da bruker ruteren organisasjonens egen nøkkel for den, og uten en nøkkel er det ingenting som svarer. En anroper kan aldri få Nexus til å bruke en leverandør som organisasjonen ikke har konfigurert.

Når en leverandør først er valgt, er feilhåndtering (failover) en egen sak. En 429, en 5xx eller en nettverksfeil flytter forespørselen nedover stigen til neste leverandør. En 400, 401, 403 eller 404 stopper umiddelbart, fordi legitimasjon og forespørselsformater ikke kan overføres mellom leverandører, og et nytt forsøk ville brent av kvoten for å ende opp med samme feil.

For å se hva ruteren ville valgt før noen stiller et spørsmål, kan du lese GET /api/ai/routing-policy/effective på gatewayen med en persons eget token. Den returnerer modellen for den påloggede organisasjonen, eller ruterens avvisning med ord når det ikke finnes noen, og den sender ingen forespørsel til en modell.

Overvåke ruteren

Tallraden nederst på hver side viser hvilken modell som er i bruk («Modell: lokal»). På Enterprise tegner KI-sentralbordet, direkte opp ruterens trafikk etter hvert som den skjer: forespørsler fra assistenten, jobber og apper som flyter gjennom roller til leverandører og nøkler, en nøkkel i sin 60-sekunders hvile tegnet i grått, en avslått nøkkel tegnet i rødt, og en reserveløsning (fallback) til den eksterne leverandøren når den lokale modellen er opptatt. Ved siden av flyten vises belastning per leverandør, forespørsler per sekund og ventetid. Tomás holder den åpen den første uken etter enhver endring i rutingspolicyen, fordi en feil rolletildeling dukker opp der i løpet av minutter som trafikk som går et sted ingen hadde tenkt at den skulle.

På Community har siden KI-modeller en knapp kalt Test hver modell som sjekker hver konfigurerte modell og markerer hvorvidt den svarer. Det er den raskeste måten å bevise at en ny nøkkel fungerer på, før noen gjør seg avhengig av den.

KI-sentralbordet, direkte
KI-sentralbordet, direkte
Ruteren i sanntid. Trafikken flyter fra assistenten og jobber gjennom roller til en lokal modell og eksterne nøkler; én nøkkel hviler, én er slått av, og gullprikker viser at reserveløsningen brukes mens den lokale modellen er opptatt.

Innebygginger

Søk og kunnskapsgrafen gjør tekst om til vektorer. Som standard gjør installasjonen dette med en innebyggingsmodell (embedding-modell) som kjører inne i klyngen på prosessoren, slik at ingen tekst forlater stedet for å bli innebygd, og en organisasjon trenger ingen nøkkel for det. Å bruke en ekstern leverandør for innebygginger er et valg en organisasjon selv tar; det går da gjennom den samme puljen og de samme reglene.

Kun tre tjenester kan be ruteren om innebygginger eller omrangering: nexus-graphrag, nexus-skills-engine og nexus-workflows. GraphRAG bygger inn som den organisasjonen som eier innholdet, med denne organisasjonens innstillinger, og sitter ikke på noen egen leverandørnøkkel. Når en organisasjon endrer innebyggingsmodellen sin, kjører nexus-workflows jobben for ny innebygging for denne organisasjonens lagre.

Personlige påloggingsdetaljer forblir personlige

Noe legitimasjon tilhører én enkelt person. Et Claude Max-abonnement, logget inn via denne personens egen konto, er det vanligste tilfellet. Slik legitimasjon er aldri en organisasjonsnøkkel: puljen avviser den med VALIDATION_FAILED, den føres aldri opp i organisasjonens nøkkeltabell, og ingen skjerm hos en annen person viser den.

Modellnøkler havner heller aldri andre steder. Siden Nøkler for eksterne data, som inneholder nøkler for eksterne datakilder, avviser alt som ser ut som en KI-modellnøkkel med AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Hvis filleseren finner modellnøkler inne i et dokument eller en konfigurasjon der de ikke hører hjemme, registrerer den CREDENTIALS_IN_WRONG_PLACE, og en administrator fjerner dem og erstatter dem.

Skript, REST og MCP

Nexus har tre offentlige verter. Hos Harrow er de console.harrow.example for konsollen, api.harrow.example for gatewayen og auth.harrow.example for pålogging. Skript og verktøy bruker den andre og den tredje.

Nøkler for skript

Et skript logger på med en nøkkel opprettet under Innstillinger, Nøkler for skript. Hver nøkkel har et navn, en rekkevidde (for eksempel «Kun start av dronetelling på området»), personen som opprettet den, og en sluttdato; en organisasjon kan låse den lengste levetiden en nøkkel kan ha. Hemmeligheten vises én gang når nøkkelen opprettes. Kopier den inn i skriptets hemmelighetslager, for Nexus beholder kun de siste fire tegnene. En nøkkel trekkes tilbake, den fjernes aldri: den slutter å virke umiddelbart og blir stående oppført med hvert kall den har utført. Rotering gir nøkkelen en ny hemmelighet og viser den én gang.

Hver nøkkel har sin egen side med kall per dag, kall per tjeneste og en aktivitetslogg med tidspunkt, adresse, tjeneste og resultat. Et kall utenfor nøkkelens rekkevidde avvises og vises i loggen.

nexus-auth betjener de samme nøklene til en pålogget person på https://auth.harrow.example/api-keys: opprett og list opp, og deretter les, endre, tilbakekall eller roter én nøkkel ved hjelp av ID-en dens.

Én nøkkel for skript
Én nøkkel for skript
Én nøkkel for skript. Siden viser nøkkelens rekkevidde, hvem som opprettet den, sluttdatoen, kall per dag og per tjeneste, samt resultatet av hvert kall; hemmeligheten slutter på …7QK2 og vises aldri igjen.

REST gjennom gatewayen

Send REST-kall til https://api.harrow.example med Authorization: Bearer <token-or-key>. Hver nøkkel må tilhøre en organisasjon. En nøkkel uten tilhørighet avvises med TOKEN_ORG_MISSING (403) av hver tjeneste som kontrollerer nøkler gjennom nexus-auth.

En anroper som spør for ofte, får svaret 429 med RATE_LIMITED, en Retry-After-topptekst (header), samt grensen og tidsvinduet i kroppen. Vent det antallet sekunder den oppgir. På Enterprise angir administratorer grenser per nøkkel, per app og per enhet under Innstillinger, Frekvensgrenser (se kapittel 2.16, Sikkerhet og nettverk).

MCP for KI-verktøy

KI-verktøy som snakker Model Context Protocol, kobler til https://api.harrow.example/mcp. De logger på gjennom OAuth 2.1-serveren (OAuth er den åpne standarden for delegert autorisasjon) på https://auth.harrow.example, som støtter klientregistrering utført av selve verktøyet, slik at et verktøy som Claude Code eller Cursor registrerer seg selv og åpner personens nettleser for pålogging. Tilkoblingen handler deretter på vegne av denne ene personen, med denne personens rettigheter og ingenting mer. En pålogget person kan hente en ferdiglaget konfigurasjon for et kommandolinjeverktøy fra https://auth.harrow.example/api/v1/mcp/cli-config.

Verktøykall som trenger en modell, går gjennom ruteren som alt annet, under personens organisasjon.