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

Boas Práticas e Resumo

Aula 12 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Resumo do Curso
  2. Escolher a Sua Abordagem
  3. As Dez Regras de Ouro
  4. Três Armadilhas Dispendiosas
  5. O Que Monitorizar
  6. Ir Mais Longe
  7. Um Pipeline Completo
  8. Pontos-chave
  9. Teste os Seus Conhecimentos

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 do finish_reason e 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.