Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

L-użu ta' client.chat.parse()

Lezzjoni 8 / 12 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Il-Metodu parse(): Il-Qalb tal-Outputs Strutturati Personalizzati
  2. Sejħa Sħiħa Minn Truf għal Truf
  3. Il-Prompt tas-Sistema Miżjud Awtomatikament
  4. .parsed vs .content: Żewġ Użi Distinti
  5. X’Jista’ Għadu Jfalli
  6. Punti Ewlenin

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() jissostitwixxi client.chat.complete() għal Outputs Strutturati Personalizzati
  • .parsed jirritorna oġġett Pydantic ittajpjat; .content jirritorna JSON raw
  • L-iskema tiżdied awtomatikament mal-prompt tas-sistema—l-ebda ħtieġa li tiddeskrivi l-format
  • Dejjem iċċekkja finish_reason u ttratta l-iżbalji SDKError u ValidationError
  • Uża model_dump() biex tikkonverti l-oġġett ippruċessat f’dizzjunarju Python