Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Kasutamine client.chat.parse()

Õppetund 8 / 12 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Meetod parse(): Kohandatud struktureeritud väljundite süda
  2. Täielik ots-otsani kõne
  3. Automaatselt lisatav süsteemiviip
  4. .parsed vs .content: Kaks erinevat kasutusviisi
  5. Mis võib ikkagi nurjuda
  6. Peamised punktid

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() asendab client.chat.complete() kohandatud struktureeritud väljundite puhul
  • .parsed tagastab tüübitud Pydanticu objekti; .content tagastab toore JSON-i
  • Skeem lisatakse süsteemiviibile automaatselt – vormingut pole vaja kirjeldada
  • Kontrolli alati finish_reason ja käsitle vigu SDKError ning ValidationError
  • Kasuta model_dump(), et teisendada parsetud objekt Pythoni sõnastikuks