Kasutamine client.chat.parse()
Sellel lehel
Meetod parse(): Kohandatud struktureeritud väljundite süda
client.chat.parse() on client.chat.complete() struktureeritud vaste. Vaba teksti või toore JSON-i tagastamise asemel, mida pead ise parsima, tagastab see otseselt sinu Pydanticu mudelile vastava tüübitud objekti. Muutus võib tunduda kosmeetiline, kuid tegelikult kõrvaldab see terve koodikihi.
Kontrast on kõige selgem kõrvuti vaadatuna. complete() korral saad stringi ja teisendad seda ise. parse() korral saabub objekt kasutusvalmis ning toor-JSON on vajadusel samuti kättesaadav.
# JSON-režiim — complete() tagastab JSON-teksti
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) # Manuaalne parsimine
# Kohandatud — parse() tagastab tüübitud objekti
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema
)
obj: MonSchema = response.choices[0].message.parsed # Pydanticu objekt
raw_json: str = response.choices[0].message.content # Toor-JSON samuti kättesaadav
Erinevus seisneb .parsed kasutamises: see on otseselt kasutatav Pydanticu objekt, mis pakub IDE-i automaatset täitmist ja tüübikontrolli.
Täielik ots-otsani kõne
Järgnev näide viib sind läbi reaalse ekstraheerimise viie sammu: skeemi määratlemine selgete kirjeldustega, kliendi loomine, parse() kutsumine, tagastatud objekti kasutamine ja vajadusel JSON-esituse hankimine.
from mistralai.client import Mistral
from pydantic import BaseModel, Field
from typing import Optional
# 1. Määratle skeem
class BookInfo(BaseModel):
title: str = Field(description="Raamatu pealkiri")
authors: list[str] = Field(description="Autorite loend")
year: Optional[int] = Field(default=None, description="Ilmumisaasta")
genre: str = Field(description="Peamine kirjandusžanr")
summary: str = Field(description="Kokkuvõte 2-3 lauses")
# 2. Loo klient
client = Mistral(api_key="your-api-key")
# 3. Kutsu parse()
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "Oled kogenud raamatukoguhoidja. Ekstraheeri mainitud raamatu kohta käiv info."
},
{
"role": "user",
"content": "Mulje avaldas '1984' George Orwellilt. See on 1949. aastal ilmunud düstoopiline romaan, mis kirjeldab totalitaarset ühiskonda pideva järelevalve all."
}
],
temperature=0
)
# 4. Kasuta parsetud objekti
book = response.choices[0].message.parsed
print(f"Pealkiri: {book.title}")
print(f"Autorid: {', '.join(book.authors)}")
print(f"Aasta: {book.year}")
print(f"Žanr: {book.genre}")
print(f"Kokkuvõte: {book.summary}")
# 5. Toor-JSON on samuti kättesaadav
raw = response.choices[0].message.content
print(f"\nToor-JSON: {raw}")
Pane tähele, mida süsteemiviip ei sisalda: oodatava vormingu kirjeldust seal pole.
Automaatselt lisatav süsteemiviip
SDK haldab seda ise. Kui kasutad parse(), lisab Mistral süsteemiviibile automaatselt eesliite:
Your output should be an instance of a JSON object following this schema: { ... }
See eesliide sisaldab sinu Pydanticu mudelist genereeritud JSON-skeemi. Sa ei pea vormingut oma viibas kirjeldama – SDK teeb selle sinu eest. See vabastab sinu süsteemisõnumi selleks, mida see oskab kõige paremini: ärikonteksti pakkumiseks ja kvaliteedinõuete seadmiseks, nagu summade täpsus või puuduvate andmete käsitlemine.
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
# JSON-vormingut pole vaja kirjeldada – see on automaatne
# Fookus on KONTEKSTIL ja KVALITEEDIL
"content": """Oled kogenud finantsanalüütik.
Ole summade ja protsentidega täpne.
Kui andmed tekstist puuduvad, kasuta null."""
},
{"role": "user", "content": report_text}
],
response_format=FinancialReport
)
.parsed vs .content: Kaks erinevat kasutusviisi
Tüübitud objekt, millele pääsed ligi .parsed kaudu, on see, mida manipuleerid oma rakenduse loogikas. See paljastab atribuudid koos nende tüüpidega, toetab iteratsiooni, teisendab sõnastikuks model_dump() abil ja serialiseerib model_dump_json() abil.
book = response.choices[0].message.parsed
# Tüübitud juurdepääs IDE-i automaatse täitmisega
print(book.title) # str
print(book.authors) # list[str]
print(book.year) # Optional[int]
# Itereeri üle loendite
for author in book.authors:
print(f" - {author}")
# Teisenda sõnastikuks
book_dict = book.model_dump()
# Serialiseeri JSON-iks
book_json = book.model_dump_json(indent=2)
Toor-JSON on seevastu kasulik süsteemipiiridel: logimiseks, andmebaasi salvestamiseks või vastuse muutmata kujul teisele API-le edastamiseks.
raw = response.choices[0].message.content
# See on JSON-string, kasulik järgnevaks:
# - Logimine
# - Andmebaasi salvestamine
# - Edastamine teisele API-le
import json
data = json.loads(raw)
Mis võib ikkagi nurjuda
Garanteeritud skeem ei tee sinu koodi kõige vastu immuunseks. API võib tagastada võrgu- või teenusevea ning .parsed võib olla None, kui vastus katkes. Allpool olev muster käsitleb mõlemat juhtumit eraldi – SDKError API jaoks ja ValidationError skeemi jaoks – ning proovib uuesti ainult piiratud arv kordi.
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):
"""Struktureeritud ekstraheerimine veakäitlusega."""
for attempt in range(max_retries + 1):
try:
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Ekstraheeri nõutud info."},
{"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 on None – vastus võib olla katkenud")
return parsed
except SDKError as e:
print(f"API viga (katse {attempt + 1}): {e}")
if attempt == max_retries:
raise
except ValidationError as e:
print(f"Valideerimisviga (katse {attempt + 1}): {e}")
if attempt == max_retries:
raise
# Kasutamine
try:
book = extract_structured("'Väike prints' Saint-Exupérylt, 1943", BookInfo)
print(f"Ekstraheeritud: {book.title} autorilt {', '.join(book.authors)}")
except Exception as e:
print(f"Lõplik ebaõnnestumine: {e}")
JSON-režiimi puhul nähtud refleks kehtib ka siin: max_tokens poolt katkestatud vastus tekitab mittetäieliku või null-objekti ning finish_reason annab sellest märku enne, kui sa seda torustikus kaugemal avastad.
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"Hoiatus: finish_reason = {response.choices[0].finish_reason}")
# "length" = katkestatud vastus, suurenda max_tokens
Peamised punktid
client.chat.parse()asendabclient.chat.complete()kohandatud struktureeritud väljundite puhul.parsedtagastab tüübitud Pydanticu objekti;.contenttagastab toore JSON-i- Skeem lisatakse süsteemiviibile automaatselt – vormingut pole vaja kirjeldada
- Kontrolli alati
finish_reasonja käsitle viguSDKErrorningValidationError - Kasuta
model_dump(), et teisendada parsetud objekt Pythoni sõnastikuks