AI-API-Gateway-Architektur: Ein Schlüssel, Model-Routing und Failover

Ein AI-API-Gateway gibt einer Anwendung einen stabilen Endpunkt, während die Infrastruktur hinter diesem Endpunkt mehrere Modelle, Provider, Konten oder Regionen verwenden kann. Der nützliche Teil besteht nicht nur darin, mehrere API-Schlüssel hinter einem Schlüssel zu verbergen. Der nützliche Teil ist, einen kontrollierten Entscheidungspunkt für jede Anfrage zu schaffen.

Dieser Entscheidungspunkt kann operative Fragen beantworten, bevor Traffic einen Modellanbieter erreicht:

• Ist dieser Client berechtigt, das angeforderte Modell aufzurufen?
• Welches Upstream erfüllt derzeit die Anforderungen der Anfrage an Fähigkeiten, Latenz und Kosten?
• Ist dieses Upstream gesund genug, um weiteren Traffic zu erhalten?
• Kann die Anfrage sicher erneut versucht werden?
• Welcher Fallback bewahrt den Antwortvertrag?
• Wie wird das Team die Route, die Kosten und den Fehler im Nachhinein erklären?

Dieser Leitfaden ordnet diese Verantwortlichkeiten in eine Produktionsarchitektur ein. Er zeigt auch, wo ein einzelner API-Schlüssel hilft, wo er nicht hilft und wie man einen OpenAI-kompatiblen Client migriert, ohne das Gateway zu einer unsichtbaren Quelle von Routing-Überraschungen zu machen.

The reference architecture in one request path

Eine praktische AI-Gateway-Anfrage durchläuft fünf Schichten:

1. Clientvertrag: Die Anwendung sendet eine authentifizierte Anfrage an eine stabile Base URL.
2. Zugriffskontrollen: Das Gateway validiert Identität, Kontingent, Modellberechtigungen, Payload-Grenzen und Anfrage-Metadaten.
3. Routing-Richtlinie: Eine Policy-Engine wandelt das angeforderte Modell oder die Fähigkeit in zulässige Upstream-Ziele um.
4. Ausführungskontrollen: Gesundheitsstatus, Parallelität, Timeout-, Retry-, Fallback- und Streaming-Regeln bestimmen, wie das ausgewählte Ziel aufgerufen wird.
5. Telemetry und Abrechnung: Das Gateway zeichnet die ausgewählte Route, den Antwortstatus, die Latenz, die Token- oder Mediennutzung und die Kostenzuordnung auf.

Application / agent
        |
        |  one API key + stable request schema
        v
AI API gateway
  ├─ authentication and tenant policy
  ├─ model alias and capability registry
  ├─ routing policy and budget rules
  ├─ health, timeout, retry, and fallback controls
  └─ logs, traces, usage, and cost attribution
        |
        ├────────> Provider or deployment A
        ├────────> Provider or deployment B
        └────────> Provider or deployment C

Das Gateway ist daher sowohl ein Control Plane als auch ein Data Plane. Das Control Plane speichert Richtlinien, Anmeldedaten, Aliase, Kontingente und Routing-Konfigurationen. Das Data Plane verarbeitet Live-Anfragen, Streaming-Antworten, Retries und Telemetrie. Wenn diese Verantwortlichkeiten konzeptionell getrennt bleiben, werden Änderungen sicherer: Betreiber können die Routing-Richtlinie aktualisieren, ohne dass jedes Anwendungsteam neuen Client-Code ausliefern muss.

What “one key” should mean

„Ein Schlüssel“ sollte ein Credential-Vertrag für die anwendungsseitige Nutzung bedeuten, nicht ein Credential, das von jeder Person, jedem Dienst und jeder Umgebung gemeinsam verwendet wird.

Ein solides Design vergibt getrennte Gateway-Credentials für Produktion, Staging, lokale Entwicklung, CI und unabhängige Workloads. Jeder Schlüssel sollte einen engen Geltungsbereich, einen Besitzer, ein Kontingent und einen Widerrufsweg haben. Das Gateway behält dann die Provider-Credentials serverseitig und ordnet einer eingehenden Identität die Upstream-Credentials zu, die sie verwenden darf.

Dies schafft eine nützliche Sicherheitsgrenze:

Der Gateway-Schlüssel sollte niemals als Anlass dienen, die Schlüsselhygiene zu lockern. Bewahren Sie ihn in einem Secret Manager auf, niemals in Browser-Code oder einem öffentlichen Repository, rotieren Sie ihn und trennen Sie ihn nach Umgebung. Eine tiefere operative Checkliste finden Sie unter sichere API-Key-Verwaltung für KI-Produkte.

Modell-Aliase trennen den Client-Vertrag von den Providern

Die erste Routing-Abstraktion ist ein Modell-Alias. Anstatt eine provider-spezifische Modellkennung in einer Anwendung hart zu codieren, fordert der Client einen stabilen Namen an, wie zum Beispiel:

support-fast
reasoning-high
code-review-default
image-generation-standard

Das Registry-System hinter jedem Alias definiert einen Fähigkeitsvertrag. Ein Text-Alias könnte Tool-Aufruf, strukturierte Ausgabe, minimale Kontextgröße, Streaming-Unterstützung und eine freigegebene Fallback-Familie festlegen. Ein Bild- oder Video-Alias benötigt andere Felder, etwa akzeptierte Eingabetypen, Ausgabeabmessungen, asynchrones Job-Verhalten und Sicherheitsbeschränkungen.

Ein Alias sollte nicht versprechen, dass sich jedes Kandidatenmodell identisch verhält. Er sollte das Mindestverhalten definieren, auf das sich die Anwendung verlassen kann.

alias: support-fast
contract:
  modality: text
  streaming: true
  tools: optional
  structured_output: required
  maximum_latency_ms: 3500
routes:
  - target: provider-a/model-fast
    priority: 1
  - target: provider-b/model-balanced
    priority: 2

Diese Indirektion macht eine stabile Basis-URL wertvoll. Anwendungen integrieren sich mit dem Alias-Vertrag; Plattformverantwortliche können den Zielsatz nach einer Evaluierung, einem Provider-Vorfall, einer Preisänderung oder einer regionalen Anforderung ändern.

Die Routing-Entscheidung sollte explizit sein

Produktions-Routing kombiniert normalerweise harte Filter und weiches Ranking.

1. Harte Eignungsfilter anwenden

Entfernen Sie jedes Ziel, das die Anfrage nicht erfüllen kann. Häufige Filter sind:

• Erforderliche Modalität und Eingabetyp
• Anforderung an Kontextfenster oder Ausgabegröße
• Unterstützung für Tool-Aufrufe oder strukturierte Ausgabe
• Datenresidenz oder regionale Verfügbarkeit
• Allowlist für Mandant oder Projekt
• Sicherheits- oder Compliance-Richtlinie
• Aktueller Quota-, Rate-Limit- oder Concurrent-Status
• Streaming-Kompatibilität

Ein Ziel, das eine harte Anforderung nicht erfüllt, sollte niemals gewinnen, nur weil es günstiger ist.

2. Die geeigneten Ziele ranken

Nach dem Filtern werden die verbleibenden Routen bewertet. Eine einfache Richtlinie kann leichter zu betreiben sein als ein undurchsichtiger Optimierer:

route score =
  quality_weight × evaluation_score
  - latency_weight × predicted_latency
  - cost_weight × estimated_cost
  - risk_weight × recent_error_rate

Die Gewichtungen sollten je nach Workload unterschiedlich sein. Interaktiver Chat kann die Zeit bis zum ersten Token priorisieren. Ein nächtlicher Extraktionsjob kann die Kosten pro erfolgreich strukturiertem Datensatz bevorzugen. Ein Coding-Agent kann Tool-Zuverlässigkeit und Langkontext-Verhalten stärker gewichten als einen kleinen Preisunterschied.

3. Den Grund protokollieren

Jede Routing-Entscheidung sollte maschinenlesbare Metadaten erzeugen, wie zum Beispiel:

{
  "requested_alias": "support-fast",
  "selected_target": "provider-a/model-fast",
  "policy_version": "support-fast-2026-07-29.3",
  "selection_reason": "healthy_primary_within_latency_budget",
  "fallback_count": 0
}

Wenn ein Team nicht rekonstruieren kann, warum eine Route ausgewählt wurde, kann es weder Kostenabweichungen, Qualitätsregressionen noch Vorfälle beim Provider debuggen.

Health-Checks brauchen mehr als ein HTTP 200

Ein Upstream kann erfolgreiche Health-Probes zurückgeben und dennoch echten Modelltraffic scheitern lassen. Die Gesundheit eines AI Gateways braucht daher mehrere Signale:

• Transportzustand: Verbindungsfehler, TLS-Fehler, DNS-Fehler und Upstream-Timeouts
• API-Zustand: Rate-Limit-Antworten, Authentifizierungsfehler, Provider-Fehler und fehlerhafte Antworten
• Modellzustand: leere Ausgabe, ungültige strukturierte Ausgabe, fehlerhafte Tool-Aufrufe oder inkompatible Streaming-Chunks
• Performance-Zustand: Zeit bis zum ersten Token, Gesamtlatenz, Warteschlangenzeit und Durchsatz
• Kapazitätszustand: gleichzeitige Anfragen, Token-pro-Minute-Druck, Kontostand oder Deployment-Quota

Verwenden Sie ein gleitendes Zeitfenster statt eines einzelnen Fehlers. Ein Circuit Breaker kann einen Target nach Überschreiten seiner Fehler- oder Latenzschwelle vorübergehend entfernen und dann vor der Wiederherstellung des vollständigen Traffics begrenzte Probes zulassen. Outlier Detection kann außerdem ein fehlerhaftes Deployment aussondern, während gesunde Deployments desselben Providers verfügbar bleiben.

Das Prinzip ist in Gateway- und Service-Mesh-Infrastrukturen gut etabliert: Retries, Circuit Breaking und Outlier Detection sind separate Mechanismen, und jeder benötigt eine begrenzte Richtlinie. Envoy dokumentiert diese Mechanismen unabhängig voneinander in seiner Anleitung zu HTTP-Retries, Circuit Breaking und Outlier Detection.

Nur erneut versuchen, wenn die Anfrage sicher ist

Retries verbessern die Zuverlässigkeit nur dann, wenn sie die Arbeit nicht vervielfachen oder doppelte Nebenwirkungen erzeugen.

Für eine nicht-streamende Text-Vervollständigung, die fehlgeschlagen ist, bevor irgendwelche Antwortbytes angekommen sind, kann ein einzelner Retry gegen denselben Target sinnvoll sein. Für eine Anfrage, die ein Tool auslöst, einen Bild- oder Video-Job startet, ein externes Konto belastet oder bereits teilweise Ausgabe gestreamt hat, kann ein blindes erneutes Versuchen Duplikate erzeugen oder die Nutzererfahrung beschädigen.

Definieren Sie die Retry-Berechtigung anhand von drei Fragen:

1. Wurde die Anfrage stromaufwärts akzeptiert? Ein Verbindungsfehler vor der Annahme ist etwas anderes als ein Timeout, nachdem der Anbieter mit der Arbeit begonnen hat.
2. Hat irgendeine Ausgabe den Client erreicht? Sobald das Streaming beginnt, kann ein Anbieterwechsel eine unterbrochene Antwort erzeugen.
3. Gibt es einen Idempotency-Key oder einen Deduplizierungsdatensatz? Langlaufende Medien- und Agent-Workflows benötigen eine stabile Operationsidentität.

Eine konservative Retry-Matrix sieht so aus:

Halten Sie eine einzige End-to-End-Deadline ein. Wenn der Client acht Sekunden erlaubt, kann das Gateway nicht sieben Sekunden für das primäre Ziel verbrauchen und dem Fallback dann noch einmal acht Sekunden geben. Jeder Versuch verbraucht dasselbe Request-Budget.

Fallbacks müssen den Vertrag bewahren

Ein Fallback ist nicht einfach „ein anderes Modell ausprobieren“. Es ist eine Vereinbarung darüber, was sich ändern darf, wenn der primäre Pfad fehlschlägt.

Definieren Sie Fallbacks auf drei Ebenen:

1. Dasselbe Modell, andere Bereitstellung oder anderes Konto: geringstes Verhaltensrisiko; nützlich bei Quoten- oder regionalen Ausfällen.
2. Äquivalente Modellfamilie: moderates Risiko; erfordert Regressionstests für Schema, Tools, Sicherheit und Ausgabestil.
3. Reduzierte Fähigkeit: höchstes Risiko; kann Tools deaktivieren, den Kontext verkleinern oder statt einer Live-Antwort eine in der Warteschlange befindliche Antwort zurückgeben.

Dokumentieren Sie für jeden Alias:

• Welche Fehlerklassen ein Fallback auslösen
• Welche Ziele kontraktkompatibel sind
• Ob dem Client mitgeteilt wird, dass ein Fallback erfolgt ist
• Maximale Versuche und gesamte Deadline
• Wie Qualitäts- und Kostenänderungen gemessen werden
• Ob die Antwort gecacht oder erneut abgespielt werden darf

Regionaler Provider-Zugriff fügt eine weitere Dimension hinzu. Ein Anbieter oder Modell kann in einer Geografie, einem Kontotyp oder einer kommerziellen Vereinbarung verfügbar sein und in einer anderen nicht. Regionales LLM-Provider-Routing erläutert die separaten Zugriffs-, Richtlinien- und Failover-Prüfungen, die für diese Pfade erforderlich sind.

Streaming ist Teil des Gateway-Vertrags

OpenAI-kompatible Request-Formate können die Client-Migration vereinfachen, aber Streaming-Kompatibilität erfordert eine bewusste Übersetzung. Das Gateway muss die Reihenfolge der Events, Abschlussgründe, Nutzungsmetadaten, Fragmente von Tool-Aufrufen, Fehlersignalisierung und Verbindungsabbruch beibehalten.

Bevor Sie zwei Modelle hinter einem Streaming-Alias routen, testen Sie:

• Zeit bis zum ersten Event und Heartbeat-Verhalten
• Inkrementales Text-Delta-Format
• Zusammenführung von Tool-Call-Argumenten
• Usage-Reporting im letzten Event
• Weitergabe von Client-Abbrüchen
• Timeout-Verhalten vor und nach dem ersten Event
• Fehlerformat, nachdem Header bereits gesendet wurden

Verstecken Sie einen Stream-Neustart nicht in einer einzelnen Antwort, sofern das Protokoll nicht ausdrücklich eine Wiederaufnahme unterstützt. In den meisten Clients ist es schlechter, eine Teilantwort eines Modells mit einer zweiten Antwort eines anderen Modells zu vermischen, als einen klaren Fehler zurückzugeben.

Observability verbindet Routing mit Ergebnissen

Gateway-Dashboards sind nützlich, aber die Diagnose in der Produktion erfordert strukturierte Telemetrie, die eine Modellanfrage mit dem umliegenden Anwendungstrace verknüpfen kann.

Mindestens sollten Sie erfassen:

Vermeiden Sie standardmäßig das Protokollieren roher Prompts und Ausgaben. Erfassen Sie Inhalte nur dann, wenn der Anwendungsfall, die Aufbewahrungsrichtlinie und die Erwartungen der Nutzer dies zulassen. Das OpenTelemetry-Projekt pflegt weiterentwickelte semantische Konventionen für generative KI-Systeme, die Teams dabei helfen können, konsistente Span- und Messnamen zu verwenden, statt für jeden Anbieter ein separates Schema zu erfinden.

Kostenkontrollen gehören vor den Upstream-Aufruf

Nachträgliche Ausgabenberichte können einen Vorfall nicht verhindern. Admission- und Routing-Richtlinien sollten die Kosten prüfen, bevor Traffic gesendet wird.

Nützliche Kontrollen umfassen:

• Harte Quoten pro Schlüssel und pro Projekt
• Weiche Budgetwarnungen
• Maximale Ein- oder Ausgabeeinheiten
• Modell-Allowlists nach Umgebung
• Kostenbewusstes Routing für flexible Workloads
• Cache-Richtlinie für wiederholbare Anfragen
• Parallelitätsgrenzen für teure Medien-Jobs
• Kill-Switches für ein Modell, einen Anbieter, einen Mandanten oder eine Route

Die Routing-Engine benötigt eine versionierte Preistabelle und eine konsistente Ebene zur Normalisierung der Nutzung. Andernfalls kann eine Richtlinie für das „günstigste Modell“ inkompatible Einheiten oder veraltete Preise vergleichen. Ein Framework, das Anbieterraten, Plattformgebühren und operative Kontrollen trennt, finden Sie unter AI gateway pricing.

Eine minimale OpenAI-kompatible Migration

Die kleinste Änderung auf Client-Seite ist in der Regel ein neuer API-Schlüssel, eine neue Base-URL und ein neuer Modellname. Mit einem OpenAI-kompatiblen Gateway kann der Anwendungscode dieselbe Client-Bibliothek beibehalten:

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.chat.completions.create(
    model="your-model-or-alias",
    messages=[
        {"role": "user", "content": "Fassen Sie diesen Vorfallbericht zusammen."}
    ],
)

Diese Codeänderung ist der einfache Teil. Eine sichere Migration hat vier Phasen:

1. Inventarisieren Sie den aktuellen Vertrag. Dokumentieren Sie Modelle, Parameter, Streaming-Verhalten, Tools, Schemas, Timeouts und Fehlerbehandlung.
2. Führen Sie Shadow- oder Offline-Evaluierungen durch. Vergleichen Sie Ausgabequalität, Schema-Gültigkeit, Latenz und Kosten anhand repräsentativer Anfragen.
3. Führen Sie einen Canary für eine Arbeitslast ein. Beginnen Sie mit einem begrenzten Verkehrsanteil und einem sofortigen Rollback-Pfad.
4. Aktivieren Sie Routing-Funktionen separat. Ändern Sie zuerst den Endpunkt, fügen Sie dann Aliase hinzu, danach ein health-basiertes Failover und schließlich Kosten- oder Qualitätsoptimierung.

Wenn Sie diese Änderungen voneinander trennen, lassen sich Vorfälle diagnostizieren. Wenn die Endpunktmigration, der Modelltausch, die Retry-Richtlinie und der Kostenoptimierer alle gleichzeitig starten, weiß das Team nicht, welche Variable eine Regression verursacht hat. Der Flatkey-Integrations-Starter behandelt das Base-URL-Migrationsmuster ausführlicher.

Checkliste für Produktionsreife

Verwenden Sie diese Checkliste, bevor Sie das Gateway als gemeinsame Infrastruktur behandeln.

Client-Vertrag

• Stabile Base-URL und versioniertes Request-Schema
• Benannte Aliase mit dokumentierten Mindestfähigkeiten
• Konsistente Fehlerhülle und Request-IDs
• Getestetes Streaming, Tool-Aufrufe und strukturierte Ausgabe

Identität und Sicherheit

• Getrennte Schlüssel nach Dienst und Umgebung
• Provider-Zugangsdaten serverseitig
• Schlüsselbereiche, Quoten, Rotation und Widerruf
• Prompt- und Response-Logging deaktiviert oder ausdrücklich geregelt

Routing und Zuverlässigkeit

• Harte Eignungsfilter vor der Kostenreihung
• Versionierte Routing-Richtlinien und Preisdaten
• Gesundheitsstatus basierend auf echtem Anfrageverhalten
• Begrenzte Retries mit einer End-to-End-Deadline
• Vertraglich kompatible Fallback-Ziele
• Circuit Breaker und Recovery-Probes

Operations

• Telemetrie zu Routing-Grund, Provider-Fehler, Latenz und Nutzung
• Warnungen für Fallback-Rate, Fehlerquote, Kostenabweichung und Quotendruck
• Kill Switches pro Modell und pro Route
• Runbook für Provider-Ausfall und Gateway-Ausfall
• Direkter oder alternativer Notfallpfad für kritische Arbeitslasten

Wie Flatkey in diese Architektur passt

Flatkey bietet einen API-Schlüssel, eine OpenAI-kompatible Base-URL und ein Dashboard für unterstützten Modellzugang, Nutzung und Abrechnung. Sein Router ist darauf ausgelegt, separate Provider-Konten und fragmentierte Integrationspfade zu reduzieren und gleichzeitig ein Switching zwischen Upstream-Anbietern sowie Load Balancing zu unterstützen.

Für ein Anwendungsteam liegt der architektonische Vorteil in einer stabilen Client-Grenze: Ein OpenAI-kompatibler Client wird auf https://router.flatkey.ai/v1 ausgerichtet, ein unterstütztes Modell ausgewählt, und der Modellzugriff bleibt hinter demselben Gateway-Endpunkt verborgen. Teams sollten dennoch ihre eigenen vertraglichen Vereinbarungen auf Anwendungsebene, Evaluierungsschwellen, Schlüsselbereiche, Ausfallbudgets und Fallback-Erwartungen definieren.

Die beste Gateway-Architektur macht Routing nicht unsichtbar. Sie macht Routing veränderbar, begrenzt und erklärbar.

FAQ

Was ist ein AI-API-Gateway?

Ein AI-API-Gateway ist eine Vermittlungsschicht zwischen Anwendungen und Modellanbietern. Es zentralisiert Authentifizierung, Modellzugriff, Routing, Zuverlässigkeitskontrollen, Nutzungsverfolgung und Richtlinien, während es eine stabile API für den Client bereitstellt.

Bedeutet ein API-Schlüssel, dass jeder Dienst denselben Schlüssel teilt?

Nein. Das bedeutet, dass Anwendungen vom Gateway ausgestellte Anmeldedaten verwenden, anstatt jede Anbieter-Anmeldeinformation direkt zu verwalten. Produktionsdienste, Umgebungen und Teams sollten weiterhin separate, begrenzte Schlüssel erhalten.

Was ist Model-Routing?

Model-Routing ist der Prozess des Filterns geeigneter Modelle oder Deployments und der Auswahl eines Ziels anhand von Fähigkeiten, Richtlinien, Zustand, Latenz, Qualität, Kosten, Region oder Kapazität.

Was ist die sicherste Fallback-Strategie?

Beginnen Sie mit demselben Modell auf einem anderen gesunden Deployment oder Konto. Ein Fallback auf ein anderes Modell sollte erst dann erfolgen, wenn Tests zeigen, dass das alternative Ziel das Schema, die Tools, das Streaming, die Sicherheits- und die Qualitätsvereinbarung der Anwendung beibehält.

Kann ein Gateway eine Streaming-Antwort auf ein anderes Modell erneut versuchen?

Normalerweise nicht, nachdem bereits Ausgabe beim Client angekommen ist. Ein Wechsel während des Streams kann inkompatible Teilantworten kombinieren. Verwenden Sie einen klaren Stream-Fehler, es sei denn, Client und Gateway implementieren ein explizites Resume-Protokoll.

Reicht eine OpenAI-kompatible API für eine Migration ohne Änderungen aus?

Sie reduziert SDK- und Request-Form-Änderungen, aber Teams müssen dennoch unterstützte Parameter, Fehler, Streaming-Ereignisse, Tool-Aufrufe, strukturierte Ausgabe, Token-Berechnung und das Modellverhalten überprüfen.