LangChain Fehlerbehandlung und Debugging
In der Agent-Entwicklung sind verschiedene Fehler unvermeidlich. Dieser Artikel fasst häufige Fehlertypen, Debugging-Methoden und Best Practices zusammen.
Häufige Fehlertypen
| Fehlertyp | Typische Ursache | Lösung |
|---|---|---|
| ImportError | Provider-Paket nicht installiert | pip install langchain-deepseek, usw. |
| API-Schlüssel-Fehler | .env nicht konfiguriert oder Schlüssel ungültig | Umgebungsvariablen und Gültigkeit des Schlüssels prüfen |
| Timeout-Fehler | Netzwerkprobleme oder langsame Modellantwort | Setzen Sie den timeout-Parameter |
| Token-Limit überschritten | Nachrichtenverlauf ist zu lang | Verwenden Sie trim_messages() zum Kürzen |
| Fehler beim Tool-Aufruf | Ausnahme im Tool | Verwenden Sie ToolException + handle_tool_errors |
| Fehler im Rückgabeformat des Modells | Modellausgabe entspricht nicht den Erwartungen | Strukturierte Ausgabe verwenden + handle_errors |
ModelRetryMiddleware - Wiederholung von Modellaufrufen
LangChain bietet integrierte Retry-Middleware:
Beispiel
from langchain.agents.middleware import ModelRetryMiddleware
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
# Integrierte Modell-Retry-Middleware
# Automatisch wiederholen, wenn Modellaufruf fehlschlägt
agent = create_agent(
model=init_chat_model("deepseek:deepseek-v4-flash", timeout=30, max_retries=2),
Middleware=[
ModelRetryMiddleware(
max_retries=3, # Bis zu 3-mal wiederholen
backoff_factor=2.0, # Backoff-Faktor (2s, 4s, 8s)
)
],
system_prompt="Du bist der Assistent von EXAMPLE.",
)
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
# Integrierte Modell-Retry-Middleware
# Automatisch wiederholen, wenn Modellaufruf fehlschlägt
agent = create_agent(
model=init_chat_model("deepseek:deepseek-v4-flash", timeout=30, max_retries=2),
Middleware=[
ModelRetryMiddleware(
max_retries=3, # Bis zu 3-mal wiederholen
backoff_factor=2.0, # Backoff-Faktor (2s, 4s, 8s)
)
],
system_prompt="Du bist der Assistent von EXAMPLE.",
)
ToolRetryMiddleware - Wiederholung von Tool-Aufrufen
Beispiel
from langchain.agents.middleware import ToolRetryMiddleware
agent = create_agent(
model="deepseek:deepseek-v4-flash",
tools=[my_tool],
Middleware=[
ToolRetryMiddleware(
max_retries=3,
backoff_factor=1.5,
)
],
)
agent = create_agent(
model="deepseek:deepseek-v4-flash",
tools=[my_tool],
Middleware=[
ToolRetryMiddleware(
max_retries=3,
backoff_factor=1.5,
)
],
)
Die integrierte RetryMiddleware und benutzerdefinierte @wrap_model_call / @wrap_tool_call können koexistieren. Platzieren Sie die integrierte Middleware an den Anfang der Middleware-Liste als äußersten Schutz.
debug=True - Detaillierte Protokolle
Beispiel
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage
# Debug-Modus aktivieren, um detaillierte Ausführungsprotokolle auszugeben
agent = create_agent(
model=init_chat_model("deepseek:deepseek-v4-flash"),
debug=True, # Debug-Protokollierung aktivieren
system_prompt="Du bist der Assistent von EXAMPLE.",
)
# Bei der Ausführung wird Folgendes ausgegeben:
# - Eingabezustand jedes Knotens
# - Ausgabezustand jedes Knotens
# - Kantensprung-Entscheidungen
result = agent.invoke({
"messages": [HumanMessage(content="Hello")]
})
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage
# Debug-Modus aktivieren, um detaillierte Ausführungsprotokolle auszugeben
agent = create_agent(
model=init_chat_model("deepseek:deepseek-v4-flash"),
debug=True, # Debug-Protokollierung aktivieren
system_prompt="Du bist der Assistent von EXAMPLE.",
)
# Bei der Ausführung wird Folgendes ausgegeben:
# - Eingabezustand jedes Knotens
# - Ausgabezustand jedes Knotens
# - Kantensprung-Entscheidungen
result = agent.invoke({
"messages": [HumanMessage(content="Hello")]
})
Beispielausgabe mit debug=True:
[DEBUG] Starting graph execution
[DEBUG] Executing node: model
[DEBUG] Node 'model' input: {'messages': [HumanMessage(content='你好')]}
[DEBUG] Node 'model' output: {'messages': [AIMessage(content='你好!...')]}
[DEBUG] Edge 'model' -> '__end__': routing to __end__
[DEBUG] Graph execution complete
stream_mode="debug" - Detaillierteste Debug-Informationen
Beispiel
# Detaillierteste Informationen über stream_mode="debug" abrufen
for event in agent.stream(
{"messages": [HumanMessage(content="Hello")]},
stream_mode="debug",
):
# event enthält: Knotenname, Eingabe, Ausgabe, Zeitstempel, Aufgabeninformationen usw.
print(f"[{event['type']}] {event.get('name', '')}")
if 'input' in event:
print(f" Eingabe: {event['input']}")
if 'output' in event:
print(f" Ausgabe: {event['output']}")
for event in agent.stream(
{"messages": [HumanMessage(content="Hello")]},
stream_mode="debug",
):
# event enthält: Knotenname, Eingabe, Ausgabe, Zeitstempel, Aufgabeninformationen usw.
print(f"[{event['type']}] {event.get('name', '')}")
if 'input' in event:
print(f" Eingabe: {event['input']}")
if 'output' in event:
print(f" Ausgabe: {event['output']}")
Allgemeine Fehlerbehebung
Problem 1: Das Modell ruft immer wieder Tools auf, ohne anzuhalten
Mögliche Ursache: Die vom Tool zurückgegebenen Informationen sind unzureichend, und das Modell kann nicht feststellen, ob die Aufgabe abgeschlossen ist. Lösungen:
- Lassen Sie das Tool explizitere Informationen zurückgeben (z. B. "Aufgabe abgeschlossen")
- Legen Sie die Stoppbedingung in system_prompt fest
- Verwenden Sie after_model, um die Schleifenanzahl zu prüfen, und führen Sie nach Überschreiten des Schwellenwerts jump_to="end" aus
Problem 2: Das Modell hat das falsche Tool oder falsche Parameter aufgerufen
Mögliche Ursache: Die Beschreibung des Tools ist unklar. Lösungen:
- Optimieren Sie den Docstring der Tool-Funktion
- Verwenden Sie args_schema, um Parameterbereiche einzuschränken
- Verwenden Sie ein besseres Modell (z. B. deepseek-v4-pro statt deepseek-v4-flash)
Problem 3: Das Konversationsgedächtnis funktioniert nicht
Checkliste:
- Haben Sie den checkpointer-Parameter übergeben?
- Haben Sie jedes Mal dieselbe thread_id verwendet?
- Wenn Sie SqliteSaver verwenden, existiert die Datenbankdatei und ist sie beschreibbar?