Erstellen Sie einen mandantenbewussten /v1/models-Katalog für ein API-Gateway mit mehreren Modellen

Ein Gateway sollte nicht jedes Modell zurückgeben, das jedem verbundenen Anbieter aus GET /v1/models bekannt ist. Es sollte die Modelle zurückgeben, die der authentifizierte API-Schlüssel autorisiert und betriebsbereit aufrufen kann.

Diese Unterscheidung ist wichtig, wenn ein API Schlüssel den Zugriff auf mehrere LLM-Anbieter ermöglicht. Eine Rohvereinigung von Upstream-Katalogen kann Modelle enthalten, die durch Teamrichtlinien verboten sind, im Rahmen des Mandantenplans nicht verfügbar sind, keine gültigen Anmeldeinformationen haben, mit der angeforderten API nicht kompatibel sind oder nicht in der erforderlichen Region bereitgestellt sind. Diese Einträge führen zu fehlerhaften Modellauswahlfunktionen und Laufzeitfehlern, die durch die Erkennung hätten verhindert werden sollen.

Der praktische Vertrag ist stärker: Jedes beworbene Modell muss die gleichen Zulassungsprüfungen bestehen, die für eine echte Anfrage gelten würden.

Definieren Sie, was „verfügbar“ bedeutet

Die Existenz des Anbieters ist nur eine Eingabe. Ein Modell sollte nur dann im Standardkatalog eines Schlüssels erscheinen, wenn alle erforderlichen Bedingungen erfüllt sind:

• Das Gateway verfügt über ein konfiguriertes öffentliches Produkt für das Modell.
• Der Mandant, das Team und der Schlüssel API sind für dieses Produkt berechtigt.
• Der geltende kommerzielle Plan erlaubt seine Nutzung.
• Richtlinie erlaubt Modell, Anbieter, Region und Datenverarbeitungsmodus.
• Mindestens eine kompatible Upstream-Bereitstellung oder Route ist vorhanden.
• Für diese Route sind verwendbare Anbieteranmeldeinformationen verfügbar.
• Die Route unterstützt mindestens eine API im Katalog beworbene Oberfläche.
• Die Route ist gemäß der Integritätsrichtlinie des Gateways betriebsbereit.

Ausgedrückt als Mengenoperation:

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

Dies ist eine Empfehlung, keine Behauptung über das OpenAI-Schema. Das Standardschema definiert nicht alle dieser Gateway-spezifischen Steuerelemente. Sie gehören zur Steuerungsebene und zum Katalogcompiler des Gateways.

Anbietererkennung normalisieren, ohne sie per Proxy zu übertragen

Fakt: Provider Discovery APIs stellen unterschiedliche Konzepte zur Verfügung. Die Modellliste von OpenAI liefert Bezeichner und grundlegende Metadaten, jedoch keine vollständige Fähigkeitsmatrix für jede API-Oberfläche. Anthropic unterscheidet Lebenszykluszustände und kann umfangreichere Funktionsinformationen zurückgeben, wenn ein Modell oder Alias ​​abgerufen wird. Gemini macht Felder wie Token-Limits und unterstützte Generierungsmethoden verfügbar. Microsoft Foundry erfordert möglicherweise einen Bereitstellungsnamen im Feld model und eine Bereitstellung kann mit einem bestimmten API nicht kompatibel sein, selbst wenn das zugrunde liegende Modell vorhanden ist.

Folglich ist die direkte Weiterleitung von Anbieterantworten kein dauerhafter Entwurf. Behandeln Sie jeden Anbieter API als Abgleichsquelle. Wandeln Sie seine Beobachtungen in einen internen Datensatz um und kombinieren Sie sie dann mit der Gateway-Konfiguration und der Mandantenrichtlinie.

Verwenden Sie einen kanonischen Katalogeintrag

Ein nützlicher interner Datensatz trennt den öffentlichen Auftrag von der vorgelagerten Implementierung:

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

Legen Sie target_id, Anmeldeinformationsverweise oder den internen Routing-Status nicht über den standardmäßigen öffentlichen Endpunkt offen. Bei diesen Feldern handelt es sich um Daten der Steuerungsebene. Halten Sie sie für die Weiterleitungszulassung, Support-Tools und Nutzungszuordnung verfügbar.

Separate IDs, Aliase und Bereitstellungen

Eine öffentliche Modell-ID ist ein Kundenvertrag. Eine Anbietermodell-ID identifiziert eine Upstream-Modellfamilie oder -Version. Ein Bereitstellungsname identifiziert eine vom Betreiber erstellte Bereitstellungsressource. Sie sind nicht austauschbar.

Lösen Sie einen öffentlichen Alias vor der Weiterleitung in eine unveränderliche Katalogrevision auf. Notieren Sie sowohl die angeforderte ID als auch das aufgelöste Ziel im Nutzungsereignis. Wenn sich der Alias später ändert, können Supportmitarbeiter immer noch rekonstruieren, welche Bereitstellung einen früheren Anruf bearbeitet hat.

Kompilieren Sie den Katalog für den authentifizierten Schlüssel

Der Katalog-Compiler sollte einen authentifizierten Prinzipal erhalten, nicht nur eine Mandanten-ID. Derselbe Mandant kann über Produktionsschlüssel, Entwicklungsschlüssel, eingeschränkte Kundenschlüssel und Dienstkonten mit unterschiedlichen Modellberechtigungen verfügen.

Eine deterministische Kompilierungssequenz ist:

1. Laden Sie die Revision des unveränderlichen Basiskatalogs.
2. Mandantenmitgliedschaft, Teammitgliedschaft und schlüsselspezifische Zuteilungen klären.
3. Plan-, Geografie-, Datenresidenz- und Anbieterbeschränkungen anwenden.
4. Routen ohne gültige Anmeldeinformationen oder kompatible Bereitstellungen entfernen.
5. Bewerten Sie die Routenbereitschaft anhand des aktuellen Zustands-Snapshots.
6. Überlebende Routen in öffentlichen Modelldatensätzen zusammenfassen.
7. Gibt nur API Oberflächen zurück, die von mindestens einer überlebenden Route unterstützt werden.

Verwenden Sie die Schnittsemantik, wenn sowohl Team- als auch Schlüsselberechtigungen vorhanden sind. Ein einem eingeschränkten Team zugewiesener Schlüssel sollte keinen umfassenderen Zugriff ermöglichen, nur weil der Mieter einen umfassenderen Plan besitzt. Dies macht KI-Modell-Zugriffskontrolle für Softwareteams vorhersehbar und reduziert versehentliche Offenlegung.

Liste und Abrufverhalten identisch halten

GET /v1/models/{model} muss dasselbe Autorisierungsprädikat wie der Listenvorgang ausführen. Andernfalls kann ein Angreifer versteckte Kennungen aufzählen, indem er erfolgreiche, verbotene und nicht gefundene Antworten vergleicht.

Für ein Modell, das der Schlüssel nicht sehen kann, wird derselbe öffentliche Fehler zurückgegeben, der für ein unbekanntes Modell verwendet wurde. Geben Sie nicht bekannt, ob ein anderer Mieter es nutzen kann, welcher Anbieter es hostet oder welche Berechtigung es freischalten würde. Administrative APIs können autorisierten Betreibern detailliertere Gründe offenlegen.

Stellen Sie API Kompatibilität explizit dar

Die Existenz eines Modells bedeutet nicht, dass jeder Endpunkt unterstützt wird. Chat-Abschlüsse, Antworten, Einbettungen, Bildgenerierung, Echtzeit, Batch und Anthropic Nachrichten haben unterschiedliche Anfrage- und Streaming-Verträge.

Die Routenzulassung sollte daher sowohl ein Modell als auch eine API Oberfläche akzeptieren:

admit(key, public_model_id, api_surface, request_features)

Das Ergebnis sollte eine kompatible Katalogrevision und eine oder mehrere geeignete Routen identifizieren. Beispielsweise kann ein Modell chat.completions unterstützen, aber nicht responses, oder Antworten nur unterstützen, wenn integrierte Tools fehlen. Ein einzelner boolescher Wert wie supports_responses reicht möglicherweise nicht aus, wenn die Kompatibilität von den angeforderten Funktionen abhängt.

Empfehlung: konservative Funktionen veröffentlichen. Kündigen Sie eine Funktion nur dann an, wenn das Gateway sie im gesamten berechtigten Routensatz durchsetzen oder eine Route auswählen kann, die sie deterministisch unterstützt. Bildeingaben, Toolaufrufe oder strukturierte Ausgaben nicht aus einem Anbieterfamiliennamen ableiten.

Kompatibilität SDK beim Hinzufügen von Metadaten beibehalten

Halten Sie die von OpenAI-kompatiblen Clients erwarteten Standardfelder stabil:

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

Eine Namespace-Erweiterung verringert das Kollisionsrisiko, aber einige Clients verwerfen unbekannte Felder. Wenn Anwendungen detaillierte Auswahldaten benötigen, stellen Sie einen separaten authentifizierten Modellinformationsendpunkt mit einem versionierten Schema bereit. Halten Sie /v1/models klein genug für SDKs, Befehlszeilentools und Modellauswahl.

Wählen Sie stabile oder gesundheitsgefilterte Einträge

Es gibt zwei angemessene Verfügbarkeitsrichtlinien.

Zustandsgefilterter Katalog: Ein Modell ausblenden, wenn derzeit keine Route fehlerfrei ist. Dies minimiert fehlgeschlagene Aufrufe, aber Kataloge können bei Vorfällen schwanken und clientseitige Auswahlen ungültig machen.

Stabiler Katalog: weiterhin berechtigte Produkte auflisten, während availability: temporarily_unavailable gemeldet wird. Dies ist für Automatisierungs- und Migrationstools einfacher, aber Clients können dennoch Aufrufe versuchen, es sei denn, sie verstehen die Erweiterung.

Eine praktische Standardeinstellung besteht darin, nicht bereitgestellte, verbotene, zurückgezogene oder für Anmeldeinformationen nicht geeignete Modelle auszublenden, während vorübergehend nicht verfügbare Modelle mit einem expliziten Status für vertrauenswürdige Clients beibehalten werden. Der minimale Kompatibilitätsendpunkt kann nicht verfügbare Einträge auslassen, wenn vorhandene Clients Statusmetadaten nicht interpretieren können.

Vorhersage: Umfangreichere Modellauswahl-Clients werden zunehmend auf Metadaten zu Funktionalität und Verfügbarkeit angewiesen sein. Bis dieses Verhalten weitgehend zuverlässig ist, muss die serverseitige Routenzulassung maßgebend bleiben.

Kompilierte Kataloge zwischenspeichern, ohne veraltete Zuschüsse bereitzustellen

Kompilieren Sie Kataloge nach Möglichkeit außerhalb des Anforderungspfads. Ein Cache-Schlüssel sollte mindestens Folgendes enthalten:

(tenant_id, key_id, entitlement_version, catalog_revision, policy_revision)

Betroffene Einträge ungültig machen, wenn sich Teammitgliedschaft, Modellzuteilungen, Preispläne, Anbieteranmeldeinformationen, Bereitstellungsstatus oder Routing-Richtlinien ändern. Kurze Gültigkeitsdauerwerte sind kein Ersatz für Sperrereignisse: Selbst ein kurzes veraltetes Fenster kann ein neu verbotenes Modell aufdecken.

Der Anbieterabgleich kann asynchron erfolgen. Bewahren Sie bei einem Ausfall der Provider-Steuerungsebene den letzten bekannten Katalog auf, zeichnen Sie dessen Beobachtungszeit auf und verhindern Sie, dass neu unsichere Routen in Frage kommen. Dadurch bleibt die Auflistung reaktionsfähig, ohne dass veraltete Entdeckungen als Beweis dafür betrachtet werden, dass eine neue Route verwendbar ist.

Katalog als Aufnahmevertrag testen

Die stärkste Konformitätseigenschaft ist einfach: Für jedes Modell und jede API Oberfläche, die an einen Schlüssel zurückgegeben werden, muss die Routenzulassung unter demselben Katalog und derselben Zustandsrevision erfolgreich sein.

Automatisierte Tests hinzufügen für:

• Ein zulässiger Schlüssel, der seine zugewiesenen Modelle sieht und abruft.
• Ein verbotener Schlüssel, der weder Listeneinträge noch abrufbare Metadaten sieht.
• Teameinschränkungen schränken den Schlüsselzugriff ein, anstatt ihn zu erweitern.
• Eine reine Chat-Bereitstellung, die nicht für Antworten angekündigt wird.
• Eine deaktivierte Anmeldeinformation, die ihre abhängigen Routen entfernt.
• Ein Alias, der zur erwarteten unveränderlichen Katalogrevision aufgelöst wird.
• Ein ausgemustertes Modell verschwindet aus dem Standardkatalog.
• Cache-Ungültigmachung nach Änderung von Zuschüssen, Mitgliedschaften oder Richtlinien.
• Unbekannte und versteckte Modell-IDs führen zu nicht unterscheidbaren öffentlichen Fehlern.
• Jede beworbene Funktion verfügt über mindestens eine geeignete Route.

Synthetische Sonden können Beweise dafür liefern, dass eine Route funktioniert, aber sie verbrauchen Kontingent, können Geld kosten und können nicht jede Funktionskombination abdecken. Verwenden Sie sie für repräsentative Routenklassen und kombinieren Sie sie mit dem Bereitstellungsstatus, Anmeldeinformationsprüfungen und dem Zustand des tatsächlichen Datenverkehrs.

Erfassen Sie genügend Beweise, um Entscheidungen zu erklären

Erfassen Sie für jede angenommene oder abgelehnte Anfrage die Katalogrevision, die angeforderte öffentliche Modell-ID, die API Oberfläche, die gelöste Route, den Fähigkeitsvertrag, die Richtlinienrevision und einen strukturierten Zulassungsgrund. Vermeiden Sie es, Aufforderungsinhalte ausschließlich für diesen Zweck zu speichern.

Die Implementierungssequenz ist unkompliziert: Definieren Sie den kanonischen Datensatz, erstellen Sie Anbieterabgleicher, kompilieren Sie Ansichten pro Schlüssel, erstellen Sie für die Liste und den Abruf ein gemeinsames Autorisierungsprädikat, verbinden Sie die Routenzulassung mit derselben Revision und fügen Sie negative Tests hinzu, bevor Sie Caches aktivieren. Sobald diese Teile vorhanden sind, wird /v1/models zu einer zuverlässigen Antwort auf die Frage „Wie kann dieser Schlüssel heißen?“ statt eines lose gefilterten Inventars.

Verwandte Lektüre

• Entwerfen einer Kompatibilitätsebene für Antworten API