Обработка ошибок и отладка в LangChain
При разработке агентов неизбежны различные ошибки. В этой статье рассматриваются распространённые типы ошибок, методы отладки и лучшие практики.
Распространённые типы ошибок
| Тип ошибки | Типичная причина | Решение |
|---|---|---|
| ImportError | Пакет провайдера не установлен | pip install langchain-deepseek и т. д. |
| Ошибка API-ключа | .env не настроен или ключ недействителен | Проверьте переменные окружения и действительность ключа |
| Ошибка тайм-аута | Проблемы с сетью или медленный ответ модели | Задайте параметр timeout |
| Превышен лимит токенов | История сообщений слишком длинная | Используйте trim_messages() для обрезки |
| Ошибка вызова инструмента | Исключение внутри инструмента | Используйте ToolException + handle_tool_errors |
| Ошибка формата ответа модели | Вывод модели не соответствует ожиданиям | Используйте структурированный вывод + handle_errors |
ModelRetryMiddleware — повторный вызов модели
LangChain предоставляет встроенное промежуточное ПО для повторных попыток:
Пример
from langchain.agents.middleware import ModelRetryMiddleware
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
# Встроенное промежуточное ПО для повторных попыток вызова модели
# Автоматически повторять при сбое вызова модели
agent = create_agent(
model=init_chat_model("deepseek:deepseek-v4-flash", timeout=30, max_retries=2),
Промежуточное ПО=[
ModelRetryMiddleware(
max_retries=3, # Повторять до 3 раз
backoff_factor=2.0, # Коэффициент задержки (2s, 4s, 8s)
)
],
system_prompt="Вы — ассистент EXAMPLE.",
)
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
# Встроенное промежуточное ПО для повторных попыток вызова модели
# Автоматически повторять при сбое вызова модели
agent = create_agent(
model=init_chat_model("deepseek:deepseek-v4-flash", timeout=30, max_retries=2),
Промежуточное ПО=[
ModelRetryMiddleware(
max_retries=3, # Повторять до 3 раз
backoff_factor=2.0, # Коэффициент задержки (2s, 4s, 8s)
)
],
system_prompt="Вы — ассистент EXAMPLE.",
)
ToolRetryMiddleware - повторная попытка вызова инструмента
Пример
from langchain.agents.middleware import ToolRetryMiddleware
agent = create_agent(
model="deepseek:deepseek-v4-flash",
tools=[my_tool],
Промежуточное ПО=[
ToolRetryMiddleware(
max_retries=3,
backoff_factor=1.5,
)
],
)
agent = create_agent(
model="deepseek:deepseek-v4-flash",
tools=[my_tool],
Промежуточное ПО=[
ToolRetryMiddleware(
max_retries=3,
backoff_factor=1.5,
)
],
)
Встроенный RetryMiddleware и пользовательские @wrap_model_call / @wrap_tool_call могут сосуществовать. Поместите встроенное промежуточное ПО в начало списка промежуточного ПО в качестве самого внешнего уровня защиты.
debug=True - Подробные логи
Пример
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage
# Включить режим отладки для вывода подробных журналов выполнения
agent = create_agent(
model=init_chat_model("deepseek:deepseek-v4-flash"),
debug=True, # Включить логирование отладки
system_prompt="Вы — ассистент EXAMPLE.",
)
# При выполнении будет выведено:
# - Входное состояние каждого узла
# - Состояние вывода каждого узла
# - Решения о переходах по рёбрам
result = agent.invoke({
"messages": [HumanMessage(content="Hello")]
})
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage
# Включить режим отладки для вывода подробных журналов выполнения
agent = create_agent(
model=init_chat_model("deepseek:deepseek-v4-flash"),
debug=True, # Включить логирование отладки
system_prompt="Вы — ассистент EXAMPLE.",
)
# При выполнении будет выведено:
# - Входное состояние каждого узла
# - Состояние вывода каждого узла
# - Решения о переходах по рёбрам
result = agent.invoke({
"messages": [HumanMessage(content="Hello")]
})
Пример вывода с 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" - Наиболее подробная отладочная информация
Пример
# Получить наиболее подробную информацию с помощью stream_mode="debug"
for event in agent.stream(
{"messages": [HumanMessage(content="Hello")]},
stream_mode="debug",
):
# event содержит: имя узла, вход, выход, временная метка, информация о задаче и т. д.
print(f"[{event['type']}] {event.get('name', '')}")
if 'input' in event:
print(f" Input: {event['input']}")
if 'output' in event:
print(f" Вывод: {event['output']}")
for event in agent.stream(
{"messages": [HumanMessage(content="Hello")]},
stream_mode="debug",
):
# event содержит: имя узла, вход, выход, временная метка, информация о задаче и т. д.
print(f"[{event['type']}] {event.get('name', '')}")
if 'input' in event:
print(f" Input: {event['input']}")
if 'output' in event:
print(f" Вывод: {event['output']}")
Общие советы по устранению неполадок
Проблема 1: Модель продолжает вызывать инструменты, не останавливаясь
Возможная причина: информация, возвращаемая инструментом, недостаточна, и модель не может определить, завершена ли задача. Решения:
- Сделайте так, чтобы инструмент возвращал более явную информацию (например, "Задача выполнена")
- Задайте условие остановки в system_prompt
- Используйте after_model для проверки количества итераций и jump_to="end" после превышения порога
Проблема 2: Модель вызвала не тот инструмент или неверные параметры
Возможная причина: описание инструмента неясно. Решения:
- Оптимизируйте docstring функции инструмента
- Используйте args_schema для ограничения диапазонов параметров
- Используйте более качественную модель (например, deepseek-v4-pro вместо deepseek-v4-flash)
Проблема 3: Память диалога не работает
Контрольный список:
- Вы передали параметр checkpointer?
- Вы каждый раз использовали один и тот же thread_id?
- Если используется SqliteSaver, существует ли файл базы данных и доступен ли он для записи?