Gestão de Erros
Nesta página
Os Erros São Inevitáveis
Em produção, as funções falham. APIs externas ficam indisponíveis, IDs não existem, parâmetros são inválidos e os tempos limite expiram. A questão não é «será que vai falhar?», mas sim «como lidamos com a falha de forma elegante?». Um rastreador de pagamentos que colapsa porque um utilizador escreveu T9999 em vez de T1001 não é um sistema de produção; é apenas uma demonstração.
A boa notícia é que dispõe aqui de um recurso que as arquiteturas clássicas não possuem: o modelo Mistral consegue compreender as mensagens de erro que lhe envia e adaptar a sua resposta em conformidade. Enquanto um backend tradicional tem de criar uma mensagem de interface para cada código de erro, pode deixar que o modelo traduza a falha numa frase útil para o utilizador. Basta fornecer-lhe a informação necessária.
Nunca Esconda um Erro do Modelo
Esta é a regra de ouro desta lição. Devolva um erro na mensagem tool exatamente como faria com um resultado normal: como JSON estruturado. O reflexo oposto — capturar a exceção e devolver uma cadeia vazia ou null — faz o modelo acreditar que a função foi bem-sucedida, mas simplesmente não tinha nada a dizer. Isto gera as respostas mais confusas possíveis.
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)}"
})
Dois campos são suficientes: um código de máquina em error e uma explicação legível por humanos em message. O código permite que o seu sistema de monitorização conte as ocorrências; a explicação permite que o modelo formule uma resposta útil. Veja o que acontece com uma transação inexistente.
# 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?"
Ninguém escreveu essa frase. Ela deriva do código de erro e chega mesmo a sugerir uma ação corretiva ao utilizador.
Um Executor Que Não Deixa Nada Passar
Proteger uma função não é suficiente: a camada que dispatcha as tool_calls tem os seus próprios modos de falha, independentes da sua lógica de negócio. O modelo pode alucinar um nome de função que não existe no seu dicionário. Pode produzir argumentos JSON mal formatados — um caso raro, mas real, com esquemas complexos. Pode também fornecer JSON válido cujas chaves não correspondem à assinatura Python, causando um TypeError durante **function_params. Cada um destes três casos merece o seu próprio código de erro, pois cada um exige uma correção diferente da sua parte.
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
}
Note que todos os ramos, incluindo os de falha, devolvem uma mensagem tool completa com o seu tool_call_id. Isto é essencial: a API rejeita um histórico onde uma tool_call fica sem resposta, e uma falha silenciosa causaria um erro de validação na próxima interação, longe da causa real.
Distinga Falhas Transitórias de Permanentes
Nem todos os erros são iguais. Uma transação em falta continuará em falta numa segunda tentativa; repetir apenas desperdiça tempo. Um tempo limite de rede ou um serviço momentaneamente saturado, no entanto, resolve-se frequentemente por si só. Para esta segunda categoria, uma nova tentativa com espera exponencial (backoff) — um segundo, depois dois, depois quatro — dá tempo ao serviço para recuperar sem o sobrecarregar com pedidos. Após esgotar as tentativas, recorre ao comportamento habitual: um JSON de erro destinado ao modelo.
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)
})
A API Mistral Também Pode Falhar
Tudo o que foi dito acima diz respeito às suas funções. A chamada à própria API Mistral é um ponto de falha distinto, tratado separadamente: aqui, não há modelo para explicar o problema, uma vez que o modelo é precisamente o que está inacessível. Um HTTPValidationError sinaliza geralmente um erro na estrutura da sua mensagem ou ferramentas, que deve corrigir no código; outras exceções relacionam-se com a rede ou o serviço e são tratadas com a mesma lógica de nova tentativa descrita acima.
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
Veja O Que Está Realmente a Acontecer
Um sistema de chamada de funções é difícil de depurar a posteriori se não souber qual a função chamada, com que argumentos e o que devolveu. O registo (logging) não é um luxo; é assim que descobrirá que uma descrição ambígua leva o modelo a confundir duas funções, ou que um em cada cinco utilizadores desencadeia sistematicamente um transaction_not_found. Registe a chamada antes da execução e, em seguida, o veredito, distinguindo o nível info do nível error para que os seus alertas possam filtrar eficazmente.
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
Pontos-chave
- Devolva sempre os erros ao modelo na mensagem
tool— ele sabe interpretá-los - Utilize códigos de erro estruturados (
transaction_not_found,invalid_arguments, etc.) - Implemente nova tentativa com espera exponencial (backoff) para erros transitórios
- Trate separadamente os erros nas suas funções e os erros na API Mistral
- Registe todas as chamadas e todos os erros para monitorização em produção