Brug af client.chat.parse()
På denne side
Metoden parse(): Hjertet i tilpassede strukturerede outputs
client.chat.parse() er den strukturerede modpart til client.chat.complete(). I stedet for at returnere frit tekst eller rå JSON, som du selv skal parsere, returnerer den direkte et typet objekt, der matcher din Pydantic-model. Ændringen kan virke kosmetisk, men den fjerner reelt et helt lag af kode.
Kontrasten står klarest, når man ser dem side om side. Med complete() modtager du en streng og transformerer den selv. Med parse() ankommer objektet klar til brug, og den rå JSON forbliver tilgængelig, hvis du får brug for den.
# JSON-tilstand — complete() returnerer JSON-tekst
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
response_format={"type": "json_object"}
)
raw_json: str = response.choices[0].message.content
data = json.loads(raw_json) # Manuel parsing
# Tilpasset — parse() returnerer et typet objekt
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema
)
obj: MonSchema = response.choices[0].message.parsed # Pydantic-objekt
raw_json: str = response.choices[0].message.content # Rå JSON også tilgængelig
Forskellen ligger i adgangen til .parsed: et direkte brugbart Pydantic-objekt med IDE-autofuldførelse og typevalidering.
Et komplet end-to-end-kald
Følgende eksempel gennemgår de fem trin i en rigtig udtrækning: definer skemaet med klare beskrivelser, opret klienten, kald parse(), brug det returnerede objekt, og hent JSON-repræsentationen, hvis det er nødvendigt.
from mistralai.client import Mistral
from pydantic import BaseModel, Field
from typing import Optional
# 1. Definer skemaet
class BookInfo(BaseModel):
title: str = Field(description="Book title")
authors: list[str] = Field(description="List of authors")
year: Optional[int] = Field(default=None, description="Publication year")
genre: str = Field(description="Main literary genre")
summary: str = Field(description="Summary in 2-3 sentences")
# 2. Opret klienten
client = Mistral(api_key="your-api-key")
# 3. Kald parse()
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "You are an expert librarian. Extract information about the mentioned book."
},
{
"role": "user",
"content": "I loved '1984' by George Orwell. It's a dystopian novel published in 1949 describing a totalitarian society under constant surveillance."
}
],
temperature=0
)
# 4. Brug det parsede objekt
book = response.choices[0].message.parsed
print(f"Title: {book.title}")
print(f"Authors: {', '.join(book.authors)}")
print(f"Year: {book.year}")
print(f"Genre: {book.genre}")
print(f"Summary: {book.summary}")
# 5. Rå JSON er også tilgængelig
raw = response.choices[0].message.content
print(f"\nRaw JSON: {raw}")
Bemærk, hvad system-prompten ikke indeholder: ingen beskrivelse af det forventede format.
Den automatisk tilføjede system-prompt
SDK’et håndterer dette. Når du bruger parse(), tilføjer Mistral automatisk et præfiks til system-prompten:
Your output should be an instance of a JSON object following this schema: { ... }
Dette præfiks indeholder JSON-skemaet genereret ud fra din Pydantic-model. Du behøver ikke at beskrive formatet i din prompt – SDK’et gør det for dig. Det frigør din systembesked til at gøre det, den er bedst til: levere forretningskontekst og sætte kvalitetskrav, såsom præcision for beløb eller hvordan manglende data skal håndteres.
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
# Ingen grund til at beskrive JSON-formatet – det sker automatisk
# Fokuser på KONTEKST og KVALITET
"content": """You are an expert financial analyst.
Be precise with amounts and percentages.
If data is not available in the text, use null."""
},
{"role": "user", "content": report_text}
],
response_format=FinancialReport
)
.parsed kontra .content: To forskellige anvendelser
Det typede objekt, som er tilgængeligt via .parsed, er det, du manipulerer i din applikationslogik. Det eksponerer attributter med deres typer, understøtter iteration, konverterer til en ordbog med model_dump() og serialiserer med model_dump_json().
book = response.choices[0].message.parsed
# Typet adgang med IDE-autofuldførelse
print(book.title) # str
print(book.authors) # list[str]
print(book.year) # Optional[int]
# Iterer over lister
for author in book.authors:
print(f" - {author}")
# Konverter til ordbog
book_dict = book.model_dump()
# Serialiser til JSON
book_json = book.model_dump_json(indent=2)
Rå JSON er derimod stadig nyttig ved systemgrænser: til logning, databaselagring eller til at sende svaret videre uændret til en anden API.
raw = response.choices[0].message.content
# Dette er en JSON-streng, nyttig til:
# - Logning
# - Databaselagring
# - Sending til en anden API
import json
data = json.loads(raw)
Hvad der stadig kan gå galt
Et garanteret skema gør ikke din kode immun over for alt. API’en kan returnere en netværks- eller tjenestefejl, og .parsed kan være None, hvis svaret blev afbrudt. Mønsteret nedenfor håndterer begge tilfælde separat – SDKError for API’en, ValidationError for skemaet – og forsøger kun et begrænset antal gange.
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
from pydantic import ValidationError
client = Mistral(api_key="your-api-key")
def extract_structured(text: str, schema, max_retries: int = 2):
"""Struktureret udtrækning med fejlhåndtering."""
for attempt in range(max_retries + 1):
try:
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Extract the requested information."},
{"role": "user", "content": text}
],
response_format=schema,
temperature=0,
max_tokens=1024
)
parsed = response.choices[0].message.parsed
if parsed is None:
raise ValueError("Parsed is None—response may be truncated")
return parsed
except SDKError as e:
print(f"API error (attempt {attempt + 1}): {e}")
if attempt == max_retries:
raise
except ValidationError as e:
print(f"Validation error (attempt {attempt + 1}): {e}")
if attempt == max_retries:
raise
# Brug
try:
book = extract_structured("'The Little Prince' by Saint-Exupéry, 1943", BookInfo)
print(f"Extracted: {book.title} by {', '.join(book.authors)}")
except Exception as e:
print(f"Final failure: {e}")
Refleksen, man ser med JSON-tilstand, gælder stadig her: et svar, der afskæres af max_tokens, producerer et ufuldstændigt eller null-objekt, og finish_reason fortæller dig dette, før du opdager det længere nede i pipeline.
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
max_tokens=256
)
if response.choices[0].finish_reason != "stop":
print(f"Warning: finish_reason = {response.choices[0].finish_reason}")
# "length" = afkortet svar, øg max_tokens
Vigtige pointer
client.chat.parse()erstatterclient.chat.complete()til tilpassede strukturerede outputs.parsedreturnerer et typet Pydantic-objekt;.contentreturnerer rå JSON- Skemaet tilføjes automatisk til system-prompten – ingen grund til at beskrive formatet
- Tjek altid
finish_reasonog håndter fejl af typenSDKErrorogValidationError - Brug
model_dump()til at konvertere det parsede objekt til en Python-ordbog