L-użu ta' client.chat.parse()
F'din il-paġna
Il-Metodu parse(): Il-Qalb tal-Outputs Strutturati Personalizzati
client.chat.parse() huwa l-ekwivalenti strutturat ta’ client.chat.complete(). Minflok ma jirritorna test liberu jew JSON raw li trid tipproċessa int stess, jirritorna oġġett ittajpjat li jaqbel direttament mal-mudell Pydantic tiegħek. Il-bidla tista’ tidher kosmetika, iżda fil-fatt telimina saff sħiħ ta’ kodiċi.
Il-kuntrast huwa l-aktar ċar meta tqabbluhom ħdejn xulxin. Ma’ complete(), tirċievi stringa u tittrasformaha int. Ma’ parse(), l-oġġett jasla lest biex tużah, u l-JSON raw jibqa’ disponibbli jekk ikollok bżonnu.
# Modalità JSON — complete() jirritorna test 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) # Parsing manwali
# Personalizzat — parse() jirritorna oġġett ittajpjat
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema
)
obj: MonSchema = response.choices[0].message.parsed # Oġġett Pydantic
raw_json: str = response.choices[0].message.content # JSON raw disponibbli wkoll
Id-differenza tinsab fl-aċċess għal .parsed: oġġett Pydantic direttament użabbli b’awtokompletament tal-IDE u validazzjoni tat-tip.
Sejħa Sħiħa Minn Truf għal Truf
L-eżempju li ġej jgħaddik mill-ħames passi ta’ estrazzjoni reali: iddefinixxi l-iskema b’deskrizzjonijiet ċari, oħloq il-klijent, sejjaħ parse(), uża l-oġġett ritornat, u rkupra r-rappreżentazzjoni JSON jekk ikun meħtieġ.
from mistralai.client import Mistral
from pydantic import BaseModel, Field
from typing import Optional
# 1. Iddefinixxi l-iskema
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. Oħloq il-klijent
client = Mistral(api_key="your-api-key")
# 3. Sejjaħ 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. Uża l-oġġett ippruċessat (parsed)
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. Il-JSON raw huwa disponibbli wkoll
raw = response.choices[0].message.content
print(f"\nRaw JSON: {raw}")
Innota x’ma fihx il-prompt tas-sistema: l-ebda deskrizzjoni tal-format mistenni.
Il-Prompt tas-Sistema Miżjud Awtomatikament
L-SDK jittratta dan. Meta tuża parse(), Mistral awtomatikament iżid prefiss mal-prompt tas-sistema:
Your output should be an instance of a JSON object following this schema: { ... }
Dan il-prefiss fih l-iskema JSON iġġenerata mill-mudell Pydantic tiegħek. M’għandekx bżonn tiddeskrivi l-format fil-prompt tiegħek—l-SDK jagħmlu għalik. Dan iħalli l-messaġġ tas-sistema tiegħek jagħmel dak li jagħmel l-aħjar: jipprovdi kuntest tan-negozju u jistabbilixxi rekwiżiti ta’ kwalità, bħall-preċiżjoni għall-ammonti jew kif tiġi ttrattata data nieqsa.
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
# L-ebda ħtieġa li tiddeskrivi l-format JSON—huwa awtomatiku
# Iffoka fuq il-KUNTEST u l-KWALITÀ
"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: Żewġ Użi Distinti
L-oġġett ittajpjat, aċċessibbli permezz ta’ .parsed, huwa dak li timmanipula fil-loġika tal-applikazzjoni tiegħek. Jesponi attributi bit-tipi tagħhom, jappoġġja l-iterazzjoni, jikkonverti f’dizzjunarju b’model_dump(), u jissirjalizza b’model_dump_json().
book = response.choices[0].message.parsed
# Aċċess ittajpjat b'awtokompletament tal-IDE
print(book.title) # str
print(book.authors) # list[str]
print(book.year) # Optional[int]
# Itera fuq il-listi
for author in book.authors:
print(f" - {author}")
# Ikkonverti f'dizzjunarju
book_dict = book.model_dump()
# Issirjalizza f'JSON
book_json = book.model_dump_json(indent=2)
Il-JSON raw, min-naħa l-oħra, jibqa’ utli fil-fruntieri tas-sistema: għal-loġġjar (logging), ħażna fid-database, jew biex tgħaddi r-rispons kif inhu lil API oħra.
raw = response.choices[0].message.content
# Din hija stringa JSON, utli għal:
# - Loġġjar
# - Ħażna fid-database
# - Tibgħat lil API oħra
import json
data = json.loads(raw)
X’Jista’ Għadu Jfalli
Skema garantita ma tagħmilx il-kodiċi tiegħek immunu kontra kollox. L-API tista’ tirritorna żball fin-network jew fis-servizz, u .parsed tista’ tkun None jekk ir-rispons ġie interrott. Il-mudell hawn taħt jittratta ż-żewġ każijiet separatament—SDKError għall-API, ValidationError għall-iskema—u jipprova mill-ġdid biss numru limitat ta’ drabi.
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):
"""Estrazzjoni strutturata b'ġestjoni tal-iżbalji."""
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
# Użu
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}")
Ir-rifless visted mal-Modalità JSON japplika hawn ukoll: rispons maqtugħ minn max_tokens jipproduċi oġġett mhux sħiħ jew null, u finish_reason jgħidlek dan qabel ma tiskoprih aktar ‘l isfel fil-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" = rispons maqtugħ, żid max_tokens
Punti Ewlenin
client.chat.parse()jissostitwixxiclient.chat.complete()għal Outputs Strutturati Personalizzati.parsedjirritorna oġġett Pydantic ittajpjat;.contentjirritorna JSON raw- L-iskema tiżdied awtomatikament mal-prompt tas-sistema—l-ebda ħtieġa li tiddeskrivi l-format
- Dejjem iċċekkja
finish_reasonu ttratta l-iżbaljiSDKErroruValidationError - Uża
model_dump()biex tikkonverti l-oġġett ippruċessat f’dizzjunarju Python