Modo JSON vs. Saídas Estruturadas Personalizadas
Nesta página
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ério | Modo JSON | Saídas Estruturadas Personalizadas |
|---|---|---|
| Ativação | response_format: {"type": "json_object"} | response_format: MyModel (Pydantic/Zod) |
| Método da API | client.chat.complete() | client.chat.parse() |
| Garantia de esquema | Não — apenas JSON válido | Sim — esquema exato imposto |
| Análise automática | Não — json.loads() manual | Sim — .parsed devolve objeto tipado |
| Flexibilidade | Alta — estrutura livre | Baixa — estrutura fixa |
| Caso de uso ideal | Prototipagem, exploração, esquemas variáveis | Produção, pipelines críticos, APIs |
| Validação necessária | Sim — obrigatória no lado do cliente | Mí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