Boas Práticas e Produção
Nesta página
- Da Prova de Conceito à Produção
- Lista de Verificação de Implementação
- Escrever Descrições que Fazem o Modelo Funcionar
- Escolher o Modelo Certo
- Estruturar a Mensagem de Sistema
- Gerir Custos em Produção
- Testar a Chamada de Funções
- Monitorização em Produção
- Próximos Passos
- Pontos-chave
- Teste os Seus Conhecimentos
Da Prova de Conceito à Produção
Agora tem todos os blocos de construção para criar sistemas de chamada de funções com a Mistral. O que separa o seu protótipo de um serviço pronto para produção não são funcionalidades em falta, mas uma série de verificações e ajustes que geralmente descobre durante um incidente. Esta última lição reúne boas práticas, armadilhas comuns e uma lista de verificação para avançar para a produção com confiança.
Lista de Verificação de Implementação
Este é o único local neste curso onde um formato de lista é obrigatório: antes de entrar no ar, assinala caixas. Quatro domínios devem ser cobertos, cada um respondendo a uma pergunta diferente.
Arquitetura garante que a mecânica se mantém. Devolver cadeias JSON na cadeia de processamento e ter um dicionário de despacho completo são as duas causas mais frequentes de falhas na primeira chamada real.
- Todas as funções devolvem cadeias JSON (nunca objetos Python brutos)
- O dicionário de despacho está completo e atualizado
- As funções tratam casos de erro e devolvem mensagens utilizáveis
- A mensagem de sistema é clara, precisa e testada
- O ciclo de conversação lida com chamadas sequenciais e paralelas
Segurança assume que os argumentos vêm de um utilizador, nunca da sua aplicação.
- Os argumentos são validados antes da execução (formato, tipo, valores)
- As consultas SQL utilizam parâmetros (sem concatenação)
- Uma lista branca limita as funções disponíveis
- Ações destrutivas exigem confirmação
- A limitação de taxa está implementada por função e por utilizador
- Os resultados são higienizados (nenhum dado sensível é devolvido ao modelo)
Fiabilidade lida com o que falha sem que ninguém tenha culpa.
- Os erros são devolvidos ao modelo num formato estruturado
- A repetição com recuo exponencial (backoff) está implementada para erros transitórios
- Os tempos limite estão configurados para cada função externa
- O tamanho do histórico é limitado para evitar exceder o número de tokens
Monitorização, finalmente, é o que lhe permite diagnosticar sem adivinhar.
- Cada chamada de função é registada (nome, argumentos, resultado, duração)
- Os erros acionam alertas (Slack, PagerDuty, etc.)
- As métricas são recolhidas (taxa de sucesso, latência, custo da API)
Escrever Descrições que Fazem o Modelo Funcionar
A qualidade da descrição tem um impacto direto na precisão e é frequentemente a alavanca mais barata de acionar. Três padrões recorrem frequentemente nas equipas com altas taxas de chamadas corretas. O primeiro ancora a descrição no contexto de negócio: em vez de parafrasear o nome da função, liste os valores de retorno possíveis e indique explicitamente quando a chamar. O segundo insere exemplos de formato na descrição do parâmetro, o que corrige a maioria dos erros de extração de ID. O terceiro substitui uma instrução em linguagem natural por um enum, a única forma de proibir verdadeiramente um valor fora da lista.
# Padrão 1: Descrição com contexto de negócio
{
"description": "Recupera o estado do pagamento. "
"Estados possíveis: paid, pending, failed, refunded. "
"Utilize esta função quando o utilizador perguntar "
"sobre o estado de um pagamento ou se foi recebido."
}
# Padrão 2: Parâmetros com exemplos
{
"transaction_id": {
"type": "string",
"description": "ID único no formato T seguido de 4 dígitos (ex.: T1001, T2345)"
}
}
# Padrão 3: Enum para valores limitados
{
"status": {
"type": "string",
"enum": ["paid", "pending", "failed", "refunded"],
"description": "Filtrar por estado do pagamento"
}
}
Escolher o Modelo Certo
A escolha do modelo equilibra precisão e custo, e não há uma resposta universal: depende do número de funções expostas e da complexidade dos seus esquemas. Um caso complexo com muitas funções e parâmetros aninhados justifica o Mistral Large 3, que é mais fiável na seleção de funções, mas mais caro. Um caso padrão com algumas funções simples em produção de alto throughput funciona muito bem no Mistral Small 4, que é rápido e económico. Para prototipagem e testes, o Mistral Medium 3.5 oferece um bom compromisso.
# Casos complexos: muitas funções, parâmetros aninhados
# -> Mistral Large 3 (mais fiável, mais caro)
model = "mistral-large-latest"
# Casos padrão: poucas funções simples, produção de alto throughput
# -> Mistral Small 4 (rápido, económico)
model = "mistral-small-latest"
# Casos de desenvolvimento: prototipagem, testes
# -> Mistral Medium 3.5 (bom compromisso)
model = "mistral-medium-latest"
O método importa tanto quanto o resultado: em produção, comece com o modelo mais capaz, meça a sua taxa de chamadas corretas e depois reduza gradualmente para encontrar a melhor relação custo/desempenho. O inverso — começar pelo modelo mais barato — priva-o da linha de base necessária para saber se a degradação vem do modelo ou das suas descrições.
Estruturar a Mensagem de Sistema
Uma boa mensagem de sistema faz a diferença entre um assistente medíocre e um excelente. Esta ilustra uma estrutura comprovada: uma declaração de papel, um bloco de regras imperativas e, em seguida, um lembrete das ferramentas disponíveis. As duas regras mais eficazes em termos de custo aqui são “Se o utilizador não fornecer um ID necessário, pergunte educadamente” e “Nunca adivinhe um ID de transação” — juntas, eliminam o comportamento mais prejudicial de todos: chamar uma função com um ID inventado.
system_message = {
"role": "system",
"content": """Você é um assistente de gestão de pagamentos para a Acme Corporation.
Regras:
- Responda sempre em inglês
- Formate os valores em euros com o símbolo e 2 casas decimais
- Se o utilizador não fornecer um ID necessário, pergunte educadamente
- Nunca adivinhe um ID de transação
- Quando uma transação falhar, ofereça-se para verificar os detalhes
Ferramentas disponíveis:
- retrieve_payment_status: para verificar o estado de um pagamento
- retrieve_payment_date: para verificar a data de um pagamento
- retrieve_payment_details: para obter todos os detalhes de uma transação
- list_customer_transactions: para visualizar todas as transações de um cliente"""
}
Gerir Custos em Produção
Cada chamada de função consome tokens, e a fatura aumenta através de dois canais subestimados: as definições de ferramentas são enviadas com cada pedido e o histórico cresce a cada turno. Filtrar funções por contexto resolve o primeiro ponto — não há necessidade de enviar as doze ferramentas quando a pergunta é claramente sobre pagamentos. Truncar o histórico além de um limiar resolve o segundo. E quando todos os dados necessários já estão no contexto, tool_choice="none" evita uma ida e volta extra.
# 1. Limitar o número de funções por pedido
# Passe apenas as funções relevantes para o contexto
def get_relevant_tools(user_input: str, all_tools: list) -> list:
"""Filtra ferramentas com base no contexto."""
if "payment" in user_input.lower() or "transaction" in user_input.lower():
return [t for t in all_tools if "payment" in t["function"]["name"]]
if "contact" in user_input.lower() or "customer" in user_input.lower():
return [t for t in all_tools if "contact" in t["function"]["name"]]
return all_tools
# 2. Limitar o tamanho do histórico
MAX_HISTORY = 20 # mensagens
# 3. Utilizar tool_choice="none" quando os dados já estiverem disponíveis
Testar a Chamada de Funções
Os testes são essenciais para evitar regressões e, aqui, visam um objeto invulgar: não está a verificar o valor de retorno da sua função, mas a decisão do modelo. Duas famílias de testes cobrem o essencial. A primeira verifica se uma questão de negócio aciona a função certa com os argumentos extraídos corretos. A segunda, igualmente importante e frequentemente esquecida, verifica se uma saudação não aciona nenhuma chamada — este teste deteta descrições demasiado amplas que empurram o modelo a chamar uma função em todas as circunstâncias.
def test_payment_status():
"""Testa se o modelo chama a função correta."""
messages = [{"role": "user", "content": "Estado do pagamento T1001?"}]
response = client.chat.complete(
model=model, messages=messages, tools=tools
)
message = response.choices[0].message
assert message.tool_calls is not None
assert len(message.tool_calls) == 1
assert message.tool_calls[0].function.name == "retrieve_payment_status"
args = json.loads(message.tool_calls[0].function.arguments)
assert args["transaction_id"] == "T1001"
def test_no_function_for_greeting():
"""Testa se o modelo não chama uma função para uma saudação."""
messages = [{"role": "user", "content": "Olá!"}]
response = client.chat.complete(
model=model, messages=messages, tools=tools
)
message = response.choices[0].message
assert message.tool_calls is None or len(message.tool_calls) == 0
assert message.content is not None
Monitorização em Produção
Agora precisa de saber o que o seu sistema faz uma vez lançado no mundo real. A classe abaixo agrega três sinais que, juntos, contam quase toda a história: taxa de sucesso global, latência média e desagregação por função. Esta última é a mais reveladora na prática — uma função cujo contador de erros deriva isoladamente aponta para um problema específico, enquanto uma taxa global degradada não lhe diz nada sobre onde procurar.
import time
import logging
logger = logging.getLogger("fc_monitor")
class FunctionCallingMonitor:
def __init__(self):
self.metrics = {
"total_calls": 0,
"successful_calls": 0,
"failed_calls": 0,
"total_latency_ms": 0,
"calls_by_function": {}
}
def record(self, function_name: str, success: bool, latency_ms: float):
self.metrics["total_calls"] += 1
self.metrics["total_latency_ms"] += latency_ms
if success:
self.metrics["successful_calls"] += 1
else:
self.metrics["failed_calls"] += 1
if function_name not in self.metrics["calls_by_function"]:
self.metrics["calls_by_function"][function_name] = {
"count": 0, "errors": 0
}
self.metrics["calls_by_function"][function_name]["count"] += 1
if not success:
self.metrics["calls_by_function"][function_name]["errors"] += 1
def get_success_rate(self) -> float:
if self.metrics["total_calls"] == 0:
return 0.0
return self.metrics["successful_calls"] / self.metrics["total_calls"]
def get_avg_latency(self) -> float:
if self.metrics["total_calls"] == 0:
return 0.0
return self.metrics["total_latency_ms"] / self.metrics["total_calls"]
monitor = FunctionCallingMonitor()
Próximos Passos
Agora que dominou a chamada de funções com a Mistral, abrem-se várias direções. A mais natural é construir agentes autónomos, combinando a chamada de funções com um ciclo de agente que planeia e executa tarefas complexas; a Mistral Agents API e o seu client.beta.agents.create() vão mais longe, oferecendo agentes persistentes com estado. Outro eixo combina RAG e chamada de funções: o modelo decide por si próprio quando consultar uma base de dados vetorial, em vez de a pesquisa ser acionada sistematicamente a montante. Do lado da experiência do utilizador, o streaming permite-lhe exibir respostas em tempo real enquanto as funções são executadas, alterando a perceção da latência em cadeias de chamadas longas. Finalmente, o multimodal abre a chamada de funções à visão para análise de documentos.
Pontos-chave
- A lista de verificação de implementação cobre arquitetura, segurança, fiabilidade e monitorização
- Descrições precisas com exemplos e enums melhoram a precisão do modelo
- Escolha o modelo certo com base na complexidade e no orçamento (Large para fiabilidade, Small para throughput)
- A mensagem de sistema é uma alavanca poderosa para guiar o comportamento
- Teste as chamadas de funções e o comportamento de não-chamada sistematicamente
- Monitore a taxa de sucesso, a latência e os custos em produção
Teste os Seus Conhecimentos
Chamada de funções de ponta a ponta: cinco verificações.
1. Quais são os cinco passos da chamada de funções?
Resposta: Definir funções (esquemas), fornecê-las à API, o modelo solicita uma chamada com os seus argumentos, o seu código executa e devolve o resultado, o modelo produz a resposta final.
2. O que constitui um bom esquema de função?
Resposta: Tipos estritos e descrições operacionais — nome claro, quando utilizá-lo, formato de cada parâmetro: este é o texto que o modelo lê para decidir e preencher.
3. O que permitem as chamadas paralelas?
Resposta: O modelo solicita múltiplas funções numa única resposta quando são independentes — menos idas e voltas, desde que associe cada resultado à sua chamada.
4. Para que serve o tool_choice?
Resposta: Para definir a liberdade do modelo: auto (ele decide), any (deve usar uma ferramenta) ou uma ferramenta forçada — sendo esta última fundamental para uma extração estruturada fiável.
5. Quais as regras de segurança para funções expostas?
Resposta: Validar os argumentos recebidos, limitar o âmbito de cada função, registar as chamadas e manter a validação humana em ações de confirmação — o modelo propõe, o seu código dispõe.
Os dois exemplos práticos neste curso (rastreador de pagamentos, CRM) aplicam exatamente estas regras — as suas próprias integrações seguirão o mesmo molde.