InloggenBriefing plannen

Hoofdstuk 2.14

AI-providers en modellen

Hoe de Provider Router voor kunstmatige intelligentie (AI) een model kiest uit de eigen sleutelpool van de organisatie, en hoe scripts en AI-tools Nexus van buitenaf bereiken.

Deze pagina is door AI vertaald vanuit het Engelse origineel. Als er iets onduidelijk is, geldt de Engelse pagina als referentie. Lees deze pagina in het Engels

16 minuten leestijd

Harrow Port Authority beheert twee installaties. De installatie op het air-gapped operationele netwerk (hoofdstuk 2.10, Air-gapped installatie) heeft helemaal geen gehoste provider. Op de verbonden bedrijfsinstallatie, die in dit hoofdstuk wordt gevolgd, worden de meeste vragen beantwoord door een model dat draait op twee graphics processing unit (GPU)-nodes in de eigen serverruimte van de haven. Een Google Gemini-sleutel, betaald door Harrow, vangt de overloop op wanneer het lokale model bezet is, en Aoife Brennan heeft het verkeer voor kunstmatige intelligentie (AI) van de organisatie vergrendeld binnen de EU. Niemand bij Harrow heeft een model binnen een service of een plug-in geconfigureerd. Ze hebben aan één component verteld wat Harrow bezit, en die component beslist over elke aanroep.

Dit hoofdstuk behandelt die component, de AI Provider Router, die in Deel 1 en in de console het AI-schakelbord wordt genoemd, en de pool van sleutels waaruit deze put. Het eindigt met de manieren waarop scripts en AI-tools Nexus van buitenaf bereiken: sleutels voor scripts, de REST (representational state transfer) application programming interface (API) en het Model Context Protocol (MCP).

De AI Provider Router

De router draait binnen de gateway, nexus-gateway. Het is de enige service die de modelinloggegevens van een organisatie beheert, en neemt de uiteindelijke beslissing over welke provider en welk model elk verzoek beantwoorden. Elk ander onderdeel van Nexus vraagt het aan de router. Een workflowstap geeft aan wat deze zou willen, en de router beslist.

Slechts enkele services mogen dit vragen, en elke lijst ligt vast in de chart:

Wat wordt gevraagd Wie mag vragen
Een aanvulling (/internal/ai/chat en de bijbehorende stream) nexus-orchestrator, nexus-workflows, nexus-skills-engine
Toolaanroepen en de overige interne AI-routes nexus-orchestrator, nexus-workflows
Embeddings en reranking nexus-graphrag, nexus-skills-engine, nexus-workflows

Elke interne route controleert achtereenvolgens twee dingen: de interne servicesleutel van de aanroeper en de identiteit van de aanroeper aan de hand van de bovenstaande lijst. Een verzoek zonder de sleutel wordt geweigerd met MISSING_SERVICE_KEY (401), een verkeerde sleutel met INVALID_SERVICE_KEY (403), een verzoek dat niet vermeldt wie er aanroept met MISSING_CALLER_IDENTITY (403), en een aanroeper die niet op de lijst staat met UNAUTHORIZED_CALLER (403). Geen van deze verzoeken wordt opnieuw geprobeerd, omdat het in geen van de gevallen om een tijdelijke fout gaat.

Apps en plug-ins komen nooit op die lijst voor. Een plug-in declareert zijn wensen bij de skills die hij registreert en verstuurt via UNO, de workflow-engine. De orchestrator vraagt het vervolgens namens de plug-in aan de router. Dit is de reden waarom één gelekt plug-ingeheim wel kan handelen als die plug-in, maar het modelbudget van niemand kan uitgeven.

Links: drie gestapelde vakken, "Assistent", "Workflowstap", "Skill", elk met een pijl naar een vak "UNO-verzending (nexus-orchestrator)". Een pijl met het label "wensen: voorkeursprovider, voorkeursmodel, capaciteitsprofiel" gaat naar rechts naar een groot vak "AI Provider Router (nexus-gateway)". Binnen het routervak staan drie kleine vakken op een rij: "Rol", "Organisatiepool", "Routeringsbeleid". Vanuit de router gaan drie pijlen naar rechts naar "Lokaal model (ai.localProvider.baseUrl)", "Gehoste providersleutel A", "Gehoste providersleutel B". Onder de router staat een apart vak "nexus-auth: de sleutelpool van de organisatie (versleuteld)" met een gestippelde pijl omhoog naar de router met het label "sleutels, opgelost per aanroep".
Hoe een verzoek een model bereikt.

De sleutelpool van de organisatie

Modelsleutels zijn eigendom van de organisatie. Elke organisatie brengt haar eigen provideraccount mee en betaalt haar eigen rekening, en de sleutel bevindt zich in de pool van de organisatie, versleuteld in nexus-auth. Er is geen gedeelde platformsleutel achter een organisatie, zodat geen enkele organisatie ooit het budget van een andere uitgeeft. De prijs van die regel is duidelijk: een organisatie zonder sleutel in haar pool krijgt geen AI-antwoorden. De assistent toont MODEL_NOT_CONNECTED (503) en vermeldt wie er een kan koppelen.

Er kan voor vier providers een sleutel aan de pool worden toegevoegd:

Provider-ID Weergegeven als
anthropic_api_key Anthropic
gemini Google Gemini
openrouter OpenRouter
scaleway Scaleway

Een eigen modelserver

Een organisatie kan ook elke server gebruiken die zij zelf beheert en die de OpenAI-compatibele API spreekt, zoals het model op de GPU-nodes van Harrow. Het installatieprogramma benoemt deze in het values-bestand:

# 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 verwijst de OpenAI-compatibele adapter van de gateway naar uw server. Op een installatie bereikt de scaleway-sleuf van de pool die server, zodat de sleutel die u toevoegt voor scaleway de sleutel is die uw eigen server verwacht.

ai.installationHosts bevat hostnamen die zich binnen de installatie bevinden, naast het eigen servicedomein van de release en de drie openbare hosts. Elke vermelding is een hostnaam, een .suffix, een IP-adres of een IPv4 Classless Inter-Domain Routing (CIDR)-bereik. De router gebruikt de lijst om een aanroep die op de locatie blijft te onderscheiden van een aanroep die de locatie verlaat; dit is wat de controle "Er verlaat niets deze locatie" op de pagina Een model op uw eigen hardware koppelen rapporteert.

Het netwerkbeleid is net zo belangrijk als de router. De namespace weigert standaard al het uitgaande verkeer (egress), zodat de gateway een modelserver buiten de namespace alleen kan bereiken wanneer het bereik ervan in networkPolicy.externalEgressCIDRs staat. Hetzelfde geldt voor een gehoste provider: als Harrow wil dat zijn Gemini-sleutel antwoordt, moeten de adresbereiken van de provider daar ook worden vermeld, anders verlaat de aanroep het cluster nooit. Hoofdstuk 2.16, Beveiliging en netwerken, behandelt het volledige beleid.

Een model op uw eigen hardware koppelen
Een model op uw eigen hardware koppelen
Een model op uw eigen hardware koppelen. De pagina toont de modellen die de server rapporteert, de rol die elk model speelt, en bevestigt dat er niets de locatie verlaat.

Sleutels toevoegen en intrekken

Eigenaren en beheerders van een organisatie beheren de pool. Anderen kunnen de sleutels niet zien en niet wijzigen, en een verzoek van hen wordt geweigerd met AUTHORITY_EXCEEDED.

In de console

Op Enterprise wordt de pool bijgehouden in het AI-schakelbord, onder de engines. Op Community worden dezelfde sleutels bijgehouden onder Instellingen, AI-modellen. Die pagina is de basisrouter, waar u sleutels en een lokaal modeladres toevoegt en kiest welk model welke taak uitvoert. Beide tonen bij elke sleutel wie deze heeft ingesteld en wanneer ("Ingesteld door Aoife, 3 sept") en een gemaskeerde hint van maximaal de laatste vier tekens, zoals ••••7f2q. De sleutel zelf wordt na het toevoegen nooit meer getoond.

De AI-schakelcentrale
De AI-schakelcentrale
Het AI-schakelbord vermeldt bij elke provider wie de sleutel heeft ingesteld en welke taken deze uitvoert. Eén sleutel rust na fouten, een andere is uitgeschakeld, en de pagina geeft aan waar gegevens naartoe mogen gaan.
AI-modellen
AI-modellen
De basisrouter op Community: een organisatiesleutel, een lokaal model op de eigen machine van de organisatie, en welk model welke taak uitvoert.

Via de BFF API

De backend for frontend (BFF) van de console bedient drie routes voor de pool. Roep deze aan met het persoonlijke toegangstoken van een gebruiker: de organisatie wordt bepaald aan de hand van het token, nooit aan de hand van het verzoek.

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

GET retourneert de providers in de pool, of elk ervan kan antwoorden, elke sleutel aan de hand van zijn hint, en de providers waarvoor een sleutel kan worden toegevoegd. Het toevoegen van een sleutel vereist een JSON-body met twee verplichte velden en één optioneel veld:

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

De sleutel wordt slechts één keer verzonden. nexus-auth versleutelt deze en informeert de router, en het antwoord bevat alleen de hint. Het antwoord is 201 met de ID van de nieuwe sleutel en de bijbehorende rij: "Toegevoegd. De Google Gemini-sleutel ••••7f2q bevindt zich in de AI-pool van de organisatie en de AI Provider Router kan er nu naartoe routeren." Een label bevat maximaal 100 tekens en een sleutel is één tekenreeks zonder spaties van maximaal 4.096 tekens. Elk ander veld in de body, of een veld dat een organisatie of een persoon noemt, wordt geweigerd.

Intrekken vereist een lege body. De router stopt onmiddellijk met het routeren naar de sleutel, en nexus-auth bewaart deze, vermeld als ingetrokken, zodat de geschiedenis behouden blijft. Er wordt nooit iets uit de pool verwijderd.

Weigering HTTP Wanneer
VALIDATION_FAILED 400 Een body die geen {provider, api_key, label?} is, een onbekende provider, of het persoonlijke abonnement van een gebruiker dat wordt aangeboden als organisatiesleutel
AUTHORITY_EXCEEDED 403 De aanroeper is geen eigenaar of beheerder van de organisatie
RECORD_NOT_FOUND 404 Er bevindt zich geen sleutel met die ID in de pool van de organisatie
TRANSITION_NOT_PERMITTED 409 De sleutel is al ingetrokken
TENANT_NOT_A_PARAMETER 403 De body of query noemde een organisatie

Sleutelstatussen

Elke sleutel in de pool bevindt zich in een van de zes statussen. Alleen een sleutel die in gebruik is, beantwoordt een chat.

Status Wat het betekent
in_use De sleutel antwoordt, tot de eventuele vervaldatum.
resting De router laat de sleutel rusten na fouten, tot een vastgestelde tijd. Verzoeken gaan in de tussentijd naar de volgende sleutel.
exhausted De sleutel heeft zijn limiet bij de provider bereikt.
invalid De provider accepteert de sleutel niet meer.
expired De sleutel is verlopen op de vervaldatum.
withdrawn Een beheerder heeft de sleutel ingetrokken. Deze blijft vermeld als geschiedenis.

Een sleutel die faalt, rust gedurende 60 seconden. Na 5 opeenvolgende fouten schakelt de router de sleutel uit, verplaatst het aandeel ervan naar de andere sleutels en legt de melding PROVIDER_KEY_SWITCHED_OFF vast. Niemand wordt geweigerd zolang een andere sleutel kan antwoorden.

Wanneer een provider geen sleutel in gebruik heeft, vermeldt de pool waarom ("Geen sleutel in gebruik: 1 ingetrokken, 1 verlopen"). Wanneer geen enkele provider in de pool een sleutel in gebruik heeft, wordt een chat geweigerd met NO_PROVIDER_FOR_ROLE (422) en de oplossing: een eigenaar of beheerder voegt een organisatiesleutel toe. Dat is een configuratiestatus, en deze blijft op het scherm staan totdat iemand het oplost.

Rollen, beleid en voorkeuren

De router denkt in rollen. Elk verzoek is bedoeld voor een van de volgende vijf: default, fast, reasoning, code of long_context. Elk model valt ook in een tier, frontier, standard of fast, en een hogere tier krijgt de voorkeur wanneer de rol dit toelaat. De organisatie beslist welke provider elke rol bedient (de roltoewijzingen) en de volgorde waarin wordt teruggevallen wanneer een provider uitvalt (de routeringsbeleidsladder). Beheerders stellen beide in via het AI-schakelbord. nexus-auth biedt ze ook aan op /auth/org/<organisation-id>/settings/ai-provider/role-assignments en /auth/org/<organisation-id>/settings/ai-provider/routing-policy voor een beheerderssleutel met ai_provider:manage.

Aanroepers kunnen aangeven wat ze zouden willen. Een skill-rij kan een voorkeursprovider en een voorkeursmodel bevatten, plus een capaciteitsprofiel. De router behandelt elk hiervan anders:

  • Een voorkeursprovider wordt alleen gehonoreerd wanneer de organisatie die provider heeft ingeschakeld en er een sleutel voor heeft. Anders kiest de router een vervanger.
  • Een voorkeursmodel wordt gehonoreerd wanneer het in de catalogus van die provider staat en binnen het profiel past.
  • Een capaciteitsprofiel is een filter dat nooit selecteert. Het kan vragen om een minimaal contextvenster, toolgebruik, vision, embeddings, lange context of een dataverblijfplaats. Alles wat hier niet aan voldoet, komt niet in aanmerking.

De router kiest in een vaste volgorde. Hij honoreert de wens wanneer dat kan, probeert vervolgens een ander model van dezelfde provider, daarna de roltoewijzing en ten slotte elke andere provider met een sleutel waarvan de catalogus past. Als er een profiel is opgegeven en geen enkele catalogus hierbij past, wordt het verzoek geweigerd met MODEL_CAPABILITY_UNAVAILABLE (422). Als er niets is toegewezen en niets overeenkomt, is dat NO_PROVIDER_FOR_ROLE (422). Er is geen standaardmodel als laatste redmiddel. Een rol die u niet hebt geconfigureerd, faalt duidelijk, waarbij de router in eigen woorden aangeeft wat er moet worden ingesteld.

Dataverblijfplaats is de enige beperking waarvoor geen vervanging mogelijk is. Een profiel met eu_only wordt bediend door een EU-provider of geweigerd. Harrow stelt deze vergrendeling in voor de hele organisatie, en het schakelbord geeft de tweede gehoste provider, die zich in een Amerikaanse regio bevindt, weer als uitgeschakeld.

Een skill kan ook één exact model vastzetten wanneer de skill dat specifieke model nodig heeft om te werken. Zelfs dan gebruikt de router daarvoor de eigen sleutel van de organisatie, en zonder sleutel antwoordt er niets. Een aanroeper kan Nexus nooit dwingen een provider te gebruiken die de organisatie niet heeft geconfigureerd.

Zodra een provider is gekozen, is failover een aparte kwestie. Een 429, een 5xx of een netwerkfout verplaatst het verzoek een trede lager op de ladder naar de volgende provider. Een 400, 401, 403 of 404 stopt onmiddellijk, omdat inloggegevens en verzoekvormen niet overdraagbaar zijn tussen providers en een nieuwe poging alleen maar quota zou verbruiken om op dezelfde fout uit te komen.

Om te zien wat de router zou kiezen voordat iemand een vraag stelt, leest u GET /api/ai/routing-policy/effective op de gateway met het persoonlijke token van een gebruiker. Dit retourneert het model voor de ingelogde organisatie, of de weigering van de router in woorden wanneer er geen model is, en stuurt geen verzoek naar een model.

De router volgen

De cijferbalk onderaan elke pagina toont het gebruikte model ("Model: lokaal"). Op Enterprise tekent Het AI-schakelbord, live het verkeer van de router terwijl het plaatsvindt: verzoeken van de assistent, taken en apps die via rollen naar providers en sleutels stromen, een sleutel in zijn rustperiode van 60 seconden in het grijs, een uitgeschakelde sleutel in het rood, en een terugval op de gehoste provider wanneer het lokale model bezet is. Naast de stroom worden de belasting per provider, het aantal verzoeken per seconde en de wachttijd in grafieken weergegeven. Tomás houdt dit gedurende de eerste week na elke wijziging in het routeringsbeleid geopend, omdat een verkeerde roltoewijzing daar binnen enkele minuten zichtbaar wordt als verkeer dat ergens naartoe gaat waar niemand het voor bedoeld had.

Op Community heeft de pagina AI-modellen een knop Test elk model die elk geconfigureerd model controleert en markeert of het antwoordt. Dit is de snelste manier om te bewijzen dat een nieuwe sleutel werkt voordat iemand erop vertrouwt.

Het AI-schakelbord, live
Het AI-schakelbord, live
De router live. Verkeer stroomt van de assistent en taken via rollen naar een lokaal model en gehoste sleutels; één sleutel rust, één is uitgeschakeld, en gouden stippen tonen een terugval terwijl het lokale model bezet is.

Embeddings

Zoekopdrachten en de kennisgraaf zetten tekst om in vectoren. Standaard doet de installatie dit met een embeddingmodel dat binnen het cluster op de processor draait, zodat er geen tekst de locatie verlaat om te worden ingebed en een organisatie er geen sleutel voor nodig heeft. Het gebruik van een gehoste provider voor embeddings is een keuze die een organisatie maakt; dit verloopt vervolgens via dezelfde pool en dezelfde regels.

Slechts drie services mogen de router om embeddings of reranking vragen: nexus-graphrag, nexus-skills-engine en nexus-workflows. GraphRAG maakt embeddings aan namens de organisatie waarvan de content is, met de instellingen van die organisatie, en beheert zelf geen providersleutel. Wanneer een organisatie haar embeddingmodel wijzigt, voert nexus-workflows de taak voor het opnieuw inbedden uit voor de opslagplaatsen van die organisatie.

Persoonlijke inloggegevens blijven persoonlijk

Sommige inloggegevens zijn van één persoon. Een Claude Max-abonnement, waarmee is ingelogd via het eigen account van die persoon, is het meest voorkomende geval. Een dergelijk inloggegeven is nooit een organisatiesleutel: de pool weigert het met VALIDATION_FAILED, het wordt nooit vermeld in de sleuteltabel van de organisatie, en geen enkel scherm van een andere persoon toont het.

Modelsleutels gaan ook nooit ergens anders naartoe. De pagina Sleutels voor externe gegevens, die sleutels bevat voor externe gegevensbronnen, weigert alles wat lijkt op een AI-modelsleutel met AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Als de bestandslezer modelsleutels aantreft in een document of configuratie waar ze niet thuishoren, legt deze CREDENTIALS_IN_WRONG_PLACE vast en verwijdert en vervangt een beheerder ze.

Scripts, REST en MCP

Nexus heeft drie openbare hosts. Bij Harrow zijn dat console.harrow.example voor de console, api.harrow.example voor de gateway en auth.harrow.example voor het inloggen. Scripts en tools gebruiken de tweede en derde.

Sleutels voor scripts

Een script logt in met een sleutel die is aangemaakt onder Instellingen, Sleutels voor scripts. Elke sleutel heeft een naam, een bereik (bijvoorbeeld "Alleen Drone-terreintelling starten"), de persoon die de sleutel heeft aangemaakt en een einddatum; een organisatie kan de maximale levensduur van een sleutel vergrendelen. Het geheim wordt één keer getoond wanneer de sleutel wordt aangemaakt. Kopieer het naar de geheimenopslag van het script, want Nexus bewaart alleen de laatste vier tekens. Een sleutel wordt ingetrokken, nooit verwijderd: deze stopt onmiddellijk en blijft vermeld met elke aanroep die ermee is gedaan. Roteren geeft de sleutel een nieuw geheim en toont dit één keer.

Elke sleutel heeft een eigen pagina met aanroepen per dag, aanroepen per service en een activiteitenlogboek met tijd, adres, service en resultaat. Een aanroep buiten het bereik van de sleutel wordt geweigerd en verschijnt in het logboek.

nexus-auth biedt dezelfde sleutels aan een ingelogde persoon aan op https://auth.harrow.example/api-keys: aanmaken en weergeven, en vervolgens één sleutel op basis van zijn ID lezen, wijzigen, intrekken of roteren.

Eén sleutel voor scripts
Eén sleutel voor scripts
Eén sleutel voor scripts. De pagina toont het bereik van de sleutel, wie deze heeft aangemaakt, de einddatum, aanroepen per dag en per service, en het resultaat van elke aanroep; het geheim eindigt op …7QK2 en wordt nooit meer getoond.

REST via de gateway

Stuur REST-aanroepen naar https://api.harrow.example met Authorization: Bearer <token-or-key>. Elke sleutel moet bij een organisatie horen. Een sleutel zonder organisatie wordt geweigerd met TOKEN_ORG_MISSING (403) door elke service die sleutels controleert via nexus-auth.

Een aanroeper die te vaak verzoeken stuurt, krijgt als antwoord 429 met RATE_LIMITED, een Retry-After-header en de limiet en het tijdvenster in de body. Wacht het aantal seconden dat wordt aangegeven. Op Enterprise stellen beheerders limieten in per sleutel, per app en per eenheid onder Instellingen, Snelheidslimieten (zie hoofdstuk 2.16, Beveiliging en netwerken).

MCP voor AI-tools

AI-tools die het Model Context Protocol spreken, maken verbinding met https://api.harrow.example/mcp. Ze loggen in via de OAuth 2.1-server (OAuth is de open standaard voor gedelegeerde autorisatie) op https://auth.harrow.example, die clientregistratie door de tool zelf ondersteunt, zodat een tool zoals Claude Code of Cursor zichzelf registreert en de browser van de persoon opent om in te loggen. De verbinding handelt vervolgens namens die ene persoon, met de rechten van die persoon en niets meer. Een ingelogde persoon kan een kant-en-klare configuratie voor een command-line-tool ophalen via https://auth.harrow.example/api/v1/mcp/cli-config.

Toolaanroepen die een model nodig hebben, gaan net als al het andere via de router, onder de organisatie van de persoon.