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

Modo JSON vs. Saídas Estruturadas Personalizadas

Aula 2 de 12 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Duas abordagens, duas filosofias
  2. Modo JSON: flexibilidade
  3. Saídas Estruturadas Personalizadas: rigor
  4. Comparação detalhada
  5. Como decidir na prática
  6. Pontos-chave

Duas abordagens, duas filosofias

A API da Mistral oferece dois mecanismos distintos para gerar saídas estruturadas. Eles não competem entre si; servem fases diferentes do ciclo de vida de um projeto. A sua escolha depende do seu caso de uso, da sua pilha tecnológica e do nível de fiabilidade que precisa de manter.

Modo JSON: flexibilidade

O Modo JSON é a abordagem mais simples. Ativa um parâmetro no seu pedido e a Mistral garante que a saída será um JSON válido. É só isto. O modelo mantém a liberdade de escolher a estrutura: chaves, tipos e profundidade de aninhamento. Você orienta o formato desejado através do seu prompt, mas nenhuma restrição técnica vincula o esquema.

# Modo JSON — o modelo escolhe a estrutura
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Analyze this text and return the result in JSON."}],
    response_format={"type": "json_object"}
)

Este minimalismo é a sua principal força: basta adicionar um parâmetro, não é necessário definir nenhum esquema antecipadamente e existe total flexibilidade quando está a explorar um problema ou a criar protótipos rapidamente. A desvantagem é simétrica. Nada garante a estrutura exata do JSON que recebe: o modelo pode omitir um campo, adicionar outro ou renomear uma chave de uma chamada para a outra. A validação do lado do cliente torna-se, portanto, obrigatória, e isso é código que tem de escrever e manter você mesmo.

Saídas Estruturadas Personalizadas: rigor

As Saídas Estruturadas Personalizadas transferem esta restrição para o lado da API. Você define um esquema preciso — usando Pydantic em Python ou Zod em TypeScript — e a Mistral força o modelo a aderir a ele exatamente.

from pydantic import BaseModel

class Analyse(BaseModel):
    sentiment: str
    score: float
    keywords: list[str]

# Personalizado — o esquema é imposto
response = client.chat.parse(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Analyze this text."}],
    response_format=Analyse
)

O benefício é imediato: todos os campos estão presentes com o tipo correto e você recebe de volta um objeto analisado pronto a usar — uma instância de um modelo Pydantic ou Zod — com autocompletamento total no IDE. Este é o modo para produção e pipelines críticos. A contrapartida resume-se a uma frase: tem de definir um modelo de dados antecipadamente, o que torna a exploração menos flexível e impõe uma ligeira sobrecarga inicial de desenvolvimento.

Comparação detalhada

CritérioModo JSONSaídas Estruturadas Personalizadas
Ativaçãoresponse_format: {"type": "json_object"}response_format: MyModel (Pydantic/Zod)
Método da APIclient.chat.complete()client.chat.parse()
Garantia de esquemaNão — apenas JSON válidoSim — esquema exato imposto
Análise automáticaNão — json.loads() manualSim — .parsed devolve objeto tipado
FlexibilidadeAlta — estrutura livreBaixa — estrutura fixa
Caso de uso idealPrototipagem, exploração, esquemas variáveisProdução, pipelines críticos, APIs
Validação necessáriaSim — obrigatória no lado do clienteMínima — o esquema faz o trabalho

Como decidir na prática

Três sinais apontam para o Modo JSON. O primeiro é a fase do projeto: quando está a fazer prototipagem e o esquema ainda não é estável, bloquear um modelo de dados atrasa-o sem adicionar valor. O segundo é a natureza da tarefa: se a estrutura da saída variar legitimamente com base na entrada, como numa análise exploratória onde as dimensões relevantes não são conhecidas antecipadamente, uma estrutura fixa seria uma camisa de forças. O terceiro é técnico: numa linguagem sem suporte para Pydantic ou Zod, o Modo JSON permanece a sua única porta de entrada.

As Saídas Estruturadas Personalizadas assumem o controlo assim que a situação se inverte. Está em produção e uma extração falhada tem um custo real; o esquema de saída é conhecido e estável; está a trabalhar em Python ou TypeScript; e quer manipular objetos tipados em vez de dicionários anónimos. Concretamente, um pipeline que classifica tickets de suporte o dia todo usando os mesmos quatro campos não tem razão para permanecer no Modo JSON.

Isto alinha-se com a documentação oficial da Mistral, que recomenda o uso de Saídas Estruturadas Personalizadas sempre que possível. O Modo JSON permanece um bom ponto de entrada, mas as Saídas Personalizadas oferecem uma fiabilidade superior e reduzem significativamente o código de validação do lado do cliente.

Pontos-chave

  • Modo JSON = JSON válido garantido, estrutura livre, simples de ativar
  • Saídas Estruturadas Personalizadas = esquema exato garantido, análise automática, ideal para produção
  • Comece com o Modo JSON para prototipagem, migre para o Personalizado para produção
  • As duas abordagens são complementares, não mutuamente exclusivas