Die Qwen API wird von Alibaba Cloud Model Studio (Bailian) bereitgestellt; DashScope ist das native Schnittstellensystem. Model Studio bietet sowohl eine OpenAI-kompatible Schnittstelle als auch die native DashScope-Schnittstelle. Für die meisten Teams ist der OpenAI-kompatible Zugang am einfachsten: Vorhandene SDKs, Agent-Frameworks und Toolchains benötigen meist nur drei Änderungen – API Key, Base URL und Modellname.
Die eigentlichen Stolperstellen liegen nicht im „Läuft es überhaupt?“, sondern in der Region der Base URL, der Gültigkeit des Modellnamens, der Interpretation von Streaming und in den Parametern, die 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 Tool-Aufrufe, Fehlersuche und eine Migrationscheckliste.
Hinweis: Qwen, Tongyi Qianwen, Alibaba Cloud, Model Studio und DashScope sind Marken oder Produktnamen der Alibaba Group und verbundener Unternehmen. Dieser Artikel dient nur der technischen Erläuterung; es besteht keine Zugehörigkeit, Vertretung oder Beauftragung gegenüber der Alibaba Group. Base URL, Modellnamen, Kontextlänge und Abrechnungsregeln können sich ändern; maßgeblich sind die offizielle Dokumentation von Alibaba Cloud Model Studio und unsere Modellpreise.
1. Vorbereitung
Klären Sie vor dem Start drei Dinge:
- Einen nutzbaren API Key, der zur Zielregion passt.
- Die richtige Base URL; Festlandchina, internationale Seite und Gateway-Adresse dürfen nicht vermischt werden.
- Einen aktuell tatsächlich verfügbaren Modellnamen; kopieren Sie keine Beispiele aus alten Artikeln.
Prüfen Sie zuerst mit curl Authentifizierung und Netzwerk und binden Sie danach das SDK an. So lässt sich bei Fehlern leichter unterscheiden, ob Key, Adresse oder Code die Ursache ist.
2. Base URL: zuerst die Region, dann die Domain
Der Pfad der OpenAI-kompatiblen Schnittstelle ist fest /compatible-mode/v1; für Chat wird zusätzlich /chat/completions angehängt. Die Domain unterscheidet sich nach Region:
| Szenario | OpenAI-kompatible Base URL | Erläuterung |
|---|---|---|
| Festlandchina (Peking, alte gemeinsame Domain) | https://dashscope.aliyuncs.com/compatible-mode/v1 |
Kompatibel mit älterem Code, derzeit weiterhin verfügbar |
| Singapur (internationale Seite) | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 |
Konto und Key der internationalen Seite |
| USA, Virginia | https://dashscope-us.aliyuncs.com/compatible-mode/v1 |
Nur IPv4; Funktionsumfang laut Dokumentation |
| Hongkong | https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1 |
Eigene Region und eigener Key |
| Workspace-spezifisch | https://{WorkspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1 |
Für Produktion empfohlen, bessere Durchsatz- und Isolationswerte |
| ZSQH AI Gateway | https://ai.zhongshangqihang.com/v1 |
Einheitlicher Multi-Modell-Zugang |
Drei Punkte sind entscheidend. Erstens ist der API Key an eine Region gebunden; regionenübergreifende Aufrufe liefern meist 401 und invalid_api_key. Das bedeutet, dass Key und Adresse nicht zusammenpassen, nicht dass der Key ungültig ist. Zweitens sind Festlandchina-Konto und internationales Konto zwei getrennte Systeme; Keys, Abrechnung und Modelllisten sind nicht austauschbar. Drittens akzeptiert die Workspace-spezifische Domain nur Keys des eigenen Workspace, bietet aber bessere Durchsatz- und Verkehrsisolierung und eignet sich für Produktion; die alte gemeinsame Domain ist praktisch für schnelle Tests und workspace-übergreifende Nutzung.
Wenn ein Team mehrere Modelle verwendet und Regionen, Kontingente und mehrere Key-Sätze nicht selbst verwalten möchte, kann es im ZSQH AI Gateway einen einheitlichen Key erstellen und die Base URL auf die letzte Zeile der Tabelle umstellen.
3. Modellnamen auswählen
Die Modellliste von Model Studio wird schnell aktualisiert. Auf der aktuellen offiziellen Modellseite umfasst die Textgenerierung unter anderem qwen3.8-max, qwen3.7-plus und qwen3.8-flash. Aus der Benennung lässt sich grob ableiten: max steht für die höchste Leistungsfähigkeit, plus für einen ausgewogenen Bereich, flash für niedrige Latenz und Kosten. Genaue Positionierung und Kontextlänge entnehmen Sie der offiziellen Modelldokumentation; Preise ändern sich und richten sich nach der Seite Modellpreise.
Wählen Sie nicht nur „das stärkste“ Modell. Für Kundendienstfragen, Batch-Klassifikation und Inhaltsprüfung 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.
Zwei weitere häufige Fallstricke: Schreibweisen wie qwen-max und qwen-plus aus älteren Anleitungen können sich geändert haben; prüfen Sie vor der Anbindung die Modellliste in der Konsole. Für Vektorfähigkeiten verwenden Sie die Embedding-Reihe (etwa qwen3.7-text-embedding); ihr Request-Body unterscheidet sich vom Chat-Aufruf. Qwen-Audio unterstützt das OpenAI-kompatible Protokoll nicht und benötigt die native DashScope-Schnittstelle.
4. Erster Aufruf mit curl
Setzen Sie zuerst eine Umgebungsvariable, damit der Key nicht in der Befehlshistorie landet:
export DASHSCOPE_API_KEY="your_key_here"
curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-max",
"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.7
}'
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 Region; bei 404 und ModelNotFound prüfen Sie den Modellnamen und ob das Modell in dieser Region freigeschaltet ist.
5. Aufruf mit dem Python SDK und Streaming
Das OpenAI SDK muss mindestens Version 1.0 haben. Nach dem Umstellen der Base URL auf Model Studio ist der Aufruf nahezu identisch mit OpenAI:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
stream = client.chat.completions.create(
model="qwen3.8-max",
messages=[{"role": "user", "content": "Schreibe eine Produktbeschreibung mit höchstens hundert Wörtern."}],
stream=True,
stream_options={"include_usage": 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. Mit stream_options={"include_usage": True} erscheint die Nutzung im letzten Chunk. Bei direktem HTTP ist die Antwort SSE-formatiert und endet mit data: [DONE]. Wenn ein Nutzer die Seite schließt, sollte der Server die Upstream-Anfrage möglichst schnell abbrechen, um weitere Generierung und Abrechnung zu vermeiden.
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 role: "tool" zurückgesendet werden. In mehrstufigen Abläufen muss jede Runde tools enthalten. In der Produktion sind Parametervalidierung, Rechteprüfung und Timeout-Kontrolle nötig; den vom Modell erzeugten Parametern darf nicht blind vertraut werden.
Die offizielle Kompatibilitätsdokumentation nennt derzeit zwei Einschränkungen für Tools: Nur ein Teil der Modelle wird unterstützt, und tools kann vorerst nicht gleichzeitig mit stream=True verwendet werden. Modellliste und Fähigkeiten werden laufend aktualisiert; testen Sie vor dem Start mit dem Zielmodell. Muss ein Geschäftsprozess während des Streamings Tools aufrufen, prüfen Sie die native DashScope-Schnittstelle oder führen Tool-Aufrufe als nicht gestreamten Schritt aus.
Bei der Migration von OpenAI sind außerdem diese Parameterunterschiede zu beachten:
messages: Nurmessages[0]darf die Rolle system haben; user und assistant sollten sich in der Regel abwechseln, die letzte Nachricht muss von user stammen.temperature: Der Bereich ist [0, 2); die offizielle Empfehlung rät von 0 ab.top_p: Der Bereich ist (0, 1.0).seed: Verwendet eine vorzeichenlose 64-Bit-Ganzzahl.stop: Array-Elemente dürfen nicht Token-IDs und Strings mischen.system_fingerprint: Wird derzeit als leerer String zurückgegeben.- Erweiterte Parameter wie
enable_search: Werden meist überextra_bodyübergeben und nicht von allen Modellen unterstützt. - Felder wie
response_formatundfrequency_penalty: Werden in der Kompatibilitätsdokumentation nicht zugesichert; setzen Sie kein identisches Verhalten wie bei OpenAI voraus.
7. Häufige Fehler im Überblick
| Symptom | Typischer Fehlercode | Mögliche Ursache | Behandlung |
|---|---|---|---|
| 401 | InvalidApiKey / invalid_api_key |
Falscher Key, Region passt nicht, Tarif-Key vermischt | Region und Typ von Key und Base URL prüfen |
| 404 | ModelNotFound / model_not_found |
Modellname falsch geschrieben, Modell in der Region nicht vorhanden, nicht freigeschaltet | Modellliste in der Konsole prüfen |
| 404 | model_not_supported |
Modell unterstützt den OpenAI-kompatiblen Modus nicht | Native DashScope-Schnittstelle verwenden |
| 403 | AccessDenied / Workspace.AccessDenied |
Fehlende Workspace- oder Modellrechte | Berechtigungen des Workspace prüfen |
| 403 | AllocationQuota.FreeTierOnly |
Kostenloses Kontingent aufgebraucht | Aufladen oder Tarif anpassen |
| 429 | Throttling-Reihe |
Anfragefrequenz, Tokens oder Parallelität überschritten | Parallelität senken, Backoff, Kontingent beantragen |
| 400 | Arrearage |
Konto im Zahlungsrückstand | Nach Aufladung erneut versuchen |
| 400 | Range of input length... |
Eingabe überschreitet Kontextlimit | Prompt kürzen oder aufteilen |
| 400 | DataInspectionFailed |
Eingabe oder Ausgabe durch Inhaltssicherheit blockiert | Inhalt anpassen und erneut versuchen |
Wiederholungen helfen nur bei 429, 5xx und Netzwerk-Timeouts. Bei 401, 403, 404 und Parameterfehlern werden sie nicht besser, sondern kosten nur Zeit und Kontingent. Erfassen Sie bei der Fehlersuche die Request ID aus der Antwort und suchen Sie damit in den Konsolen-Logs; das ist schneller als Raten.
8. Checkliste für die Migration von OpenAI
- Bestehende Prompts, Modellparameter und Evaluationssets sichern.
- Einen Qwen-Key anlegen, der zur Zielregion passt; keine Keys anderer Anbieter wiederverwenden.
- Base URL und Modellnamen in die Konfiguration verschieben.
- Die Rollenregeln von
messagesprüfen: erste Nachricht system, letzte Nachricht user. - Streaming-Parsing und Erfassung der
usageprüfen. - Mit echten Tools einen Regressionstest für Tool-Aufrufe durchführen.
- Mit derselben Stichprobe Ausgabequalität, Latenz und Nutzung vergleichen.
- Wiederholungen, Timeouts und Parallelität anpassen und eine Woche beobachten, bevor der gesamte Verkehr umgestellt wird.
- Request IDs in Logs erfassen und einen Rollback-Schalter bereithalten.
9. Häufige Fragen (FAQ)
1. Ist die Qwen API mit OpenAI kompatibel?
Die meisten gängigen Chat-Schnittstellen sind kompatibel, doch es gibt Unterschiede bei Regionsbindung, Rollenreihenfolge, Parameterbereichen und Einschränkungen von Tool-Aufrufen. Prüfen Sie die offizielle OpenAI-kompatible Dokumentation Punkt für Punkt und setzen Sie kein identisches Verhalten aller Parameter voraus.
2. Können Festlandchina und internationale Seite denselben Key verwenden?
Nein. Konten, Keys, Zugangsdomains und Abrechnung der beiden Seiten sind unabhängig. Regionen- oder seitenübergreifende Aufrufe liefern meist 401 und invalid_api_key.
3. Sollte man die alte Domain oder die Workspace-spezifische Domain verwenden?
Für schnelle Tests kann die alte gemeinsame Domain genügen; für Produktion empfiehlt sich die Workspace-spezifische Domain wegen besserer Durchsatz- und Isolationswerte. Entscheidend ist, dass der Key zur Region und zum Workspace der Domain passt.
4. Warum kommt model_not_found, obwohl der Modellname korrekt ist?
Häufige Ursachen sind: Das Modell ist in dieser Region nicht verfügbar, nicht freigeschaltet, die Groß-/Kleinschreibung stimmt nicht, oder es handelt sich um eine abgekündigte Version. Maßgeblich ist die aktuelle Modellliste in der Konsole.
5. Können tools und stream zusammen verwendet werden?
Laut offizieller Kompatibilitätsdokumentation ist beides derzeit nicht gleichzeitig möglich, und Tool-Aufrufe werden nur für einen Teil der Modelle genannt. Fähigkeiten und Einschränkungen ändern sich mit den Modellen; testen Sie vor dem Start mit dem Zielmodell oder verwenden Sie die native DashScope-Schnittstelle.
