Gestion des erreurs et débogage LangChain
Lors du développement d’Agent, diverses erreurs sont inévitables. Cet article répertorie les types d’erreurs courants, les méthodes de débogage et les bonnes pratiques.
Types d'erreurs courantes
| Type d’erreur | Cause typique | Solution |
|---|---|---|
| ImportError | Paquet du fournisseur non installé | pip install langchain-deepseek, etc. |
| Erreur de clé API | .env non configuré ou clé non valide | Vérifiez les variables d'environnement et la validité de la clé |
| Erreur de délai d'attente | Problèmes réseau ou réponse lente du modèle | Définissez le paramètre timeout |
| Limite de jetons dépassée | L'historique des messages est trop long | Utilisez trim_messages() pour tronquer |
| Erreur d'appel d'outil | Exception à l'intérieur de l'outil | Utilisez ToolException + handle_tool_errors |
| Erreur de format de retour du modèle | La sortie du modèle ne répond pas aux attentes | Utiliser une sortie structurée + handle_errors |
ModelRetryMiddleware - Réessai d'appel de modèle
LangChain fournit un middleware de réessai intégré :
Exemple
from langchain.agents.middleware import ModelRetryMiddleware
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
# Middleware intégré de réessai de modèle
# Réessayer automatiquement lorsque l'appel au modèle échoue
agent = create_agent(
model=init_chat_model("deepseek:deepseek-v4-flash", timeout=30, max_retries=2),
middleware=[
ModelRetryMiddleware(
max_retries=3, # Réessayer jusqu'à 3 fois
backoff_factor=2.0, # Facteur de temporisation (2s, 4s, 8s)
)
],
system_prompt="Vous êtes l'assistant d'EXAMPLE.",
)
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
# Middleware intégré de réessai de modèle
# Réessayer automatiquement lorsque l'appel au modèle échoue
agent = create_agent(
model=init_chat_model("deepseek:deepseek-v4-flash", timeout=30, max_retries=2),
middleware=[
ModelRetryMiddleware(
max_retries=3, # Réessayer jusqu'à 3 fois
backoff_factor=2.0, # Facteur de temporisation (2s, 4s, 8s)
)
],
system_prompt="Vous êtes l'assistant d'EXAMPLE.",
)
ToolRetryMiddleware - Nouvelle tentative d'appel d'outil
Exemple
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,
)
],
)
Le RetryMiddleware intégré et les @wrap_model_call / @wrap_tool_call personnalisés peuvent coexister. Placez le middleware intégré au début de la liste des middlewares comme protection la plus externe.
debug=True - Journaux détaillés
Exemple
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage
# Activer le mode debug pour afficher des journaux d'exécution détaillés
agent = create_agent(
model=init_chat_model("deepseek:deepseek-v4-flash"),
debug=True, # Activer la journalisation de débogage
system_prompt="Vous êtes l'assistant d'EXAMPLE.",
)
# Lors de l'exécution, il imprimera :
# - État d'entrée de chaque nœud
# - État de sortie de chaque nœud
# - Décisions de saut d'arête
result = agent.invoke({
"messages": [HumanMessage(content="Hello")]
})
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage
# Activer le mode debug pour afficher des journaux d'exécution détaillés
agent = create_agent(
model=init_chat_model("deepseek:deepseek-v4-flash"),
debug=True, # Activer la journalisation de débogage
system_prompt="Vous êtes l'assistant d'EXAMPLE.",
)
# Lors de l'exécution, il imprimera :
# - État d'entrée de chaque nœud
# - État de sortie de chaque nœud
# - Décisions de saut d'arête
result = agent.invoke({
"messages": [HumanMessage(content="Hello")]
})
Exemple de sortie avec 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" - Informations de débogage les plus détaillées
Exemple
# Obtenir les informations les plus détaillées via stream_mode="debug"
for event in agent.stream(
{"messages": [HumanMessage(content="Hello")]},
stream_mode="debug",
):
# event contient : nom du nœud, entrée, sortie, horodatage, informations de tâche, etc.
print(f"[{event['type']}] {event.get('name', '')}")
if 'input' in event:
print(f" Entrée : {event['input']}")
if 'output' in event:
print(f" Output: [output]")
for event in agent.stream(
{"messages": [HumanMessage(content="Hello")]},
stream_mode="debug",
):
# event contient : nom du nœud, entrée, sortie, horodatage, informations de tâche, etc.
print(f"[{event['type']}] {event.get('name', '')}")
if 'input' in event:
print(f" Entrée : {event['input']}")
if 'output' in event:
print(f" Output: [output]")
Dépannage courant
Le modèle continue d'appeler des outils sans s'arrêter
Cause possible : Les informations renvoyées, et le modèle ne peut pas déterminer si la tâche est terminée
- Faire en sorte que l'outil renvoie des informations plus explicites (par ex., "Tâche terminée")
- la condition d'arrêt dans system_prompt
- Utiliser le compteur de boucles, et "end" après dépassement
Problème 2 : Le modèle a appelé le mauvais outil ou les mauvais paramètres
Cause possible : La description de l'outil n'est pas claire. Solutions :
- Optimiser la docstring de la fonction d'outil
- Utiliser args_schema pour restreindre les plages de paramètres
- Utiliser un meilleur modèle (par ex., deepseek-v4-pro au lieu de deepseek-v4-flash)
Problème 3 : la mémoire de conversation ne fonctionne pas
Liste de vérification :
- Avez-vous passé le paramètre checkpointer ?
- Avez-vous utilisé le même thread_id à chaque fois ?
- Si vous utilisez SqliteSaver, le fichier de base de données existe-t-il et est-il accessible en écriture ?