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

Boas Práticas e Próximos Passos

Aula 14 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Resumo do Curso
  2. Proteger as Suas Chaves de API
  3. Gestão de Erros
  4. Conviver com Limites de Taxa
  5. Controlo de Custos
  6. Observar o Que Acontece
  7. Próximos Passos
  8. Pontos-chave
  9. Teste os Seus Conhecimentos

Resumo do Curso

Já cobriu todos os fundamentos da utilização da API Mistral: criação de conta, gestão de chaves, seleção de planos, instalação dos SDKs Python e TypeScript, streaming, conversas multi-turno, migração V1/V2 e implementação nos principais fornecedores de cloud. O que se segue já não diz respeito à aprendizagem da API em si, mas à diferença entre um script que funciona e uma aplicação que resiste em produção.

Proteger as Suas Chaves de API

Esta é a causa mais comum de incidentes em produção, quase sempre pela mesma razão: uma chave codificada «apenas para testes» e depois esquecida num commit. Uma chave de API nunca deve aparecer no código-fonte; deve residir numa variável de ambiente ou, melhor ainda, num gestor de segredos como o AWS Secrets Manager, o Azure Key Vault ou o HashiCorp Vault.

A segregação vem a seguir. Utilize uma chave por ambiente — desenvolvimento, staging, produção — para impedir que um teste falhado consuma a sua quota de serviço em direto. Utilize uma chave por aplicação para limitar o raio de impacto: se uma chave for comprometida, revoga apenas a da aplicação afetada. Planeie a rotação a cada 90 dias em produção e configure alertas na Consola Mistral para utilizações anómalas: uma chave comprometida manifesta-se primeiro como uma curva de utilização que dispara sem motivo aparente.

Gestão de Erros

Em produção, qualquer chamada à API pode falhar. A questão não é saber se vai acontecer, mas quando. Quatro códigos de estado cobrem a maioria das situações que irá encontrar:

CódigoSignificadoAção
401 UnauthorizedChave de API inválida ou expiradaVerifique a sua variável de ambiente
429 Too Many RequestsLimite de taxa atingidoTente novamente com backoff exponencial
500 Internal Server ErrorProblema do lado da MistralTentativa automática após alguns segundos
503 Service UnavailableSobrecarga temporáriaTente novamente com backoff

A distinção é crucial: nunca resolve um erro 401 tentando novamente; a falha está na sua configuração. Os outros três são transitórios e a resposta correta é tentar novamente com atrasos progressivamente maiores — um segundo, depois dois, depois quatro. Tentar imediatamente num ciclo perante um 429 apenas agrava a saturação que está a experienciar.

Eis o padrão em Python: no máximo três tentativas, propague a exceção se a última falhar e duplique o tempo de espera após cada falha utilizando 2 ** attempt.

import time
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

def call_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.chat.complete(
                model="mistral-small-latest",
                messages=messages,
            )
            return response
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            waitTime = 2 ** attempt  # 1s, 2s, 4s
            print(f"Error: {e}. Retrying in {waitTime}s...")
            time.sleep(waitTime)

A transposição para TypeScript segue exatamente a mesma lógica, exceto que o tempo de espera é expresso em milissegundos e a pausa é construída com uma promise e setTimeout:

async function callWithRetry(
  client: Mistral,
  messages: Array<{ role: string; content: string }>,
  maxRetries = 3
) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.chat.complete({
        model: 'mistral-small-latest',
        messages,
      });
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      const waitTime = Math.pow(2, attempt) * 1000;
      console.log(`Error. Retrying in ${waitTime}ms...`);
      await new Promise((r) => setTimeout(r, waitTime));
    }
  }
}

Conviver com Limites de Taxa

Os limites de taxa protegem a API de abusos, e a lógica de repetição por si só não basta para os respeitar: apenas corrige as coisas a posteriori. Verifique os seus limites na Consola Mistral — pedidos por segundo, tokens por minuto — e implemente depois uma limitação (throttling) do lado do cliente para evitar excedê-los. Os pedidos em excesso devem ser colocados em fila, não descartados: um utilizador prefere esperar dois segundos a receber um erro.

Quando ocorre um 429 apesar dos seus melhores esforços, a resposta inclui um cabeçalho Retry-After que indica quando tentar novamente; lê-lo é preferível a adivinhar. E se a sua utilização legítima exceder consistentemente os limites do plano Scale, solicite um aumento de quota através do suporte em vez de multiplicar soluções de contorno.

Controlo de Custos

A primeira alavanca, e de longe a mais eficaz, é a seleção do modelo. Classificação, extração de campos ou reformulação não exigem raciocínio elaborado: o mistral-small-latest trata disso muito bem. Reserve o mistral-large-latest para tarefas onde a qualidade do raciocínio faz a diferença — análise, síntese complexa, escrita de longa-forma — e utilize o codestral-latest para geração de código. Não pague ao Mistral Large 3 para fazer o que o Mistral Small faz igualmente bem: em volume de produção, a diferença mede-se em ordens de grandeza.

A segunda alavanca diz respeito ao número de tokens trocados. Um prompt conciso, despojado de instruções redundantes acumuladas ao longo de iterações, custa menos em cada chamada. Em conversas multi-turno, envie apenas as mensagens necessárias: retransmitir um histórico de trinta trocas para cada pergunta inflaciona a fatura muito rapidamente. Ajuste o max_tokens ao que realmente espera e coloque em cache as respostas recorrentes — o pedido mais barato é aquele que não faz.

Observar o Que Acontece

Em produção, registe todas as chamadas. Sem isso, não saberá porque é que uma resposta foi truncada nem qual a utilização que explica a fatura do mês. A função abaixo envolve a chamada com dois registos: o que sai e o que entra, incluindo a contagem total de tokens e o motivo de paragem.

import logging

logger = logging.getLogger("mistral")

def logged_call(client, messages, model="mistral-small-latest"):
    logger.info(f"API Call — model: {model}, messages: {len(messages)}")

    response = client.chat.complete(model=model, messages=messages)

    logger.info(
        f"Response — tokens: {response.usage.total_tokens}, "
        f"finish: {response.choices[0].finish_reason}"
    )

    return response

Estas duas linhas respondem à maioria das perguntas que virá a colocar mais tarde. Um finish_reason que sinaliza um limite de comprimento explica uma resposta cortada a meio; uma média de tokens à deriva revela um prompt que cresceu ou um histórico que não foi devidamente purgado.

Próximos Passos

Com os fundamentos assentes, abrem-se vários caminhos. A chamada de funções (function calling) permite ao modelo invocar as suas próprias funções e APIs. O RAG (Retrieval-Augmented Generation) enriquece as respostas com os seus dados internos, enquanto os embeddings, que transformam texto em vetores, constituem o bloco de construção da pesquisa semântica. O fine-tuning adapta um modelo ao seu domínio quando o prompting já não é suficiente, os agentes encadeiam chamadas para construir sistemas autónomos e a avaliação oferece-lhe uma forma de medir a qualidade das respostas em vez de a estimar a olho nu.

Cada um destes temas possui cursos dedicados no catálogo da Corsen Academy.

Pontos-chave

  • Proteja as suas chaves de API com um gestor de segredos e rotação regular
  • Implemente sistematicamente a tentativa com backoff exponencial
  • Escolha o modelo mais leve capaz de executar a sua tarefa
  • Registe todas as chamadas à API para diagnóstico e otimização de custos
  • A API Mistral é a sua base — os próximos passos (chamada de funções, RAG, agentes) constroem sobre tudo o que aprendeu

Teste os Seus Conhecimentos

Consola, SDK, fornecedores de cloud: a base da API está assegurada?

1. Que reflexos deve ter relativamente à chave de API assim que esta é criada?

Resposta: Guarde-a em segurança (é apresentada apenas uma vez), mantenha-a fora do código através de variáveis de ambiente, utilize uma chave por ambiente e rode-a em caso de dúvida.

2. O que diferencia os planos Experiment e Scale?

Resposta: Quotas e preços: o Experiment para descoberta e prototipagem, o Scale para produção — verifique os seus limites na consola antes de dimensionar.

3. Qual é a estrutura de uma primeira chamada em Python?

Resposta: Cliente inicializado com a chave, chamada de chat com o modelo e a lista de mensagens, leitura do conteúdo da resposta — e o streaming está ativado para exibição progressiva.

4. Como gere uma conversa multi-turno via API?

Resposta: Mantendo o histórico por si próprio: cada pedido envia a lista completa de mensagens (utilizador e assistente) — a API é stateless.

5. O que deve saber sobre implementações via Azure, Vertex ou Bedrock?

Resposta: Os modelos Mistral estão disponíveis aí com a autenticação e faturação da cloud escolhida — mesma família de modelos, ponto de acesso diferente, útil para restrições de infraestrutura.

Chave protegida, histórico gerido, plano adaptado: as boas práticas finais transformam esta base num alicerce de produção.