Die häufigste Ursache für ein gescheitertes „Llama API einrichten“ ist nicht die Modellqualität, sondern drei nicht abgestimmte Parameter: Base URL, Authentifizierungsart und Modellname. Nach dem Ende der öffentlichen Meta-Llama-API-Vorschau im Juli 2026 verteilen sich die Llama-Zugänge auf Cloud-Anbieter, Inferenzplattformen, selbst betriebene Dienste und OpenAI-kompatible Gateways. Die Anfrageformen ähneln sich, die Details unterscheiden sich aber.

Dieser Beitrag geht der Reihe nach vor: Einstieg klären, URL zusammensetzen, Modellnamen finden, erste Anfrage senden, Streaming und Tool-Aufrufe behandeln, Fehler eingrenzen und von der alten Schnittstelle migrieren. Die Beispiele nutzen OpenAI-kompatible Schnittstellen; Modellliste und Preise richten sich nach den Modellpreisen auf dieser Website.

Hinweis: Meta und Llama sind Marken von Meta Platforms, Inc.; Groq, OpenRouter, AWS, Google Cloud und weitere Namen sind Marken der jeweiligen Inhaber. Dieser Beitrag dient der technischen Erläuterung und begründet keine Zugehörigkeits-, Vertretungs- oder Fürsprachebeziehung zu den genannten Plattformen.

1. Vor der Anbindung drei Dinge klären

Unabhängig vom Anbieter gehören drei Angaben in die Konfiguration:

  • Base URL: Protokoll, Domain und Pfadpräfix, meist mit /v1 am Ende.
  • Authentifizierung: Bearer-Token, IAM-Signatur oder Servicekonto – nicht vermischen.
  • Modellname: die interne Modell-ID der Plattform, nicht der Produktname auf der Werbeseite.

Dazu zwei nichttechnische Punkte: durch welche Regionen und Knoten die Daten laufen und wie der Versionslebenszyklus des Modells aussieht. Ersteres betrifft die Compliance, letzteres die Frage, ob in einem halben Jahr migriert werden muss.

2. Base URL: das SDK ergänzt den Pfad selbst

Die base_url des OpenAI SDK endet am Versionspräfix; das SDK hängt /chat/completions an. Daher:

  • Richtig: https://api.groq.com/openai/v1
  • Falsch: https://api.groq.com/openai/v1/chat/completions (doppelter Pfad)
  • Falsch: https://api.groq.com/openai (ohne /v1, die meisten Plattformen liefern 404)

Die Pfadpräfixe unterscheiden sich: Groq nutzt /openai/v1, OpenRouter /api/v1, ein selbst betriebenes vLLM standardmäßig /v1. Cloud-Endpunkte sind komplexer; die OpenAI-kompatible Adresse von Vertex AI enthält Projekt, Region und Endpunktpfad und darf nicht nur als Domain kopiert werden. Am sichersten die vollständige Base URL aus dem „Beispielaufruf“ der Konsole übernehmen und mit einer minimalen Anfrage prüfen.

3. Modellnamen: bei jeder Plattform anders

Dasselbe Llama-Modell kann auf verschiedenen Plattformen völlig unterschiedlich heißen:

Einstieg Base-URL-Beispiel Modellname-Beispiel Hinweis
Groq https://api.groq.com/openai/v1 llama-3.3-70b-versatile Aktuelle Modellliste maßgeblich
OpenRouter https://openrouter.ai/api/v1 meta-llama/llama-3.3-70b-instruct Aggregiertes Routing, Präfix beachten
Eigenes vLLM http://localhost:8000/v1 von --served-model-name gesetzt Ohne Angabe der Gewichtspfad
AWS Bedrock https://bedrock-runtime.us-east-1.amazonaws.com us.meta.llama4-scout-17b-instruct-v1:0 Invoke/Converse, nicht OpenAI-kompatibel
Kompatibles Gateway https://ai.zhongshangqihang.com/v1 laut Modellliste der Konsole Ein Key für mehrere Modelle

Modellnamen unterscheiden Groß-/Kleinschreibung, Versionsnummer, Quantisierung und Inferenzvariante. Llama-3.3-70B-Instruct, llama-3.3-70b-versatile und meta-llama/llama-3.3-70b-instruct können unterschiedliche Deployments bezeichnen. Keine ID aus einem Blog übernehmen, sondern in der Konsole oder über GET /models prüfen.

Auch den Lebenszyklus beachten. Google Cloud hat angekündigt, dass llama-3.3-70b-instruct-maas am 21. Oktober 2026 außer Betrieb geht; AWS Llama 4 Scout befindet sich im Legacy-Status mit angekündigtem Support-Ende am 30. März 2027. Modell-IDs gehören in die Konfiguration, nicht verstreut in die Geschäftslogik, damit bei einer Migration nicht das ganze Repository durchsucht werden muss.

4. Erster Aufruf: zuerst curl

Einen Test-Key in eine Umgebungsvariable legen, damit er nicht in der Befehlshistorie erscheint:

export LLAMA_API_KEY="IHR_KEY"

curl -s https://api.groq.com/openai/v1/chat/completions \
  -H "Authorization: Bearer $LLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-versatile",
    "messages": [{"role": "user", "content": "Erklaere in einem Satz, was eine OpenAI-kompatible Schnittstelle ist"}],
    "max_tokens": 128
  }'

Im zurückgegebenen JSON vier Felder prüfen: ob choices[0].message.content Inhalt hat, ob finish_reason stop oder length ist, ob usage Eingabe- und Ausgabe-Tokens zählt und ob model der Anfrage entspricht. Weicht das zurückgegebene model ab, kann ein Routing oder Alias dahinterstecken; Abrechnung und Evaluation werden dadurch beeinflusst.

5. Python SDK: Unterschiede in die Konfiguration verlagern

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LLAMA_API_KEY"],
    base_url=os.environ["LLAMA_BASE_URL"],
)

resp = client.chat.completions.create(
    model=os.environ["LLAMA_MODEL"],
    messages=[{"role": "user", "content": "Erklaere in einem Satz, was eine OpenAI-kompatible Schnittstelle ist"}],
    max_tokens=128,
    timeout=60,
)
print(resp.choices[0].message.content)

Drei Gewohnheiten ersparen später Ärger: Timeout explizit setzen; Retries begrenzen und nur wiederholbare Fehler wiederholen; base_url, model und max_tokens vollständig in die Konfiguration aufnehmen. Keine unbegrenzten Retries und keine Wiederholung von 400-Parameterfehlern.

Auch die Parameternamen unterscheiden sich. Manche Plattformen akzeptieren nur max_tokens, andere sind bereits auf max_completion_tokens umgestiegen; manche beschränken den Bereich von temperature, die Anzahl von stop oder die Rollen. Maßgeblich ist die Dokumentation der Zielplattform; OpenAI-Parameter nicht ungeprüft durchreichen.

6. Streaming: blockweise verarbeiten, nicht auf alles warten

Mit stream=True antwortet der Server üblicherweise per Server-Sent Events; jede Zeile beginnt mit data:, beendet wird mit data: [DONE]. Der Client liest choices[0].delta.content blockweise und behandelt leere Blöcke, Heartbeats und Verbindungsabbrüche. Drei häufige Probleme:

  • delta.content wird als immer vorhanden angenommen und bricht bei None ab.
  • Proxy oder Gateway puffern die Antwort; im Frontend wirkt es „nicht gestreamt“, tatsächlich kommt alles am Ende.
  • Nach einem Client-Abbruch generiert der Server weiter und verbraucht Kontingent; Abbruch und Timeout müssen auf Geschäftsebene geregelt sein.

Bei einem Gateway vorher klären, ob es SSE durchreicht und Fehlerereignisse umschreibt. Streaming ist empfindlicher als nicht gestreamte Aufrufe; vor dem Start separat testen.

7. Tool-Aufrufe: zuerst prüfen, ob die Plattform sie unterstützt

Der OpenAI-Stil mit tools wird nicht von jedem Llama-Host vollständig unterstützt. Vor dem Aufruf drei Dinge prüfen: Das Modell unterstützt Tool-Aufrufe, die Plattform reicht tools und tool_choice durch, und finish_reason kann tool_calls liefern.

Die zurückgegebenen Tool-Parameter sind meist ein JSON-String, kein Objekt. Das Backend muss JSON parsen und gegen ein Schema prüfen, bevor die eigentliche Funktion läuft; Modellausgaben nie direkt in SQL, Shell oder interne Schnittstellen einsetzen. Tool-Ausführung braucht Timeout, Idempotenz und Rechtegrenzen; Fehlerergebnisse gehen an das Modell zurück, das über Wiederholung oder geänderte Parameter entscheidet. Parallele Tool-Aufrufe, strikte Schemata und gestreamte Tool-Aufrufe unterscheiden sich am stärksten zwischen Plattformen und müssen einzeln geprüft werden.

8. Häufige Fehler: erst Statuscode, dann Antwortkörper

  • 401: Key fehlt, ist falsch formatiert, stammt von einer anderen Plattform oder wurde gesperrt.
  • 404: Base URL mit doppeltem oder fehlendem /v1 oder Modellname existiert nicht.
  • 400: Parameter nicht unterstützt, etwa max_tokens und max_completion_tokens gemischt oder ungültige Rollen.
  • 403: Key gültig, aber keine Berechtigung für Modell, Projekt oder Region.
  • 429: Rate- oder Parallelitätslimit erreicht. Retry-After lesen, exponentielles Backoff mit Jitter verwenden, nicht in festem Takt wiederholen.
  • 5xx: Störung oder Timeout stromaufwärts. Nur idempotente Anfragen wiederholen und die Request-ID protokollieren.
  • 200, aber leerer Inhalt: möglich sind finish_reason=length, Inhaltsfilter oder ein Streaming-Parsefehler.

Von außen nach innen vorgehen: zuerst mit curl die Geschäftslogik umgehen, dann das offizielle SDK testen, erst zuletzt den Prompt verdächtigen. Request-ID, Statuscode, Modellname und Base URL ins Log schreiben, sonst sind plattformübergreifende Probleme kaum reproduzierbar.

9. Migration von der alten Llama API: der Reihe nach

  1. Code und Konfiguration nach api.llama.com, /compat/v1 und alten Modellnamen durchsuchen und alle Aufrufstellen auflisten.
  2. Auf der neuen Plattform einen Key erstellen, Base URL und Modellname prüfen und zuerst eine minimale curl-Anfrage durchführen.
  3. Eine Modellzuordnung anlegen: neue Modell-ID, Kontextgrenze, Ausgabeobergrenze, Streaming- und Tool-Unterstützung.
  4. Base URL und Authentifizierung ersetzen, Timeout, Retry und Logfelder beibehalten und nicht nebenbei die Geschäftslogik ändern.
  5. Streaming und Tool-Aufrufe separat testen; hier tritt „nicht gestreamt funktioniert, gestreamt nicht“ am häufigsten auf.
  6. Mit echten Anfragen eine kleine Evaluation durchführen, dann 5 bis 10 Prozent des Traffics umstellen und Fehlerrate sowie p95-Latenz beobachten.
  7. Alten Kanal oder Ersatz-Host behalten und erst nach einer Rollback-Übung vollständig wechseln.

Eine Migration ist nicht abgeschlossen, wenn „Text zurückkommt“, sondern wenn Qualität, Latenz, Limits und Abrechnung akzeptabel sind und Probleme einer konkreten Anfrage zugeordnet werden können.

Häufig gestellte Fragen

Ist die Base URL der Llama API fest?

Nein. Der alte Meta-Llama-API-Einstieg ist eingestellt; die Base URL hängt von der gewählten Plattform ab. Groq, OpenRouter, eigenes vLLM und kompatible Gateways nutzen unterschiedliche Pfadpräfixe; maßgeblich ist das Konsolenbeispiel.

Warum heißt dasselbe Llama-Modell auf verschiedenen Plattformen anders?

Plattformen ergänzen eigene Präfixe, Versionen, Quantisierungen und Deployment-Kennungen. Der Modellname ist eine interne ID, nicht der allgemeine Name der Modellfamilie. Beim Plattformwechsel ändert sich der Name meist mit.

Kann das OpenAI SDK direkt Llama aufrufen?

Ja, sofern die Zielplattform eine OpenAI-kompatible /chat/completions-Schnittstelle bietet. base_url auf die Plattformadresse, api_key auf den Plattform-Key und model auf die Plattform-ID setzen; damit ist der minimale Aufruf möglich. Tool-Aufrufe, Streaming und Fehlerstrukturen sind weiterhin einzeln zu prüfen.

Braucht Streaming ein anderes SDK?

Die meisten OpenAI-SDKs unterstützen stream=True, ein Wechsel ist nicht nötig. Zu prüfen ist, ob die Plattform standardmäßige SSE liefert, ob das Ende [DONE] ist und ob ein Gateway die Antwort puffert.

Was zuerst prüfen, wenn Tool-Aufrufe scheitern?

Zuerst, ob Modell und Plattform Tool-Aufrufe deklarieren; dann, ob das JSON-Schema von tools gültig und tool_choice akzeptiert ist; schließlich finish_reason und ob die Parameter-JSON parsebar ist. Schicht für Schicht eingrenzen, nicht zuerst den Prompt ändern.

Nächster Schritt

Wählen Sie einen Einstieg, führen Sie mit Base URL und Modellname aus dem Konsolenbeispiel eine curl-Anfrage durch und binden Sie dann das Python SDK an; Streaming und Tool-Aufrufe separat abnehmen. Wer einen einheitlichen Einstieg, Logs und Modellwechsel braucht, kann mit der Registrierung beim ZSQH AI Gateway beginnen; Modellliste und Abrechnung richten sich nach den Modellpreisen.

Weiterführende Beiträge: