IBM watsonx 2.4.x – Model Gateway einrichten

Überblick: Wozu ein Model Gateway?

Sobald mehr als ein Modell im Einsatz ist, verteilen sich Endpunkte, Authentifizierungsverfahren und API-Dialekte über den ganzen Anwendungsbestand. Jeder Modellwechsel wird dann zum Code-Change in mehreren Repositories.

Das Problem und die Antwort

Jeder Modellanbieter bringt eigene Endpunkte, eigene Auth-Verfahren und eigene Request-Formate mit. Das Model Gateway legt eine einheitliche, OpenAI-kompatible Fassade davor und routet Anfragen an den passenden Anbieter weiter. Die Zugangsdaten liegen dabei nicht im Gateway, sondern in einem Secrets Manager; das Gateway hält nur eine Referenz darauf.

Das Gateway ist die Telefonzentrale – Anrufer wählen immer dieselbe Nummer und nennen einen Namen. Wer dahinter wirklich abhebt und in welchem Haus der sitzt, entscheidet die Zentrale.

Was das Gateway leistet

Einheitliche API – OpenAI-kompatibel für alle Anbieter
Aliase – Anwendungen adressieren Namen statt Modell-IDs
Load Balancing – Verteilung über Modelle mit gleichem Alias
Zentrale Credentials – im Secrets Manager, nicht in der Anwendung
Access Policies und Rate Limits – Zugriff und Verbrauch steuerbar

Was es nicht leistet

keine Garantie, dass jeder Anbieter jeden Endpunkt unterstützt
keine Vereinheitlichung von Modellverhalten oder Prompt-Format
kein Ersatz für einen Secrets Manager – der wird vorausgesetzt
keine automatische Modell-Erkennung bei exotischen Anbietern

Ein Alias vereinheitlicht die Adresse, nicht die Antwort. Ein Wechsel des dahinterliegenden Modells verändert weiterhin Qualität, Token-Verbrauch und Latenz.

Die vier Bausteine

Baustein	Wo	Aufgabe
Secrets Manager	Software Hub vault oder externer Vault	hält die Zugangsdaten der Anbieter als `Key-value`-Secret
Provider	Model Gateway	benannte Verbindung zu einem Anbieter, verweist per Referenz auf ein Secret
Modell	Model Gateway	freigeschaltete Modell-ID unterhalb eines Providers
Alias	Model Gateway	frei gewählter Name, unter dem Anwendungen das Modell ansprechen

Ein Provider kann viele Modelle führen; ein Alias kann auf mehrere Modelle zeigen. Genau daraus entsteht später das Load Balancing.

Zwei Produktvarianten, eine Dokumentation: Die UI-Beschreibung gilt für die On-Prem-Installation (Software Hub), große Teile der programmatischen Dokumentation sind dagegen für die Cloud-Variante geschrieben – dort mit IBM Cloud Secrets Manager, CRN-Referenzen und IAM-Bearer-Token. Das JSON-Schema der Secrets ist in beiden Fällen identisch, die Auth-Verfahren und die Art der Secret-Referenz sind es nicht. Wer Cloud-Beispiele unbesehen On-Prem übernimmt, baut CRNs in eine Umgebung ein, die keine kennt.

Voraussetzungen schaffen

Der Wizard bricht ab, wenn ein Baustein fehlt – und zwar erst mitten im Ablauf, nicht am Anfang. Diese drei Dinge gehören vorher erledigt.

Was vor dem ersten Klick stehen muss

Secrets-Manager-Instanz bereitstellenOhne provisionierte Instanz lässt sich in Schritt 4 des Wizards nichts auswählen. Entweder der Software Hub vault oder ein angebundener externer Vault.
Zugangsdaten je Anbieter beschaffenAPI-Key für OpenAI, Anthropic, Mistral und Vergleichbares; Access Key und Secret Key für AWS Bedrock; nur eine Host-Adresse für Ollama.
Berechtigungen prüfenLesezugriff auf die Secrets-Manager-Instanz und eine Administratorrolle für die Plattform. Ohne Adminrolle ist der Menüpunkt entweder nicht sichtbar oder das Absenden schlägt fehl.

Base URL bei Provider `IBM watsonx`

Wird watsonx selbst als Anbieter eingetragen, hängt die Base URL davon ab, wie die Installation aufgesetzt wurde. Der Wert lässt sich am Cluster ermitteln – der Eintrag in der Spalte HOST/PORT ist die gesuchte Basis-URL.

# Route der watsonx-Instanz ermitteln
oc get route -n <namespace>

# Spalte HOST/PORT liefert die Base URL, z.B.
# cpd-watsonx.apps.cluster.example.com

Hinweis: Läuft das Gateway im selben Cluster wie der angesprochene Dienst, ist die interne Service-Adresse der stabilere Weg – sie umgeht Ingress und externes Zertifikat.

Die eigene CA ist der häufigste stille Blocker: Zeigt die Base URL auf einen Endpunkt mit selbst signiertem oder unternehmenseigenem Zertifikat, scheitert die Verbindung im TLS-Handshake. In der Oberfläche erscheint nur eine allgemeine Fehlermeldung, die eigentliche Ursache steht als x509: certificate signed by unknown authority im Log des Gateway-Pods. Die CA muss vorher im Trust-Bundle liegen.

Provider in der Oberfläche anlegen

Der Einstieg liegt im Navigationsmenü unter Administration → Model Gateway. Der Wizard führt in drei Etappen: Provider auswählen, Modelle auswählen, Modelle konfigurieren.

Der Ablauf im Wizard

Reiter Model provider öffnenDort Add model provider anklicken.
Anbieter wählenBei einem der gelisteten Anbieter auf Add provider klicken – ein Konfigurationsfenster öffnet sich.
Verbindung benennenName vergeben, Beschreibung optional. Der Name taucht später in jeder Modellliste auf.
Secrets-Manager-Instanz auswählenIst keine provisioniert, endet der Ablauf hier.
Secret festlegenBestehendes Secret wählen, neu anlegen oder für einen externen Vault vorbereiten – siehe Tabelle unten.
Mit Add bestätigenDie Verbindung erscheint im Bereich Added providers.
Für weitere Anbieter wiederholenDanach Next – die Modellliste enthält anschließend die Modelle aller verbundenen Anbieter.

Die drei Wege zum Secret

Situation	Auswahl	Folge
Secret existiert bereits	vorhandenes Secret auswählen	schnellster Weg – aber nur zuverlässig, wenn das Secret dem erwarteten Schema entspricht
Kein Secret, Software Hub vault	Create new secret	die Oberfläche erzeugt Struktur und Inhalt korrekt
Kein Secret, externer Vault	Copy a key to create in your external vault	Felder ausfüllen, Show JSON erzeugt das fertige Objekt zum Anlegen im Vault

Beim dritten Weg wird das JSON-Objekt im externen Vault angelegt und danach in der Oberfläche das Refresh-Symbol geklickt – erst dann taucht das Secret in der Auswahlliste auf.

Der Provider-Eintrag ist ein Schild mit Fachnummer, kein Schlüssel – im Gateway steht nur, in welchem Fach des Schlüsselkastens der Schlüssel liegt. Der Schlüssel selbst verlässt den Kasten nie.

Secret-Namen sind global eindeutig: Auch über verschiedene Anbieter hinweg lässt sich ein Name kein zweites Mal vergeben. Ein Schema wie apikey für jeden Provider funktioniert genau einmal – danach kollidiert jeder weitere Anlageversuch. Sinnvoll ist ein Präfix je Anbieter, etwa gw-openai-prod.

Fremd angelegte Secrets erscheinen, funktionieren aber nicht: Secrets, die nicht über die Gateway-Oberfläche entstanden sind, tauchen in der Auswahlliste trotzdem auf. Stimmt der Typ nicht (Key-value ist Pflicht) oder weicht die JSON-Struktur ab, scheitert erst der Verbindungsaufbau – die Auswahl selbst meldet nichts.

Secret-Schema je Anbieter

Das Secret ist immer vom Typ Key-value und enthält ein flaches JSON-Objekt. Welche Schlüssel Pflicht sind, hängt vom Anbieter ab – und genau hier entstehen die meisten Fehlkonfigurationen.

Pflicht- und Zusatzfelder

Anbieter	Pflicht	Optional
OpenAI	`apikey`	`base_url`
Anthropic	`apikey`	–
Azure OpenAI	`apikey`, `resource_name`, `api_version`	`subscription_id`, `resource_group_name`, `account_name`
AWS Bedrock	`access_key_id`, `secret_access_key`, `region`	`session_token`, `base_url`
IBM watsonx.ai	`base_url`	`apikey`, `project_id`, `space_id`, `auth_url`, `api_version`
Ollama	`host`	`keep_alive`, `clean_on_close`
Google Gemini, Groq, Mistral, Cohere, Cerebras, NVIDIA NIM, xAI	`apikey`	–

Bei Azure OpenAI ist api_version mit 2024-10-21 vorbelegt; die drei optionalen Felder werden erst gebraucht, damit die Modellliste befüllt werden kann. Bei Ollama liegt keep_alive standardmäßig bei fünf Minuten.

Beispiel: watsonx als Anbieter

Minimal genügt die Basis-URL. Alles Weitere ist optional, weil project_id und space_id auch pro Request über Header mitgegeben werden können.

// minimal
{
  "base_url": "<watsonx-endpunkt>"
}

// vollständig
{
  "base_url": "<watsonx-endpunkt>",
  "apikey": "<api-key>",
  "project_id": "<project-id>",
  "auth_url": "https://iam.cloud.ibm.com/identity/token",
  "api_version": "2023-07-07"
}

Hinweis: Statt fest hinterlegter Werte lassen sich project_id und space_id per Request-Header X-IBM-Project-Id beziehungsweise X-IBM-Space-Id übergeben. Das erlaubt einen Provider-Eintrag für mehrere Projekte.

Das Feld auth_url ist ein Cloud-Artefakt: Der Wert https://iam.cloud.ibm.com/identity/token stammt aus der Cloud-Variante. In einer abgeschotteten On-Prem-Installation ist diese Adresse nicht erreichbar – ein Eintrag dort führt zu Timeouts beim Verbindungsaufbau, nicht zu einer klaren Fehlermeldung. Im On-Prem-Fall bleibt das Feld leer oder zeigt auf den lokalen Authentifizierungsendpunkt.

Ollama ist der Nachbar ohne Türschloss – kein Schlüssel im Secret, nur eine Adresse. Erreichbarkeit ist dort die einzige Zugangskontrolle, also gehört sie auf Netzwerkebene geregelt.

Modelle auswählen und Aliase vergeben

Nach dem Anlegen der Provider zeigt der Wizard alle Modelle aller verbundenen Anbieter in einer gemeinsamen Liste. Auswählen, optional Aliase vergeben, absenden – hinter der harmlosen Alias-Spalte steckt allerdings mehr als ein Anzeigename.

Von der Liste zum fertigen Eintrag

Modelle auswählenEin oder mehrere Modelle markieren, dann Next.
Fehlende Modelle nachtragenÜber Import model: Anbieter wählen, Modell-ID eintragen (etwa gpt-3.5-turbo-xxxx), Add. Das Modell steht danach zur Auswahl.
Aliase vergebenOptional, aber in der Praxis der eigentliche Zweck der Übung.
AbsendenMit Submit. Verbindungen und Modelle erscheinen anschließend im Reiter Model provider, dort auch such- und sortierbar.

Die Modell-ID beim Import muss ein beim Anbieter tatsächlich existierender Bezeichner sein. Das Gateway prüft ihn beim Anlegen nicht – ein Tippfehler fällt erst beim ersten Request auf.

Der Alias und seine Nebenwirkung

Ein Alias ist ein frei gewählter Name, unter dem Anwendungen ein Modell adressieren. Der eigentliche Nutzen: Anwendungen sprechen chat-standard an, und welches Modell dahinter liegt, wird zur Konfigurationsfrage statt zum Code-Change.

Derselbe Alias darf mehreren Modellen zugewiesen werden – und genau dadurch wird Load Balancing nach dem Verfahren der geringsten Verbindungszahl aktiviert. Innerhalb eines Anbieters ist ein Alias dagegen exklusiv: Zwei Modelle desselben Providers können ihn sich nicht teilen.

Konstellation	Erlaubt	Wirkung
Ein Alias, ein Modell	ja	reine Umbenennung, entkoppelt Anwendung und Modell-ID
Ein Alias, mehrere Modelle verschiedener Anbieter	ja	Lastverteilung über die Modelle hinweg
Ein Alias, mehrere Modelle desselben Anbieters	nein	wird abgewiesen

Der Alias ist der Service vor den Pods – die Anwendung kennt nur den Namen, dahinter kann ein Modell stehen oder fünf. Wer denselben Namen mehrfach vergibt, hat keinen Zweitnamen vergeben, sondern eine zweite Instanz hinter denselben Service gehängt.

Vereinheitlichte Alias-Namen schalten unbemerkt Lastverteilung ein: Wer aus Ordnungsliebe mehreren Modellen denselben Alias gibt, verteilt damit den Traffic über sie – und bekommt bei fachlich unterschiedlichen Modellen wechselnde Antwortqualität, ohne dass sich an der Anwendung etwas geändert hätte. Die Fehlersuche führt dann in den Prompt statt in die Gateway-Konfiguration. Ein Alias pro fachlicher Rolle, nicht pro Modellfamilie.

Der programmatische Weg

Die Oberfläche ist für den Erstaufbau bequem und für Wiederholbarkeit ungeeignet. Über die API entsteht dieselbe Konfiguration reproduzierbar – in drei Schritten: Secret ablegen, Provider registrieren, Modelle hinzufügen.

Die drei Schritte

Secret im Secrets Manager ablegenTyp Key-value, Inhalt nach dem Schema aus Abschnitt 3.
Provider mit Verweis auf das Secret registrierenDer Provider bekommt einen Namen und eine Referenz – nie den Wert selbst.
Modelle unter der Provider-UUID anlegenJe Modell die ID beim Anbieter und optional den Alias.

Provider-UUID ermitteln

Fast jeder weitere Aufruf braucht die UUID des Providers. Sie steht in der Provider-Liste – der schnellste Weg, um von Namen auf IDs zu kommen:

# alle konfigurierten Provider auflisten
curl -sS "${GATEWAY_URL}/v1/providers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}"

# nur Name und UUID – Feldname je nach Version pruefen
curl -sS "${GATEWAY_URL}/v1/providers" \
  -H "Authorization: Bearer ${TOKEN}" | jq -r '.resources[] | "\(.name)  \(.id)"'

Hinweis: Der Name des umschließenden Arrays unterscheidet sich zwischen Versionen. Einmal ohne Filter abrufen, die Struktur ansehen, dann den jq-Ausdruck festlegen.

Provider registrieren und Modell hinzufügen

Der Provider verweist über data_reference auf das abgelegte Secret. Wie diese Referenz aussieht, hängt von der Umgebung ab – in der Cloud-Variante ist es die CRN der Secrets-Manager-Instanz.

# Provider anlegen (Cloud-Variante mit CRN-Referenz)
curl -sS "${GATEWAY_URL}/v1/providers/<provider>" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d "$(jq -n \
    --arg resource "$SM_CRN" \
    --arg name "openai-prod" \
    '{name: $name, data_reference: {resource: $resource}}')"

# Modell unterhalb des Providers anlegen, mit Alias
curl -X POST "${GATEWAY_URL}/v1/providers/${PROVIDER_UUID}/models" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{ "alias": "chat-standard", "id": "<model_id>" }'

Der Provider-Eintrag ist ein Adressbucheintrag – Name plus Fachnummer im Schlüsselkasten. Wer stattdessen den Schlüssel selbst einträgt, hat den Sinn des Kastens aufgehoben.

Die Beispiele der Dokumentation sind für die Cloud geschrieben: SM_CRN, ibmcloud secrets-manager und der IAM-Bearer-Token existieren in der On-Prem-Installation nicht. Übernommen wird das Muster – Secret ablegen, referenzieren, Modelle anhängen – nicht die konkrete Referenzform und nicht das Auth-Verfahren. Auf welche Weise ein Software-Hub-Vault-Secret referenziert wird, gehört gegen die eigene Installation geprüft, statt aus dem Beispiel abgeleitet zu werden.

Requests über das Gateway

Steht die Konfiguration, sprechen Anwendungen nur noch OpenAI-Dialekt gegen einen Endpunkt. Vier Endpunktgruppen stehen bereit – vorausgesetzt, der dahinterliegende Anbieter unterstützt sie auch.

Authentifizierung: zwei Verfahren

Variante	Verfahren	Lebensdauer
On-Prem, Software Hub	`Authorization: ZenApiKey <token>`	bis zum Widerruf
On-Prem, Sonderfälle	Bearer-Token über den Plattform-Endpunkt	befristet, muss erneuert werden
Cloud	IAM-Bearer-Token aus einem API-Key	befristet, muss erneuert werden

Der ZenApiKey entsteht aus Benutzername und API-Key, base64-kodiert. Den API-Key selbst erzeugt die Weboberfläche unter Profile and settings – er wird genau einmal angezeigt.

# Token bauen – das -n ist entscheidend
echo -n "<username>:<api_key>" | base64 -w0

# und verwenden
curl -sS "${GATEWAY_URL}/v1/models" \
  -H "Authorization: ZenApiKey ${TOKEN}"

ZenApiKey ist die Jahreskarte, das Bearer-Token das Tagesticket – für einen unbeaufsichtigt laufenden Dienst nimmt man die Jahreskarte, sonst baut man einen Token-Erneuerer, den niemand betreiben will.

echo ohne -n kodiert einen Zeilenumbruch mit: Das Ergebnis sieht aus wie ein gültiges Token, wird aber mit 401 abgewiesen – ohne Hinweis darauf, dass ein unsichtbares Zeichen die Ursache ist. Dasselbe gilt für base64 ohne -w0 bei langen Eingaben: Der Umbruch zerlegt das Token.

Die Endpunkte

Zweck	Pfad	Anmerkung
Provider auflisten	`/v1/providers`	liefert Namen und UUIDs
Modelle eines Providers	`/v1/providers/{uuid}/models`	nur die freigeschalteten
Alle Modelle	`/v1/models`	über alle Provider hinweg
Chat	`/v1/chat/completions`	unterstützt Streaming
Text	`/v1/completions`	unterstützt Streaming
Embeddings	`/v1/embeddings`	–

Beispiel: Chat-Request und Anbindung eines OpenAI-SDK

Im Feld model steht der Alias oder die Modellbezeichnung – nicht die interne UUID.

curl "${GATEWAY_URL}/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: ZenApiKey ${TOKEN}" \
  -d '{
    "model": "chat-standard",
    "messages": [
      {"role": "system", "content": "Antworte knapp."},
      {"role": "user", "content": "Was ist ein Reverse Proxy?"}
    ]
  }'

Weil das Gateway die OpenAI-API nachbildet, funktioniert jedes OpenAI-SDK ohne Anpassung – es genügt, base_url und Schlüssel auszutauschen:

from openai import OpenAI

client = OpenAI(
    base_url="https://<route>/ml/gateway/v1",
    api_key="<token>",
)

completion = client.chat.completions.create(
    model="chat-standard",
    messages=[{"role": "user", "content": "Hallo"}],
)

Damit lassen sich bestehende Anwendungen ohne Codeänderung umhängen. Genau darin liegt der Betriebsnutzen des Gateways.

Nicht jeder Anbieter kann jeden Endpunkt: Unterstützt ein Backend einen Endpunkt nicht, kommt der Fehler erst zur Laufzeit aus der Antwort – die Konfiguration selbst wird ohne Beanstandung angenommen. Besonders /v1/embeddings und /v1/completions sind längst nicht überall vorhanden. Jeden Provider nach dem Anlegen einmal gegen jeden Endpunkt anfassen, den die Anwendungen später benutzen sollen.

Betrieb: Fehlerbilder und Komplettablauf

Die meisten Störungen im Gateway sehen gleich aus – die Verbindung schlägt fehl, die Oberfläche nennt keinen Grund. Diese Tabelle ordnet Symptom und Ursache zu, danach folgt der gesamte Ablauf in vier Phasen.

Symptom und Ursache

Symptom	Wahrscheinliche Ursache	Prüfen
Verbindung schlägt beim Anlegen fehl	Zertifikat der Base URL nicht vertraut	Log des Gateway-Pods auf `x509`
Secret auswählbar, Provider bleibt fehlerhaft	falscher Typ oder abweichendes JSON-Schema	Typ `Key-value`, Pflichtfelder aus Abschnitt 3
Secret lässt sich nicht anlegen	Name bereits vergeben – global, nicht pro Provider	bestehende Secret-Namen
`401` trotz gültigem Schlüssel	Zeilenumbruch im base64-Token	`echo -n`, `base64 -w0`
Modell antwortet nicht, andere schon	Modell-ID beim Import falsch geschrieben	Bezeichner beim Anbieter
Antwortqualität schwankt ohne Änderung	mehrere Modelle teilen sich einen Alias	Alias-Zuordnung im Reiter Model provider
Endpunkt liefert Fehler, andere funktionieren	Anbieter unterstützt diesen Endpunkt nicht	Anbieterdokumentation
Timeout beim Verbindungsaufbau	`auth_url` zeigt nach außen, Umgebung abgeschottet	Feld `auth_url` im Secret

Die vier Phasen auf einen Blick

Phase A · VorbereitenSchritte 1–3: Secrets Manager, Anbieter-Zugangsdaten, Berechtigungen und Zertifikatsvertrauen.
Phase B · VerbindenSchritte 4–6: Provider anlegen, Secret hinterlegen, Verbindung bestätigen.
Phase C · Modelle freigebenSchritte 7–9: Modelle auswählen oder importieren, Aliase bewusst vergeben, absenden.
Phase D · In Betrieb nehmenSchritte 10–12: Token erzeugen, Endpunkte durchtesten, Anwendungen umhängen.

Phase A · Vorbereiten

Schritt 1 · Secrets Manager bereitstellen

Ohne provisionierte Instanz endet der Wizard mitten im Ablauf, nachdem bereits Name und Beschreibung eingetragen wurden. Zuerst klären, ob der Software Hub vault genutzt wird oder ein externer Vault angebunden ist – die beiden Wege unterscheiden sich später bei der Secret-Erstellung deutlich.

Schritt 2 · Zugangsdaten und Basis-URLs sammeln

Je Anbieter genau die Felder aus Abschnitt 3 zusammentragen. Für watsonx als Anbieter wird die Basis-URL aus der Route ermittelt:

oc get route -n <namespace>
# Spalte HOST/PORT ist die Base URL

Schritt 3 · Zertifikatsvertrauen herstellen

Bei eigener CA muss deren Zertifikat im Trust-Bundle des Gateways liegen, bevor der erste Provider angelegt wird. Wird dieser Schritt übersprungen, erscheint später eine unspezifische Verbindungsmeldung, deren Ursache nur im Pod-Log steht.

# Log auf TLS-Fehler pruefen
oc logs -n <namespace> deploy/<gateway-deployment> | grep -i x509

Phase B · Verbinden

Schritt 4 · Provider anlegen

Über Administration → Model Gateway → Reiter Model provider → Add model provider. Der Verbindungsname erscheint später in jeder Modellliste – ein sprechender Name mit Umgebungskennzeichnung erspart Verwechslungen zwischen Test und Produktion.

Schritt 5 · Secret hinterlegen

Beim Software Hub vault über Create new secret, beim externen Vault über Copy a key to create in your external vault. Im zweiten Fall erzeugt Show JSON das vollständige Objekt, das im Vault angelegt wird; danach muss die Liste über das Refresh-Symbol neu geladen werden, sonst bleibt das eben erstellte Secret unsichtbar.

Der Secret-Name muss global eindeutig sein. Bewährt hat sich ein Präfix je Anbieter und Umgebung.

Schritt 6 · Verbindung bestätigen und wiederholen

Mit Add abschließen. Die Verbindung erscheint unter Added providers. Für jeden weiteren Anbieter wiederholen, danach mit Next zur Modellauswahl. Sind mehrere Verbindungen angelegt, enthält die folgende Liste die Modelle aller Anbieter gemeinsam.

Phase C · Modelle freigeben

Schritt 7 · Modelle auswählen

Nur die Modelle freigeben, die tatsächlich benutzt werden sollen. Jedes freigeschaltete Modell ist ein Zugang zu einem kostenpflichtigen Anbieter-Endpunkt – die Auswahl ist damit auch eine Kostenentscheidung.

Schritt 8 · Fehlende Modelle importieren

Erscheint ein Modell nicht in der Liste, über Import model nachtragen: Anbieter auswählen, Modell-ID eintragen, Add. Die ID wird nicht validiert, deshalb gehört sie aus der Anbieterdokumentation kopiert und nicht aus dem Gedächtnis getippt.

Schritt 9 · Aliase vergeben und absenden

Ein Alias pro fachlicher Rolle. Mehrere Modelle unter demselben Alias bedeuten Lastverteilung, nicht bloß einen gemeinsamen Namen – diese Entscheidung sollte bewusst fallen. Anschließend Submit.

Phase D · In Betrieb nehmen

Schritt 10 · Token erzeugen

API-Key in der Weboberfläche unter Profile and settings erzeugen und sofort sichern – er wird nur einmal angezeigt. Daraus den ZenApiKey bilden:

echo -n "<username>:<api_key>" | base64 -w0

Schritt 11 · Endpunkte durchtesten

Vor dem Umhängen der Anwendungen jeden benötigten Endpunkt einmal manuell aufrufen – erst die Auflistung, dann den fachlichen Aufruf. So wird sichtbar, ob ein Anbieter einen Endpunkt gar nicht bedient, bevor es eine Anwendung tut.

# Erreichbarkeit und Modellliste
curl -sS "${GATEWAY_URL}/v1/models" \
  -H "Authorization: ZenApiKey ${TOKEN}" | jq

# fachlicher Aufruf gegen den Alias
curl -sS "${GATEWAY_URL}/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: ZenApiKey ${TOKEN}" \
  -d '{"model":"chat-standard","messages":[{"role":"user","content":"ping"}]}'

Schritt 12 · Anwendungen umhängen

In bestehenden Anwendungen genügt der Austausch von Basis-URL und Schlüssel, weil die OpenAI-Kompatibilität erhalten bleibt. Die Modellbezeichnung wird durch den Alias ersetzt – ab diesem Punkt ist ein Modellwechsel eine Konfigurationsänderung im Gateway und kein Deployment mehr.

Einordnung

Technisch ist das Model Gateway ein Reverse Proxy mit Alias-Schicht, Credential-Auslagerung und Lastverteilung – ein Muster, das es außerhalb von watsonx ebenfalls gibt. Der Mehrwert liegt weniger in der Funktion als in der Integration: Secrets Manager, Zugriffssteuerung und Verbrauchsgrenzen sind Teil derselben Plattform statt drei getrennter Betriebsgegenstände.

Der Aufwand steckt entsprechend nicht im Wizard, sondern davor: im Secrets Manager, im Zertifikatsvertrauen und in der Frage, welche Aliase es geben soll. Diese drei Punkte entscheiden, ob das Gateway funktioniert – die Klickstrecke selbst ist in zehn Minuten erledigt.

Das Gateway ist eine Zwischendecke, kein Fundament – es verbirgt die Leitungen und macht sie austauschbar, trägt aber nichts, was nicht schon vorher stand.