Logga inBoka en genomgång

Kapitel 2.14

AI-leverantörer och modeller

Hur routern för leverantörer av artificiell intelligens (AI) väljer en modell från organisationens egen nyckelpool, och hur skript och AI-verktyg når Nexus utifrån.

Denna sida har översatts av AI från det engelska originalet. Om något är oklart är den engelska sidan referensen. Läs denna sida på engelska

16 minuters läsning

Harrow Port Authority driver två installationer. Den på deras luftgapade driftnätverk (kapitel 2.10, Luftgapad installation) har ingen molnbaserad leverantör alls. På den anslutna företagsinstallationen, som detta kapitel följer, besvaras de flesta frågor av en modell som körs på två grafikprocessornoder (GPU) i hamnens eget serverrum. En Google Gemini-nyckel, som betalas av Harrow, tar hand om överflödet när den lokala modellen är upptagen, och Aoife Brennan har låst organisationens trafik för artificiell intelligens (AI) till EU. Ingen på Harrow konfigurerade en modell inuti en tjänst eller ett insticksprogram. De angav för en enda komponent vad Harrow äger, och den komponenten beslutar om varje anrop.

Detta kapitel behandlar den komponenten, AI Provider Router, som i del 1 och i konsolen kallas AI-växeln, samt den pool av nycklar som den använder. Kapitlet avslutas med de sätt på vilka skript och AI-verktyg når Nexus utifrån: nycklar för skript, REST-API:et (representational state transfer application programming interface) och Model Context Protocol (MCP).

AI-leverantörsroutern

Routern körs inuti gatewayen, nexus-gateway. Det är den enda tjänsten som innehar en organisations modellautentiseringsuppgifter, och den fattar det slutgiltiga beslutet om vilken leverantör och vilken modell som besvarar varje förfrågan. Alla andra delar av Nexus frågar den. Ett arbetsflödessteg anger vad det önskar, och routern bestämmer.

Endast ett fåtal tjänster får fråga, och varje lista är fastställd av Helm-chartet:

Vad som efterfrågas Vem som får fråga
Ett slutförande (/internal/ai/chat och dess ström) nexus-orchestrator, nexus-workflows, nexus-skills-engine
Verktygsanrop och de övriga interna AI-rutterna nexus-orchestrator, nexus-workflows
Inbäddningar och omrangering nexus-graphrag, nexus-skills-engine, nexus-workflows

Varje intern rutt kontrollerar två saker i tur och ordning: anroparens interna tjänstenyckel och anroparens identitet mot listan ovan. En förfrågan utan nyckeln nekas med MISSING_SERVICE_KEY (401), en felaktig nyckel med INVALID_SERVICE_KEY (403), en förfrågan som inte anger vem som anropar med MISSING_CALLER_IDENTITY (403) och en anropare utanför listan med UNAUTHORIZED_CALLER (403). Ingen av dessa försöks igen, eftersom ingen av dem är ett tillfälligt fel.

Appar och insticksprogram förekommer aldrig på den listan. Ett insticksprogram deklarerar sina önskemål på de färdigheter det registrerar och skickar dem via UNO, arbetsflödesmotorn. Orkestreraren frågar sedan routern på insticksprogrammets vägnar. Det är därför en läckt hemlighet för ett insticksprogram kan agera som det insticksprogrammet, men inte förbruka någons modellbudget.

Vänster: tre staplade rutor, "Assistent", "Arbetsflödessteg", "Färdighet", var och en med en pil in i en ruta "UNO-utskick (nexus-orchestrator)". En pil märkt "önskemål: föredragen leverantör, föredragen modell, kapabilitetsprofil" går åt höger in i en stor ruta "AI Provider Router (nexus-gateway)". Inuti routerrutan finns tre små rutor i rad: "Roll", "Organisationspool", "Dirigeringspolicy". Från routern går tre pilar åt höger till "Lokal modell (ai.localProvider.baseUrl)", "Molnbaserad leverantörsnyckel A", "Molnbaserad leverantörsnyckel B". Under routern finns en separat ruta "nexus-auth: organisationens nyckelpool (krypterad)" med en streckad pil upp in i routern märkt "nycklar, hämtade per anrop".
Hur en förfrågan når en modell.

Organisationens nyckelpool

Modellnycklar tillhör organisationen. Varje organisation tar med sitt eget leverantörskonto och betalar sin egen räkning, och nyckeln ligger i organisationens pool, krypterad i nexus-auth. Det finns ingen delad plattformsnyckel bakom en organisation, så ingen organisation förbrukar någonsin en annans budget. Kostnaden för den regeln är tydlig: en organisation utan nyckel i sin pool får inga AI-svar. Assistenten visar MODEL_NOT_CONNECTED (503) och anger vem som kan ansluta en.

En nyckel kan läggas till i poolen för fyra leverantörer:

Leverantörs-id Visas som
anthropic_api_key Anthropic
gemini Google Gemini
openrouter OpenRouter
scaleway Scaleway

En egen modellserver

En organisation kan också använda vilken server som helst som den själv driver och som talar det OpenAI-kompatibla API:et, såsom modellen på Harrows GPU-noder. Installatören namnger den i värdefilen:

# 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 pekar gatewayens OpenAI-kompatibla adapter mot er server. I en installation når poolens scaleway-plats den servern, så nyckeln ni lägger till för scaleway är den nyckel som er egen server förväntar sig.

ai.installationHosts listar värdnamn som finns inuti installationen, utöver utgåvans egen tjänstedomän och de tre publika värdarna. Varje post är ett värdnamn, en .suffix, en IP-adress eller ett IPv4 CIDR-intervall (Classless Inter-Domain Routing). Routern använder listan för att skilja ett anrop som stannar på platsen från ett som lämnar den, vilket är vad kontrollen "Inget lämnar denna plats" på sidan Anslut en modell på er egen hårdvara rapporterar.

Nätverkspolicyn är lika viktig som routern. Namnrymden nekar all utgående trafik som standard, så gatewayen kan nå en modellserver utanför namnrymden endast när dess intervall finns i networkPolicy.externalEgressCIDRs. Detsamma gäller för en molnbaserad leverantör: om Harrow vill att dess Gemini-nyckel ska svara, måste leverantörens adressintervall också listas där, annars lämnar anropet aldrig klustret. Kapitel 2.16, Säkerhet och nätverk, behandlar policyn i sin helhet.

Anslut en modell på er egen hårdvara
Anslut en modell på er egen hårdvara
Ansluta en modell på er egen hårdvara. Sidan listar de modeller som servern rapporterar, vilken roll var och en spelar, och bekräftar att inget lämnar platsen.

Lägga till och dra tillbaka nycklar

Ägare och administratörer i en organisation sköter dess pool. Ingen annan kan se nycklarna eller ändra dem, och en förfrågan från dem nekas med AUTHORITY_EXCEEDED.

I konsolen

I Enterprise hålls poolen i AI-växeln, under motorerna. I Community hålls samma nycklar under Inställningar, AI-modeller. Den sidan är den grundläggande routern, där ni lägger till nycklar och en lokal modelladress samt väljer vilken modell som utför vilket jobb. Båda visar varje nyckel utifrån vem som lade in den och när ("Inlagd av Aoife, 3 sep") samt med en maskerad ledtråd med högst dess fyra sista tecken, såsom ••••7f2q. Själva nyckeln visas aldrig igen efter att ni har lagt till den.

AI-växeln
AI-växeln
AI-växeln listar varje leverantör med vem som lade in dess nyckel och vilka jobb den utför. En nyckel vilar efter fel, en annan har stängts av, och sidan anger vart data får skickas.
AI-modeller
AI-modeller
Den grundläggande routern i Community: en organisationsnyckel, en lokal modell på organisationens egen maskin och vilken modell som utför vilket jobb.

Genom BFF-API:et

Konsolens backend för frontend (BFF) betjänar tre rutter för poolen. Anropa dem med en persons egen åtkomsttoken: organisationen hämtas från token, aldrig från förfrågan.

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

GET returnerar leverantörerna i poolen, huruvida var och en kan svara, varje nyckel via dess ledtråd samt de leverantörer som en nyckel kan läggas till för. Att lägga till en nyckel kräver en JSON-kropp med två obligatoriska fält och ett valfritt:

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

Nyckeln skickas en gång. nexus-auth krypterar den och informerar routern, och svaret innehåller endast ledtråden. Svaret är 201 med den nya nyckelns id och dess rad: "Tillagd. Google Gemini-nyckeln ••••7f2q finns i organisationens AI-pool, och AI Provider Router kan dirigera till den nu." En etikett är högst 100 tecken, och en nyckel är en sträng utan mellanslag på högst 4 096 tecken. Alla andra fält i kroppen, eller ett fält som namnger en organisation eller en person, nekas.

Att återkalla kräver en tom kropp. Routern slutar genast att dirigera till nyckeln, och nexus-auth behåller den, listad som återkallad, så att dess historik finns kvar. Ingenting i poolen raderas någonsin.

Nekande HTTP När
VALIDATION_FAILED 400 En kropp som inte är {provider, api_key, label?}, en okänd leverantör, eller en persons egen prenumeration som erbjuds som en organisationsnyckel
AUTHORITY_EXCEEDED 403 Anroparen är inte ägare eller administratör för organisationen
RECORD_NOT_FOUND 404 Ingen nyckel med det id:t finns i organisationens pool
TRANSITION_NOT_PERMITTED 409 Nyckeln är redan återkallad
TENANT_NOT_A_PARAMETER 403 Kroppen eller frågan namngav en organisation

Nyckeltillstånd

Varje nyckel i poolen befinner sig i ett av sex tillstånd. Endast en nyckel som är i bruk besvarar en chatt.

Tillstånd Vad det innebär
in_use Nyckeln svarar, fram till sitt utgångsdatum om den har ett.
resting Routern har låtit den vila efter fel, fram till en angiven tidpunkt. Förfrågningar går till nästa nyckel under tiden.
exhausted Den har förbrukat sin gräns hos leverantören.
invalid Leverantören accepterar den inte längre.
expired Den förföll på sitt utgångsdatum.
withdrawn En administratör återkallade den. Den förblir listad som historik.

En nyckel som misslyckas vilar i 60 sekunder. Efter 5 fel i rad stänger routern av den, flyttar dess andel till de andra nycklarna och registrerar meddelandet PROVIDER_KEY_SWITCHED_OFF. Ingen nekas så länge en annan nyckel kan svara.

När en leverantör inte har någon nyckel i bruk anger poolen varför ("Ingen nyckel i bruk: 1 återkallad, 1 förfallen"). När ingen leverantör i poolen har en nyckel i bruk nekas en chatt med NO_PROVIDER_FOR_ROLE (422) och åtgärden: en ägare eller administratör lägger till en organisationsnyckel. Det är ett konfigurationstillstånd, och det stannar kvar på skärmen tills någon åtgärdar det.

Roller, policy och önskemål

Routern tänker i roller. Varje förfrågan gäller en av fem: default, fast, reasoning, code eller long_context. Varje modell tillhör också en nivå, frontier, standard eller fast, och en högre nivå föredras när rollen tillåter det. Organisationen bestämmer vilken leverantör som betjänar varje roll (dess rolltilldelningar) och i vilken ordning reservval ska ske när en leverantör misslyckas (dess stege för dirigeringspolicy). Administratörer ställer in båda i AI-växeln. nexus-auth tillhandahåller dem också på /auth/org/<organisation-id>/settings/ai-provider/role-assignments och /auth/org/<organisation-id>/settings/ai-provider/routing-policy för en administratörsnyckel som innehar ai_provider:manage.

Anropare kan ange vad de önskar. En färdighetsrad kan innehålla en föredragen leverantör och en föredragen modell, plus en kapabilitetsprofil. Routern behandlar var och en olika:

  • En föredragen leverantör tillgodoses endast när organisationen har den leverantören aktiverad och har en nyckel för den. Annars ersätter routern den.
  • En föredragen modell tillgodoses när den finns i den leverantörens katalog och passar profilen.
  • En kapabilitetsprofil är ett filter som aldrig väljer. Den kan begära ett minsta kontextfönster, verktygsanvändning, bildförståelse, inbäddningar, lång kontext eller en datalagringsregion. Allt som inte uppfyller profilen är inte kvalificerat.

Routern väljer i en fast ordning. Den tillgodoser önskemålet när den kan, provar sedan en annan modell från samma leverantör, därefter rolltilldelningen och slutligen varje annan leverantör med en nyckel vars katalog passar. Om en profil angavs och ingen katalog passar den nekas förfrågan med MODEL_CAPABILITY_UNAVAILABLE (422). Om ingenting är tilldelat och ingenting matchar blir det NO_PROVIDER_FOR_ROLE (422). Det finns ingen standardmodell som sista utväg. En roll som ni inte har konfigurerat misslyckas tydligt, där routerns egna ord anger vad som behöver ställas in.

Datalagringsregion är den enda begränsningen som inte kan kringgås genom ersättning. En profil med eu_only betjänas av en EU-leverantör eller nekas. Harrow ställer in detta lås för hela organisationen, och växeln ritar upp den andra molnbaserade leverantören, som befinner sig i en amerikansk region, som avstängd.

En färdighet kan också låsa en exakt modell när färdigheten behöver den modellen för att fungera. Även då använder routern organisationens egen nyckel för den, och utan en sådan svarar ingenting. En anropare kan aldrig få Nexus att använda en leverantör som organisationen inte har konfigurerat.

När en leverantör väl har valts är reservövergång en separat fråga. Ett 429-, ett 5xx- eller ett nätverksfel flyttar förfrågan nedåt på stegen till nästa leverantör. Ett 400-, 401-, 403- eller 404-fel stoppar genast, eftersom autentiseringsuppgifter och förfrågningsformat inte kan överföras mellan leverantörer och ett nytt försök skulle förbruka kvot för att nå samma fel.

För att se vad routern skulle välja innan någon ställer en fråga, läs GET /api/ai/routing-policy/effective på gatewayen med en persons egen token. Den svarar med modellen för den inloggade organisationen, eller routerns nekande i ord när det inte finns någon, och den skickar ingen förfrågan till en modell.

Övervaka routern

Sifferraden längst ned på varje sida visar vilken modell som används ("Modell: lokal"). I Enterprise ritar AI-växeln, live upp routerns trafik medan den sker: förfrågningar från assistenten, jobb och appar som flödar genom roller till leverantörer och nycklar, en nyckel i sin 60-sekunders vila ritad i grått, en avstängd nyckel ritad i rött och en reservövergång till den molnbaserade leverantören när den lokala modellen är upptagen. Bredvid flödet visas diagram över belastning per leverantör, förfrågningar per sekund och väntetid. Tomás håller den öppen under den första veckan efter varje ändring i dirigeringspolicyn, eftersom en felaktig rolltilldelning syns där inom några minuter som trafik på väg någonstans dit ingen avsåg att den skulle gå.

I Community har sidan AI-modeller en knapp, Testa varje modell, som kontrollerar varje konfigurerad modell och markerar om den svarar. Det är det snabbaste sättet att bevisa att en ny nyckel fungerar innan någon förlitar sig på den.

AI-växeln, live
AI-växeln, live
Routern live. Trafik flödar från assistenten och jobb genom roller till en lokal modell och molnbaserade nycklar; en nyckel vilar, en är avstängd och guldfärgade prickar visar en reservövergång medan den lokala modellen är upptagen.

Inbäddningar

Sökfunktionen och kunskapsgrafen omvandlar text till vektorer. Som standard gör installationen detta med en inbäddningsmodell som körs inuti klustret på processorn, så ingen text lämnar platsen för att bäddas in och en organisation behöver ingen nyckel för det. Att använda en molnbaserad leverantör för inbäddningar är ett val som en organisation gör; det går då genom samma pool och samma regler.

Endast tre tjänster får be routern om inbäddningar eller omrangering: nexus-graphrag, nexus-skills-engine och nexus-workflows. GraphRAG bäddar in som den organisation vars innehåll det är, med den organisationens inställningar, och innehar ingen egen leverantörsnyckel. När en organisation ändrar sin inbäddningsmodell kör nexus-workflows om-inbäddningsjobbet för den organisationens lagringsplatser.

Personliga inloggningsuppgifter förblir personliga

Vissa autentiseringsuppgifter tillhör en enskild person. En Claude Max-prenumeration, inloggad via den personens eget konto, är det vanliga fallet. En sådan autentiseringsuppgift är aldrig en organisationsnyckel: poolen nekar den med VALIDATION_FAILED, den listas aldrig i organisationens nyckeltabell och ingen annan persons skärm visar den.

Modellnycklar hamnar heller aldrig någon annanstans. Sidan Nycklar för externa data, som innehåller nycklar för externa datakällor, nekar allt som ser ut som en AI-modellnyckel med AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Om filläsaren hittar modellnycklar inuti ett dokument eller en konfiguration där de inte hör hemma, registrerar den CREDENTIALS_IN_WRONG_PLACE och en administratör tar bort dem och ersätter dem.

Skript, REST och MCP

Nexus har tre publika värdar. Hos Harrow är de console.harrow.example för konsolen, api.harrow.example för gatewayen och auth.harrow.example för inloggning. Skript och verktyg använder den andra och tredje.

Nycklar för skript

Ett skript loggar in med en nyckel som skapats under Inställningar, Nycklar för skript. Varje nyckel har ett namn, en räckvidd (till exempel "Starta endast räkning på drönargården"), personen som skapade den och ett slutdatum; en organisation kan låsa den längsta livslängd en nyckel får ha. Hemligheten visas en gång när nyckeln skapas. Kopiera den till skriptets hemlighetslagring, eftersom Nexus endast sparar dess fyra sista tecken. En nyckel återkallas, tas aldrig bort: den slutar fungera genast och förblir listad med varje anrop den gjorde. Rotering ger nyckeln en ny hemlighet och visar den en gång.

Varje nyckel har sin egen sida med anrop per dag, anrop per tjänst och en aktivitetslogg med tid, adress, tjänst och resultat. Ett anrop utanför nyckelns räckvidd nekas och visas i loggen.

nexus-auth tillhandahåller samma nycklar till en inloggad person på https://auth.harrow.example/api-keys: skapa och lista, samt därefter läsa, ändra, återkalla eller rotera en nyckel via dess id.

En nyckel för skript
En nyckel för skript
En nyckel för skript. Sidan visar nyckelns räckvidd, vem som skapade den, dess slutdatum, anrop per dag och per tjänst samt resultatet av varje anrop; hemligheten slutar på …7QK2 och visas aldrig igen.

REST genom gatewayen

Skicka REST-anrop till https://api.harrow.example med Authorization: Bearer <token-or-key>. Varje nyckel måste tillhöra en organisation. En nyckel utan organisation nekas med TOKEN_ORG_MISSING (403) av varje tjänst som kontrollerar nycklar via nexus-auth.

En anropare som frågar för ofta får svaret 429 med RATE_LIMITED, ett Retry-After-huvud samt gränsen och tidsfönstret i kroppen. Vänta det antal sekunder som anges. I Enterprise ställer administratörer in gränser per nyckel, per app och per enhet under Inställningar, Frekvensbegränsningar (se kapitel 2.16, Säkerhet och nätverk).

MCP för AI-verktyg

AI-verktyg som talar Model Context Protocol ansluter till https://api.harrow.example/mcp. De loggar in via OAuth 2.1-servern (OAuth är den öppna standarden för delegerad auktorisering) på https://auth.harrow.example, vilken stöder klientregistrering av verktyget självt, så ett verktyg såsom Claude Code eller Cursor registrerar sig självt och öppnar personens webbläsare för inloggning. Anslutningen agerar sedan för den enskilda personen, med den personens rättigheter och ingenting mer. En inloggad person kan hämta en färdig konfiguration för ett kommandoradsverktyg från https://auth.harrow.example/api/v1/mcp/cli-config.

Verktygsanrop som behöver en modell går genom routern precis som allt annat, under personens organisation.