JSON-modus inschakelen
Op deze pagina
Bijgewerkt op 3 november 2026: De eerdere TypeScript-voorbeelden importeerden
Mistralals een standaardexport (import Mistral from …), maar de SDK biedt alleen een benoemde export:import { Mistral } from "@mistralai/mistralai". Ze gaven ook inhoud van het typestring | ContentChunk[]direct door aanJSON.parseen hardcodden de API-sleutel in de broncode. Geverifieerd door compilatie met SDK 3.5.0 en TypeScript 7.0.2. Bron: Mistral TypeScript SDK.
Hoe JSON-modus werkt
JSON-modus is het eenvoudigste mechanisme om gestructureerde uitvoer van Mistral te verkrijgen. Door één parameter in te schakelen, garandeert u dat het antwoord van het model geldige JSON is. Geen schema om te definiëren, geen gegevensmodel om te schrijven—alleen syntactisch correcte JSON bij elke aanroep.
Inschakelen in Python
U schakelt dit in via de parameter response_format in de methode client.chat.complete(). Let op: de prompt zelf moet de verwachte structuur beschrijven; we leggen zo uit waarom dit niet optioneel is.
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)
De uitvoer is geldige JSON, klaar voor direct gebruik:
{
"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."
}
]
}
Inschakelen in TypeScript
De TypeScript-SDK volgt exact dezelfde logica, met camelCase-namen: de parameter is responseFormat en parsing gebeurt met JSON.parse(). Er geldt één extra voorzorgsmaatregel: de SDK typeert content als string | ContentChunk[], dus JSON.parse accepteert de waarde pas nadat u heeft geverifieerd dat het inderdaad een string is.
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);
Expliciete instructies zijn niet optioneel
Dit is het punt dat veel ontwikkelaars missen, en de reden voor de meeste teleurstelling over JSON-modus: het inschakelen van de parameter is niet genoeg. De modus garandeert de syntaxis, niet de inhoud. U moet het model expliciet instrueren, binnen de prompt, over het formaat dat u verwacht.
Vergelijk de volgende twee aanroepen. Bij de eerste wordt geen structurele begeleiding gegeven: het model produceert wel JSON, maar de sleutels, hun namen en hun nesting variëren van aanroep tot aanroep, waardoor uw downstreamcode geen stabiele aanknopingspunten heeft.
# Slechte praktijk — geen JSON-instructie in de prompt
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{"role": "user", "content": "What are the advantages of cloud?"}
],
response_format={"type": "json_object"}
)
# Het model produceert JSON, maar de structuur is onvoorspelbaar
Bij de tweede wordt een structureel skelet direct in de prompt opgenomen. Het model heeft nu een doel om na te bootsen, waardoor de uitvoer voorspelbaar wordt bij opeenvolgende aanroepen.
# Goede praktijk — duidelijke instructie in de 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"}
)
Het opnemen van een structuurvoorbeeld in uw prompt leidt het model naar het gewenste formaat. Dit is geen absolute garantie zoals bij Aangepaste Gestructureerde Uitvoer, maar het is meer dan voldoende voor de meeste use-cases.
Formaatinstructies verplaatsen naar de systeemprompt
Zodra dezelfde verwerking zich herhaalt over honderden inputs, wordt het onbeheersbaar om formaatinstructies in het gebruikersbericht te laten: u kopieert ze bij elke aanroep en ze raken vermengd met de te verwerken inhoud. Verplaats ze in plaats daarvan naar de systeemprompt.
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"}
)
Deze scheiding—formaatinstructies gedragen door de rol system, en te verwerken inhoud gedragen door de rol user—maakt uw code aanzienlijk onderhoudbaarder: het wijzigen van het formaat gebeurt slechts op één plek.
Het antwoord parseren
Een laatste gewoonte om aan te leren: het antwoord van JSON-modus is altijd een JSON-string binnen message.content, nooit een object. Parsen is uw verantwoordelijkheid, in beide talen.
import json
raw = response.choices[0].message.content
data = json.loads(raw)
# Toegang tot de gegevens
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}`);
});
Belangrijkste punten
- Schakel JSON-modus in met
response_format: {"type": "json_object"} - Gebruik
client.chat.complete()(nietparse()) - Instrueer het model altijd in de prompt over de verwachte JSON-structuur
- Het antwoord is een JSON-string—pars deze met
json.loads()ofJSON.parse() - Plaats formaatinstructies in de systeemprompt voor repetitieve pipelines