JSON-modus versus aangepaste gestructureerde uitvoer
Op deze pagina
Twee benaderingen, twee filosofieën
De Mistral API biedt twee verschillende mechanismen voor het genereren van gestructureerde uitvoer. Ze concurreren niet met elkaar; ze dienen verschillende fasen in de levenscyclus van een project. Uw keuze hangt af van uw use case, uw tech stack en het betrouwbaarheidsniveau dat u moet handhaven.
JSON-modus: flexibiliteit
JSON-modus is de eenvoudigste benadering. U schakelt een parameter in uw verzoek in en Mistral garandeert dat de uitvoer geldige JSON is. Dat is alles. Het model blijft vrij om de structuur te kiezen: sleutels, typen en nestingsdiepte. U stuurt het gewenste formaat via uw prompt, maar er binden geen technische beperkingen het schema.
# JSON Mode — the model chooses the structure
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"}
)
Dit minimalisme is de grootste kracht: slechts één parameter toevoegen, geen schema vooraf definiëren en totale flexibiliteit wanneer u een probleem verkent of snel prototypeert. Het nadeel is symmetrisch. Niets garandeert de exacte structuur van de JSON die u ontvangt: het model kan een veld weglaten, een ander toevoegen of een sleutel van de ene aanroep naar de andere hernoemen. Validatie aan de clientzijde wordt daarom verplicht, en dat is code die u zelf moet schrijven en onderhouden.
Aangepaste gestructureerde uitvoer: nauwkeurigheid
Aangepaste gestructureerde uitvoer verlegt deze beperking naar de API-zijde. U definieert een nauwkeurig schema—met Pydantic in Python of Zod in TypeScript—en Mistral dwingt het model om zich hier exact aan te houden.
from pydantic import BaseModel
class Analyse(BaseModel):
sentiment: str
score: float
keywords: list[str]
# Custom — the schema is enforced
response = client.chat.parse(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Analyze this text."}],
response_format=Analyse
)
Het voordeel is direct: elk veld is aanwezig met het juiste type en u ontvangt een geparsed object dat klaar is voor gebruik—een instantie van een Pydantic- of Zod-model—met volledige IDE-autocompletion. Dit is de modus voor productie en kritieke pipelines. De afweging komt neer op één zin: u moet vooraf een datamodel definiëren, wat exploratie minder flexibel maakt en een lichte initiële ontwikkelingsoverhead oplegt.
Gedetailleerde vergelijking
| Criterium | JSON-modus | Aangepaste gestructureerde uitvoer |
|---|---|---|
| Activering | response_format: {"type": "json_object"} | response_format: MyModel (Pydantic/Zod) |
| API-methode | client.chat.complete() | client.chat.parse() |
| Schema-garantie | Nee — alleen geldige JSON | Ja — exact schema afgedwongen |
| Automatisch parsen | Nee — handmatige json.loads() | Ja — .parsed retourneert getypeerd object |
| Flexibiliteit | Hoog — vrije structuur | Laag — vaste structuur |
| Ideale use case | Prototyping, exploratie, variabele schema’s | Productie, kritieke pipelines, API’s |
| Validatie vereist | Ja — verplicht aan clientzijde | Minimaal — het schema doet het werk |
De keuze in de praktijk
Drie signalen wijzen op JSON-modus. Ten eerste de projectfase: wanneer u prototypeert en het schema nog niet stabiel is, vertraagt het vastleggen van een datamodel u zonder waarde toe te voegen. Ten tweede de aard van de taak: als de uitvoerstructuur legitiem varieert op basis van de input, zoals bij exploratieve analyse waar relevante dimensies niet vooraf bekend zijn, zou een vaste structuur een keurslijf zijn. Ten derde technisch: in een taal zonder ondersteuning voor Pydantic of Zod blijft JSON-modus uw enige instappunt.
Aangepaste gestructureerde uitvoer neemt het over zodra de situatie omdraait. U bevindt zich in productie en een mislukte extractie heeft reële kosten; het uitvoerschema is bekend en stabiel; u werkt in Python of TypeScript; en u wilt getypeerde objecten manipuleren in plaats van anonieme dictionaries. Concreet heeft een pipeline die de hele dag door supporttickets classificeert met dezelfde vier velden geen reden om in JSON-modus te blijven.
Dit sluit aan bij de officiële Mistral-documentatie, die aanbeveelt om wanneer mogelijk aangepaste gestructureerde uitvoer te gebruiken. JSON-modus blijft een goed instappunt, maar aangepaste uitvoer biedt superieure betrouwbaarheid en reduceert de validatiecode aan de clientzijde aanzienlijk.
Belangrijkste punten
- JSON-modus = gegarandeerd geldige JSON, vrije structuur, eenvoudig in te schakelen
- Aangepaste gestructureerde uitvoer = gegarandeerd exact schema, automatisch parsen, ideaal voor productie
- Begin met JSON-modus voor prototyping, migreer naar aangepast voor productie
- De twee benaderingen zijn complementair, niet wederzijds uitsluitend