Hantera LLM-gatewayer

En LLM-gateway är en språkmodellslutpunkt som registreras en gång för hela plattformen. Plattformstjänster som använder en språkmodell — i dag Sentinel — ber plattformen om en gateway varje gång de körs, i stället för att bära med sig en egen URL och API-nyckel.

Gatewayer hanteras under Inställningar → Plattformsinställningar, på fliken LLM-gatewayer. Vilken gateway och modell varje Sentinel-steg använder ställs in på fliken Sentinel-inställningar. Båda flikarna visas bara för principaler som kan läsa gatewayer — se Behörigheter.

Vad som kan vara en gateway

Varje server med ett OpenAI-kompatibelt API: LiteLLM, vLLM, llama.cpp, Ollama, eller en hostad leverantör som erbjuder ett. Plattformen kontrollerar en gateway med GET /v1/models, och Sentinel skickar sina anrop till /v1/chat/completions, båda under gatewayens bas-URL.

Skapa en gateway

1. Öppna fliken LLM-gatewayer och välj Lägg till gateway.

2. Fyll i Lägg till LLM-gateway:

   Fält	Vad du anger
   Namn	Ett visningsnamn, till exempel LiteLLM (prod). Högst 100 tecken
   Slug	Namnet som tjänster ber om gatewayen med, föreslaget utifrån namnet. 1–40 gemener, siffror och bindestreck, med en gemen eller siffra först, och inte använt av någon annan gateway. Det kan inte ändras senare
   Bas-URL	Serverns rot, till exempel https://litellm.example.com. Ett avslutande /v1 eller /v1/chat/completions tas bort. Se Regler för bas-URL
   API-nyckel	Valfri. Lämna den tom för en gateway utan autentisering
   Ange som standardgateway	Tjänster som inte namnger en gateway får standardgatewayen. Den första gateway du lägger till blir standard oavsett vad du väljer här

3. Välj Testa anslutning för att prova URL:en och nyckeln innan du sparar — se Testa en anslutning.

4. Välj Lägg till gateway.

Plattformen kontrollerar gatewayen när du sparar och behåller den oavsett vad kontrollen visar: en gateway som ligger nere just nu registreras ändå, och meddelandet efter sparandet säger vad kontrollen kom fram till.

Viktigt

API-nyckeln kan bara skrivas. Den lagras krypterad och skickas till gatewayen som en Bearer-token, och varken portalen eller admin-API:et visar den någonsin igen. Gatewayens detaljer och redigeringspanelen säger bara Nyckel angiven eller Ingen nyckel. Nyckeln lämnas ut i klartext via plattformens interna kanal till varje principal som har kernel/llmGateways/resolve på roten — Sentinels tjänstekonto, och även Platform Owners och Platform Contributors, vars */* omfattar den. Varje utlämning registreras, se Vad som registreras.

Regler för bas-URL

Bas-URL:en måste vara en absolut http://- eller https://-URL på högst 2048 tecken, och får inte innehålla:

• inloggningsuppgifter, som i https://user:password@host — ange API-nyckeln i stället;
• en frågesträng eller ett fragment;
• en länklokal adress som 169.254.169.254;
• en loopback- eller ospecificerad adress som localhost, 127.0.0.1 eller 0.0.0.0, som från en plattformstjänst är tjänstens egen pod. Ett plattforms-API som körs i miljön Development godtar dem.

Privata adresser godtas, så en gateway som körs i klustret kan registreras. Ett värdnamn slås inte upp när du sparar.

Testa en anslutning

Testa anslutning anropar GET /v1/models under bas-URL:en, med nyckeln, och rapporterar ett av:

Listan över gatewayer

Varje rad visar namnet, med märket Standard på standardgatewayen; slug; bas-URL:en; hälsan, med när den senast kontrollerades och det senaste felet om kontrollen misslyckades; och hur många av gatewayens modeller som är aktiverade. Hälsan är något av resultaten ovan, eller Inte kontrollerad för en gateway som inte har kontrollerats.

Plattformen kontrollerar varje gateway igen var 15:e minut som standard, och uppdaterar dess hälsa och modellista. Det senaste felet citerar början av serverns svar, med nyckeln borttagen. Hälsan är till för dig att läsa: tjänster får en gateway oavsett dess hälsa, och deras eget anrop är det verkliga testet.

Välj vilka modeller tjänster får använda

Välj en gateway i listan för att öppna dess detaljer. Modeller listar varje modell som gatewayen har; bara de som är Aktiverad erbjuds tjänster.

• Första gången en gateway listar sina modeller aktiveras alla. Modeller som dyker upp i senare kontroller kommer in inaktiverade, så att du bestämmer om tjänster får använda dem.
• En modell som servern slutar lista markeras Saknas. Den tas inte bort och behåller sin inställning: en aktiverad modell som markerats Saknas erbjuds fortfarande tjänster tills du inaktiverar den.
• Lägg till modell via id lägger till en modell som servern inte listar. Den aktiveras direkt och markeras Manuell. Manuella modeller kan tas bort; en modell som servern har listat kan inte det, inte ens när den markerats Saknas, och en manuell modell som servern börjar lista slutar vara manuell. Ett modell-id är högst 200 tecken, utan mellanslag.
• Varje ändring sparar gatewayens hela modellista, och en sparad lista får innehålla högst 500 modeller. Kontrollerna lägger till varje modell som servern listar utan den gränsen, så på en gateway som listar fler än 500 modeller avvisas varje ändring här.

Varje ändring sparas direkt. En modell som ett Sentinel-steg är tilldelat kan inte inaktiveras eller tas bort; felet namnger stegets syfte, till exempel sentinel.brain. Tilldela först steget en annan modell — se Välj gateway och modell för varje Sentinel-steg.

Redigera en gateway

Välj Redigera i gatewayens detaljer. Du kan ändra Namn, Bas-URL, API-nyckel och Ange som standardgateway; slug går inte att ändra. En ändrad bas-URL eller nyckel gör att gatewayen kontrolleras igen när du sparar, och den kontrollen uppdaterar modellistan på samma sätt som den periodiska kontrollen: modeller som servern nu listar kommer in inaktiverade, och modeller som den inte längre listar markeras Saknas men förblir aktiverade. Gå igenom gatewayens Modeller när du har pekat den mot en annan server.

Nyckelfältet visar Nyckel angiven eller Ingen nyckel och behåller den lagrade nyckeln om du inte väljer:

• Byt nyckel, eller Lägg till nyckel när ingen är angiven, för att ange en ny nyckel;
• Ta bort nyckel, för att ta bort den lagrade nyckeln när du sparar;
• Behåll nuvarande nyckel, för att gå tillbaka till att behålla den.

Testa anslutning i redigeringspanelen använder den lagrade nyckeln om du inte har bytt eller tagit bort den.

Flytta en gateway till en annan värd

En lagrad nyckel skickas bara till den adress den sparades för: samma schema, värd och port. När den nya bas-URL:en pekar någon annanstans ber redigeringspanelen om nyckeln igen. Ange den för den nya värden, eller välj Ta bort nyckel om den värden inte behöver någon; tills du gör det är Testa anslutning avstängd och ändringen kan inte sparas. Att bara ändra sökvägen, till exempel lägga till /litellm, behåller den lagrade nyckeln.

Kontrollera en gateway igen

Välj Kontrollera igen i gatewayens detaljer. Gatewayen kontrolleras direkt, och dess hälsa och modellista uppdateras som vid den periodiska kontrollen.

Byt standardgateway

Välj Ange som standard i detaljerna för den gateway som ska bli standard, eller kryssa i Ange som standardgateway när du lägger till eller redigerar den. Den tidigare standardgatewayen upphör att vara det. Standardgatewayen har ingen knapp Ange som standard och dess kryssruta kan inte avmarkeras: för att byta standard gör du en annan gateway till standard.

Ta bort en gateway

Välj Ta bort i gatewayens detaljer och bekräfta med Ta bort gateway. Tjänster som ber om den här gatewayen får den inte längre från och med nästa körning. Det går inte att ångra.

Plattformen vägrar ta bort gatewayen, och dialogrutan säger varför, när:

• gatewayen är standard och det finns andra gatewayer — gör en annan till standard först. Den enda gatewayen kan tas bort trots att den är standard;
• ett Sentinel-steg är tilldelat den — felet namnger stegen. Tilldela dem en annan gateway, eller rensa deras tilldelning, först.

Välj gateway och modell för varje Sentinel-steg

Öppna fliken Sentinel-inställningar. Modelltilldelningar har en rad per Sentinel-steg:

För varje steg du vill ställa in:

1. Välj en Gateway. Inte tilldelad (använd standardgateway) rensar tilldelningen.
2. Välj en Modell. Bara gatewayens aktiverade modeller erbjuds; en modell som servern inte längre listar visas men kan inte väljas.
3. Välj Spara på den raden. Varje rad sparas för sig och visar när den senast ändrades.

Ändringar gäller från Sentinels nästa körning, och Sentinel körs var 30:e minut som standard. En rad kan ha en varning:

Hur en tjänst väljer gateway och modell

I början av varje körning ber Sentinel plattformen om en gateway en gång per steg, och namnger stegets syfte — sentinel.triage, sentinel.brain eller sentinel.code. Plattformen lämnar ut gatewayens bas-URL, API-nyckel och aktiverade modeller:

• Ett steg med en tilldelning får den tilldelade gatewayen och modellen.
• Ett steg utan tilldelning får standardgatewayen och använder dess första aktiverade modell, som kan vara en modell som markerats Saknas.

Ingenting sparas mellan körningar, så en ny nyckel, en ny standardgateway, en nyss aktiverad modell eller en ändrad tilldelning får effekt vid nästa körning utan någon omstart.

När ett steg inte kan få det det behöver — ingen gateway är registrerad, standardgatewayen har inga aktiverade modeller, Sentinel saknar behörigheten, eller plattformens API kan inte nås — hoppar Sentinel över körningen och registrerar varför, och nästa körning försöker igen. En gateway som inte är Frisk lämnas ändå ut.

Sentinels äldre inställningar för egna slutpunkter, gateway och modeller — Agent__TriageBaseUrl, Agent__BrainBaseUrl, Agent__CodeBaseUrl, Agent__Gateway, Agent__ModelName och de stegvisa Agent__TriageModel, Agent__BrainModel och Agent__CodeModel — sätts inte av installern, och när Sentinel rullas ut tas de bort ur dess konfiguration. Det som väljs på de här flikarna är det som Sentinel använder.

Behörigheter

Varje åtgärd kontrolleras på plattformens rot, så bara roller som tilldelats där ger den; en roll som tilldelats på en boundary, inte ens Owner, gör det aldrig.

Platform Owner och Platform Contributor har alla fyra, resolve inräknad. Platform Reader har read och ser båda flikarna utan deras kontroller. Sidomenyn visar Plattformsinställningar bara för dem som kan ändra e-postinställningarna, så en Platform Reader öppnar sidan på https://portal.example.com/admin/platform-settings.

Rollen LLM Gateway Consumer har resolve men ingen av de tre andra, och kan bara tilldelas på plattformens rot. Plattformens RBAC-tjänst tilldelar den där till Sentinels tjänstekonto — Keycloak-klienten stackship-module-sentinel — och tilldelar den igen om den tas bort; se Installationsinställningar.

Vad som registreras

Varje ändring registreras i plattformens granskningslogg under resurstypen llmgateways, med gatewayens slug som resursnamn:

Själva nyckeln registreras aldrig. En utlämning som inte kan registreras avvisas, så ingen nyckel lämnas ut oregistrerad; en ändring som inte kan registreras sparas ändå. Kontroller — Testa anslutning, Kontrollera igen och den periodiska kontrollen — registreras inte, och inte heller de uppdateringar av hälsa och modellista som de gör.

Installationsinställningar

Ange dem som miljövariabler, till exempel LlmGateways__HealthCheckInterval=00:05:00 eller ModuleGrantReconciler__LlmGatewayConsumerClientIds__0=stackship-module-sentinel. RBAC-modulen kontrollerar de här tilldelningarna när den startar och sedan var 10:e minut (ModuleGrantReconciler:SweepInterval), och tilldelar igen de som saknas. En klient som inte finns hoppas över.

Med API:et

Portalen använder de här rutterna under https://api.example.com. Var och en kontrolleras på plattformens rot.

POST https://api.example.com/admin/llm-gateways
Content-Type: application/json

{ "name": "LiteLLM", "slug": "litellm", "baseUrl": "https://litellm.example.com", "apiKey": "sk-…" }

I en PUT till en gateway är varje fält valfritt. apiKey utelämnad eller null behåller den lagrade nyckeln, "" tar bort den, och varje annat värde ersätter den. models är, när det anges, den fullständiga listan med { "id": …, "enabled": … }-poster: manuella modeller som saknas i den tas bort, och modeller som servern listar behålls. "isDefault": false på standardgatewayen lämnar plattformen utan standardgateway, så att tjänster som inte namnger någon gateway inte får någon — gör i stället en annan gateway till standard.

En tilldelning skickas som { "gatewayId": "…", "model": "…" }; { "gatewayId": null } rensar tilldelningen. Ogiltiga indata besvaras med 400 och ett meddelande per fält, och en konflikt — en slug som redan används, att ta bort standardgatewayen eller en tilldelad gateway, att inaktivera en tilldelad modell — med 409.