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

FehlertypTypische UrsacheLösung
ImportErrorProvider-Paket nicht installiertpip install langchain-deepseek, usw.
API-Schlüssel-Fehler.env nicht konfiguriert oder Schlüssel ungültigUmgebungsvariablen und Gültigkeit des Schlüssels prüfen
Timeout-FehlerNetzwerkprobleme oder langsame ModellantwortSetzen Sie den timeout-Parameter
Token-Limit überschrittenNachrichtenverlauf ist zu langVerwenden Sie trim_messages() zum Kürzen
Fehler beim Tool-AufrufAusnahme im ToolVerwenden Sie ToolException + handle_tool_errors
Fehler im Rückgabeformat des ModellsModellausgabe entspricht nicht den ErwartungenStrukturierte 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.",
)

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,
        )
    ],
)

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")]
})

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']}")

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?
Andere Erweiterungen