Byg et lejerbevidst /v1/models-katalog til en multimodel API-gateway

En gateway bør ikke returnere alle modeller, som alle tilsluttede udbydere kender fra GET /v1/models. Den skulle returnere de modeller, som den godkendte API-nøgle er autoriseret og operationelt i stand til at kalde.

Denne sondring har betydning, når én API-nøgle giver adgang til flere LLM-udbydere. En rå forening af upstream-kataloger kan omfatte modeller, der er forbudt af teampolitikken, utilgængelige i henhold til lejerens plan, mangler en sund legitimation, inkompatible med det anmodede API eller ikke er implementeret i det påkrævede område. Disse poster producerer ødelagte modelvælgere og køretidsfejl, som opdagelse burde have forhindret.

Den praktiske kontrakt er stærkere: Hver annonceret model skal bestå de samme adgangskontroller, som ville gælde for en reel anmodning.

Definer, hvad "tilgængelig" betyder

Udbydereksistens er kun én input. En model bør kun vises i en nøgles standardkatalog, når alle påkrævede betingelser er opfyldt:

• Gatewayen har et konfigureret offentligt produkt til modellen.
• Lejeren, teamet og API-nøglen er berettiget til det pågældende produkt.
• Den gældende kommercielle plan tillader dens brug.
• Politik tillader model-, udbyder-, region- og datahåndteringstilstand.
• Der findes mindst én kompatibel upstream-implementering eller rute.
• En brugbar udbyderoplysninger er tilgængelig for den rute.
• Ruten understøtter mindst én API overflade, der annonceres i kataloget.
• Ruten er driftsklar i henhold til gatewayens sundhedspolitik.

Udtrykt som en indstillet handling:

visible_models(key) =
  configured_products
  ∩ tenant_entitlements
  ∩ team_grants
  ∩ key_grants
  ∩ commercial_rights
  ∩ policy_eligible_routes
  ∩ compatible_deployments
  ∩ operationally_ready_routes

Dette er en anbefaling, ikke en påstand om OpenAI-skemaet. Standardskemaet definerer ikke alle disse gateway-specifikke kontroller. De hører hjemme i gatewayens kontrolplan og katalogkompiler.

Normaliser udbyderopdagelse uden at proxye det

Fakta: provider discovery API'er afslører forskellige koncepter. OpenAIs modelliste leverer identifikatorer og grundlæggende metadata, men ikke en komplet funktionsmatrix for hver API overflade. Anthropic skelner mellem livscyklustilstande og kan returnere rigere kapacitetsoplysninger, når en model eller et alias hentes. Gemini viser felter såsom token-grænser og understøttede genereringsmetoder. Microsoft Foundry kræver muligvis et implementeringsnavn i model-feltet, og en implementering kan være inkompatibel med et bestemt API, selv når den underliggende model eksisterer.

Som følge heraf er videresendelse af svar fra udbydere ikke et holdbart design. Behandl hver udbyder API som en afstemningskilde. Konverter dens observationer til en intern registrering, og kombiner dem derefter med gateway-konfiguration og lejerpolitik.

Brug en kanonisk katalogpost

En nyttig intern registrering adskiller den offentlige kontrakt fra upstreamimplementering:

{
  "catalog_revision": "cat_2026_11_05_0182",
  "public_model_id": "reasoning-large",
  "lifecycle": "active",
  "api_surfaces": ["chat.completions", "responses"],
  "input_modalities": ["text", "image"],
  "output_modalities": ["text"],
  "limits": {
    "context_tokens": 200000,
    "max_output_tokens": 32000
  },
  "capabilities": {
    "tools": true,
    "structured_output": true,
    "batch": false
  },
  "entitlement_profile": "advanced-reasoning",
  "routes": [
    {
      "provider": "provider-a",
      "target_type": "deployment",
      "target_id": "prod-reasoning-east",
      "region": "us-east",
      "state": "ready"
    }
  ]
}

Undlad at udsætte target_id, legitimationsoplysninger eller intern routingtilstand gennem det offentlige standardslutpunkt. Disse felter er kontrolplandata. Hold dem tilgængelige til ruteadgang, supportværktøjer og brugstilskrivning.

Separate id'er, aliaser og implementeringer

Et offentligt model-id er en kundekontrakt. Et udbydermodel-id identificerer en opstrømsmodelfamilie eller -version. Et implementeringsnavn identificerer en operatøroprettet serveringsressource. De er ikke udskiftelige.

Løs et offentligt alias til en uforanderlig katalogrevision før routing. Registrer både det anmodede ID og det løste mål i brugshændelsen. Hvis aliaset ændres senere, kan supportpersonalet stadig rekonstruere, hvilken implementering der håndterede et tidligere opkald.

Kompilér kataloget for den godkendte nøgle

Katalogkompileren bør modtage en godkendt principal, ikke blot et lejer-id. Den samme lejer kan have produktionsnøgler, udviklingsnøgler, begrænsede kundenøgler og servicekonti med forskellige modelbevillinger.

En deterministisk kompileringssekvens er:

1. Indlæs den uforanderlige basiskatalogrevision.
2. Løs lejermedlemskab, teammedlemskab og nøglespecifikke bevillinger.
3. Anvend begrænsninger for plan, geografi, dataophold og udbyder.
4. Fjern ruter uden gyldige legitimationsoplysninger eller kompatible implementeringer.
5. Evaluer ruteberedskab ved hjælp af det aktuelle helbredsøjebliksbillede.
6. Samle overlevende ruter til offentlige modelregistre.
7. Returner kun API overflader understøttet af mindst én overlevende rute.

Brug krydsningssemantik, når der findes både team- og nøglebevillinger. En nøgle, der er tildelt et begrænset team, bør ikke genvinde bredere adgang, blot fordi lejeren ejer en bredere plan. Dette gør AI-modeladgangskontrol for softwareteams forudsigelig og reducerer utilsigtet offentliggørelse.

Behold listen og hent adfærd identisk

GET /v1/models/{model} skal køre det samme autorisationsprædikat som listeoperationen. Ellers kan en angriber opregne skjulte identifikatorer ved at sammenligne succes, forbudte og ikke-fundne svar.

For en model, som nøglen ikke kan se, skal du returnere den samme offentlige fejl, der blev brugt til en ukendt model. Afslør ikke, om en anden lejer kan bruge det, hvilken udbyder der hoster det, eller hvilken rettighed der ville låse det op. Administrative API'er kan afsløre mere detaljerede årsager til autoriserede operatører.

Repræsenter API kompatibilitet eksplicit

En models eksistens indebærer ikke understøttelse af hvert slutpunkt. Chatafslutninger, svar, indlejringer, billedgenerering, realtid, batch- og Anthropic-meddelelser har forskellige anmodnings- og streamingkontrakter.

Ruteadgang bør derfor acceptere både en model og en API overflade:

admit(key, public_model_id, api_surface, request_features)

Resultatet bør identificere en kompatibel katalogrevision og en eller flere kvalificerede ruter. En model kan f.eks. understøtte chat.completions men ikke responses, eller understøtte svar kun, når indbyggede værktøjer er fraværende. En enkelt boolsk som supports_responses kan være utilstrækkelig, når kompatibiliteten afhænger af de ønskede funktioner.

Anbefaling: udgiv konservative funktioner. Annoncer kun for en funktion, når gatewayen kan håndhæve den på tværs af det kvalificerede rutesæt eller kan vælge en rute, der understøtter den deterministisk. Udled ikke billedinput, værktøjsopkald eller struktureret output fra en udbyders familienavn.

Bevar SDK-kompatibilitet, mens du tilføjer metadata

Hold de standardfelter, der forventes af OpenAI-kompatible klienter, stabile:

{
  "id": "reasoning-large",
  "object": "model",
  "created": 1793836800,
  "owned_by": "gateway",
  "x_gateway": {
    "catalog_revision": "cat_2026_11_05_0182",
    "lifecycle": "active",
    "api_surfaces": ["chat.completions", "responses"],
    "input_modalities": ["text", "image"],
    "availability": "available"
  }
}

En udvidelse med navneafstand reducerer kollisionsrisikoen, men nogle klienter kasserer ukendte felter. Hvis applikationer har brug for detaljerede udvælgelsesdata, skal du angive et separat godkendt modelinformationsendepunkt med et versioneret skema. Hold /v1/models lille nok til SDK'er, kommandolinjeværktøjer og modelvælgere.

Vælg stabile eller sundhedsfiltrerede fortegnelser

Der findes to rimelige tilgængelighedspolitikker.

Sundhedsfiltreret katalog: skjul en model, når ingen rute i øjeblikket er sund. Dette minimerer mislykkede opkald, men kataloger kan svinge under hændelser og ugyldiggøre valg på klientsiden.

Stabilt katalog: fortsæt med at angive berettigede produkter, mens du rapporterer availability: temporarily_unavailable. Dette er nemmere for automatiserings- og migreringsværktøjer, men klienter kan stadig forsøge at ringe, medmindre de forstår udvidelsen.

En praktisk standard er at skjule modeller, der ikke er implementeret, forbudte, pensionerede eller ikke-kvalificerede med legitimationsoplysninger, mens de midlertidigt utilgængelige modeller med en eksplicit status for betroede kunder bevares. Det minimale kompatibilitetsslutpunkt kan udelade utilgængelige poster, hvis eksisterende klienter ikke kan fortolke statusmetadata.

Forudsigelse: rigere modeludvalgsklienter vil i stigende grad afhænge af metadata for kapacitet og tilgængelighed. Indtil denne adfærd er stort set pålidelig, skal ruteadgang på serversiden forblive autoritativ.

Cache kompilerede kataloger uden at tjene uaktuelle bevillinger

Kompilér kataloger uden for anmodningsstien, hvor det er muligt. En cache-nøgle skal mindst indeholde:

(tenant_id, key_id, entitlement_version, catalog_revision, policy_revision)

Ugyldiggør berørte poster, når teammedlemskab, modeltilskud, prisplaner, udbyderlegitimationsoplysninger, implementeringstilstand eller routingpolitik ændres. Kort levetid-værdier er ikke en erstatning for tilbagekaldelsesbegivenheder: Selv et kort forældet vindue kan afsløre en nyligt forbudt model.

Udbyderafstemning kan være asynkron. Under en udbyderkontrolflyafbrydelse skal du bevare det sidst kendte katalog, registrere dets observationstid og forhindre nye usikre ruter i at blive berettiget. Dette holder fortegnelsen responsiv uden at behandle gammel opdagelse som bevis på, at en ny rute er brugbar.

Test kataloget som en optagelseskontrakt

Den stærkeste overensstemmelsesegenskab er enkel: For hver model og API overflade, der returneres til en nøgle, skal ruteoptagelse lykkes under samme katalog og sundhedsrevision.

Tilføj automatiske test for:

• En tilladt nøgle, der ser og henter dens tildelte modeller.
• En forbudt nøgle, der hverken ser listeposter eller metadata, der kan hentes.
• Teambegrænsninger, der indsnævrer, i stedet for at udvide, nøgleadgang.
• En implementering af kun chat, der ikke annonceres for svar.
• En deaktiveret legitimationsoplysninger fjerner dens afhængige ruter.
• Et alias, der løser den forventede uforanderlige katalogrevision.
• En pensioneret model, der forsvinder fra standardkataloget.
• Cache-invalidering efter ændring af bevillinger, medlemskaber eller politikker.
• Ukendte og skjulte model-id'er, der producerer offentlige fejl, der ikke kan skelnes.
• Hver annoncerede kapacitet har mindst én kvalificeret rute.

Syntetiske sonder kan tilføje beviser for, at en rute fungerer, men de bruger kvoter, kan koste penge og kan ikke dække enhver funktionskombination. Brug dem til repræsentative ruteklasser, og kombiner dem med implementeringstilstand, legitimationskontrol og reel trafiktilstand.

Optag nok beviser til at forklare beslutninger

For hver accepteret eller afvist anmodning skal du registrere katalogrevisionen, anmodet offentlig model-id, API overflade, løst rute, kapacitetskontrakt, politikrevision og en struktureret adgangsårsag. Undgå at gemme promptindhold udelukkende til dette formål.

Implementeringssekvensen er ligetil: Definer den kanoniske post, byg udbyderafstemninger, kompilér visninger pr. nøgle, lav en liste og hent del et autorisationsprædikat, forbind ruteadgang til den samme revision, og tilføj negative test, før du aktiverer caches. Når disse dele er på plads, bliver /v1/models et pålideligt svar på "hvad kan denne nøgleringe?" snarere end en løst filtreret beholdning.

Relateret læsning

• designing a Responses API compatibility layer