Bygg en Tenant-Aware /v1/models-katalog för en Multi-Model API Gateway

En gateway bör inte returnera alla modeller som är kända för alla anslutna leverantörer från GET /v1/models. Den bör returnera de modeller som den autentiserade API-nyckeln är auktoriserad och operativt kan anropa.

Denna distinktion är viktig när en API-nyckel ger åtkomst till flera LLM-leverantörer. En rå sammanslutning av uppströmskataloger kan inkludera modeller som är förbjudna enligt teampolicy, otillgängliga enligt hyresgästens plan, saknar sunda referenser, inkompatibla med den begärda API, eller som inte distribueras i den nödvändiga regionen. Dessa poster producerar trasiga modellväljare och körtidsfel som upptäckten borde ha förhindrat.

Det praktiska avtalet är starkare: alla annonserade modeller måste klara samma antagningskontroller som skulle gälla för en verklig förfrågan.

Definiera vad "tillgänglig" betyder

Provider existens är bara en ingång. En modell bör endast visas i en nyckels standardkatalog när alla obligatoriska villkor är uppfyllda:

• Gatewayen har en konfigurerad offentlig produkt för modellen.
• Hyresgästen, teamet och API-nyckeln har rätt till den produkten.
• Den tillämpliga kommersiella planen tillåter dess användning.
• Policy tillåter modell, leverantör, region och datahanteringsläge.
• Det finns minst en kompatibel uppströmsimplementering eller rutt.
• En användbar leverantörsuppgifter finns för den rutten.
• Rutten stöder minst en API yta som annonseras i katalogen.
• Rutten är driftsklar enligt gatewayens hälsopolicy.

Uttryckt som en inställd operation:

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

Detta är en rekommendation, inte ett påstående om OpenAI-schemat. Standardschemat definierar inte alla dessa gateway-specifika kontroller. De hör hemma i gatewayens kontrollplan och katalogkompilator.

Normalisera leverantörsupptäckt utan att proxyservera det

Fakta: API:er för leverantörsupptäckt avslöjar olika koncept. OpenAIs modelllista tillhandahåller identifierare och grundläggande metadata, men inte en komplett kapacitetsmatris för varje API yta. Anthropic särskiljer livscykeltillstånd och kan returnera rikare kapacitetsinformation när en modell eller ett alias hämtas. Gemini visar fält som tokengränser och genereringsmetoder som stöds. Microsoft Foundry kan kräva ett distributionsnamn i model-fältet, och en distribution kan vara inkompatibel med ett visst API även när den underliggande modellen finns.

Därför är att vidarebefordra svar från leverantörer direkt inte en hållbar design. Behandla varje leverantör API som en avstämningskälla. Konvertera dess observationer till en intern post och kombinera dem sedan med gatewaykonfiguration och klientpolicy.

Använd en kanonisk katalogpost

En användbar intern post skiljer det offentliga kontraktet från uppströ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"
    }
  ]
}

Exponera inte target_id, referenser för autentiseringsuppgifter eller internt routingtillstånd genom den vanliga offentliga slutpunkten. Dessa fält är kontrollplansdata. Håll dem tillgängliga för rutttillträde, supportverktyg och användningstillskrivning.

Separata ID:n, alias och implementeringar

Ett offentligt modell-ID är ett kundkontrakt. Ett leverantörsmodell-ID identifierar en uppströmsmodellfamilj eller version. Ett distributionsnamn identifierar en operatörskapad serverresurs. De är inte utbytbara.

Lös ett offentligt alias till en oföränderlig katalogrevision innan du dirigerar. Registrera både det begärda ID:t och det lösta målet i användningshändelsen. Om aliaset ändras senare kan supportpersonalen fortfarande rekonstruera vilken distribution som hanterade ett tidigare samtal.

Kompilera katalogen för den autentiserade nyckeln

Katalogkompilatorn bör få en autentiserad principal, inte bara ett klient-ID. Samma hyresgäst kan ha produktionsnycklar, utvecklingsnycklar, begränsade kundnycklar och tjänstekonton med olika modellbidrag.

En deterministisk kompileringssekvens är:

1. Ladda den oföränderliga baskatalogrevisionen.
2. Lös hyresgästmedlemskap, teammedlemskap och nyckelspecifika anslag.
3. Tillämpa begränsningar för plan, geografi, datauppehållstillstånd och leverantör.
4. Ta bort rutter utan giltiga referenser eller kompatibla implementeringar.
5. Utvärdera ruttberedskapen med hjälp av den aktuella hälsoöversiktsbilden.
6. Aggregera överlevande rutter till offentliga modellregister.
7. Returnera endast API ytor som stöds av minst en överlevande rutt.

Använd korsningssemantik när både team- och nyckelanslag finns. En nyckel som tilldelats ett begränsat team bör inte få bredare åtkomst bara för att hyresgästen äger en bredare plan. Detta gör AI-modellens åtkomstkontroll för programvaruteam förutsägbar och minskar oavsiktlig avslöjande.

Behåll listan och hämta beteende identisk

GET /v1/models/{model} måste köra samma auktoriseringspredikat som listoperationen. Annars kan en angripare räkna upp dolda identifierare genom att jämföra framgång, förbjudna och icke-hittade svar.

För en modell som nyckeln inte kan se, returnera samma offentliga fel som används för en okänd modell. Avslöja inte om en annan hyresgäst kan använda den, vilken leverantör som är värd för den eller vilken rättighet som skulle låsa upp den. Administrativa API:er kan avslöja mer detaljerade skäl för auktoriserade operatörer.

Representera API kompatibilitet uttryckligen

En modells existens innebär inte stöd för varje slutpunkt. Chattavslut, svar, inbäddningar, bildgenerering, realtids-, batch- och Anthropic-meddelanden har olika förfrågnings- och streamingkontrakt.

Rutttillträde bör därför acceptera både en modell och en API-yta:

admit(key, public_model_id, api_surface, request_features)

Resultatet bör identifiera en kompatibel katalogrevision och en eller flera kvalificerade rutter. Till exempel kan en modell stödja chat.completions men inte responses, eller stödja svar endast när inbyggda verktyg saknas. En enskild boolesk som supports_responses kan vara otillräcklig när kompatibiliteten beror på begärda funktioner.

Rekommendation: publicera konservativa funktioner. Annonsera en funktion endast när gatewayen kan tillämpa den över den kvalificerade ruttuppsättningen eller kan välja en rutt som stöder den deterministiskt. Dra inte slutledning av bildinmatning, verktygsanrop eller strukturerad utdata från en leverantörs efternamn.

Bevara SDK-kompatibilitet medan du lägger till metadata

Håll standardfälten som förväntas av OpenAI-kompatibla klienter stabila:

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

Ett namnavgränsat tillägg minskar kollisionsrisken, men vissa klienter kasserar okända fält. Om applikationer behöver detaljerade urvalsdata, tillhandahåll en separat autentiserad modellinformationsändpunkt med ett versionsschema. Håll /v1/models tillräckligt liten för SDK:er, kommandoradsverktyg och modellväljare.

Välj stabila eller hälsofiltrerade listor

Det finns två rimliga tillgänglighetspolicyer.

Hälsofiltrerad katalog: dölj en modell när ingen rutt för närvarande är hälsosam. Detta minimerar misslyckade samtal, men kataloger kan fluktuera under incidenter och ogiltigförklara val på klientsidan.

Stabil katalog: fortsätt att lista berättigade produkter samtidigt som du rapporterar availability: temporarily_unavailable. Detta är enklare för automatiserings- och migreringsverktyg, men klienter kan fortfarande försöka ringa om de inte förstår tillägget.

En praktisk standard är att dölja modeller som är outplacerade, förbjudna, pensionerade eller inte kvalificerade för autentiseringsuppgifter, samtidigt som de behåller tillfälligt otillgängliga modeller med en explicit status för betrodda kunder. Den minimala kompatibilitetsslutpunkten kan utelämna otillgängliga poster om befintliga klienter inte kan tolka statusmetadata.

Prognos: rikare modellvalsklienter kommer i allt högre grad att bero på metadata för kapacitet och tillgänglighet. Tills det beteendet är i stort sett tillförlitligt måste rutttillträde på serversidan förbli auktoritativt.

Cachekompilerade kataloger utan att tjäna inaktuella anslag

Kompilera kataloger utanför begäranden om möjligt. En cachenyckel bör innehålla minst:

(tenant_id, key_id, entitlement_version, catalog_revision, policy_revision)

Ogiltigförklara berörda poster när teammedlemskap, modellbidrag, prisplaner, leverantörsuppgifter, implementeringstillstånd eller routingpolicy ändras. Korta tid-till-live-värden är inte en ersättning för återkallelsehändelser: även ett kort inaktuellt fönster kan avslöja en nyligen förbjuden modell.

Leverantörsavstämning kan vara asynkron. Under ett flygplansavbrott, bevara den senast kända katalogen, registrera dess observationstid och förhindra att nya osäkra rutter blir berättigade. Detta gör listorna responsiva utan att behandla inaktuella upptäckter som ett bevis på att en ny rutt är användbar.

Testa katalogen som ett antagningskontrakt

Den starkaste överensstämmelseegenskapen är enkel: för varje modell och API yta som returneras till en nyckel måste rutttillträde lyckas under samma katalog och hälsorevision.

Lägg till automatiska tester för:

• En tillåten nyckel som ser och hämtar sina tilldelade modeller.
• En förbjuden nyckel som varken ser listposter eller återhämtningsbar metadata.
• Teambegränsningar som begränsar, snarare än breddar, nyckelåtkomst.
• En implementering av enbart chatt annonseras inte för svar.
• En inaktiverad referens som tar bort dess beroende rutter.
• Ett alias som löser den förväntade oföränderliga katalogrevisionen.
• En pensionerad modell som försvinner från standardkatalogen.
• Cache-ogiltighet efter ändring av bidrag, medlemskap eller policyer.
• Okända och dolda modell-ID:n som ger oskiljbara offentliga fel.
• Alla annonserade funktioner har minst en kvalificerad rutt.

Syntetiska sonder kan lägga till bevis på att en rutt fungerar, men de förbrukar kvoter, kan kosta pengar och kan inte täcka alla funktioner. Använd dem för representativa ruttklasser och kombinera dem med driftsättningstillstånd, autentiseringskontroller och verklig trafikhälsa.

Anteckna tillräckligt med bevis för att förklara beslut

För varje accepterad eller avvisad begäran, registrera katalogrevisionen, begärt offentligt modell-ID, API yta, löst rutt, kapacitetskontrakt, policyrevision och en strukturerad antagningsanledning. Undvik att lagra snabbt innehåll enbart för detta ändamål.

Implementeringssekvensen är enkel: definiera den kanoniska posten, bygg leverantörsavstämningar, kompilera vyer per nyckel, gör en lista och hämta dela ett auktoriseringspredikat, koppla rutttillträde till samma version och lägg till negativa test innan du aktiverar cachar. När de här delarna är på plats blir /v1/models ett pålitligt svar på "vad kan den här nyckeln ringa?" snarare än ett löst filtrerat inventarium.

Relaterad läsning

• designa ett svar API kompatibilitetslager