Model Mapping und Fallback

Lassen Sie einen Upstream-Ausfall nicht zu Ihrem eigenen Ausfall werden.

• Model Mapping ist die Funktion auf Gateway-Ebene, die den Modell-Alias in einer Client-Anfrage in das tatsächliche Upstream-Modell umschreibt.
• Error Fallback ist die Funktion, bei der das Gateway beim Fehlschlagen des Primärmodells automatisch Ersatzmodelle in einer vorab konfigurierten Prioritätsreihenfolge ausprobiert, transparent für den Client.

​

1. Mapping von Modellnamen

Nachdem für das Zielmodell ein Kanal ausgewählt wurde, führt die Plattform intern ein weiteres Mapping auf Kanalebene zum tatsächlichen Upstream-Modell durch. Diese Ebene ist für Sie transparent und erfordert keine Konfiguration. Sie müssen sich nur um die Ebene “Alias → Zielmodell” kümmern.

Alle Modellnamen in der obigen Tabelle können auf der AIHubMix-Modellseite nachgeschlagen werden.

• Der Client schränkt das Format des Modellnamens ein. Zum Beispiel verlangt Claude Desktop Modellnamen im Claude-Stil (siehe Abschnitt 5).
• Einen kürzeren, stabileren Alias für eine komplexe Model ID festlegen.
• Die Client-Konfiguration unverändert lassen und das tatsächliche Modell im AIHubMix-Backend umstellen.
• Mehrere Plattformen teilen sich ein gemeinsames Benennungsschema für die Verbindung, leiten aber je nach Key zu unterschiedlichen Modellen weiter.

Zeichengenaue Übereinstimmung: Der vom Client gesendete Modellname muss zeichengenau mit der linken Seite des Mappings übereinstimmen. Zum Beispiel sind my-gpt-5.5 und my-gpt-5-5 zwei unterschiedliche Zeichenketten; stimmen sie nicht überein, wird das Mapping nicht getroffen.

​

2. Error Fallback

​

2.1 Auslösebedingungen

1. Für den Key ist eine nicht leere Liste von Ersatzmodellen konfiguriert.
2. Jeder Kanal des Primärmodells wurde ausprobiert und ist mit einem “wiederholbaren Fehler” fehlgeschlagen (Kanäle ausgeschöpft).
3. Die Antwort hat noch nicht begonnen zurückzukommen (das erste Byte / der Header wurde noch nicht an den Client gesendet).
4. Der Fehler ist kein Fehler auf Key- / Benutzerebene (siehe die Vergleichstabelle in 2.2 unten).

​

2.2 Was einen Fallback auslöst und was nicht

Hinweis: “Key ungültig” bedeutet hier, dass Ihr eigener AIHubMix-Key ungültig ist, was keinen Fallback auslöst. Wenn der Key eines Upstream-Kanals defekt ist, wechselt das Gateway die Kanäle, und nachdem die Kanäle ausgeschöpft sind, kann dennoch ein Fallback erfolgen. Verwechseln Sie die beiden nicht.

​

2.3 Abrechnungsgrundlage

​

2.4 Regel für kostenlose Modelle

Typische Verwendung: Legen Sie ein kostenloses Modell als Primärmodell fest und setzen Sie kostenpflichtige Modelle in die Ersatzliste. Wenn das kostenlose Primärmodell auf ein Kontingent- / Ratenlimit trifft, erfolgt automatisch ein Fallback auf ein kostenpflichtiges Ersatzmodell. Im Normalfall sparen Sie Kosten, indem Sie das kostenlose Kontingent nutzen, und nach einer Ratenbegrenzung wechseln Sie nahtlos zu einem kostenpflichtigen Modell, um die Verfügbarkeit zu garantieren. Dies ist einer der häufigsten Anwendungsfälle des Fallbacks.

​

3. AIHubMix im Vergleich zu OpenRouter / LiteLLM

​

4. Konfiguration und Verifizierung

​

4.1 Konfiguration

1. Konfigurieren Sie das Alias-Mapping auf dem Key: Der Alias auf der linken Seite muss zeichengenau mit dem Modellnamen übereinstimmen, den der Client tatsächlich sendet.
2. Konfigurieren Sie die Liste der Ersatzmodelle (eine geordnete Prioritätsliste) auf demselben Key.
3. Die Ersatzliste sollte nur kostenpflichtige / verfügbare Modelle enthalten, keine kostenlosen Modelle (diese werden übersprungen).
4. Modelle in der Ersatzliste müssen innerhalb des für den Key verfügbaren Modellbereichs liegen (Modelle außerhalb dieses Bereichs werden übersprungen).

​

4.2 Verifizierung – prüfen Sie zuerst die Antwort-Header, nicht die Logs

• X-Aihubmix-Fallback: true: Bei dieser Anfrage ist ein Fallback aufgetreten (wird hinzugefügt, wenn das letztliche Modell ≠ dem Primärmodell ist).
• X-Aihubmix-Model: Das Modell, das bei dieser Anfrage tatsächlich geantwortet hat und entsprechend abgerechnet wurde.

curl -i https://aihubmix.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{"model":"my-gpt","messages":[{"role":"user","content":"hi"}]}' \
  | grep -i -E 'x-aihubmix-(model|fallback)'

​

5. Szenario eins Claude Desktop

​

5.1 Warum ein Mapping nötig ist

Claude Desktop verwendet die native Claude-Schnittstelle /v1/messages, sodass in den Beispielen in diesem Artikel sowohl das Mapping als auch der Fallback wirksam werden.

​

5.2 AIHubMix-Konfiguration für Mapping und Fallback

claude-g-p-t-5.5 -> gpt-5.5-pro
claude-gemi-3.1 -> gemini-3.1-pro-preview
claude-depsek-v4 -> deepseek-v4

fallback:
1. gpt-5.4
2. gemini-3.1-pro-preview

​

5.3 Claude-Desktop-Modellliste

• Verwenden Sie das Präfix claude- für die Model ID.
• Schreiben Sie nicht direkt echte Modellfamiliennamen wie gpt, gemini oder deepseek; verwenden Sie Aliase wie g-p-t, gemi, depsek.
• Die Model ID muss zeichengenau mit der linken Seite des AIHubMix-Mappings übereinstimmen, andernfalls trifft die Anfrage nicht das erwartete Mapping und fällt möglicherweise weiter auf das Error-Fallback-Modell durch.

​

6. Szenario zwei Multimodaler Fähigkeits-Fallback

claude-g-l-m-4.6 -> coding-glm-4.6-free
claude-g-p-t-5.5 -> gpt-5.5-pro
claude-gemi-3.1 -> gemini-3.1-pro-preview

fallback:
1. gpt-5.4
2. gemini-3.1-flash-image
3. veo-3

Seien Sie sich über den Auslösegrund im Klaren: Der Fallback erfolgt hier, weil der Upstream für diese Bildeingabe einen wiederholbaren Fehler zurückgab und die Kanäle des Primärmodells ausgeschöpft waren — es ist derselbe Fallback-Mechanismus wie “Fallback, nachdem das Primärmodell ratenbegrenzt wurde”, nur durch einen anderen Fehlertyp ausgelöst (Ersteres ist eine nicht unterstützte Eingabe, Letzteres ist ein Kontingent- / Ratenlimit). Unterscheiden Sie Verständnis von Generierung: Dies bezieht sich auf den Fallback beim Bild- / Videoverständnis, nicht auf die Bilderzeugung oder Videoerzeugung. Eine Chat-Anfrage verwandelt sich nicht automatisch in einen Generierungs-Endpunkt; um das Zeichnen oder die Videoerzeugung zu testen, sollten Sie den entsprechenden Generierungs-Endpunkt und das entsprechende Modell verwenden. Die Fähigkeiten eines Modells werden durch die Input Modalities bestimmt, die aktuell auf der AIHubMix-Modellseite markiert sind.

​

7. Szenario drei Fallback bei kostenlosem Modell

primary model (free): coding-glm-4.6-free

fallback:
1. gpt-5.4
2. gemini-3.1-pro-preview

• Solange das kostenlose Kontingent noch ausreicht, wird die Anfrage vom Primärmodell coding-glm-4.6-free beantwortet und als kostenlos abgerechnet.
• Nachdem das kostenlose Primärmodell ratenbegrenzt wurde, erfolgt automatisch ein Fallback auf gpt-5.4; wenn gpt-5.4 ebenfalls nicht verfügbar ist, wird anschließend gemini-3.1-pro-preview ausprobiert.
• Welches Modell auch immer letztlich antwortet, ist dasjenige, das Ihnen in Rechnung gestellt wird (siehe 2.3).

Hinweis: Ein kostenloses Modell kann nur das Primärmodell sein und kann nicht in die Fallback-Liste aufgenommen werden (falls doch, wird es übersprungen; siehe 2.4). Der korrekte Weg, einen “Fallback bei kostenlosem Modell” umzusetzen, ist also: kostenlos als Primärmodell, kostenpflichtig als Ersatz, nicht umgekehrt.

​

8. Unterstützte Endpunkte

• Model Mapping und Error Fallback unterstützen drei Schnittstellenkategorien: OpenAI-kompatible Schnittstellen, natives Claude /v1/messages und OpenAI Responses /v1/responses.
• Andere native Passthrough-Schnittstellen (natives Gemini, Ideogram, Video, TTS, Stability, OCR, Predictions usw.), Passthrough für einen bestimmten Kanal sowie Schnittstellen für den Abruf nach Ressourcen-ID / Dateityp werden noch nicht unterstützt.
• Claude Desktop verwendet das native Claude /v1/messages, sodass in den Beispielen in diesem Artikel sowohl das Mapping als auch der Fallback wirksam werden.

​

9. FAQ

​

Verwandte Ressourcen

• AIHubMix in Claude Desktop verbinden: vollständige Schritte für Entwicklermodus, Gateway-Konfiguration, Auth-Schema und mehr.
• AIHubMix-Modellseite: Modellnamen, Preise und Input Modalities nachschlagen.
• AIHubMix in LiteLLM verbinden: eine Referenz für den Fall, dass Sie ein selbst gebautes Gateway + Modell-Mapping / Fallback benötigen.