Boas Práticas e Próximos Passos
Nesta página
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ódigo | Significado | Ação |
|---|---|---|
| 401 Unauthorized | Chave de API inválida ou expirada | Verifique a sua variável de ambiente |
| 429 Too Many Requests | Limite de taxa atingido | Tente novamente com backoff exponencial |
| 500 Internal Server Error | Problema do lado da Mistral | Tentativa automática após alguns segundos |
| 503 Service Unavailable | Sobrecarga temporária | Tente 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.