7 Migrationstests vor einem Wechsel der KI-API-Basis-URL

Migrationstests für die Basis-URL der KI-API sollten vor den Änderungen der Umgebungsvariablen stattfinden, nicht nachdem der Produktionsverkehr ausfällt. Die Änderung einer einzigen baseURL oder base_url kann Authentifizierung, Modellauswahl, Streaming, Tool-Aufrufe, Nutzungsaufzeichnungen, Quotenverhalten und Rollback-Kontrolle gleichzeitig auf einen neuen Pfad verschieben.

Flatkey ist für Teams konzipiert, die einen einzigen Schlüssel, eine OpenAI-kompatible Routing-Schicht und eine klarere Abrechnungs- und Nutzungsübersicht über verschiedene Modellanbieter hinweg wünschen. Die öffentliche Flatkey-Homepage zeigte am 7. Juli 2026 die Beispielroute https://router.flatkey.ai/v1/chat/completions, während die aktuellen Seiten für Modelle und Preise den Kontext für Modell, Endpunkt, Anbieter und Abrechnung zur Überprüfung darlegten. Behandeln Sie diese Seiten als Nachweis für den Migrationstag und führen Sie dann Ihre eigenen Smoke-Tests für Ihr Konto durch, bevor Sie den Datenverkehr umleiten.

Verwenden Sie diesen Leitfaden als praktische Abfolge von Migrationstests für die KI-API-Basis-URL. Das Ziel ist nicht, jeden App-Pfad zu beweisen. Das Ziel ist, den kleinsten sicheren Pfad durch die neue Basis-URL zu beweisen und dann Funktionen schichtweise hinzuzufügen.

Die 7 Migrationstests für die KI-API-Basis-URL

Führen Sie die Tests in dieser Reihenfolge durch. Jeder Test sollte einen Nachweis erbringen, den Sie einem Deployment-Ticket beifügen können.

Überspringen Sie die frühen Tests nicht, nur weil ein Framework-Wrapper bereits in der Staging-Umgebung funktioniert hat. Die meisten Migrationstests für die KI-API-Basis-URL schlagen fehl, weil das SDK stillschweigend einen anderen Schlüssel liest, den falschen Basis-URL-Stamm erhält oder ein gültiges Modell an die falsche Endpunktfamilie sendet.

Test 1: Authentifizierung und Zusammensetzung der Basis-URL

Beginnen Sie außerhalb der Anwendung. Sie müssen nachweisen, dass der Schlüssel und die Basis-URL die einfachste Endpunktform erreichen können.

Der häufigste Fehler bei der Basis-URL besteht darin, den vollständigen Endpunkt an das SDK zu übergeben. Bei einem OpenAI-kompatiblen SDK ist die Basis-URL normalerweise der API-Stamm, wie z. B. https://router.flatkey.ai/v1, und das SDK hängt /chat/completions, /responses oder einen anderen Endpunkt an. Die Übergabe von https://router.flatkey.ai/v1/chat/completions als Basis-URL kann zu einem doppelten Pfad führen.

Verwenden Sie zuerst eine geschwärzte Umgebungsprüfung:

test -n "$FLATKEY_API_KEY" && echo "FLATKEY_API_KEY is set"
printf '%s' "$FLATKEY_API_KEY" | wc -c
printf '%s\n' "$FLATKEY_BASE_URL"

Machen Sie dann eine direkte Anfrage:

export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-current-flatkey-model-alias"

curl -sS "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      {"role": "user", "content": "Reply with exactly: base url ok"}
    ]
  }'

Wenn dies 401 zurückgibt, korrigieren Sie den Schlüssel und den Auth-Header, bevor Sie die Modelle ändern. Wenn es 404 zurückgibt, überprüfen Sie den Host, den /v1-Stamm und ob der Endpunktpfad dupliziert wurde. Wenn es 403 zurückgibt, überprüfen Sie die Richtlinien für Konto, Projekt, Modell, Region oder IP. Die Fehlercode-Dokumentation von OpenAI behandelt 401 als Authentifizierung, 429 als Raten- oder Quotenlimit und 500 oder 503 als Server- oder Überlastungszustände; ein Gateway kann weitere Details hinzufügen, speichern Sie also den Antworttext.

Test 2: Modellkatalog und Endpunktfamilie

Eine OpenAI-kompatible Basis-URL macht nicht jeden Modellnamen portabel. Die OpenAI-API hat einen Endpunkt zum Auflisten von Modellen (List models), und ihre Endpunkte für Chat-Vervollständigungen (Chat Completions) und Antworten (Responses) verwenden unterschiedliche Anfrageformate. Eine Gateway- oder anbieterkompatible Route kann ein Modell für eine Endpunktfamilie verfügbar machen, aber nicht für eine andere.

Bevor Sie die Produktionskonfiguration ändern, erstellen Sie eine kleine Modellzuordnung:

Die Erfolgsbedingung lautet nicht „der Modellname sieht richtig aus“. Die Erfolgsbedingung ist, dass die aktuelle Flatkey-Konsole, das Modellverzeichnis oder der Anbieterkatalog den exakten Alias für die exakte Endpunktfamilie anzeigt, die Sie aufrufen möchten. Verknüpfen Sie diese Arbeit mit Ihrer umfassenderen Modell-Governance mithilfe des Leitfadens für OpenAI-kompatible Modellnamen.

Test 3: Einfache Chat-Vervollständigung

Der dritte Migrationstest für die KI-API-Basis-URL ist die kleinste echte Generierungsanfrage. Halten Sie sie nicht-streamend. Fügen Sie keine Tools, JSON-Schema, Dateien, Bilder, Wiederholungsversuche oder App-Middleware hinzu.

Speichern:

Wenn die einfache Anfrage fehlschlägt, debuggen Sie das Streaming noch nicht. Verwenden Sie den Leitfaden zur Fehlerbehebung bei OpenAI-kompatiblen APIs, um zuerst Probleme mit dem Schlüssel, der Route, der Endpunktfamilie und dem Modell-Alias zu isolieren.

Test 4: SDK-Parität

Nachdem curl funktioniert, beweisen Sie, dass das SDK dieselbe Route erstellt. Die aktuellen offiziellen Dokumente von OpenAI verweisen Entwickler auf die offiziellen SDKs für JavaScript und Python. Das OpenAI-Cookbook zeigt auch die Verwendung benutzerdefinierter Endpunkte, bei denen ein Client mit einem Token und einer benutzerdefinierten Basis-URL erstellt wird. Machen Sie dies für die Migration im Code explizit, anstatt sich auf übrig gebliebene OPENAI_API_KEY- oder OPENAI_BASE_URL-Werte zu verlassen.

Python-Vorlage:

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[{"role": "user", "content": "Reply with exactly: sdk ok"}],
)

print(response.choices[0].message.content)
print(response.usage)

Node-Vorlage:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL!,
  messages: [{ role: "user", content: "Reply with exactly: sdk ok" }],
});

console.log(response.choices[0]?.message?.content);
console.log(response.usage);

Protokollieren Sie die aufgelöste Basis-URL beim Prozessstart, aber protokollieren Sie nicht den Schlüssel. Wenn curl erfolgreich ist und das SDK fehlschlägt, überprüfen Sie die Priorität der Umgebungsvariablen, die SDK-Version, die Pfadverknüpfung, die Organisations-/Projekt-Header und das Proxy-Verhalten, bevor Sie das Modell ändern.

Test 5: Streaming oder SSE

Streaming ist der Punkt, an dem viele Migrationen auf der HTTP-Ebene gesund aussehen, aber in der App fehlschlagen. Die Referenz zu den Chat-Vervollständigungen von OpenAI gibt entweder ein JSON-Objekt oder gestreamte Chat-Vervollständigungs-Chunks zurück, wenn Streaming aktiviert ist. Die Responses-API kann auch text/event-stream zurückgeben, mit Ereignisnamen, die sich von den Chat-Vervollständigungs-Chunks unterscheiden.

Führen Sie dies aus, nachdem die nicht-streamende Anfrage funktioniert:

curl -N "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count from one to five slowly."}
    ]
  }'

Erfolgsbedingungen:

Für eine tiefere Analyse des Streams vergleichen Sie ihn mit dem bestehenden Test für OpenAI-kompatibles Streaming mit SSE.

Test 6: Tool- oder Funktionsaufruf

Der Aufruf von Tools birgt Schema- und Fähigkeitsrisiken. Der Leitfaden von OpenAI zum Funktionsaufruf beschreibt einen mehrstufigen Ablauf: Tools senden, einen Tool-Aufruf empfangen, App-Code ausführen, Tool-Ausgabe zurückgeben und dann die endgültige Modellantwort empfangen. Eine Migration der Basis-URL kann an jeder dieser Grenzen fehlschlagen, selbst wenn einfacher Text funktioniert.

Beginnen Sie nicht mit Ihrer gesamten Produktions-Tool-Oberfläche. Verwenden Sie eine winzige Funktion:

{
  "model": "your-current-flatkey-model-alias",
  "messages": [
    {"role": "user", "content": "Verwende das Tool für Bestellung A123."}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "lookup_order",
        "description": "Gibt einen Testbestellstatus zurück.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {"type": "string"}
          },
          "required": ["order_id"],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Wenn dies fehlschlägt, während der einfache Chat funktioniert, debuggen Sie nicht mehr die Basis-URL. Sie debuggen die Modellfähigkeit, die Endpunktfamilie, die Schema-Strenge, tool_choice oder die Gateway-Unterstützung für die ausgewählte Route. Der veröffentlichte Leitfaden zur Kompatibilität von Tool-Aufrufen deckt eine größere Anbieter-Checkliste ab.

Test 7: Nutzung, Kontingent und Rollback

Die letzten Migrationstests für die KI-API-Basis-URL sind betrieblicher Natur. Eine generierte Antwort reicht nicht aus, wenn die Finanzabteilung sie nicht abgleichen kann, Kontingente sich nicht wie erwartet verhalten oder ein Rollback eine Notfall-Codeänderung erfordert.

Überprüfen Sie nach einem erfolgreichen Smoke-Test:

Verwenden Sie eine Rollback-Datei, die einfach genug ist, um sie unter Druck auszuführen:

# aktiv
AI_API_BASE_URL=https://router.flatkey.ai/v1
AI_API_MODEL=your-current-flatkey-model-alias

# Rollback
AI_API_BASE_URL_ROLLBACK=https://previous-provider.example/v1
AI_API_MODEL_ROLLBACK=previous-production-model
AI_API_ROLLBACK_OWNER=platform-oncall

Verlassen Sie sich beim Rollback nicht auf Ihr Gedächtnis. Speichern Sie die vorherige Konfiguration, das Feature-Flag, den Bereitstellungsbefehl und den Überprüfungsbefehl im selben Bereitstellungsticket wie die Migrationstests für die KI-API-Basis-URL.

Das aufzubewahrende Nachweispaket

Bewahren Sie für jede Umgebung ein Paket auf, das diese Fragen beantwortet:

Dies ist der praktische Vorteil der Durchführung von Migrationstests für die KI-API-Basis-URL vor der Umstellung. Das Artefakt ist nützlich für die Überprüfung der Bereitstellung, die Reaktion auf Vorfälle, den Abgleich der Nutzung und als Nachweis für die Beschaffung.

Wo Flatkey ins Spiel kommt

Flatkey kann die Ausbreitung von Migrationen reduzieren, indem es den Modellzugriff, das Routing, die Abrechnung, die Nutzungsanalyse und die betriebliche Überprüfung hinter einem einzigen Schlüssel zentralisiert. Das entbindet nicht von der Notwendigkeit zu testen. Es gibt dem Team einen einzigen Kontrollpunkt, an dem Technik, Finanzen und Betrieb dieselben Routennachweise einsehen können.

Bevor Sie migrieren, überprüfen Sie die Live-Seiten für Flatkey-Modelle und Preise, bestätigen Sie die aktuelle Basis-URL der Konsole und beginnen Sie mit einem kleinen Routentest. Wenn Sie noch die breitere Umstellung planen, kombinieren Sie diesen Leitfaden mit dem Leitfaden zur Migration OpenAI-kompatibler APIs. Wenn Sie bereit sind, Ihre eigenen Tests durchzuführen, holen Sie sich einen Schlüssel und halten Sie die erste Anfrage klein genug, um sie von Hand zu überprüfen.

FAQ

Was sind Migrationstests für die KI-API-Basis-URL?

Migrationstests für die KI-API-Basis-URL sind Überprüfungen vor der Umstellung, die belegen, dass der neue API-Stamm für Authentifizierung, Modell-Routing, einfachen Chat, SDK-Nutzung, Streaming, Tools, Nutzungsabfrage, Kontingentverhalten und Rollback funktioniert.

Sollte ich zuerst curl oder das SDK testen?

Testen Sie zuerst curl. Curl beweist den Schlüssel, die URL, den Endpunktpfad und den Modellalias ohne Framework-Verhalten. Testen Sie dann das SDK mit denselben Werten.

Sollte die Basis-URL /chat/completions enthalten?

Normalerweise nicht. Geben Sie dem SDK den API-Stamm wie /v1 an und lassen Sie das SDK dann den Endpunkt anhängen. Verwenden Sie den vollständigen Endpunkt nur für direkte curl-Anfragen.

Warum schlägt Streaming fehl, wenn der einfache Chat funktioniert?

Streaming kann fehlschlagen, weil die Route Antworten puffert, der Client-Parser die falsche Ereignisform erwartet, Middleware den Stream verbraucht oder die ausgewählte Endpunktfamilie die von Ihnen verwendete Stream-Form nicht unterstützt.

Was ist, wenn ich noch keine Live-Anfragen an Flatkey ausführen kann?

Behalten Sie Code-Snippets als Vorlagen, validieren Sie die öffentlichen Dokumente und die Konsolenkonfiguration und verlagern Sie den Produktionsverkehr erst, wenn ein echter Schlüssel die sieben Migrationstests für die KI-API-Basis-URL in Ihrer eigenen Umgebung bestätigt.

Fazit

Das Ändern einer KI-API-Basis-URL ist eine Produktionsmigration und keine bloße Bearbeitung einer Zeichenfolge. Führen Sie die Migrationstests für die KI-API-Basis-URL in der folgenden Reihenfolge aus: Auth, Modellkatalog, einfacher Chat, SDK-Parität, Streaming, Tools sowie Nutzung plus Rollback. Wenn alle sieben erfolgreich sind, wird die Änderung der Basis-URL zu einer kontrollierten Umstellung anstatt zu einer späten Debugging-Sitzung.