Uporaba metode client.chat.parse()
Na tej strani
Metoda parse(): Srce prilagojenih strukturiranih izhodov
client.chat.parse() je strukturirani ekvivalent metode client.chat.complete(). Namesto da bi vrnila prosto besedilo ali surov JSON, ki ga moraš ročno razčleniti, neposredno vrne tipiziran objekt, ki ustreza tvojemu modelu Pydantic. Sprememba se morda zdi zgolj kozmetična, vendar v resnici odpravi celoten sloj kode.
Kontrast je najbolj očiten pri neposredni primerjavi. Z complete() prejmeš niz in ga sam pretvoriš. Z parse() objekt prispe pripravljen za uporabo, surov JSON pa ostane na voljo, če ga potrebuješ.
# Način JSON — complete() vrne besedilo JSON
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) # Ročno razčlenjevanje
# Prilagojeno — parse() vrne tipiziran objekt
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema
)
obj: MonSchema = response.choices[0].message.parsed # Objekt Pydantic
raw_json: str = response.choices[0].message.content # Surov JSON prav tako na voljo
Razlika je v dostopu do .parsed: neposredno uporaben objekt Pydantic s samodejnim dopolnjevanjem v IDE-ju in preverjanjem tipov.
Popoln klic od začetka do konca
Naslednji primer prikazuje pet korakov prave ekstrakcije: definiranje sheme z jasnimi opisi, ustvarjanje odjemalca, klic parse(), uporaba vrnjenega objekta in po potrebi pridobitev zapisa JSON.
from mistralai.client import Mistral
from pydantic import BaseModel, Field
from typing import Optional
# 1. Definiraj shemo
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. Ustvari odjemalca
client = Mistral(api_key="your-api-key")
# 3. Pokliči 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. Uporabi razčlenjeni 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. Surov JSON je prav tako na voljo
raw = response.choices[0].message.content
print(f"\nRaw JSON: {raw}")
Opazi, kaj sistemski poziv ne vsebuje: nobenega opisa pričakovane oblike.
Samodejno dodani sistemski poziv
SDK to opravi namesto tebe. Ko uporabiš parse(), Mistral samodejno doda predpono sistemskemu pozivu:
Your output should be an instance of a JSON object following this schema: { ... }
Ta predpona vsebuje shemo JSON, generirano iz tvojega modela Pydantic. V pozivu ni treba opisovati oblike – to stori SDK namesto tebe. To sprosti tvoje sistemsko sporočilo, da dela tisto, kar zna najbolje: zagotavlja poslovni kontekst in določa zahteve glede kakovosti, kot so natančnost zneskov ali ravnanje s manjkajočimi podatki.
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
# Ni treba opisovati oblike JSON – to je samodejno
# Osredotoči se na KONTEKST in KAKOVOST
"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 proti .content: Dve različni uporabi
Tipiziran objekt, dostopen prek .parsed, je tisto, s čimer upravljaš v logiki svoje aplikacije. Izpostavlja atribute z njihovimi tipi, podpira iteracijo, pretvorbo v slovar z model_dump() in serializacijo z model_dump_json().
book = response.choices[0].message.parsed
# Tipiziran dostop s samodejnim dopolnjevanjem v IDE-ju
print(book.title) # str
print(book.authors) # list[str]
print(book.year) # Optional[int]
# Iteracija po seznamih
for author in book.authors:
print(f" - {author}")
# Pretvorba v slovar
book_dict = book.model_dump()
# Serializacija v JSON
book_json = book.model_dump_json(indent=2)
Surov JSON je po drugi strani še vedno uporaben na mejah sistema: za beleženje dogodkov, shranjevanje v bazo podatkov ali posredovanje odziva takšnega, kot je, drugemu API-ju.
raw = response.choices[0].message.content
# To je niz JSON, uporaben za:
# - Beleženje dogodkov
# - Shranjevanje v bazo podatkov
# - Pošiljanje drugemu API-ju
import json
data = json.loads(raw)
Kaj lahko še vedno spodleti
Zagotovljena shema ne naredi tvoje kode imune na vse. API lahko vrne napako omrežja ali storitve, .parsed pa je lahko None, če je bil odziv prekinjen. Spodnji vzorec obravnava oba primera ločeno – SDKError za API in ValidationError za shemo – ter ponovi poskus le omejeno število krat.
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):
"""Strukturirana ekstrakcija z obravnavo napak."""
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
# Uporaba
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}")
Refleks, ki smo ga videli pri načinu JSON, velja tudi tukaj: odziv, prekinjen zaradi max_tokens, proizvede nepopoln ali ničelni objekt, finish_reason pa ti to sporoči, preden to odkriješ kasneje v cevovodu.
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" = okrnjen odziv, povečaj max_tokens
Ključne ugotovitve
client.chat.parse()nadomeščaclient.chat.complete()za prilagojene strukturirane izhode.parsedvrne tipiziran objekt Pydantic;.contentvrne surov JSON- Shema se samodejno doda sistemskemu pozivu – oblike ni treba opisovati
- Vedno preveri
finish_reasonin obravnavaj napakiSDKErrorterValidationError - Uporabi
model_dump()za pretvorbo razčlenjenega objekta v slovar Python