Bouw een huurderbewuste /v1/models-catalogus voor een multi-model API-gateway

Een gateway mag niet elk model retourneren dat bekend is bij elke aangesloten provider van GET /v1/models. Het zou de modellen moeten retourneren die de geverifieerde API sleutel geautoriseerd en operationeel in staat is om aan te roepen.

Dit onderscheid is van belang wanneer één API sleutel toegang biedt tot meerdere LLM-providers. Een onbewerkte unie van upstream-catalogi kan modellen bevatten die verboden zijn door teambeleid, niet beschikbaar zijn onder het plan van de tenant, een gezonde referentie missen, incompatibel zijn met de aangevraagde API, of niet geïmplementeerd zijn in de vereiste regio. Deze vermeldingen produceren defecte modelkiezers en runtimefouten die ontdekking had moeten voorkomen.

Het praktische contract is sterker: elk geadverteerd model moet dezelfde toelatingscontroles doorstaan die van toepassing zouden zijn op een echt verzoek.

Definieer wat 'beschikbaar' betekent

Het bestaan van een aanbieder is slechts één invoer. Een model zou alleen in de standaardcatalogus van een sleutel moeten verschijnen als aan alle vereiste voorwaarden wordt voldaan:

• De gateway heeft een geconfigureerd openbaar product voor het model.
• De tenant, het team en de API sleutel hebben recht op dat product.
• Het toepasselijke commerciële plan staat het gebruik ervan toe.
• Het beleid staat het model, de provider, de regio en de gegevensverwerkingsmodus toe.
• Er bestaat ten minste één compatibele upstream-implementatie of route.
• Er is een bruikbare providerreferentie beschikbaar voor die route.
• De route ondersteunt ten minste één API oppervlak dat in de catalogus wordt geadverteerd.
• De route is operationeel gereed volgens het statusbeleid van de gateway.

Uitgedrukt als een vaste bewerking:

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

Dit is een aanbeveling, geen claim over het OpenAI schema. Het standaardschema definieert niet al deze gateway-specifieke bedieningselementen. Ze horen thuis in het controlevlak en de cataloguscompiler van de gateway.

Normaliseer de detectie van providers zonder deze te proxyen

Feit: API's voor het ontdekken van providers leggen verschillende concepten bloot. De modellijst van OpenAI levert identificatiegegevens en basismetagegevens, maar geen volledige mogelijkhedenmatrix voor elk API-oppervlak. Anthropic maakt onderscheid tussen levenscyclusstatussen en kan rijkere mogelijkhedeninformatie retourneren wanneer een model of alias wordt opgehaald. Gemini geeft velden weer zoals tokenlimieten en ondersteunde generatiemethoden. Microsoft Foundry vereist mogelijk een implementatienaam in het veld model, en een implementatie kan incompatibel zijn met een bepaalde API, zelfs als het onderliggende model bestaat.

Daarom is het rechtstreeks doorsturen van antwoorden van providers geen duurzaam ontwerp. Behandel elke provider API als een afstemmingsbron. Converteer de observaties naar een intern record en combineer ze vervolgens met de gatewayconfiguratie en het tenantbeleid.

Gebruik een canonieke catalogusrecord

Een nuttig intern document scheidt het overheidscontract van de upstream-implementatie:

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

Maak target_id, referentiereferenties of interne routeringsstatus niet openbaar via het standaard openbare eindpunt. Deze velden zijn gegevens op het besturingsvlak. Houd ze beschikbaar voor toegangsroutes, ondersteuningstools en gebruiksattributie.

Afzonderlijke ID's, aliassen en implementaties

Een openbaar model-ID is een klantcontract. Een providermodel-ID identificeert een upstream-modelfamilie of -versie. Een implementatienaam identificeert een door de operator gemaakte weergavebron. Ze zijn niet uitwisselbaar.

Repareer een openbare alias naar een onveranderlijke catalogusrevisie voordat u deze doorstuurt. Registreer zowel de aangevraagde ID als het opgeloste doel in de gebruiksgebeurtenis. Als de alias later verandert, kan het ondersteuningspersoneel nog steeds reconstrueren welke implementatie een eerdere oproep heeft afgehandeld.

Stel de catalogus samen voor de geverifieerde sleutel

De cataloguscompiler moet een geverifieerde opdrachtgever ontvangen, niet alleen maar een tenant-ID. Dezelfde tenant kan productiesleutels, ontwikkelingssleutels, beperkte klantsleutels en serviceaccounts met verschillende modeltoekenningen hebben.

Een deterministische compilatiereeks is:

1. Laad de onveranderlijke basiscatalogusrevisie.
2. Tenantlidmaatschap, teamlidmaatschap en sleutelspecifieke toekenningen oplossen.
3. Pas plan-, geografie-, gegevenslocatie- en providerbeperkingen toe.
4. Verwijder routes zonder geldige inloggegevens of compatibele implementaties.
5. Evalueer de routegereedheid met behulp van de huidige statusmomentopname.
6. Aggregeer overgebleven routes in openbare modelrecords.
7. Retourneer alleen API oppervlakken die worden ondersteund door ten minste één overgebleven route.

Gebruik intersectiesemantiek wanneer zowel team- als sleuteltoekenningen bestaan. Een sleutel die aan een beperkt team is toegewezen, mag geen bredere toegang krijgen alleen maar omdat de huurder een breder plan bezit. Dit maakt AI-modeltoegangscontrole voor softwareteams voorspelbaar en vermindert onbedoelde openbaarmaking.

Lijst bijhouden en gedrag identiek ophalen

GET /v1/models/{model} moet hetzelfde autorisatiepredikaat uitvoeren als de lijstbewerking. Anders kan een aanvaller verborgen ID's opsommen door succesvolle, verboden en niet-gevonden reacties te vergelijken.

Voor een model dat de sleutel niet kan zien, retourneert u dezelfde openbare fout die wordt gebruikt voor een onbekend model. Maak niet bekend of een andere tenant het kan gebruiken, welke provider het host, of welk recht het zou ontgrendelen. Beheer-API's kunnen meer gedetailleerde redenen aan geautoriseerde operators bekendmaken.

Representeer API compatibiliteit expliciet

Het bestaan van een model impliceert niet dat elk eindpunt wordt ondersteund. Chatvoltooiingen, reacties, insluitingen, het genereren van afbeeldingen, realtime, batch- en Anthropic berichten hebben verschillende verzoek- en streamingcontracten.

Routetoelating moet daarom zowel een model als een API oppervlak accepteren:

admit(key, public_model_id, api_surface, request_features)

Het resultaat moet een compatibele catalogusrevisie en een of meer in aanmerking komende routes identificeren. Een model kan bijvoorbeeld chat.completions ondersteunen, maar niet responses, of alleen Reacties ondersteunen als ingebouwde tools ontbreken. Een enkele Boolean zoals supports_responses kan onvoldoende zijn als de compatibiliteit afhangt van de gevraagde functies.

Aanbeveling: publiceer conservatieve mogelijkheden. Maak alleen reclame voor een functie als de gateway deze kan afdwingen via de in aanmerking komende routeset of een route kan selecteren die deze deterministisch ondersteunt. Leid geen beeldinvoer, toolaanroepen of gestructureerde uitvoer af van de achternaam van een provider.

Behoud SDK compatibiliteit tijdens het toevoegen van metadata

Houd de standaardvelden die worden verwacht door OpenAI-compatibele clients stabiel:

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

Een extensie met een naamruimte vermindert het risico op botsingen, maar sommige clients negeren onbekende velden. Als toepassingen gedetailleerde selectiegegevens nodig hebben, geef dan een afzonderlijk geverifieerd eindpunt met modelinformatie op met een versieschema. Houd /v1/models klein genoeg voor SDK's, opdrachtregelprogramma's en modelkiezers.

Kies stabiele of op gezondheid gefilterde vermeldingen

Er bestaan twee redelijke beschikbaarheidsbeleidsregels.

Door gezondheid gefilterde catalogus: verberg een model wanneer geen enkele route momenteel in orde is. Dit minimaliseert mislukte oproepen, maar catalogi kunnen fluctueren tijdens incidenten en selecties aan de clientzijde ongeldig maken.

Stabiele catalogus: ga door met het vermelden van de betreffende producten terwijl u availability: temporarily_unavailable rapporteert. Dit is gemakkelijker voor automatiserings- en migratietools, maar klanten kunnen nog steeds proberen aanroepen, tenzij ze de extensie begrijpen.

Een praktische standaard is het verbergen van modellen die niet zijn geïmplementeerd, verboden, ingetrokken of niet in aanmerking komen voor inloggegevens, terwijl tijdelijk niet-beschikbare modellen met een expliciete status voor vertrouwde clients behouden blijven. Het minimale compatibiliteitseindpunt kan niet-beschikbare vermeldingen weglaten als bestaande clients de statusmetagegevens niet kunnen interpreteren.

Voorspelling: klanten met rijkere modelselectie zullen steeds meer afhankelijk zijn van de mogelijkheden en beschikbaarheid van metadata. Totdat dat gedrag in grote lijnen betrouwbaar is, moet routetoelating aan de serverzijde gezaghebbend blijven.

Cache van samengestelde catalogi zonder verouderde subsidies

Stel waar mogelijk catalogi buiten het verzoekpad samen. Een cachesleutel moet ten minste het volgende bevatten:

(tenant_id, key_id, entitlement_version, catalog_revision, policy_revision)

Betreffende vermeldingen ongeldig maken wanneer teamlidmaatschap, modeltoekenningen, prijsplannen, providergegevens, implementatiestatus of routeringsbeleid worden gewijzigd. Korte time-to-live-waarden zijn geen vervanging voor intrekkingsgebeurtenissen: zelfs een korte, verouderde periode kan een nieuw verboden model blootleggen.

Afstemming tussen providers kan asynchroon zijn. Bewaar tijdens een storing in het controlevliegtuig van een provider de laatst bekende catalogus, registreer de observatietijd ervan en voorkom dat nieuwe onzekere routes in aanmerking komen. Hierdoor blijft de lijst responsief zonder verouderde ontdekkingen te beschouwen als bewijs dat een nieuwe route bruikbaar is.

Test de catalogus als toegangscontract

De sterkste conformiteitseigenschap is eenvoudig: voor elk model en API oppervlak dat naar een sleutel wordt geretourneerd, moet de routetoelating slagen onder dezelfde catalogus en statusrevisie.

Geautomatiseerde tests toevoegen voor:

• Een toegestane sleutel kan de toegewezen modellen zien en ophalen.
• Een verboden sleutel die geen lijstitems of ophaalbare metagegevens ziet.
• Teambeperkingen beperken de sleuteltoegang in plaats van deze te verbreden.
• Een implementatie voor alleen chat waarvoor geen reclame wordt gemaakt voor Responses.
• Een uitgeschakelde inloggegevens verwijderen de afhankelijke routes.
• Een alias die wordt omgezet in de verwachte onveranderlijke catalogusrevisie.
• Een gepensioneerd model verdwijnt uit de standaardcatalogus.
• Cache-invalidatie na wijzigingen in subsidies, lidmaatschappen of beleid.
• Onbekende en verborgen model-ID's die niet te onderscheiden openbare fouten veroorzaken.
• Elke geadverteerde mogelijkheid heeft ten minste één in aanmerking komende route.

Synthetische probes kunnen bewijs toevoegen dat een route werkt, maar ze verbruiken quota, kunnen geld kosten en kunnen niet elke functiecombinatie dekken. Gebruik ze voor representatieve routeklassen en combineer ze met implementatiestatus, referentiecontroles en echte verkeersstatus.

Neem voldoende bewijsmateriaal op om beslissingen uit te leggen

Registreer voor elk geaccepteerd of afgewezen verzoek de catalogusrevisie, de aangevraagde openbare model-ID, API oppervlak, opgeloste route, capaciteitscontract, beleidsrevisie en een gestructureerde toelatingsreden. Vermijd het opslaan van promptinhoud uitsluitend voor dit doel.

De implementatievolgorde is eenvoudig: definieer het canonieke record, bouw provider-reconcilers, compileer weergaven per sleutel, maak een lijst en haal deze op, deel één autorisatiepredicaat, verbind routetoegang met dezelfde revisie en voeg negatieve tests toe voordat caches worden ingeschakeld. Zodra deze stukjes op hun plaats zitten, wordt /v1/models een betrouwbaar antwoord op “wat kan deze sleutel oproepen?” in plaats van een losjes gefilterde inventaris.

Gerelateerd leesmateriaal

• het ontwerpen van een Responses API-compatibiliteitslaag