Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Best Practices en Samenvatting

Les 12 van 12 Bijgewerkt op 2 november 2026 Ontwikkelaar
Op deze pagina
  1. Samenvatting van de Cursus
  2. Uw Aanpak Kiezen
  3. De Tien Gouden Regels
  4. Drie Kostbare Valkuilen
  5. Wat U Moet Monitoren
  6. Verder Gaan
  7. Een Volledige Pipeline
  8. Belangrijkste punten
  9. Test Uw Kennis

Samenvatting van de Cursus

U heeft het volledige scala aan mechanismen voor gestructureerde output verkend die de Mistral API biedt. Deze laatste les bundelt wat het verschil maakt in het dagelijkse werk: hoe u kiest tussen de twee benaderingen, de niet-onderhandelbare instellingen, de meest voorkomende valkuilen en wat u moet monitoren zodra u in productie bent.

Uw Aanpak Kiezen

Vier vragen volstaan om te beslissen, in deze volgorde. Heeft u een gedefinieerd outputschema? Als het antwoord nee is, blijf dan bij JSON Mode: u bevindt zich in een verkennings- of prototypingfase en het vastleggen van een datamodel zou voorbarig zijn. Als het antwoord ja is, gaat u door naar de volgende vraag.

Werkt u in Python of TypeScript? Zo ja, dan staan Custom Structured Outputs voor u klaar met Pydantic of Zod. Zo niet, dan blijft JSON Mode met handmatige validatie uw pad.

Bent u in productie? Zo ja, dan zijn Custom Structured Outputs altijd verplicht. Anders is JSON Mode meer dan voldoende voor prototyping.

Verandert het schema frequent? Een schema dat nog evolueert, maakt JSON Mode in eerste instantie praktischer, totdat de vereisten stabiliseren; een vast schema pleit voor Custom Structured Outputs en de betrouwbaarheid die ze bieden.

De Tien Gouden Regels

De eerste vijf hebben betrekking op hoe u uw calls schrijft. Stel temperature=0 altijd in voor productie: variabiliteit door temperatuur is de vijand van betrouwbaarheid, en extractie heeft geen creativiteit nodig.

# Production: deterministic
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema,
    temperature=0  # Reproducibility
)

Controleer altijd finish_reason. Dit is de enige indicator die u waarschuwt voor een afgekapte respons voordat u deze probeert te gebruiken.

if response.choices[0].finish_reason != "stop":
    # Response is truncated — increase max_tokens
    raise ValueError(f"Incomplete response: {response.choices[0].finish_reason}")

Geef in JSON Mode altijd instructies aan het model in de prompt. De parameter garandeert de syntaxis, niet de structuur: het is aan u om de sleutels en hun typen te specificeren.

# JSON Mode — the prompt MUST describe the structure
messages = [
    {
        "role": "system",
        "content": "Return JSON with keys: name (string), age (number), city (string)."
    },
    {"role": "user", "content": text}
]

Documenteer uw velden in de Custom-modus. Een precieze beschrijving is meer waard dan een lange prompt en reist mee met het schema in beide talen.

class Product(BaseModel):
    name: str = Field(description="Commercial product name")
    price: float = Field(description="Price in EUR excluding tax, rounded to 2 decimals")
const ProductSchema = z.object({
  name: z.string().describe("Commercial product name"),
  price: z.number().describe("Price in EUR excluding tax, rounded to 2 decimals"),
});

Scheid context van inhoud. Instructies horen thuis in het systeembericht, de te verwerken data in het gebruikersbericht—nooit andersom, anders verwart het model de instructie met de brontekst.

messages = [
    {"role": "system", "content": "You are a data extractor. [Format instructions]"},
    {"role": "user", "content": "[Text to process — NO format instructions here]"}
]

De volgende twee regels betreffen uw veiligheidsnet. Implementeer een retry-mechanisme: doe nooit een enkele call zonder back-up; opnieuw proberen met feedback is het minimale patroon in productie. En valideer verder dan het schema, aangezien het schema de structuur garandeert terwijl semantische validatie—grenswaarden, consistentie, bedrijfslogica—uw verantwoordelijkheid blijft.

De laatste drie hebben betrekking op orchestratie. Kies het juiste model voor de juiste use case: mistral-large-latest voor complexe taken en extractie van meerdere velden, mistral-small-latest voor eenvoudige classificatie en basisextractie, ministral-8b-latest voor hoge frequentie en minimale latentie. Log elke call in productie, waarbij u het gebruikte model, de duur, finish_reason en de uitkomst vastlegt: zonder logs bent u blind. Tot slot, optimaliseer de prompt niet te vroeg—begin eenvoudig, meet, iterere; voortijdige prompt-optimalisatie is een veelvoorkomende valkuil, terwijl het schema en de validatie de echte hefbomen zijn.

Drie Kostbare Valkuilen

De eerste is een max_tokens-waarde die te laag is. JSON wordt afgekapte bij lange responsen, en de fout manifesteert zich pas bij grote documenten, vaak pas na livegang.

# Dangerous — JSON will be truncated for long responses
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema,
    max_tokens=128  # Too low for a complex schema
)

Stel max_tokens in op basis van de verwachte grootte van uw output: een factuur met 20 regels vereist meer tokens dan een eenvoudige classificatie.

De tweede is een temperatuur hoger dan nul, waardoor uw resultaten niet-reproduceerbaar worden zonder enig voordeel voor een extractietaak.

# Dangerous in production — non-reproducible results
response = client.chat.parse(
    ...,
    temperature=0.7  # Unnecessary variation for extraction
)

De derde is de reflex om één enkel model te gebruiken. Gebruik niet mistral-large voor alles: een binaire classificatie vereist niet het krachtigste model, en ministral-8b doet het werk 5x sneller voor minder kosten.

Wat U Moet Monitoren

Vier metrics vertellen u iets over de gezondheid van uw pipeline. Het slagingspercentage meet het percentage calls dat bij de eerste poging een geldig object retourneert; het retry-percentage meet het percentage calls dat een tweede kans nodig had. P50/P95-latentie geeft de mediane responstijd en het 95e percentiel, wat onthullender is dan het gemiddelde. Kosten per extractie, uitgedrukt in verbruikte tokens per call, houdt de factuur onder controle.

Op basis van deze metrics houden enkele alertdrempels stand: een slagingspercentage onder de 95% rechtvaardigt een gele alert, onder de 85% een rode alert; een P95-latentie groter dan 10 s vereist onderzoek; en een geopende circuit breaker vraagt om een onmiddellijke alert.

Verder Gaan

Vier richtingen breiden deze cursus op natuurlijke wijze uit. Function calling gebruikt gestructureerde outputs om functieaanroepen in een agent te voeden. Streaming stelt u in staat de gestructureerde output progressief te ontvangen, wat belangrijk is bij lange responsen. Fine-tuning past een Mistral-model aan om de extractiekwaliteit op uw specifieke data te verbeteren. Evaluatie ten slotte bestaat uit het opzetten van een automatisch framework gebaseerd op een gouden dataset en metrics—dit is wat u vertelt of een wijziging in de prompt daadwerkelijk verbetering brengt.

Een Volledige Pipeline

De volgende code brengt de praktijken uit de cursus samen in één flow: een veld-voor-veld beschreven schema, een validator die scores buiten bereik afwijst, een model dat op de taak is afgestemd, temperature=0, een expliciete max_tokens, verificatie van finish_reason en logging voor beide mogelijke uitkomsten.

from mistralai.client import Mistral
from pydantic import BaseModel, Field, field_validator
import logging
import time

logger = logging.getLogger("pipeline")

class CustomerFeedback(BaseModel):
    sentiment: str = Field(description="positive, negative, or neutral")
    score: float = Field(description="Score between -1.0 and 1.0")
    category: str = Field(description="product, service, delivery, price, or other")
    action_required: bool = Field(description="True if action is required")
    summary: str = Field(description="One-sentence summary")

    @field_validator("score")
    @classmethod
    def score_in_range(cls, v):
        if not -1.0 <= v <= 1.0:
            raise ValueError(f"Score out of bounds: {v}")
        return v

def analyze_feedback(client: Mistral, text: str) -> CustomerFeedback:
    start = time.time()
    try:
        response = client.chat.parse(
            model="mistral-small-latest",
            messages=[
                {"role": "system", "content": "Analyze customer feedback."},
                {"role": "user", "content": text}
            ],
            response_format=CustomerFeedback,
            temperature=0,
            max_tokens=256
        )
        assert response.choices[0].finish_reason == "stop"
        result = response.choices[0].message.parsed
        logger.info(f"OK in {time.time()-start:.2f}s — {result.sentiment} ({result.score:+.1f})")
        return result
    except Exception as e:
        logger.error(f"ERROR in {time.time()-start:.2f}s — {e}")
        raise

Ongeveer dertig regels, en u heeft een component dat veilig in het midden van een systeem kan worden geplaatst: dit is precies wat gestructureerde outputs mogelijk maken.

Belangrijkste punten

  • Gebruik Custom Structured Outputs in productie, JSON Mode voor prototyping
  • temperature=0, het controleren van finish_reason en retry zijn niet-onderhandelbaar
  • Kies het model op basis van taakcomplexiteit en budget
  • Monitor slagingspercentage, latentie en kosten
  • Begin eenvoudig, meet en optimaliseer vervolgens

Test Uw Kennis

JSON Mode, schema’s, retry: gestructureerde output onder controle?

1. JSON Mode vs Custom Structured Outputs: wat is het verschil?

Antwoord: JSON Mode garandeert syntactisch geldige JSON; Custom Structured Outputs dwingen bovendien uw exacte schema af—velden, typen, structuur: het volledige contract.

2. Wat biedt client.chat.parse() met Pydantic?

Antwoord: De volledige lus: het Pydantic-schema declareert de structuur, de API beperkt de generatie en de respons komt al gevalideerd en getypt als een Python-object binnen—geen handmatige parsing nodig.

3. En aan de TypeScript-kant?

Antwoord: Hetzelfde comfort met Zod: het Zod-schema definieert en valideert de structuur—een enkele bron van waarheid voor generatie en typering.

4. Wat te doen wanneer de output het schema niet respecteert?

Antwoord: Valideer systematisch en plan een retry-strategie: vraag opnieuw aan met de fout in de context, of degradeer elegant—vertrouw nooit blindelings op de output.

5. Wanneer is gestructureerde output onmisbaar?

Antwoord: Zodra een programma de respons consumeert zonder menselijke review: extractie, integraties, pipelines—het formaat houdt op een beleefdheid te zijn, het wordt een interface.

Gedeclareerd schema, gecontroleerde generatie, output-validatie: de triade die AI plugbaar maakt in echte software.