Die Anbindung der GLM API ist einfacher, als viele erwarten: Sie bietet eine OpenAI-kompatible Schnittstelle, und vorhandene OpenAI-SDKs benötigen meist nur drei Änderungen – API Key, Base URL und Modellname. Die eigentlichen Stolperstellen liegen nicht im „Läuft es überhaupt?“, sondern darin, ob der Modellname gültig ist, wie Streaming verarbeitet wird, welches Format Tool-Aufrufe zurückgeben und welche Parameter bei einer Migration von OpenAI nicht unverändert übernommen werden dürfen.
Dieser Artikel bringt die Verbindung mit einer minimalen Anfrage zum Laufen und ergänzt danach Streaming, Tool-Aufrufe, Fehlersuche und eine Migrationscheckliste. Alle Beispiele lassen sich nach dem Ersetzen des Keys direkt ausführen.
Hinweis: Zhipu, GLM und BigModel sind Marken ihrer jeweiligen Inhaber. Dieser Artikel dient nur der technischen Erläuterung; es besteht keine Zugehörigkeit, Vertretung oder Beauftragung gegenüber Zhipu. Base URL, Modellnamen, Kontextlänge und Abrechnungsregeln können sich ändern; maßgeblich sind die offizielle Dokumentation der Zhipu-Plattform und unsere Modellpreise.
1. Vorbereitung
Klären Sie vor dem Start drei Dinge:
- Einen nutzbaren API Key, dessen Typ zur aufgerufenen Schnittstelle passt.
- Die richtige Base URL; offizieller Zugang und Gateway-Adresse dürfen nicht vermischt werden.
- Einen aktuell tatsächlich verfügbaren Modellnamen; kopieren Sie keine Beispiele aus alten Artikeln.
Bei neuen Projekten empfiehlt es sich, zuerst mit curl Authentifizierung und Netzwerk zu prüfen und erst danach das SDK anzubinden. So lässt sich bei Fehlern leichter unterscheiden, ob Key, Adresse oder Code die Ursache ist.
2. Wie die Base URL lautet
Die offizielle OpenAI-kompatible Schnittstelle von Zhipu verwendet üblicherweise diese Base URL:
https://open.bigmodel.cn/api/paas/v4
Die OpenAI-kompatible Adresse des ZSQH AI Gateway lautet:
https://ai.zhongshangqihang.com/v1
Beide werden mit dem OpenAI-Pfad /chat/completions kombiniert. Achten Sie darauf, Versionssegment oder /chat/completions nicht doppelt anzuhängen und nicht beliebig Schrägstriche am Ende zu ergänzen oder zu entfernen.
| Zugang | Beispiel für Base URL | Geeignet für | Hinweis |
|---|---|---|---|
| Zhipu offiziell | https://open.bigmodel.cn/api/paas/v4 |
Nur GLM, neueste Funktionen | Offizielles Konto und Guthaben nötig |
| ZSQH Gateway | https://ai.zhongshangqihang.com/v1 |
Einheitlicher Multi-Modell-Zugang und Abrechnung | Key im Gateway erstellen |
3. Modellnamen auswählen
Die GLM-Reihe ist nach Fähigkeiten in Text, Vision, Sprache, Embeddings und weitere Kategorien gegliedert. Bei Textmodellen gibt es unterschiedliche Stufen: einige für allgemeine Dialoge und Agenten, einige für niedrige Latenz und hohe Parallelität, einige mit längerem Kontext. Die aktuell in der offiziellen Dokumentation gelistete GLM-5-Reihe umfasst beispielsweise Schreibweisen wie glm-5.3, glm-5.3-flash und glm-5.2. Modelle werden jedoch laufend aktualisiert; maßgeblich für die tatsächlich verfügbaren Namen sind die Konsole und die Seite Modellpreise.
Wählen Sie nicht nur „das stärkste“ Modell. Für Kundendienstfragen und Batch-Klassifikation ist eine Stufe mit niedriger Latenz oft wirtschaftlicher; lange Dokumentanalysen und komplexe Agenten benötigen die höhere Ausstattung. Machen Sie den Modellnamen zur Konfigurationsoption statt zu einem festen Wert im Code; spätere Wechsel werden dadurch deutlich einfacher.
Wenn die Aufgabe Bildverständnis umfasst, wählen Sie ein Modell mit Vision-Eingabe; für Vektorsuche verwenden Sie die Embedding-Reihe. Pfade und Parameter von Text-, Vision- und Embedding-Modellen sind nicht vollständig identisch; derselbe Request-Body lässt sich nicht einfach auf alle anwenden. Nehmen Sie vor dem Start die Kandidatenmodelle in dasselbe Evaluationsset auf und vergleichen Sie Genauigkeit, Latenz und Nutzung, bevor Sie Haupt- und Ersatzmodell festlegen.
4. Erster Aufruf mit curl
Setzen Sie zuerst eine Umgebungsvariable, damit der Key nicht in der Befehlshistorie landet:
export GLM_API_KEY="your_key_here"
curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
-H "Authorization: Bearer $GLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.3",
"messages": [
{"role": "system", "content": "Du bist ein knapper technischer Assistent."},
{"role": "user", "content": "Erkläre in drei Sätzen, was ein API-Gateway ist."}
],
"temperature": 0.6
}'
Bei einer normalen Antwort sind drei Felder wichtig: choices[0].message.content ist die Antwort, usage die Nutzung dieser Anfrage und finish_reason der Grund für das Ende. Bei 401 prüfen Sie zuerst Key und Header; bei 1211 prüfen Sie zuerst den Modellnamen.
5. Aufruf mit dem Python SDK und Streaming
Das OpenAI SDK muss mindestens Version 1.0 haben. Nach dem Umstellen der Base URL auf GLM ist der Aufruf nahezu identisch mit OpenAI:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("GLM_API_KEY"),
base_url="https://open.bigmodel.cn/api/paas/v4",
)
stream = client.chat.completions.create(
model="glm-5.3",
messages=[{"role": "user", "content": "Schreibe eine Produktbeschreibung mit höchstens hundert Wörtern."}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
Beim Streaming gilt: Der erste Chunk kann nur Rolleninformationen enthalten, content ist dann leer; nehmen Sie nicht an, dass jeder Chunk Text enthält. Im Denkmodus kann der Denkinhalt im Feld reasoning_content erscheinen, während die endgültige Antwort weiterhin in content steht. Beide müssen getrennt behandelt werden, damit der Denkprozess nicht direkt an Endnutzer ausgeliefert wird.
6. Tool-Aufrufe und Parameterunterschiede
Tool-Aufrufe verwenden das OpenAI-Format tools und tool_choice. Wenn das Modell message.tool_calls zurückgibt, muss für jeden Aufruf function.arguments als JSON geparst, die lokale Funktion ausgeführt und das Ergebnis als Nachricht mit der Rolle tool zurückgesendet werden. In der Produktion sind Parametervalidierung und Timeout-Kontrolle nötig; den vom Modell erzeugten Parametern darf nicht blind vertraut werden.
Bei der Migration von OpenAI sind einige Unterschiede zu beachten: temperature liegt üblicherweise zwischen 0 und 1, wobei 0 möglicherweise nicht wirkt; der Standardwert liegt bei etwa 0.6; einige neue Fähigkeiten werden über extra_body übergeben. Maßgeblich sind die offiziellen OpenAI-kompatiblen Dokumentationen.
Im Streaming muss außerdem der Verbindungsabbruch durch den Client behandelt werden. Wenn ein Nutzer die Seite schließt, sollte der Server die Upstream-Anfrage möglichst schnell abbrechen, um weitere Generierung und Abrechnung zu vermeiden. Muss die Ausgabe zwingend vollständig erzeugt werden, verschieben Sie die Aufgabe in eine Hintergrundwarteschlange, statt sich auf die Frontend-Verbindung zu verlassen.
7. Häufige Fehler im Überblick
| Symptom | Mögliche Ursache | Behandlung |
|---|---|---|
| 401 / 1000 | Falscher Key, Typ passt nicht | Key-Typ und Header prüfen |
| 1211 | Modellname existiert nicht oder ist nicht freigeschaltet | Verfügbare Modelle in der Konsole prüfen |
| 1261 | Eingabe überschreitet Kontextlimit | Prompt kürzen oder aufteilen |
| 1302 / 1305 | Konto gedrosselt oder Plattform ausgelastet | Parallelität senken, Backoff verwenden |
| 1113 | Konto im Zahlungsrückstand | Nach Aufladung erneut versuchen |
| Verbindungs-Timeout | DNS, Proxy oder Netzwerkpfad | Zuerst mit curl die Netzwerkebene lokalisieren |
Wiederholungen helfen nur bei 429, 5xx und Netzwerk-Timeouts. Fehler wie 401, 1211 oder 1261 werden durch Wiederholen nicht besser; sie kosten nur Zeit und Kontingent.
8. Checkliste für die Migration von OpenAI
- Bestehende Prompts, Modellparameter und Evaluationssets sichern.
- Einen eigenen GLM-Key anlegen; keine Keys anderer Anbieter wiederverwenden.
- Base URL und Modellnamen in die Konfiguration verschieben.
- Mit derselben Stichprobe Ausgabequalität, Latenz und Nutzung vergleichen.
- Streaming-Parsing, Tool-Aufrufe und JSON-Ausgabe auf Kompatibilität prüfen.
- Wiederholungen, Timeouts und Parallelität anpassen und eine Woche beobachten, bevor der gesamte Verkehr umgestellt wird.
9. Häufige Fragen (FAQ)
1. Ist die GLM API vollständig OpenAI-kompatibel?
Die meisten gängigen Schnittstellen sind kompatibel, doch bei Parameterbereichen, Denkfeldern und einigen fortgeschrittenen Funktionen gibt es Unterschiede. Prüfen Sie die offizielle OpenAI-kompatible Dokumentation Punkt für Punkt und setzen Sie nicht voraus, dass sich alle Parameter gleich verhalten.
2. Muss am Ende der Base URL ein Schrägstrich stehen?
In der offiziellen Dokumentation kommen Varianten mit und ohne Schrägstrich vor; das SDK behandelt das meist automatisch. Entscheidend ist, Pfade nicht doppelt anzuhängen. Legen Sie eine Schreibweise fest und verwenden Sie sie im Projekt einheitlich.
3. Liefert Streaming den Denkprozess?
Einige Modelle geben im Denkmodus reasoning_content zurück. Ob dieser Inhalt angezeigt wird, hängt vom Produktdesign ab; Endnutzern wird üblicherweise nur die endgültige Antwort gezeigt.
4. Sind Tool-Aufrufe genauso formatiert wie bei OpenAI?
Tool-Definition und Rückgabestruktur folgen weitgehend dem OpenAI-Format, doch Parametradetails können sich je nach Modell ändern. Führen Sie vor dem Start einen Regressionstest mit echten Tools durch.
5. Sind die Modellnamen bei offiziellem Zugang und Gateway identisch?
Meist wird dieselbe Modellnamensmenge verwendet. Ob ein Gateway ein bestimmtes Modell anbietet und einen bestimmten Parameter unterstützt, richtet sich jedoch nach der Gateway-Konsole und der Seite Modellpreise.
