Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Käytetään client.chat.parse()-metodia

Oppitunti 8 / 12 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. parse()-metodi: Mukautettujen jäsenneltyjen tulosteiden ydin
  2. Täydellinen end-to-end-kutsu
  3. Automaattisesti lisättävä järjestelmäkehote
  4. .parsed vs .content: Kaksi erillistä käyttötarkoitusta
  5. Mikä voi silti epäonnistua
  6. Keskeiset asiat

parse()-metodi: Mukautettujen jäsenneltyjen tulosteiden ydin

client.chat.parse() on jäsennelty vastine metodille client.chat.complete(). Vapaan tekstin tai raakaa JSONia palauttamisen sijaan, jota sinun täytyisi itse jäsentää, se palauttaa suoraan Pydantic-mallisi mukaisen tyypitetyn objektin. Muutos saattaa vaikuttaa kosmeettiselta, mutta se poistaa kokonaisen koodikerroksen.

Ero näkyy selkeimmin rinnakkain. complete()-metodilla haet merkkijonon ja muunnat sen itse. parse()-metodilla objekti saapuu käyttövalmiina, ja raaka JSON on edelleen saatavilla, jos tarvitset sitä.

# JSON-tila — complete() palauttaa JSON-tekstin
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)  # Manuaalinen jäsennys

# Mukautettu — parse() palauttaa tyypitetyn objektin
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema
)
obj: MonSchema = response.choices[0].message.parsed  # Pydantic-objekti
raw_json: str = response.choices[0].message.content   # Raaka JSON myös saatavilla

Ero piilee .parsed-attribuutin käytössä: se on suoraan käytettävä Pydantic-objekti, jossa on IDE:n automaattinen täydennys ja tyyppivalidointi.

Täydellinen end-to-end-kutsu

Seuraava esimerkki käy läpi todellisen tiedonpoiston viisi vaihetta: määritä skeema selkeillä kuvauksilla, luo asiakasohjelma, kutsu parse(), käytä palautettua objektia ja hae JSON-esitys tarvittaessa.

from mistralai.client import Mistral
from pydantic import BaseModel, Field
from typing import Optional

# 1. Määritä skeema
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. Luo asiakasohjelma
client = Mistral(api_key="your-api-key")

# 3. Kutsu 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. Käytä jäsennettyä objektia
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. Raaka JSON on myös saatavilla
raw = response.choices[0].message.content
print(f"\nRaw JSON: {raw}")

Huomaa, mitä järjestelmäkehotteessa ei ole: ei odotetun muodon kuvausta.

Automaattisesti lisättävä järjestelmäkehote

SDK hoitaa tämän. Kun käytät parse()-metodia, Mistral lisää automaattisesti etuliitteen järjestelmäkehotteeseen:

Your output should be an instance of a JSON object following this schema: { ... }

Tämä etuliite sisältää Pydantic-mallistasi generoidun JSON-skeeman. Sinun ei tarvitse kuvata muotoa kehotteessasi – SDK tekee sen puolestasi. Tämä vapauttaa järjestelmäviestisi hoitamaan sen, missä se on paras: tarjoamaan liiketoimintakontekstin ja asettamaan laatuvaatimukset, kuten summien tarkkuuden tai puuttuvien tietojen käsittelyn.

response = client.chat.parse(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            # JSON-muotoa ei tarvitse kuvata – se on automaattista
            # Keskity KONTEKSTIIN ja LAATUUN
            "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: Kaksi erillistä käyttötarkoitusta

Tyypitetty objekti, joka on käytettävissä .parsed-attribuutin kautta, on se, jota manipuloit sovelluslogiikassasi. Se paljastaa attribuutit tyyppeineen, tukee iterointia, muuntaa sanakirjaksi model_dump()-metodilla ja sarjoittaa model_dump_json()-metodilla.

book = response.choices[0].message.parsed

# Tyypitetty käyttö IDE:n automaattisella täydennyksellä
print(book.title)        # str
print(book.authors)      # list[str]
print(book.year)         # Optional[int]

# Iteroi listoja
for author in book.authors:
    print(f"  - {author}")

# Muunna sanakirjaksi
book_dict = book.model_dump()

# Sarjoita JSONiksi
book_json = book.model_dump_json(indent=2)

Raaka JSON on sitä vastoin hyödyllinen järjestelmärajoilla: lokitukseen, tietokantatallennukseen tai vastauksen sellaisenaan välittämiseen toiselle rajapinnalle.

raw = response.choices[0].message.content

# Tämä on JSON-merkkijono, hyödyllinen seuraaviin:
# - Lokitus
# - Tietokantatallennus
# - Lähettäminen toiselle rajapinnalle

import json
data = json.loads(raw)

Mikä voi silti epäonnistua

Taattu skeema ei tee koodistasi immuunia kaikelle. Rajapinta voi palauttaa verkko- tai palveluvirheen, ja .parsed voi olla None, jos vastaus keskeytyi. Alla oleva malli käsittelee molemmat tapaukset erikseen – SDKError rajapinnalle ja ValidationError skeemalle – ja yrittää uudelleen vain rajoitetun määrän kertoja.

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):
    """Jäsennelty tiedonpoisto virheenkäsittelyllä."""
    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

# Käyttö
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}")

JSON-tilan kanssa havaittu refleksi pätee myös täällä: max_tokens-rajan katkaisema vastaus tuottaa epätäydellisen tai null-objektin, ja finish_reason kertoo tästä ennen kuin huomaat sen myöhemmin putkistossa.

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" = katkaistu vastaus, kasvata max_tokens-arvoa

Keskeiset asiat

  • client.chat.parse() korvaa client.chat.complete()-metodin mukautetuissa jäsennellyissä tulosteissa
  • .parsed palauttaa tyypitetyn Pydantic-objektin; .content palauttaa raan JSONin
  • Skeema lisätään automaattisesti järjestelmäkehotteeseen – muotoa ei tarvitse kuvata
  • Tarkista aina finish_reason ja käsittele SDKError- ja ValidationError-virheet
  • Käytä model_dump()-metodia muuntaaksesi jäsennetyn objektin Python-sanakirjaksi