Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Boas Práticas e Produção

Aula 14 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Da Prova de Conceito à Produção
  2. Lista de Verificação de Implementação
  3. Escrever Descrições que Fazem o Modelo Funcionar
  4. Escolher o Modelo Certo
  5. Estruturar a Mensagem de Sistema
  6. Gerir Custos em Produção
  7. Testar a Chamada de Funções
  8. Monitorização em Produção
  9. Próximos Passos
  10. Pontos-chave
  11. 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.