LangChain ist kein Modelldienst; das Framework verbindet Prompts, Modelle, Tools und Output-Parser zu einer Anwendung. Bietet der Ziel-Dienst eine OpenAI-kompatible Schnittstelle, lässt er sich mit ChatOpenAI aus langchain-openai anbinden und auf die eigene Base URL richten. In der Praxis scheitern die meisten weniger am Framework als an drei Feldern: bis zu welcher Ebene die Adresse reicht, woher der Key gelesen wird und ob der Modellname mit dem übereinstimmt, was das Gateway bereitstellt.
Dieser Artikel folgt der Reihenfolge Installation, Minimalbeispiel, Umgebungsvariablen, Ketten, Streaming, Agenten, Fehlersuche und Migration. LangChain entwickelt sich schnell; Klassennamen und Parameter richten sich nach der installierten Version.
Hinweis: LangChain ist eine Marke von LangChain, Inc., OpenAI eine Marke der jeweiligen Rechteinhaber. Dieser Artikel steht in keiner Zugehörigkeit zu den genannten Unternehmen. Modellnamen und Preise entnehmen Sie den Modellpreisen, Schnittstellendetails der offiziellen Dokumentation.
1. Installation: zwei Pakete genügen
Nach dem Anlegen einer virtuellen Umgebung installieren:
python -m venv .venv
source .venv/bin/activate
pip install -U langchain langchain-openai
langchain-openai ist die Integration für OpenAI und kompatible Schnittstellen, langchain liefert Ketten, Agenten und weitere höhere Funktionen, langchain-core wird als Abhängigkeit mitinstalliert. In der Produktion sollten Versionen in requirements.txt festgeschrieben werden, damit nicht verschiedene Maschinen unterschiedliche APIs erhalten. Der in älteren Anleitungen verbreitete Pfad langchain.chat_models.ChatOpenAI wurde migriert; der neue Import lautet langchain_openai.
2. Minimalbeispiel: ChatOpenAI auf eine eigene Adresse richten
Im Kern sind es drei Parameter: model, base_url und api_key. base_url endet üblicherweise auf /v1 und enthält kein /chat/completions; den Pfad ergänzt der Client selbst.
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="IhrModellname",
base_url="https://ihre-gateway-adresse/v1",
api_key="sk-IhrKey",
temperature=0.3,
timeout=60,
)
resp = llm.invoke("Erkläre in einem Satz, was eine OpenAI-kompatible Schnittstelle ist.")
print(resp.content)
Erst diesen Block zum Laufen bringen, dann Prompts und Tools ergänzen. Empfohlene Prüfreihenfolge:
- Mit curl
base_urlplus/chat/completionsaufrufen und Adresse sowie Key bestätigen. - In Python
ChatOpenAIerzeugen und genau einmalinvokeausführen. resp.contentundresp.response_metadataausgeben und Modellname sowie Verbrauchsfelder prüfen.- Danach Prompt-Vorlagen, Output-Parser und Tools ergänzen.
Ergibt dieser Schritt 404, zuerst die Adressebenen prüfen; 401 deutet auf Key und Auth-Header; ein unbekanntes Modell erfordert einen Abgleich mit /v1/models. Der Modellname muss exakt dem entsprechen, was das Gateway zurückgibt; Groß-/Kleinschreibung, Datumssuffix und Aliase zählen als Unterschiede.
3. Parameter und Umgebungsvariablen verwalten
Keys nicht fest in den Code schreiben. Das OpenAI SDK liest OPENAI_API_KEY und kann OPENAI_BASE_URL verwenden; ältere Codebeispiele und Dokumentationen nutzen teils OPENAI_API_BASE. Das Verhalten unterscheidet sich je nach Version; am zuverlässigsten sind explizite Parameter, Umgebungsvariablen dienen nur als Standardwerte.
| Parameter | Funktion | Übliche Angabe |
|---|---|---|
model |
Modellbezeichnung | Identisch mit der Ausgabe von /v1/models |
base_url |
Wurzeladresse der Schnittstelle | https://host/v1 |
api_key |
Authentifizierungsschlüssel | Explizit übergeben oder OPENAI_API_KEY lesen |
temperature |
Zufälligkeit der Stichprobe | Im unterstützten Bereich des Modells |
timeout |
Timeout einer Anfrage | Nach Aufgabenlänge anpassen |
max_retries |
Wiederholungen im Client | Üblicherweise etwa 2 |
Für die lokale Entwicklung eignet sich eine .env-Datei mit python-dotenv, die aber zwingend in .gitignore gehört. Im Team sollten Keys nach Projekt und Umgebung getrennt, Produktion und Test mit eigenen Limits versehen und bei Problemen einzeln deaktivierbar sein.
4. Ketten: Prompt und Modell mit LCEL verbinden
Die LangChain Expression Language (LCEL) kombiniert Komponenten mit dem Pipe-Operator. Die grundlegende Kette lautet „Prompt → Modell → Output-Parser“:
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
prompt = ChatPromptTemplate.from_messages([
("system", "Du bist ein technischer Support-Assistent. Antworte konkret und nenne zuerst das Ergebnis."),
("user", "{question}"),
])
chain = prompt | llm | StrOutputParser()
print(chain.invoke({"question": "Bis zu welcher Ebene sollte die Base URL reichen?"}))
invoke nimmt eine Eingabe und liefert ein Ergebnis, batch verarbeitet eine Liste, stream gibt Blöcke zurück. Der Output-Parser wandelt Modellnachrichten in Strings oder strukturierte Objekte. Wird JSON benötigt, vorrangig die strukturierte Ausgabe des Modells nutzen und zusätzlich parsen und validieren, statt sich nur auf den Prompt zu verlassen.
5. Streaming und Batch-Aufrufe
Streaming eignet sich für Chat-Oberflächen und lange Antworten:
for chunk in chain.stream({"question": "Erkläre kurz, was ein Tool-Aufruf ist"}):
print(chunk, end="", flush=True)
Funktioniert invoke, liefert stream aber keine schrittweise Ausgabe, puffert meist ein Proxy auf der Strecke oder der Upstream unterstützt kein Streaming. Prüfen, ob das Gateway text/event-stream zurückgibt und ob der Reverse Proxy Buffering abgeschaltet hat. Bei Batch-Aufrufen auf die Parallelität achten: batch sendet standardmäßig möglicherweise parallel; bei 429 die Parallelität senken oder in Portionen arbeiten und fehlgeschlagene Elemente für einen erneuten Lauf behalten.
6. Agenten: Modell plus Tools plus Schleife
Ein Agent ist im Kern eine Schleife: Das Modell entscheidet, ob ein Tool nötig ist, die Laufzeit führt es aus und gibt das Ergebnis zurück, das Modell entscheidet den nächsten Schritt, bis die endgültige Antwort steht. LangChain 1.x bietet übergeordnete Schnittstellen wie create_agent; Version 0.3 und älter nutzten häufig AgentExecutor. Die Schreibweisen unterscheiden sich; das Kopieren alter Anleitungen führt leicht zu Importfehlern.
Tools lassen sich per Decorator definieren; Funktionsname, Parametertypen und Docstring beeinflussen die Auswahl durch das Modell:
from langchain_core.tools import tool
@tool
def get_order_status(order_id: str) -> str:
"""Fragt den Versandstatus anhand der Bestellnummer ab."""
return "Versandt, Zustellung voraussichtlich innerhalb von drei Tagen"
Bei einem eigenen Gateway ist wichtig: Tool-Aufrufe setzen vollständige Unterstützung von tools, tool_choice und dem Format der Ergebnisrückgabe voraus. Manche kompatiblen Dienste implementieren nur die Basiskonversation und ignorieren Parameter oder melden Fehler. Zuerst mit einem Tool und einer einfachen Frage testen, dann Zahl der Tools und parallele Aufrufe erhöhen.
7. Häufige Fehler und Vorgehen
| Symptom | Mögliche Ursache | Maßnahme |
|---|---|---|
| 401 Unauthorized | Key ungültig, nicht übergeben oder mit Leerzeichen | api_key explizit setzen, Umgebungsvariable prüfen |
| 404 model_not_found | Modellname weicht ab oder Adresse enthält zusätzlichen Pfad | /v1/models abfragen, base_url nur bis /v1 |
| 429 Too Many Requests | Parallelität zu hoch oder Kontingent erschöpft | Parallelität senken, aufteilen, Backoff-Retry |
| 400 context_length_exceeded | Eingabe über dem Kontextlimit | Verlauf kürzen, Dokumente teilen, vorher zusammenfassen |
| OutputParserException | Modellausgabe entspricht nicht dem Format | Format vorgeben, validieren, einmal erneut versuchen |
| APIConnectionError / Timeout | Netzwerk, Proxy, Zertifikat oder Upstream-Störung | Proxy-Variablen, DNS und Timeout prüfen |
| Tool-Aufruf ohne Reaktion | Upstream unterstützt das tools-Protokoll nicht | Modell mit Tool-Unterstützung oder normale Kette verwenden |
Bei der Fehlersuche zuerst LangChain umgehen und mit curl oder dem OpenAI SDK dieselbe Adresse direkt ansprechen. Gelingt der Direktaufruf, liegt es meist an Parameternamen, Umgebungsvariablen oder Version; scheitern beide, an Gateway, Key oder Netzwerk.
8. Migration von älteren Schreibweisen
- Importpfad:
langchain.chat_models.ChatOpenAIwird zulangchain_openai.ChatOpenAI. - Parameternamen:
model_namewird zumodel,openai_api_basezubase_url. - Die alte Text-Completion-Klasse
OpenAIweicht zunehmend den Chat-Modellen; neue Projekte nutzen direktChatOpenAI. - Alte Ketten und Agenten sind in 1.x teilweise in Kompatibilitätspakete überführt; vor der Migration die offiziellen Hinweise lesen und keine mehreren Hauptversionen mischen.
- Abhängigkeiten: Vor dem Upgrade Versionen festhalten und die Kernstrecke in einer Testumgebung durchlaufen, besonders Streaming, Tool-Aufrufe und strukturierte Ausgabe.
Häufige Fragen
Gehört /v1 nun in die base_url oder nicht?
Die meisten OpenAI-kompatiblen Dienste erwarten /v1; der Client ergänzt /chat/completions. Manche Gateways legen das Versionspräfix auf einen anderen Pfad, maßgeblich ist die Anbieterdokumentation. Der einfache Test: base_url + /chat/completions muss per curl funktionieren.
Kann die Umgebungsvariable OPENAI_BASE_URL verwendet werden?
Ja, das OpenAI SDK liest sie; manche älteren Dokumente nennen OPENAI_API_BASE. Die Unterstützung unterscheidet sich je nach Version; in Produktionscode sollte base_url explizit übergeben werden, damit Umgebungsunterschiede nicht zu falschen Adressen führen.
Warum liefert invoke Ergebnisse, stream aber nichts?
Häufige Ursachen sind Proxy-Buffering, fehlende Streaming-Unterstützung beim Upstream oder Code, der das gestreamte Ergebnis wie einen vollständigen String behandelt. Zuerst prüfen, ob der Antworttyp ein Ereignisstrom ist, dann Reverse-Proxy-Konfiguration und Leseweise kontrollieren.
Kann LangChain auch Claude, DeepSeek und andere Nicht-OpenAI-Modelle anbinden?
Ja. Bietet der Dienst eine OpenAI-kompatible Schnittstelle, genügen bei ChatOpenAI neue Adresse und Modellname; bei nativen Protokollen wird das jeweilige Integrationspaket verwendet. Parameter und Tool-Fähigkeiten unterscheiden sich und müssen getrennt geprüft werden.
Was tun, wenn der Agent beim Tool-Aufruf Parameterfehler meldet?
Zuerst prüfen, ob die zurückgegebene Tool-Struktur dem Protokoll entspricht, dann Parametertypen und Pflichtfelder der Funktion kontrollieren. Manche kompatiblen Gateways unterstützen parallele Tool-Aufrufe nur teilweise; parallele Aufrufe deaktivieren und jeweils ein Tool anbieten, um schrittweise einzugrenzen.
Nächste Schritte
Der Schlüssel zur Anbindung liegt darin, Adresse, Key und Modellname festzulegen, mit einer minimalen Anfrage zu prüfen und erst danach Ketten und Tools zu ergänzen. Für einen einheitlichen OpenAI-kompatiblen Zugang, virtuelle Keys und Verbrauchsprotokolle können Sie sich im ZSQH AI Gateway registrieren; Modelle und Preise entnehmen Sie den Modellpreisen.
Weiterlesen:
