Bygg en leietakerbevisst /v1/models-katalog for en multimodell API-gateway

En gateway skal ikke returnere alle modeller som er kjent for alle tilkoblede leverandører fra GET /v1/models. Den skal returnere modellene som den autentiserte API-nøkkelen er autorisert og operativt i stand til å kalle.

Denne forskjellen er viktig når én API-nøkkel gir tilgang til flere LLM-leverandører. En rå forening av oppstrømskataloger kan inkludere modeller som er forbudt av teampolicy, utilgjengelige under leietakers plan, mangler en sunn legitimasjon, inkompatible med den forespurte API, eller som ikke er distribuert i den nødvendige regionen. Disse oppføringene produserer ødelagte modellvelgere og kjøretidsfeil som oppdagelsen burde ha forhindret.

Den praktiske kontrakten er sterkere: Alle annonserte modeller må bestå de samme opptakskontrollene som gjelder for en reell forespørsel.

Definer hva "tilgjengelig" betyr

Tilbydereksistens er bare én inngang. En modell skal bare vises i en nøkkels standardkatalog når alle nødvendige betingelser er oppfylt:

• Gatewayen har et konfigurert offentlig produkt for modellen.
• Leietakeren, teamet og API-nøkkelen har rett til det produktet.
• Den gjeldende kommersielle planen tillater bruk.
• Retningslinjer tillater modell-, leverandør-, region- og databehandlingsmodus.
• Det finnes minst én kompatibel oppstrøms distribusjon eller rute.
• En brukbar leverandørlegitimasjon er tilgjengelig for den ruten.
• Ruten støtter minst én API-flate som annonseres i katalogen.
• Ruten er driftsklar i henhold til gatewayens helsepolicy.

Uttrykt som en settoperasjon:

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-skjemaet. Standardskjemaet definerer ikke alle disse gateway-spesifikke kontrollene. De hører hjemme i gatewayens kontrollplan og katalogkompilatoren.

Normaliser leverandøroppdagelse uten å bruke proxy

Fakta: API-er for leverandøroppdagelse avslører forskjellige konsepter. OpenAIs modellliste gir identifikatorer og grunnleggende metadata, men ikke en komplett funksjonsmatrise for hver API overflate. Anthropic skiller livssyklustilstander og kan returnere rikere funksjonsinformasjon når en modell eller et alias hentes. Gemini viser felt som token-grenser og støttede genereringsmetoder. Microsoft Foundry kan kreve et distribusjonsnavn i model-feltet, og en distribusjon kan være inkompatibel med et bestemt API selv når den underliggende modellen eksisterer.

Følgelig er ikke videresending av svar fra leverandøren et holdbart design. Behandle hver leverandør API som en avstemmingskilde. Konverter observasjonene til en intern registrering, og kombiner dem deretter med gateway-konfigurasjon og leietakerpolicy.

Bruk en kanonisk katalogpost

En nyttig intern registrering skiller den offentlige kontrakten fra oppstrømsimplementeringen:

{
  "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"
    }
  ]
}

Ikke utsett target_id, legitimasjonsreferanser eller intern rutingstilstand gjennom det standard offentlige endepunktet. Disse feltene er kontrollplandata. Hold dem tilgjengelige for rutetilgang, støtteverktøy og bruksattribusjon.

Separate IDer, aliaser og distribusjoner

En offentlig modell-ID er en kundekontrakt. En leverandørmodell-ID identifiserer en oppstrøms modellfamilie eller versjon. Et distribusjonsnavn identifiserer en operatøropprettet serveringsressurs. De er ikke utskiftbare.

Løs et offentlig alias til en uforanderlig katalogrevisjon før ruting. Registrer både forespurt ID og løst mål i brukshendelsen. Hvis aliaset endres senere, kan støttepersonell fortsatt rekonstruere hvilken distribusjon som håndterte et tidligere anrop.

Kompiler katalogen for den autentiserte nøkkelen

Katalogkompilatoren bør motta en autentisert oppdragsgiver, ikke bare en leietaker-ID. Den samme leietakeren kan ha produksjonsnøkler, utviklingsnøkler, begrensede kundenøkler og tjenestekontoer med ulike modelltildelinger.

En deterministisk kompileringssekvens er:

1. Last inn den uforanderlige basiskatalogrevisjonen.
2. Løs leietakermedlemskap, teammedlemskap og nøkkelspesifikke tilskudd.
3. Bruk restriksjoner for plan, geografi, dataopphold og leverandør.
4. Fjern ruter uten gyldig legitimasjon eller kompatible distribusjoner.
5. Vurder ruteberedskapen ved å bruke det gjeldende øyeblikksbildet av helse.
6. Samle overlevende ruter inn i offentlige modellregister.
7. Returner bare API flater støttet av minst én overlevende rute.

Bruk skjæringssemantikk når både team- og nøkkelbevilgninger finnes. En nøkkel tildelt et begrenset team bør ikke gjenopprette bredere tilgang bare fordi leietakeren eier en bredere plan. Dette gjør AI-modelltilgangskontroll for programvareteam forutsigbar og reduserer utilsiktet avsløring.

Behold listen og hent oppførselen identisk

GET /v1/models/{model} må kjøre det samme autorisasjonspredikatet som listeoperasjonen. Ellers kan en angriper telle opp skjulte identifikatorer ved å sammenligne suksess, forbudte og ikke-funne svar.

For en modell nøkkelen ikke kan se, returner den samme offentlige feilen som ble brukt for en ukjent modell. Ikke avslør om en annen leietaker kan bruke den, hvilken leverandør som er vert for den, eller hvilken rettighet som vil låse den opp. Administrative API-er kan avsløre mer detaljerte årsaker til autoriserte operatører.

Representer API kompatibilitet eksplisitt

En modells eksistens innebærer ikke støtte for hvert endepunkt. Chatfullføringer, svar, innebygginger, bildegenerering, sanntid, batch og Anthropic-meldinger har forskjellige forespørsels- og strømmekontrakter.

Ruteopptak bør derfor godta både en modell og en API overflate:

admit(key, public_model_id, api_surface, request_features)

Resultatet bør identifisere en kompatibel katalogrevisjon og én eller flere kvalifiserte ruter. En modell kan for eksempel støtte chat.completions men ikke responses, eller støtte svar bare når innebygde verktøy mangler. En enkelt boolsk som supports_responses kan være utilstrekkelig når kompatibilitet avhenger av forespurte funksjoner.

Anbefaling: publiser konservative funksjoner. Annonser en funksjon bare når gatewayen kan håndheve den på tvers av det kvalifiserte rutesettet eller kan velge en rute som støtter det deterministisk. Ikke utlede bildeinndata, verktøykall eller strukturert utdata fra en leverandørs familienavn.

Bevar SDK-kompatibilitet mens du legger til metadata

Hold standardfeltene som forventes av 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 utvidelse med navneavstand reduserer kollisjonsrisikoen, men noen klienter forkaster ukjente felt. Hvis applikasjoner trenger detaljerte utvalgsdata, oppgi et eget autentisert modellinformasjonsendepunkt med et versjonsskjema. Hold /v1/models liten nok for SDK-er, kommandolinjeverktøy og modellvelgere.

Velg stabile eller helsefiltrerte oppføringer

Det finnes to rimelige retningslinjer for tilgjengelighet.

Helsefiltrert katalog: skjul en modell når ingen rute er sunn for øyeblikket. Dette minimerer mislykkede anrop, men kataloger kan svinge under hendelser og ugyldiggjøre valg på klientsiden.

Stabil katalog: fortsett å liste opp berettigede produkter mens du rapporterer availability: temporarily_unavailable. Dette er enklere for automatisering og migreringsverktøy, men klienter kan fortsatt forsøke å ringe med mindre de forstår utvidelsen.

En praktisk standard er å skjule modeller som ikke er implementert, forbudt, pensjonert eller ikke er kvalifisert for legitimasjon, samtidig som midlertidig utilgjengelige modeller med eksplisitt status for pålitelige kunder beholdes. Det minimale kompatibilitetsendepunktet kan utelate utilgjengelige oppføringer hvis eksisterende klienter ikke kan tolke statusmetadata.

Prediksjon: rikere modellutvalgsklienter vil i økende grad avhenge av metadata for kapasitet og tilgjengelighet. Inntil denne oppførselen er stort sett pålitelig, må rutetilgang på tjenersiden forbli autoritativ.

Bufret kompilerte kataloger uten å tjene foreldede tilskudd

Kompiler kataloger utenfor forespørselsbanen der det er mulig. En hurtigbuffernøkkel bør inneholde minst:

(tenant_id, key_id, entitlement_version, catalog_revision, policy_revision)

Ugyldiggjør berørte oppføringer når teammedlemskap, modelltilskudd, prisplaner, leverandørlegitimasjon, distribusjonsstatus eller rutingpolicy endres. Kort levetid-verdier er ikke en erstatning for tilbakekallingshendelser: selv et kort foreldet vindu kan avsløre en nylig forbudt modell.

Leverandøravstemming kan være asynkron. Under et leverandørkontrollflyavbrudd, bevar den sist kjente katalogen, registrer observasjonstiden og forhindrer at nye usikre ruter blir kvalifisert. Dette gjør oppføringen responsiv uten å behandle foreldede oppdagelser som bevis på at en ny rute er brukbar.

Test katalogen som en opptakskontrakt

Den sterkeste samsvarsegenskapen er enkel: for hver modell og API-overflate som returneres til en nøkkel, må rutetilgang lykkes under samme katalog- og helserevisjon.

Legg til automatiske tester for:

• En tillatt nøkkel som ser og henter de tildelte modellene.
• En forbudt nøkkel som verken ser listeoppføringer eller gjenfinnbare metadata.
• Teambegrensninger som begrenser, i stedet for å utvide, nøkkeltilgang.
• En nettprat-implementering som ikke annonseres for svar.
• En deaktivert legitimasjon som fjerner de avhengige rutene.
• Et alias som løser den forventede uforanderlige katalogrevisjonen.
• En pensjonert modell som forsvinner fra standardkatalogen.
• Ugyldig hurtigbuffer etter endring av tilskudd, medlemskap eller retningslinjer.
• Ukjente og skjulte modell-ID-er som produserer offentlige feil som ikke kan skilles.
• Alle annonserte funksjoner har minst én kvalifisert rute.

Syntetiske sonder kan legge til bevis på at en rute fungerer, men de bruker kvoter, kan koste penger og kan ikke dekke alle funksjonskombinasjoner. Bruk dem for representative ruteklasser og kombiner dem med distribusjonsstatus, legitimasjonssjekker og reell trafikkhelse.

Registrer nok bevis til å forklare avgjørelser

For hver akseptert eller avvist forespørsel, noter katalogrevisjonen, forespurt offentlig modell-ID, API-overflate, løst rute, evnekontrakt, revisjon av retningslinjer og en strukturert opptaksårsak. Unngå å lagre forespørsler kun for dette formålet.

Implementeringssekvensen er enkel: definer den kanoniske posten, bygg leverandøravstemminger, kompiler per-nøkkelvisninger, lag liste og hent del ett autorisasjonspredikat, koble rutetilgang til samme revisjon, og legg til negative tester før du aktiverer cacher. Når disse brikkene er på plass, blir /v1/models et pålitelig svar på "hva kan denne nøkkelen ringe?" i stedet for en løst filtrert beholdning.

Relatert lesing

• designing a Responses API-kompatibilitetslag