OpenAI-kompatible Modellnamen sind der stille Punkt, an dem ansonsten saubere Migrationen scheitern. Das SDK akzeptiert einen model-String, die Request-Struktur wirkt vertraut, und die Base-URL zeigt auf eine OpenAI-kompatible Route. Dann sieht die Produktion model_not_found, ein stilles Fallback auf die falsche Fähigkeit oder ein Bildmodell, das an einen Chat-Endpunkt gesendet wurde.
Die Lösung besteht nicht darin, jeden Katalog jedes Providers auswendig zu kennen. Behandeln Sie OpenAI-kompatible Modellnamen als kontrollierte Konfiguration: Jeder String gehört zu einem Provider-Katalog, einer Endpunktfamilie, einer Route, einer Versionsrichtlinie und einem Abrechnungsdatensatz. Prüfen Sie alle fünf, bevor Sie echten Traffic umstellen.
Flatkey ist hier nützlich, weil Teams den Modellszugang, das Routing, die Abrechnung, Nutzungsanalysen und operative Prüfungen hinter einem Gateway zentralisieren können. Aber ein Gateway macht lose Modellstrings nicht sicher. Dieser Leitfaden gibt Ihnen einen Verifizierungs-Workflow für OpenAI-kompatible Modellnamen, bevor Sie eine Base-URL, eine SDK-Einstellung oder einen Produktions-Alias ändern.
Warum OpenAI-kompatible Modellnamen auseinanderlaufen
„OpenAI-kompatibel“ beschreibt eine API-Struktur, keinen universellen Namensstandard. Ein kompatibler Endpunkt kann OpenAI-ähnliches JSON und SDKs akzeptieren und trotzdem seine eigenen Modell-IDs verlangen.
Das bedeutet, dass diese Strings nicht austauschbar sind:
| Woher der String stammt | Warum er fehlschlagen kann |
|---|---|
| Marketingseite des Providers | Der angezeigte Produktname ist möglicherweise nicht die API-Modell-ID. |
| Altes Codebeispiel | Das Modell kann veraltet, umbenannt oder auf einen anderen Endpunkt beschränkt sein. |
| Ein anderes Gateway | Gateway-Aliase sind lokale Routing-Konfiguration, nicht die providerweite Wahrheit. |
| Eine andere Endpunktfamilie | Routen für Chat, Responses, Embeddings, Bilder, Audio und Video können unterschiedliche Modellmengen bereitstellen. |
| Eine andere Region oder ein anderer Workspace | Einige Provider machen Endpunkt und Modellkatalog von Region, Workspace oder Kontozugriff abhängig. |
Die sichere Regel ist einfach: Genehmigen Sie OpenAI-kompatible Modellnamen nicht aus dem Gedächtnis. Genehmigen Sie sie aus dem aktuellen Katalog, der aktuellen Endpunktfamilie und einem Smoke-Test.
Der Verifizierungs-Workflow für Modellnamen
Verwenden Sie diesen Workflow, bevor Sie OPENAI_BASE_URL, baseURL, model, einen Flatkey-Alias oder eine Produktions-Routing-Richtlinie ändern.
| Schritt | Frage | Zu speichernder Nachweis |
|---|---|---|
| 1. Katalog | Stellt der aktuelle Provider- oder Flatkey-Katalog diesen exakten Modellstring bereit? | Screenshot, API-Rückgabe oder Katalogexport mit Zeitstempel. |
| 2. Endpunktfamilie | Ist das Modell für chat/completions, responses, Bilder, Embeddings oder eine andere Route aktiviert? |
Routenspezifische Dokumentation und eine minimale Anfrage. |
| 3. Alias-Eigentümer | Verwendet die App eine direkte Provider-ID oder einen Gateway-Alias? | Konfigurationsdatei, Flatkey-Modellalias und Owner-/Team-Feld. |
| 4. Versionsrichtlinie | Ist der String stabil, datiert, Preview, veraltet oder providergeroutet? | Hinweis zur Abkündigung, Modellseite, Changelog oder Freigabedatensatz. |
| 5. Laufzeitnachweis | Ruft die exakte Anwendungsumgebung die Route erfolgreich auf? | Curl-Antwort, SDK-Antwort, Request-ID und Nutzungsdatensatz. |
| 6. Rollback | Welchen String und welche Route stellen Sie wieder her, wenn es fehlschlägt? | Vorherige Konfiguration, Feature-Flag und Rollback-Eigentümer. |
Das ist der zentrale Wert einer Checkliste für Modellnamen: Sie verwandelt OpenAI-kompatible Modellnamen von ad-hoc-Strings in geprüfte Bereitstellungs-Inputs.
Aktuelle Provider-Beispiele zum Lernen
Nutzen Sie offizielle Dokumentationen, um das Muster zu verstehen, und prüfen Sie dann vor dem Go-live Ihren eigenen Account oder Katalog des Gateways.
| Provider-Pfad | Offizielles Muster, geprüft am 7. Juli 2026 | Migrationslektion |
|---|---|---|
| OpenAI | Die API verwendet ein model-Feld für Chat Completions und Responses, und der Endpunkt zum Auflisten von Modellen gibt Modelle zurück, die für das authentifizierte Konto verfügbar sind. Die aktuelle OpenAI-Modellberatung nennt gpt-5.5 als neueste Familie, während API-Beispiele weiterhin ältere Beispielstrings zeigen können. |
Verwenden Sie die Dokumentation für den Vertrag, aber den Kontokatalog für die Verfügbarkeit. |
| Google Gemini OpenAI-Kompatibilität | Google dokumentiert eine OpenAI-kompatible Base-URL unter https://generativelanguage.googleapis.com/v1beta/openai/ und Beispiele wie gemini-3.5-flash für Chat. |
Ersetzen Sie kein Gemini-Modell durch einen OpenAI-ähnlichen Namen. Behalten Sie die Gemini-ID bei. |
| xAI | xAI-Dokumente zeigen OpenAI-SDK-Nutzung mit base_url="https://api.x.ai/v1" und Beispiel-Modellstrings wie grok-build-0.1. |
Das SDK kann OpenAI-ähnlich aufgebaut sein, während der Modellstring xAI-spezifisch bleibt. |
| Alibaba Cloud DashScope | DashScope dokumentiert den OpenAI-kompatiblen Modus für Qwen-Modelle, regions- oder workspace-spezifische compatible-mode/v1-URLs und Beispiele wie qwen-plus. |
Base-URL, Region, Workspace und Modellname gehören zusammen. Prüfen Sie sie gemeinsam. |
| Flatkey | Die öffentliche Homepage von Flatkey zeigt eine OpenAI-artige Route unter https://router.flatkey.ai/v1/chat/completions und positioniert das Produkt rund um einen Schlüssel, Modellzugang, Routing, Abrechnung, Nutzungsanalysen und Betriebssteuerungen. |
Verwenden Sie die aktuelle Flatkey-Konsole oder den Katalog für den echten Alias und führen Sie dann einen Smoke-Test für die exakte Route durch. |
Diese Beispiele zeigen, warum OpenAI-kompatible Modellnamen als anbieterspezifische Zeichenfolgen behandelt werden sollten. Kompatibilität reduziert Änderungen auf der Client-Seite; sie hebt Katalogunterschiede nicht auf.
Erstellen Sie eine freigegebene Modellzuordnung
Verstreuen Sie keine rohen Modellstrings über Anwendungscode, Notebooks, Automatisierungstools und Support-Skripte. Legen Sie freigegebene OpenAI-kompatible Modellnamen in einer kleinen Zuordnung ab und leiten Sie jeden Dienst darüber.
type EndpointFamily = "chat" | "responses" | "embeddings" | "images" | "video";
type ApprovedModelRoute = {
alias: string;
providerModel: string;
endpointFamily: EndpointFamily;
baseURL: string;
owner: string;
reviewedAt: string;
rollbackAlias: string;
};
export const models: Record<string, ApprovedModelRoute> = {
support_chat: {
alias: "support_chat",
providerModel: process.env.FLATKEY_SUPPORT_CHAT_MODEL!,
endpointFamily: "chat",
baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
owner: "support-platform",
reviewedAt: "2026-07-07",
rollbackAlias: "support_chat_previous",
},
};
Die Zuordnung trennt den Namen, den Ihre Anwendung verwendet, von der Modellzeichenfolge des Anbieters oder Gateways. Das gibt Einkauf, Finanzen und Incident-Responder einen stabilen Ort, um zu fragen: Wer hat dieses Modell freigegeben, für welchen Endpunkt ist es gedacht, und wie rollen wir es zurück?
Für eine breitere Katalog-Governance kombinieren Sie dies mit dem Leitfaden zum KI-Modellkatalog. Für die Migration der Base-URL verwenden Sie den Leitfaden zur Migration der OpenAI-kompatiblen API.
Testen Sie den exakten Namen vor der SDK-Migration
Ein Smoke-Test des Modellnamens sollte klein genug sein, um ihn manuell zu prüfen. Beginnen Sie nicht mit Tools, Streaming, JSON-Schema oder einem Framework-Wrapper. Beginnen Sie mit der Route, dem Schlüssel und der Modellzeichenfolge, die Sie ausliefern wollen.
export FLATKEY_API_KEY="sk-fk-..."
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="the-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: model route ok"}
]
}'
Wenn dies fehlschlägt, debuggen Sie nicht das SDK. Prüfen Sie zuerst die Modellzeichenfolge, die Endpunktfamilie, den Schlüsselumfang, die Route und den Katalog. Wenn es funktioniert, speichern Sie den Response-Body, den Statuscode, die Request-ID, falls vorhanden, den Zeitstempel, das Usage-Objekt und den Flatkey-Usage-Readback.
Testen Sie dann dieselben OpenAI-kompatiblen Modellnamen über das SDK:
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 route ok" }],
});
console.log(response.choices[0]?.message?.content);
Der SDK-Test sollte dieselbe Base-URL-Root, denselben Modellalias und dieselbe Endpunktfamilie verwenden. Wenn curl funktioniert, das SDK aber fehlschlägt, prüfen Sie die Umgebungsvariablen, bevor Sie Modellnamen ändern.
Trennen Sie Aliase von Provider-IDs
Ein Alias ist nicht dasselbe wie eine Provider-ID. Eine Provider-ID ist die Zeichenfolge, die vom Upstream-Anbieter oder von einer providerkompatiblen Route akzeptiert wird. Ein Gateway-Alias ist die Zeichenfolge, die Ihr Gateway einem Providermodell, einer Fallback-Policy, einer Preisgruppe oder einem Konto zuordnet.
Beides kann gültig sein. Probleme beginnen, wenn Teams nicht mehr kennzeichnen, welche Variante sie verwenden.
Verwenden Sie diese Namensdisziplin:
| Feld | Beispielstruktur | Regel |
|---|---|---|
| App-Alias | support_chat |
Stabiler Name, der von Ihrer Anwendung verwendet wird. |
| Gateway-Alias | support-chat-balanced |
Vom Gateway- oder Plattformteam verwaltet. |
| Provider-Modell-ID | qwen-plus, gemini-3.5-flash oder aktueller Katalogwert |
Aus der Anbieterdokumentation oder dem Katalog verifiziert. |
| Endpunktfamilie | chat, responses, images, embeddings |
Muss zur Route und zum Parser passen. |
| Versionsstatus | stable, preview, dated, deprecated | Vor Produktionsverkehr geprüft. |
Dadurch werden OpenAI-kompatible Modellnamen prüfbar. Wenn eine Route fehlschlägt, können Sie erkennen, ob das Problem beim App-Alias, beim Flatkey-Alias, bei der Provider-Modell-ID oder bei der Endpunktfamilie liegt.
Vermeiden Sie Nichtübereinstimmungen bei der Endpunktfamilie
model_not_found bedeutet nicht immer, dass die Zeichenfolge falsch geschrieben ist. Es kann bedeuten, dass die Zeichenfolge auf einer anderen Route gültig ist.
Ein Chat-Modell ist möglicherweise auf einer Responses-Route nicht verfügbar. Ein Bildmodell kann einen Endpunkt zur Bildgenerierung verwenden. Ein Videomodell kann eine andere Payload-Familie erfordern. Eine Kompatibilitätsschicht für Provider kann nicht unterstützte Felder stillschweigend ignorieren oder nur einen Teil des Provider-Katalogs bereitstellen.
Bevor Sie optionale Parameter hinzufügen, beantworten Sie diese Fragen:
- Ist dieses Modell für die Route, die ich aufrufe, freigegeben?
- Erwartet dieser Endpunkt
messages,input,prompt, Bilder, Dateien oder eine andere Request-Struktur? - Hängt das ausgewählte SDK den Endpunktpfad nach der Basis-URL an?
- Erfordert der Provider eine regionsspezifische oder workspace-spezifische Basis-URL?
- Leitet Flatkey diesen Alias in Staging und Produktion an dieselbe Endpunktfamilie weiter?
Der Leitfaden zur Fehlerbehebung bei OpenAI-kompatiblen APIs deckt den breiteren Debugging-Pfad ab. Halten Sie bei der Arbeit an Modellnamen den Fehler klein: eine Route, ein Modellstring, eine kurze Anfrage.
Planen Sie Version- und Abschreibungsänderungen
OpenAI-kompatible Modellnamen ändern sich im Laufe der Zeit. Manche Namen sind stabile Familien, manche datierte Snapshots, manche Preview-Modelle und manche Gateway-Aliase, die Ihr eigenes Team kontrolliert.
Erstellen Sie einen Review-Rhythmus für jede produktive Modellroute:
| Signal | Aktion |
|---|---|
| Neue Provider-Modellfamilie | Nur zu Staging hinzufügen, dann Qualität, Kosten, Latenz und Tool-Verhalten vergleichen. |
| Preview- oder Beta-Suffix | Vor der produktiven Nutzung einen Verantwortlichen und ein Rollback-Datum festlegen. |
| Hinweis auf Abschreibung | Eine Migrationsaufgabe mit Frist, Ersatz, Testplan und Routenverantwortlichem erstellen. |
| Änderung des Gateway-Alias | Den Smoke-Test und die Usage-Rückmeldung ausführen, bevor die Produktivkonfiguration aktualisiert wird. |
| Änderung der Provider-Region | Basis-URL, Workspace, Katalog, Abrechnung und Latenz erneut prüfen. |
Vergraben Sie diese Entscheidungen nicht allein in Umgebungsvariablen. Bewahren Sie die Nachweise in einem prüfbaren Paket auf, damit Engineering, Betrieb und Einkauf sehen können, warum das Modell erlaubt ist.
Was Sie vor dem Cutover in Flatkey prüfen sollten
Nutzen Sie Flatkey als operativen Kontrollpunkt, nicht als Grund, die Verifikation zu überspringen.
Bevor Sie Produktionsverkehr umstellen, bestätigen Sie:
- Die aktuelle Flatkey-Basis-URL in Ihrer Konsole oder Ihren Onboarding-Notizen.
- Den genauen Modell-Alias, den Sie aus der App senden werden.
- Das Provider-Modell oder die Route hinter dem Alias.
- Die Endpunktfamilie, etwa Chat Completions oder Responses.
- Kontingent- und Ausgabenlimits für den Schlüssel oder Workspace.
- Die Usage-Rückmeldung nach einem erfolgreichen Smoke-Test.
- Das Fallback-Verhalten, falls die primäre Route ausfällt.
- Rollback-Konfiguration für die vorherige Provider-Route oder den vorherigen Flatkey-Alias.
Vergleichen Sie dann die operative Seite auf Flatkey-Preise und einen Schlüssel erhalten für einen Testpfad. Behandeln Sie Preis- und Modellkatalogseiten nur dann als aktuelle Nachweise, wenn Sie sie am Tag Ihrer Migration prüfen.
Häufig gestellte Fragen
Sind OpenAI-kompatible Modellnamen universell?
Nein. OpenAI-kompatible Modellnamen sind weiterhin provider- oder gateway-spezifische Strings. Die Request-Struktur kann kompatibel sein, während der Modellkatalog unterschiedlich bleibt.
Warum gibt meine OpenAI-kompatible Route model_not_found zurück?
Der Modellstring könnte falsch geschrieben sein, für das Konto nicht verfügbar, im Gateway deaktiviert, an die falsche Endpunktfamilie gesendet, auf eine andere Region beschränkt oder abgeschrieben sein. Prüfen Sie den exakten String im aktuellen Katalog und führen Sie einen minimalen Routentest aus.
Sollte ich direkte Provider-Modell-IDs oder Flatkey-Aliase verwenden?
Verwenden Sie einen Flatkey-Alias, wenn Sie zentrales Routing, Abrechnung, Usage-Review, Fallback-Kontrolle oder Governance auf Teamebene wünschen. Halten Sie den Alias auf eine verifizierte Provider-Modell-ID gemappt und dokumentieren Sie den Verantwortlichen.
Kann ich einen Modellnamen aus einer alten Provider-Anleitung kopieren?
Nur als Ausgangspunkt. Alte Anleitungen können eingestellte, Preview- oder nur als Beispiel gedachte Strings enthalten. Prüfen Sie die aktuellen Provider-Dokumente, den aktuellen Flatkey-Katalog und einen Live-Smoke-Test erneut.
Was sollte in einer Review zu Modellnamenänderungen enthalten sein?
Fügen Sie den alten String, den neuen String, die Endpunktfamilie, die Basis-URL, den Provider- oder Flatkey-Alias, den Verantwortlichen, die Quelldokumente, die Smoke-Test-Antwort, die Usage-Rückmeldung, die erwarteten Kostenauswirkungen, das Fallback-Verhalten und den Rollback-Plan hinzu.
Fazit
OpenAI-kompatible Modellnamen sind Eingaben für Migrationen, keine Nebensachen. Prüfen Sie Katalog, Endpunktfamilie, Alias-Verantwortlichen, Versionsrichtlinie und Laufzeitnachweis, bevor Sie Produktionsverkehr ändern. Wenn Sie diese Prüfungen in Flatkey zentralisieren, können dieselben Belege zu Modellnamen Engineering-Cutover, Incident-Review, Usage-Abgleich und Einkaufsfreigabe unterstützen.
Wenn Sie bereit zum Testen sind, beginnen Sie mit einem Schlüssel, einer Basis-URL, einer Endpunktfamilie und einem freigegebenen Modell-Alias. Das ist der schnellste Weg, OpenAI-kompatible Modellnamen langweilig genug für die Produktion zu machen.
