Ativar o Modo JSON
Nesta página
Atualizado em 3 de novembro de 2026: Os exemplos em TypeScript importavam anteriormente
Mistralcomo 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 comostring | ContentChunk[]diretamente paraJSON.parsee 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ãoparse()) - Sempre instrua o modelo no prompt sobre a estrutura JSON esperada
- A resposta é uma string JSON — analise-a com
json.loads()ouJSON.parse() - Coloque as instruções de formato no prompt do sistema para pipelines repetitivos