Обработка на грешки
На тази страница
Грешките са неизбежни
В производствена среда функциите се провалят. Външните API сървъри спират, идентификаторите не съществуват, параметрите са невалидни, а времето за изчакване изтича. Въпросът не е „дали ще се провали?“, а „как да обработим неуспеха по елегантен начин?“. Система за проследяване на плащания, която се срива, защото потребителят е въвел T9999 вместо T1001, не е производствена система; тя е просто демонстрация.
Добрата новина е, че разполагате с ресурс, който липсва на класическите архитектури: моделът Mistral може да разбира съобщенията за грешки, които му изпращате, и съответно да адаптира отговора си. Докато традиционният бекенд трябва да генерира потребителско съобщение за всеки код на грешка, Вие можете да оставите модела да превърне неуспеха в полезно изречение за потребителя. Трябва само да му предоставите необходимата информация.
Никога не скривайте грешка от модела
Това е златното правило на този урок. Връщайте грешка в съобщението tool точно както бихте върнали нормален резултат: като структуриран JSON. Обратният рефлекс – да хванете изключението и да върнете празен низ или null – кара модела да повярва, че функцията е изпълнена успешно, но просто няма какво да каже. Това поражда най-объркващите възможни отговори.
def retrieve_payment_status(df, transaction_id: str) -> str:
"""Retrieves status with full error handling."""
try:
if transaction_id not in df["transaction_id"].values:
return json.dumps({
"error": "transaction_not_found",
"message": f"Transaction {transaction_id} does not exist in the database."
})
status = df[df["transaction_id"] == transaction_id]["payment_status"].values[0]
return json.dumps({"status": status, "transaction_id": transaction_id})
except Exception as e:
return json.dumps({
"error": "internal_error",
"message": f"Error retrieving data: {str(e)}"
})
Две полета са достатъчни: машинен код в error и четимо за човека обяснение в message. Кодът позволява на системата Ви за мониторинг да брои случаите; обяснението позволява на модела да формулира полезен отговор. Вижте какво се случва при несъществуваща транзакция.
# User requests a non-existent transaction
messages = [{"role": "user", "content": "Status of payment T9999?"}]
# Model calls retrieve_payment_status(transaction_id="T9999")
# Your function returns: {"error": "transaction_not_found", ...}
# Model formulates:
# → "I couldn't find a transaction with ID T9999.
# Could you check the number and try again?"
Никой не е написал това изречение. То произтича от кода на грешката и дори предлага на потребителя коригиращо действие.
Изпълнител, който не пропуска нищо
Защитата на една функция не е достатъчна: слойът, който разпределя tool_calls, има свои собствени режими на отказ, независими от Вашата бизнес логика. Моделът може да халюцинира име на функция, което не съществува във Вашия речник. Може да генерира невалидни JSON аргументи – рядък, но реален случай при сложни схеми. Също така може да предостави валиден JSON, чиито ключове не съвпадат с подписа на Python функцията, което причинява TypeError по време на **function_params. Всеки от тези три случая заслужава собствен код на грешка, защото всеки изисква различно поправяне от Ваша страна.
def execute_tool_call(tool_call, available_functions):
"""Executes a tool_call with full error handling."""
function_name = tool_call.function.name
# Check if function exists
if function_name not in available_functions:
return {
"role": "tool",
"name": function_name,
"content": json.dumps({
"error": "function_not_found",
"message": f"Function {function_name} is not available."
}),
"tool_call_id": tool_call.id
}
# Parse arguments
try:
function_params = json.loads(tool_call.function.arguments)
except json.JSONDecodeError as e:
return {
"role": "tool",
"name": function_name,
"content": json.dumps({
"error": "invalid_arguments",
"message": f"Invalid JSON arguments: {str(e)}"
}),
"tool_call_id": tool_call.id
}
# Execute function
try:
result = available_functions[function_name](**function_params)
return {
"role": "tool",
"name": function_name,
"content": result,
"tool_call_id": tool_call.id
}
except TypeError as e:
return {
"role": "tool",
"name": function_name,
"content": json.dumps({
"error": "invalid_params",
"message": f"Incompatible parameters: {str(e)}"
}),
"tool_call_id": tool_call.id
}
except Exception as e:
return {
"role": "tool",
"name": function_name,
"content": json.dumps({
"error": "execution_error",
"message": f"Execution error: {str(e)}"
}),
"tool_call_id": tool_call.id
}
Забележете, че всеки клон, включително тези за грешки, връща пълно съобщение tool със своя tool_call_id. Това е от съществено значение: API отхвърля история, в която tool_call остава без отговор, а тихият отказ би причинил грешка при валидиране в следващия ход, далеч от истинската причина.
Разграничавайте временни от постоянни грешки
Не всички грешки са еднакви. Липсваща транзакция ще липсва и при втория опит; повторният опит само губи време. Мрежов таймаут или временно претоварен сервис обаче често се разрешават сами. За тази втора категория повторен опит с експоненциално забавяне (една секунда, после две, после четири) дава време на сервиса да се възстанови, без да го затрупвате със заявки. След изчерпване на опитите се връщате към обичайното поведение: JSON с грешка, предназначен за модела.
import time
def execute_with_retry(func, params, max_retries=3, base_delay=1.0):
"""Executes a function with exponential retry."""
for attempt in range(max_retries):
try:
result = func(**params)
return result
except ConnectionError as e:
if attempt < max_retries - 1:
delay = base_delay * (2 ** attempt)
time.sleep(delay)
else:
return json.dumps({
"error": "service_unavailable",
"message": f"Service unavailable after {max_retries} attempts.",
"details": str(e)
})
Mistral API също може да се провали
Всичко по-горе се отнася за Вашите функции. Самото извикване към Mistral API е отделна точка на отказ, която се обработва различно: тук няма модел, на който да се обясни проблемът, тъй като точно моделът е недостъпен. HTTPValidationError обикновено сигнализира за грешка във структурата на съобщенията или инструментите Ви, която трябва да поправите в кода; други изключения се отнасят до мрежата или сервиса и се обработват със същата логика за повторен опит, както по-горе.
from mistralai.client import Mistral
from mistralai.client.errors import HTTPValidationError
def safe_chat_complete(client, model, messages, tools):
"""Mistral API call with error handling."""
try:
return client.chat.complete(
model=model,
messages=messages,
tools=tools
)
except HTTPValidationError as e:
print(f"Validation error: {e}")
return None
except Exception as e:
print(f"API error: {e}")
return None
Вижте какво всъщност се случва
Система за извикване на функции е трудна за отстраняване на грешки постфактум, ако не знаете коя функция е извикана, с какви аргументи и какво е върнала. Логването не е лукс; то е начинът, по който ще откриете, че неясно описание кара модела да бърка две функции, или че един от петима потребители системно предизвиква transaction_not_found. Логвайте извикването преди изпълнение, след това резултата, като разграничавате ниво info от ниво error, за да могат Вашите-alerts да филтрират ефективно.
import logging
logger = logging.getLogger("function_calling")
def execute_and_log(tool_call, available_functions):
"""Executes and logs the result."""
function_name = tool_call.function.name
function_params = json.loads(tool_call.function.arguments)
logger.info(f"Call: {function_name}({function_params})")
result = execute_tool_call(tool_call, available_functions)
content = json.loads(result["content"])
if "error" in content:
logger.error(f"Failure {function_name}: {content['error']} - {content['message']}")
else:
logger.info(f"Success {function_name}: {content}")
return result
Ключови изводи
- Винаги връщайте грешки към модела в съобщението
tool– той знае как да ги интерпретира - Използвайте структурирани кодове на грешки (
transaction_not_found,invalid_argumentsи др.) - Внедрете повторен опит със забавяне за временни грешки
- Обработвайте грешките във Вашите функции и грешките в Mistral API поотделно
- Логвайте всяко извикване и всяка грешка за производствен мониторинг