Boas Práticas e Resumo
Nesta página
Resumo do Curso
Explorou toda a gama de mecanismos de saída estruturada oferecidos pela API da Mistral. Esta última lição reúne o que faz a diferença no trabalho diário: como escolher entre as duas abordagens, as configurações inegociáveis, as armadilhas mais comuns e o que monitorizar assim que estiver em produção.
Escolher a Sua Abordagem
Quatro perguntas bastam para decidir, por esta ordem. Tem um esquema de saída definido? Se a resposta for não, mantenha-se no Modo JSON: está em modo de exploração ou prototipagem, e bloquear um modelo de dados seria prematuro. Se sim, passe à próxima pergunta.
Está a trabalhar em Python ou TypeScript? Se sim, as Saídas Estruturadas Personalizadas estão prontas para si com Pydantic ou Zod. Se não, o Modo JSON com validação manual continua a ser o seu caminho.
Está em produção? Se sim, as Saídas Estruturadas Personalizadas são obrigatórias, sempre. Caso contrário, o Modo JSON é mais do que suficiente para prototipagem.
O esquema muda frequentemente? Um esquema ainda em evolução torna o Modo JSON mais prático inicialmente, até que os requisitos se estabilizem; um esquema fixo defende as Saídas Estruturadas Personalizadas e a fiabilidade que trazem.
As Dez Regras de Ouro
As primeiras cinco dizem respeito à forma como escreve as suas chamadas. Defina sempre temperature=0 em produção: a variabilidade da temperatura é inimiga da fiabilidade, e a extração não precisa de criatividade.
# Produção: determinístico
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
temperature=0 # Reprodutibilidade
)
Verifique sempre o finish_reason. Este é o único indicador que o avisa de uma resposta truncada antes de tentar utilizá-la.
if response.choices[0].finish_reason != "stop":
# Resposta truncada — aumente max_tokens
raise ValueError(f"Resposta incompleta: {response.choices[0].finish_reason}")
No Modo JSON, instrua sempre o modelo no prompt. O parâmetro garante a sintaxe, não a estrutura: cabe-lhe a si declarar as chaves e os seus tipos.
# Modo JSON — o prompt DEVE descrever a estrutura
messages = [
{
"role": "system",
"content": "Devolver JSON com chaves: name (string), age (number), city (string)."
},
{"role": "user", "content": text}
]
No modo Personalizado, documente os seus campos. Uma descrição precisa vale mais do que um prompt longo e viaja com o esquema em ambas as linguagens.
class Product(BaseModel):
name: str = Field(description="Nome comercial do produto")
price: float = Field(description="Preço em EUR sem IVA, arredondado a 2 casas decimais")
const ProductSchema = z.object({
name: z.string().describe("Nome comercial do produto"),
price: z.number().describe("Preço em EUR sem IVA, arredondado a 2 casas decimais"),
});
Separe contexto de conteúdo. As instruções vivem na mensagem de sistema, os dados a processar na mensagem do utilizador — nunca o inverso, ou o modelo confundirá a instrução com o texto de origem.
messages = [
{"role": "system", "content": "É um extrator de dados. [Instruções de formato]"},
{"role": "user", "content": "[Texto a processar — SEM instruções de formato aqui]"}
]
As duas regras seguintes concernem a sua rede de segurança. Implemente um mecanismo de repetição (retry): nunca faça uma única chamada sem backup; repetir com feedback é o padrão mínimo em produção. E valide para além do esquema, já que o esquema garante a estrutura, enquanto a validação semântica — limites, consistência, lógica de negócio — permanece da sua responsabilidade.
As últimas três relacionam-se com a orquestração. Escolha o modelo certo para o caso de uso certo: mistral-large-latest para tarefas complexas e extração de múltiplos campos, mistral-small-latest para classificação simples e extração básica, ministral-8b-latest para alta frequência e latência mínima. Registe todas as chamadas em produção, registando o modelo utilizado, a duração, o finish_reason e o resultado: sem registos, está cego. Finalmente, não otimize demasiado cedo o prompt — comece simples, meça, itere; a otimização prematura do prompt é uma armadilha comum, enquanto o esquema e a validação são as verdadeiras alavancas.
Três Armadilhas Dispendiosas
A primeira é um valor de max_tokens demasiado baixo. O JSON será truncado em respostas longas, e o erro só se manifestará em documentos grandes, muitas vezes após a entrada em produção.
# Perigoso — o JSON será truncado para respostas longas
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
max_tokens=128 # Demasiado baixo para um esquema complexo
)
Defina max_tokens com base no tamanho esperado da sua saída: uma fatura com 20 linhas requer mais tokens do que uma classificação simples.
A segunda é uma temperatura diferente de zero, o que torna os seus resultados não reproduzíveis sem ganho algum numa tarefa de extração.
# Perigoso em produção — resultados não reproduzíveis
response = client.chat.parse(
...,
temperature=0.7 # Variação desnecessária para extração
)
A terceira é o reflexo de usar um único modelo. Não use mistral-large para tudo: uma classificação binária não requer o modelo mais poderoso, e o ministral-8b fará o trabalho 5 vezes mais rápido por um custo menor.
O Que Monitorizar
Quatro métricas indicam a saúde do seu pipeline. A taxa de sucesso mede a percentagem de chamadas que devolvem um objeto válido à primeira tentativa; a taxa de repetição, a percentagem de chamadas que precisaram de uma segunda oportunidade. A latência P50/P95 fornece o tempo de resposta mediano e o percentil 95, o que é mais revelador do que a média. O custo por extração, expresso em tokens consumidos por chamada, mantém a fatura sob controlo.
Nestas métricas, alguns limiares de alerta funcionam bem: uma taxa de sucesso abaixo de 95% justifica um alerta amarelo, abaixo de 85% um alerta vermelho; uma latência P95 superior a 10 s warrants investigação; e um disjuntor (circuit breaker) aberto exige um alerta imediato.
Ir Mais Longe
Quatro direções estendem naturalmente este curso. A chamada de funções (function calling) usa saídas estruturadas para alimentar chamadas de função num agente. O streaming permite receber a saída estruturada progressivamente, o que importa para respostas longas. O ajuste fino (fine-tuning) adapta um modelo Mistral para melhorar a qualidade da extração nos seus dados específicos. A avaliação, finalmente, consiste em configurar um quadro automático baseado num conjunto de dados de referência (golden dataset) e métricas — é isto que lhe dirá se uma alteração no prompt realmente melhora as coisas.
Um Pipeline Completo
O código seguinte reúne as práticas do curso num único fluxo: um esquema descrito campo por campo, um validador que rejeita pontuações fora dos limites, um modelo dimensionado à tarefa, temperature=0, um max_tokens explícito, verificação do finish_reason e registo para ambos os resultados possíveis.
from mistralai.client import Mistral
from pydantic import BaseModel, Field, field_validator
import logging
import time
logger = logging.getLogger("pipeline")
class CustomerFeedback(BaseModel):
sentiment: str = Field(description="positive, negative, or neutral")
score: float = Field(description="Score between -1.0 and 1.0")
category: str = Field(description="product, service, delivery, price, or other")
action_required: bool = Field(description="True if action is required")
summary: str = Field(description="One-sentence summary")
@field_validator("score")
@classmethod
def score_in_range(cls, v):
if not -1.0 <= v <= 1.0:
raise ValueError(f"Score out of bounds: {v}")
return v
def analyze_feedback(client: Mistral, text: str) -> CustomerFeedback:
start = time.time()
try:
response = client.chat.parse(
model="mistral-small-latest",
messages=[
{"role": "system", "content": "Analyze customer feedback."},
{"role": "user", "content": text}
],
response_format=CustomerFeedback,
temperature=0,
max_tokens=256
)
assert response.choices[0].finish_reason == "stop"
result = response.choices[0].message.parsed
logger.info(f"OK in {time.time()-start:.2f}s — {result.sentiment} ({result.score:+.1f})")
return result
except Exception as e:
logger.error(f"ERROR in {time.time()-start:.2f}s — {e}")
raise
Cerca de trinta linhas, e tem um componente que pode ser ligado com segurança no meio de um sistema: é exatamente isto que as saídas estruturadas tornam possível.
Pontos-chave
- Utilize Saídas Estruturadas Personalizadas em produção, Modo JSON para prototipagem
temperature=0, verificação dofinish_reasone repetição (retry) são inegociáveis- Escolha o modelo com base na complexidade da tarefa e no orçamento
- Monitore a taxa de sucesso, a latência e o custo
- Comece simples, meça e, depois, otimize
Teste os Seus Conhecimentos
Modo JSON, esquemas, repetição: saída estruturada sob controlo?
1. Modo JSON vs Saídas Estruturadas Personalizadas: qual é a diferença?
Resposta: O Modo JSON garante JSON sintaticamente válido; as Saídas Estruturadas Personalizadas impõem adicionalmente o seu esquema exato — campos, tipos, estrutura: o contrato completo.
2. O que fornece client.chat.parse() com Pydantic?
Resposta: O ciclo completo: o esquema Pydantic declara a estrutura, a API restringe a geração e a resposta chega já validada e tipada como um objeto Python — zero análise manual.
3. E do lado do TypeScript?
Resposta: O mesmo conforto com Zod: o esquema Zod define e valida a estrutura — uma única fonte de verdade para geração e tipagem.
4. O que fazer quando a saída não respeita o esquema?
Resposta: Valide sistematicamente e planeie uma estratégia de repetição: solicite novamente com o erro no contexto ou degrade graciosamente — nunca confie cegamente na saída.
5. Quando é a saída estruturada indispensável?
Resposta: Assim que um programa consome a resposta sem revisão humana: extração, integrações, pipelines — o formato deixa de ser uma cortesia, torna-se uma interface.
Esquema declarado, geração condicionada, validação da saída: a tríade que torna a IA plugável em software real.