A client.chat.parse() használata
Ezen az oldalon
A parse() metódus: Az egyéni strukturált kimenetek szíve
A client.chat.parse() a client.chat.complete() strukturált megfelelője. Ahelyett, hogy szabad szöveget vagy nyers JSON-t adna vissza, amit neked kellene feldolgoznod, közvetlenül egy typed objektumot ad vissza, amely illeszkedik a Pydantic modelledhez. A változás első ránézésre csak kozmetikai jellegűnek tűnhet, de valójában teljes kódrétegeket szüntet meg.
A különbség oldal-by-oldal összehasonlítva a legegyértelműbb. A complete() használatakor egy stringet kapsz vissza, amit neked kell átalakítanod. A parse() esetén az objektum használatra készen érkezik, és a nyers JSON is elérhető marad, ha szükséged van rá.
# JSON mód — a complete() JSON szöveget ad vissza
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) # Kézi feldolgozás
# Egyéni — a parse() typed objektumot ad vissza
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema
)
obj: MonSchema = response.choices[0].message.parsed # Pydantic objektum
raw_json: str = response.choices[0].message.content # A nyers JSON is elérhető
A különbség a .parsed elérésében rejlik: ez egy közvetlenül használható Pydantic objektum, IDE automatikus kiegészítéssel és típusellenőrzéssel.
Egy teljes végponttól-végpontig tartó hívás
Az alábbi példa végigvezet egy valós kinyerés öt lépésén: a séma meghatározása világos leírásokkal, a kliens létrehozása, a parse() meghívása, a visszaadott objektum használata, és szükség esetén a JSON reprezentáció lekérése.
from mistralai.client import Mistral
from pydantic import BaseModel, Field
from typing import Optional
# 1. A séma meghatározása
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. A kliens létrehozása
client = Mistral(api_key="your-api-key")
# 3. A parse() meghívása
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. A feldolgozott objektum használata
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. A nyers JSON is elérhető
raw = response.choices[0].message.content
print(f"\nRaw JSON: {raw}")
Figyeld meg, mit nem tartalmaz a rendszerüzenet (system prompt): nincs benne leírás a várt formátumról.
Az automatikusan hozzáadott rendszerüzenet
Az SDK ezt intézi. Amikor a parse()-t használod, a Mistral automatikusan egy előtagot fűz a rendszerüzenethez:
Your output should be an instance of a JSON object following this schema: { ... }
Ez az előtag a Pydantic modelledből generált JSON sémát tartalmazza. Nem kell leírnod a formátumot a promptodban – az SDK megcsinálja helyetted. Ez felszabadítja a rendszerüzenetedet arra, hogy azt csinálja, amiben a legjobb: üzleti kontextust biztosítson és minőségi követelményeket szabjon meg, például az összegek pontosságát vagy a hiányzó adatok kezelését.
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
# Nem kell leírni a JSON formátumot – ez automatikus
# Fókuszálj a KONTEXTUSRA és a MINŐSÉGRE
"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 vs .content: Két eltérő használati mód
A typed objektum, amely a .parsed segítségével érhető el, az, amit az alkalmazáslogikádban kezelsz. Feltárja az attribútumokat a típusukkal, támogatja az iterációt, szótárrá alakítható a model_dump() segítségével, és JSON-ná serializálható a model_dump_json() metódussal.
book = response.choices[0].message.parsed
# Typed hozzáférés IDE automatikus kiegészítéssel
print(book.title) # str
print(book.authors) # list[str]
print(book.year) # Optional[int]
# Iterálás listákon
for author in book.authors:
print(f" - {author}")
# Átalakítás szótárrá
book_dict = book.model_dump()
# Serializálás JSON-ná
book_json = book.model_dump_json(indent=2)
A nyers JSON ezzel szemben továbbra is hasznos a rendszerhatárokon: naplózásra, adatbázis-tárolásra, vagy a válasz változatlan továbbítására egy másik API-nak.
raw = response.choices[0].message.content
# Ez egy JSON string, amely hasznos:
# - Naplózásra
# - Adatbázis-tárolásra
# - Továbbításra egy másik API-nak
import json
data = json.loads(raw)
Ami mégis hibázhat
A garantált séma nem teszi a kódodat immunissá mindenre. Az API hálózati vagy szolgáltatási hibát adhat vissza, és a .parsed értéke None lehet, ha a válasz megszakadt. Az alábbi minta külön kezeli mindkét esetet – SDKError az API számára, ValidationError a sémának –, és csak korlátozott számú alkalommal próbálkozik újra.
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):
"""Strukturált kinyerés hibakezeléssel."""
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
# Használat
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}")
A JSON módnál látott reflexió itt is érvényes: ha a max_tokens miatt levágják a választ, az hiányos vagy null objektumot eredményez, és a finish_reason ezt még a pipeline későbbi szakasza előtt jelzi neked.
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" = levágott válasz, növeld a max_tokens értékét
Főbb megállapítások
- A
client.chat.parse()leváltja aclient.chat.complete()-ot az egyéni strukturált kimeneteknél - A
.parsedegy typed Pydantic objektumot ad vissza; a.contentnyers JSON-t - A séma automatikusan hozzáadódik a rendszerüzenethez – nem kell leírni a formátumot
- Mindig ellenőrizd a
finish_reasonértékét, és kezeld azSDKErrorésValidationErrorhibákat - Használd a
model_dump()metódust a feldolgozott objektum Python szótárrá alakításához