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

Ativar o Modo JSON

Aula 4 de 12 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Como Funciona o Modo JSON
  2. Ativação em Python
  3. Ativação em TypeScript
  4. Instruções Explícitas Não São Opcionais
  5. Mover Instruções de Formato para o Prompt do Sistema
  6. Análise da Resposta
  7. Pontos-chave

Atualizado em 3 de novembro de 2026: Os exemplos em TypeScript importavam anteriormente Mistral como uma exportação padrão (import Mistral from …), mas o SDK apenas fornece uma exportação nomeada: import { Mistral } from "@mistralai/mistralai". Além disso, passavam conteúdo tipado como string | ContentChunk[] diretamente para JSON.parse e codificavam a chave da API no código-fonte. Verificado por compilação com o SDK 3.5.0 e TypeScript 7.0.2. Fonte: Mistral TypeScript SDK.

Como Funciona o Modo JSON

O Modo JSON é o mecanismo mais simples para obter resultados estruturados da Mistral. Ao ativar um único parâmetro, garante que a resposta do modelo será um JSON válido. Não é necessário definir um esquema nem escrever um modelo de dados — apenas JSON sintaticamente correto em cada chamada.

Ativação em Python

Ativa esta funcionalidade através do parâmetro response_format no método client.chat.complete(). Note que o próprio prompt deve descrever a estrutura esperada; explicaremos brevemente por que isto não é opcional.

from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {
            "role": "user",
            "content": "Describe the 3 main advantages of cloud computing. Return the result as JSON with a key 'advantages' containing a list of objects with 'title' and 'description'."
        }
    ],
    response_format={"type": "json_object"}
)

print(response.choices[0].message.content)

O resultado será um JSON válido, pronto a usar tal como está:

{
  "advantages": [
    {
      "title": "Scalability",
      "description": "Dynamic adjustment of resources based on demand."
    },
    {
      "title": "Cost Reduction",
      "description": "No investment in physical infrastructure required."
    },
    {
      "title": "Accessibility",
      "description": "Access services from anywhere."
    }
  ]
}

Ativação em TypeScript

O SDK em TypeScript segue exatamente a mesma lógica, com nomenclatura em camelCase: o parâmetro é responseFormat e a análise utiliza JSON.parse(). Aplica-se uma precaução adicional: o SDK tipa content como string | ContentChunk[], pelo que JSON.parse só aceitará o valor após verificar que este é efetivamente uma string.

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

const response = await client.chat.complete({
  model: "mistral-large-latest",
  messages: [
    {
      role: "user",
      content: "List 3 popular JavaScript frameworks in JSON with 'name' and 'useCase'."
    }
  ],
  responseFormat: { type: "json_object" },
});

const contenu = response.choices[0]?.message?.content;
if (typeof contenu !== "string") {
  throw new Error("Response does not contain JSON text.");
}
const data = JSON.parse(contenu);
console.log(data);

Instruções Explícitas Não São Opcionais

Eis o ponto que muitos programadores ignoram e a razão da maior parte das desilusões com o Modo JSON: ativar o parâmetro não é suficiente. O modo garante a sintaxe, não o conteúdo. Deve instruir explicitamente o modelo, dentro do prompt, sobre o formato que espera.

Compare as duas chamadas seguintes. Na primeira, não é dada qualquer orientação estrutural: o modelo produzirá JSON, mas as chaves, os seus nomes e a sua aninhamento variarão de chamada para chamada, deixando o seu código subsequente sem pontos de ancoragem estáveis.

# Má prática — sem instrução JSON no prompt
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {"role": "user", "content": "What are the advantages of cloud?"}
    ],
    response_format={"type": "json_object"}
)
# O modelo produzirá JSON, mas a estrutura será imprevisível

Na segunda, insere-se um esqueleto estrutural diretamente no prompt. O modelo tem agora um alvo a imitar, tornando o resultado previsível entre chamadas.

# Boa prática — instrução clara no prompt
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {
            "role": "user",
            "content": """What are the advantages of cloud computing?

Return your answer in JSON with the following structure:
{
  "topic": "string",
  "advantages": [
    {"title": "string", "description": "string"}
  ]
}"""
        }
    ],
    response_format={"type": "json_object"}
)

Incluir um exemplo de estrutura no seu prompt guia o modelo para o formato desejado. Isto não é uma garantia absoluta como as Saídas Estruturadas Personalizadas, mas é mais do que suficiente para a maioria dos casos de uso.

Mover Instruções de Formato para o Prompt do Sistema

Assim que o mesmo processamento se repete em centenas de entradas, manter as instruções de formato na mensagem do utilizador torna-se ingovernável: copia-as em cada chamada e elas misturam-se com o conteúdo a processar. Mova-as, em vez disso, para o prompt do sistema.

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            "content": "You are a data extraction assistant. You ALWAYS return your responses in JSON with the keys 'entities', 'confidence', and 'source'."
        },
        {
            "role": "user",
            "content": "Extract information from this text: 'Acme Corp, founded in 2019 in Lyon, employs 250 people.'"
        }
    ],
    response_format={"type": "json_object"}
)

Esta separação — instruções de formato transportadas pelo papel system e conteúdo a processar transportado pelo papel user — torna o seu código significativamente mais fácil de manter: alterar o formato acontece num único local.

Análise da Resposta

Um último hábito a adotar: a resposta do Modo JSON é sempre uma string JSON dentro de message.content, nunca um objeto. A análise é da sua responsabilidade, em ambas as linguagens.

import json

raw = response.choices[0].message.content
data = json.loads(raw)

# Aceder aos dados
for advantage in data["advantages"]:
    print(f"- {advantage['title']}: {advantage['description']}")
const contenu = response.choices[0]?.message?.content;
if (typeof contenu !== "string") {
  throw new Error("Response does not contain JSON text.");
}
const data = JSON.parse(contenu);

data.advantages.forEach((adv: any) => {
  console.log(`- ${adv.title}: ${adv.description}`);
});

Pontos-chave

  • Ative o Modo JSON com response_format: {"type": "json_object"}
  • Utilize client.chat.complete() (não parse())
  • Sempre instrua o modelo no prompt sobre a estrutura JSON esperada
  • A resposta é uma string JSON — analise-a com json.loads() ou JSON.parse()
  • Coloque as instruções de formato no prompt do sistema para pipelines repetitivos