Versjon 1.0.0-alpha.1nyeste
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

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




