Version 1.0.0-alpha.1seneste
Kapitel 2.14
AI-udbydere og modeller
Hvordan udbyderrouteren til kunstig intelligens (AI) vælger en model fra organisationens egen pulje af nøgler, og hvordan scripts og AI-værktøjer tilgår Nexus udefra.
Denne side er oversat af AI fra den engelske original. Hvis noget er uklart, er den engelske side gældende. Læs denne side på engelsk

Harrow Port Authority driver to installationer. Den på deres air-gappede driftsnetværk (kapitel 2.10, Air-gapped installation) har slet ingen hostet udbyder. På den tilsluttede virksomhedsinstallation, som dette kapitel følger, besvares de fleste spørgsmål af en model, der kører på to grafikprocessornoder (GPU) i havnens eget serverrum. En Google Gemini-nøgle, som Harrow betaler for, tager spidsbelastningen, når den lokale model har travlt, og Aoife Brennan har låst organisationens trafik for kunstig intelligens (AI) til EU. Ingen hos Harrow har konfigureret en model inde i en tjeneste eller et plugin. De fortalte én komponent, hvad Harrow ejer, og den komponent afgør hvert enkelt kald.
Dette kapitel gennemgår den komponent, AI Provider Router, som del 1 og konsollen kalder AI-omstillingsbordet, samt den pulje af nøgler, den trækker på. Det slutter med de måder, hvorpå scripts og AI-værktøjer når Nexus udefra: nøgler til scripts, REST-API'et (representational state transfer application programming interface) og Model Context Protocol (MCP).
AI Provider Router
Routeren kører inde i gatewayen, nexus-gateway. Det er den eneste tjeneste, der opbevarer en organisations modellegitimationsoplysninger, og den træffer den endelige beslutning om, hvilken udbyder og hvilken model der besvarer hver forespørgsel. Alle andre dele af Nexus spørger den. Et workflow-trin angiver, hvad det ønsker, og routeren bestemmer.
Kun få tjenester må spørge, og hver liste er fastlagt af chartet:
| Hvad der spørges om | Hvem der må spørge |
|---|---|
En færdiggørelse (/internal/ai/chat og dens stream) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Værktøjskald og de øvrige interne AI-ruter | nexus-orchestrator, nexus-workflows |
| Indlejringer (embeddings) og omrangering (reranking) | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Hver intern rute kontrollerer to ting efter hinanden: kalderens interne tjenestenøgle og kalderens identitet op imod listen ovenfor. En forespørgsel uden nøglen afvises med MISSING_SERVICE_KEY (401), en forkert nøgle med INVALID_SERVICE_KEY (403), en forespørgsel, der ikke angiver, hvem der kalder, med MISSING_CALLER_IDENTITY (403), og en kalder uden for listen med UNAUTHORIZED_CALLER (403). Ingen af disse forsøges igen, fordi ingen af dem er en forbigående fejl.
Apps og plugins optræder aldrig på den liste. Et plugin erklærer sine ønsker på de færdigheder (skills), det registrerer, og sender dem via UNO, workflow-motoren. Orkestratoren spørger derefter routeren på pluginets vegne. Det er grunden til, at én lækket plugin-hemmelighed nok kan optræde som det pågældende plugin, men ikke kan bruge nogens modelbudget.
Organisationens pulje af nøgler
Modelnøgler tilhører organisationen. Hver organisation medbringer sin egen udbyderkonto og betaler sin egen regning, og nøglen ligger i organisationens pulje, krypteret i nexus-auth. Der ligger ingen delt platformsnøgle bag en organisation, så ingen organisation bruger nogensinde en andens budget. Prisen for den regel er ligetil: En organisation uden en nøgle i sin pulje får ingen AI-svar. Assistenten viser MODEL_NOT_CONNECTED (503) og oplyser, hvem der kan tilknytte en.
En nøgle kan føjes til puljen for fire udbydere:
| Udbyder-id | Vises som |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
En modelserver, De selv driver
En organisation kan også bruge enhver server, den selv driver, som taler det OpenAI-kompatible API, såsom modellen på Harrows GPU-noder. Installatøren navngiver den i 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 peger gatewayens OpenAI-kompatible adapter mod Deres server. På en installation når puljens scaleway-plads frem til den pågældende server, så den nøgle, De tilføjer for scaleway, er den nøgle, Deres egen server forventer.
ai.installationHosts angiver værtsnavne, der befinder sig inden for installationen, ud over udgivelsens eget tjenestedomæne og de tre offentlige værter. Hver post er et værtsnavn, et .suffix, en IP-adresse eller et IPv4 Classless Inter-Domain Routing-interval (CIDR). Routeren bruger listen til at skelne et kald, der forbliver på stedet, fra et, der forlader det, hvilket er det, kontrollen "Nothing leaves this site" på siden Tilslut en model på egen hardware rapporterer.
Netværkspolitikken er lige så vigtig som routeren. Namespacet afviser som standard al udgående trafik (egress), så gatewayen kan kun nå en modelserver uden for namespacet, når dens interval står i networkPolicy.externalEgressCIDRs. Det samme gælder for en hostet udbyder: Hvis Harrow ønsker, at deres Gemini-nøgle skal svare, skal udbyderens adresseintervaller også være opført der, ellers forlader kaldet aldrig klyngen. Kapitel 2.16, Sikkerhed og netværk, beskriver politikken i sin helhed.
Tilføjelse og tilbagekaldelse af nøgler
Ejere og administratorer af en organisation vedligeholder dens pulje. Andre kan hverken se nøglerne eller ændre dem, og en forespørgsel fra dem afvises med AUTHORITY_EXCEEDED.
I konsollen
På Enterprise opbevares puljen i AI-omstillingsbordet under motorerne. På Community opbevares de samme nøgler under Indstillinger, AI-modeller. Den side er den grundlæggende router, hvor De tilføjer nøgler og en lokal modeladresse og vælger, hvilken model der udfører hvilken opgave. Begge viser hver nøgle med angivelse af, hvem der har indstillet den og hvornår ("Set by Aoife, 3 Sept"), samt et maskeret fingerpeg med højst de sidste fire tegn, såsom ••••7f2q. Selve nøglen vises aldrig igen, efter at De har tilføjet den.
Gennem BFF-API'et
Konsollens backend for frontend (BFF) betjener tre ruter for puljen. Kald dem med en persons eget adgangstoken: Organisationen kommer fra tokenet, aldrig fra forespørgslen.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET returnerer udbyderne i puljen, hvorvidt hver enkelt kan svare, hver nøgle ved dens fingerpeg og de udbydere, der kan tilføjes en nøgle for. Tilføjelse af en nøgle kræver en JSON-body med to påkrævede felter og ét valgfrit:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }Nøglen sendes én gang. nexus-auth krypterer den og giver routeren besked, og svaret indeholder kun fingerpeget. Svaret er 201 med den nye nøgles id og dens række: "Added. The Google Gemini key ••••7f2q is in the organisation's AI pool, and the AI Provider Router can route to it now." En mærkat er på højst 100 tegn, og en nøgle er én streng uden mellemrum på højst 4.096 tegn. Ethvert andet felt i bodyen, eller et felt, der nævner en organisation eller en person, afvises.
Tilbagetrækning kræver en tom body. Routeren stopper straks med at dirigere til nøglen, og nexus-auth beholder den, opført som trukket tilbage, så dens historik bevares. Intet i puljen slettes nogensinde.
| Afvisning | HTTP | Hvornår |
|---|---|---|
VALIDATION_FAILED |
400 | En body, der ikke er {provider, api_key, label?}, en ukendt udbyder eller en persons eget abonnement tilbudt som en organisationsnøgle |
AUTHORITY_EXCEEDED |
403 | Kalderen er ikke ejer eller administrator af organisationen |
RECORD_NOT_FOUND |
404 | Der er ingen nøgle med det id i organisationens pulje |
TRANSITION_NOT_PERMITTED |
409 | Nøglen er allerede trukket tilbage |
TENANT_NOT_A_PARAMETER |
403 | Bodyen eller forespørgslen nævnte en organisation |
Nøgletilstande
Hver nøgle i puljen befinder sig i en af seks tilstande. Kun en nøgle i brug besvarer en chat.
| Tilstand | Hvad det betyder |
|---|---|
in_use |
Nøglen svarer indtil sin udløbsdato, hvis den har en. |
resting |
Routeren satte den på pause efter fejl indtil et fastsat tidspunkt. Forespørgsler går i mellemtiden til den næste nøgle. |
exhausted |
Den har opbrugt sin grænse hos udbyderen. |
invalid |
Udbyderen accepterer den ikke længere. |
expired |
Den udløb på sin udløbsdato. |
withdrawn |
En administrator trak den tilbage. Den forbliver opført som historik. |
En nøgle, der fejler, hviler i 60 sekunder. Efter 5 fejl i træk slår routeren den fra, flytter dens andel til de andre nøgler og registrerer meddelelsen PROVIDER_KEY_SWITCHED_OFF. Ingen afvises, så længe en anden nøgle kan svare.
Når en udbyder ikke har nogen nøgle i brug, oplyser puljen årsagen ("No key in use: 1 withdrawn, 1 lapsed"). Når ingen udbyder i puljen har en nøgle i brug, afvises en chat med NO_PROVIDER_FOR_ROLE (422) samt løsningen: En ejer eller administrator tilføjer en organisationsnøgle. Det er en konfigurationstilstand, og den bliver stående på skærmen, indtil nogen retter den.
Roller, politik og ønsker
Routeren tænker i roller. Hver forespørgsel gælder en af fem: default, fast, reasoning, code eller long_context. Hver model befinder sig også på et niveau (tier), frontier, standard eller fast, og et højere niveau foretrækkes, når rollen tillader det. Organisationen beslutter, hvilken udbyder der betjener hver rolle (dens rolletildelinger), og hvilken rækkefølge der skal faldes tilbage i, når en udbyder fejler (dens routingpolitik-stige). Administratorer indstiller begge dele i AI-omstillingsbordet. nexus-auth stiller dem også til rådighed på /auth/org/<organisation-id>/settings/ai-provider/role-assignments og /auth/org/<organisation-id>/settings/ai-provider/routing-policy for en administratornøgle med ai_provider:manage.
Kaldere kan angive, hvad de ønsker. En færdighedsrække kan indeholde en foretrukken udbyder og en foretrukken model samt en kapabilitetsprofil. Routeren behandler hver af dem forskelligt:
- En foretrukken udbyder imødekommes kun, når organisationen har aktiveret den pågældende udbyder og har en nøgle til den. Ellers vælger routeren en erstatning.
- En foretrukken model imødekommes, når den findes i den pågældende udbyders katalog og passer til profilen.
- En kapabilitetsprofil er et filter, der aldrig selv foretager valget. Den kan kræve et mindste kontekstvindue, værktøjsbrug, billedforståelse (vision), indlejringer (embeddings), lang kontekst eller et krav om datalokalisering. Alt, der ikke opfylder den, kommer ikke i betragtning.
Routeren vælger i en fast rækkefølge. Den imødekommer ønsket, når den kan, prøver derefter en anden model fra samme udbyder og derefter rolletildelingen samt enhver anden udbyder med en nøgle, hvis katalog passer. Hvis der blev angivet en profil, og intet katalog passer til den, afvises forespørgslen med MODEL_CAPABILITY_UNAVAILABLE (422). Hvis intet er tildelt, og intet matcher, returneres NO_PROVIDER_FOR_ROLE (422). Der er ingen standardmodel som sidste udvej. En rolle, De ikke har konfigureret, fejler tydeligt, idet routeren med egne ord oplyser, hvad der skal indstilles.
Datalokalisering er den ene begrænsning, der ikke kan omgås ved udskiftning. En profil med eu_only betjenes af en EU-udbyder eller afvises. Harrow indstiller denne lås for hele organisationen, og omstillingsbordet viser den anden hostede udbyder, som ligger i en amerikansk region, som slået fra.
En færdighed kan også fastlåse én bestemt model, når færdigheden kræver netop den model for at fungere. Selv da bruger routeren organisationens egen nøgle til den, og uden en sådan svarer intet. En kalder kan aldrig få Nexus til at bruge en udbyder, som organisationen ikke har konfigureret.
Når en udbyder er valgt, er failover en særskilt sag. En 429-, en 5xx- eller en netværksfejl flytter forespørgslen et trin ned ad stigen til den næste udbyder. En 400-, 401-, 403- eller 404-fejl stopper med det samme, fordi legitimationsoplysninger og forespørgselsformater ikke kan overføres mellem udbydere, og et nyt forsøg blot ville opbruge kvote for at ende i den samme fejl.
For at se, hvad routeren ville vælge, før nogen stiller et spørgsmål, kan De læse GET /api/ai/routing-policy/effective på gatewayen med en persons eget token. Den returnerer modellen for den organisation, der er logget ind, eller routerens afvisning i tekstform, når der ikke er nogen, og den sender ingen forespørgsel til en model.
Overvågning af routeren
Talbjælken nederst på hver side viser den model, der er i brug ("Model: local"). På Enterprise viser AI-omstillingsbordet, live routerens trafik, mens den finder sted: forespørgsler fra assistenten, opgaver og apps, der flyder gennem roller til udbydere og nøgler, en nøgle i sin 60-sekunders pause tegnet med gråt, en nøgle slået fra tegnet med rødt og et fald tilbage til den hostede udbyder, når den lokale model har travlt. Ved siden af strømmen viser det belastning pr. udbyder, forespørgsler i sekundet og ventetid. Tomás holder det åbent i den første uge efter enhver ændring af routingpolitikken, fordi en forkert rolletildeling viser sig der inden for få minutter som trafik, der går et sted hen, ingen havde tænkt sig.
På Community har siden AI-modeller knappen Test alle modeller, der kontrollerer hver konfigureret model og markerer, om den svarer. Det er den hurtigste måde at bevise, at en ny nøgle virker, før nogen er afhængig af den.
Indlejringer
Søgning og vidensgrafen omdanner tekst til vektorer. Som standard gør installationen dette med en indlejringsmodel (embedding-model), der kører inde i klyngen på processoren, så ingen tekst forlader stedet for at blive indlejret, og en organisation behøver ingen nøgle til det. At bruge en hostet udbyder til indlejringer er et valg, en organisation træffer; det går derefter gennem den samme pulje og de samme regler.
Kun tre tjenester må bede routeren om indlejringer eller omrangering: nexus-graphrag, nexus-skills-engine og nexus-workflows. GraphRAG indlejrer som den organisation, hvis indhold det er, med den pågældende organisations indstillinger, og opbevarer ingen egen udbydernøgle. Når en organisation ændrer sin indlejringsmodel, kører nexus-workflows genindlejringsopgaven for den pågældende organisations lagre.
Personlige legitimationsoplysninger forbliver personlige
Nogle legitimationsoplysninger tilhører én enkelt person. Et Claude Max-abonnement, logget ind via den pågældende persons egen konto, er det almindelige tilfælde. En sådan legitimationsoplysning er aldrig en organisationsnøgle: Puljen afviser den med VALIDATION_FAILED, den opføres aldrig i organisationens tabel over nøgler, og ingen skærm hos en anden person viser den.
Modelnøgler sendes heller aldrig andre steder hen. Siden Nøgler til eksterne data, som opbevarer nøgler til eksterne datakilder, afviser alt, der ligner en AI-modelnøgle, med AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Hvis fillæseren finder modelnøgler inde i et dokument eller en konfiguration, hvor de ikke hører hjemme, registrerer den CREDENTIALS_IN_WRONG_PLACE, og en administrator fjerner dem og udskifter dem.
Scripts, REST og MCP
Nexus har tre offentlige værter. Hos Harrow er de console.harrow.example for konsollen, api.harrow.example for gatewayen og auth.harrow.example for login. Scripts og værktøjer bruger den anden og tredje.
Nøgler til scripts
Et script logger ind med en nøgle oprettet under Indstillinger, Nøgler til scripts. Hver nøgle har et navn, en rækkevidde (for eksempel "Start Drone yard count only"), den person, der har oprettet den, og en slutdato; en organisation kan låse den længste levetid, en nøgle må have. Hemmeligheden vises én gang, når nøglen oprettes. Kopiér den ind i scriptets hemmelighedslager, da Nexus kun gemmer dens sidste fire tegn. En nøgle trækkes tilbage og fjernes aldrig: Den stopper med det samme og forbliver opført med hvert kald, den har foretaget. Rotation giver nøglen en ny hemmelighed og viser den én gang.
Hver nøgle har sin egen side med kald pr. dag, kald pr. tjeneste og en aktivitetslog med tidspunkt, adresse, tjeneste og resultat. Et kald uden for nøglens rækkevidde afvises og vises i loggen.
nexus-auth stiller de samme nøgler til rådighed for en person, der er logget ind, på https://auth.harrow.example/api-keys: opret og vis liste, og læs, ændr, tilbagekald eller rotér derefter én nøgle ud fra dens id.
REST gennem gatewayen
Send REST-kald til https://api.harrow.example med Authorization: Bearer <token-or-key>. Hver nøgle skal tilhøre en organisation. En nøgle uden organisation afvises med TOKEN_ORG_MISSING (403) af enhver tjeneste, der kontrollerer nøgler gennem nexus-auth.
En kalder, der spørger for ofte, får svaret 429 med RATE_LIMITED, en Retry-After-header samt grænsen og tidsvinduet i bodyen. Vent det antal sekunder, den angiver. På Enterprise indstiller administratorer grænser pr. nøgle, pr. app og pr. enhed under Indstillinger, Hastighedsgrænser (se kapitel 2.16, Sikkerhed og netværk).
MCP til AI-værktøjer
AI-værktøjer, der taler Model Context Protocol, opretter forbindelse til https://api.harrow.example/mcp. De logger ind via OAuth 2.1-serveren (OAuth er den åbne standard for delegeret autorisation) på https://auth.harrow.example, som understøtter klientregistrering foretaget af selve værktøjet, så et værktøj som Claude Code eller Cursor registrerer sig selv og åbner personens browser for at logge ind. Forbindelsen handler derefter på vegne af denne ene person, med den pågældende persons rettigheder og intet mere. En person, der er logget ind, kan hente en færdiglavet konfiguration til et kommandolinjeværktøj fra https://auth.harrow.example/api/v1/mcp/cli-config.
Værktøjskald, der kræver en model, går gennem routeren ligesom alt andet, under personens organisation.




