Przejdź do głównej treści
Polski— Wybierz język
Menu

Korzystanie z client.chat.parse()

Lekcja 8 z 12 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Metoda parse(): Serce niestandardowych wyjść strukturalizowanych
  2. Kompletne wywołanie end-to-end
  3. Automatycznie dodawany monit systemowy
  4. .parsed kontra .content: Dwa różne zastosowania
  5. Co nadal może się nie powieść
  6. Kluczowe wnioski

Metoda parse(): Serce niestandardowych wyjść strukturalizowanych

client.chat.parse() to strukturalny odpowiednik client.chat.complete(). Zamiast zwracać zwykły tekst lub surowy JSON, który musisz samodzielnie przetworzyć, metoda ta zwraca bezpośrednio typowany obiekt zgodny z Twoim modelem Pydantic. Zmiana ta może wydawać się jedynie kosmetyczna, ale w rzeczywistości eliminuje całą warstwę kodu.

Kontrast jest najbardziej widoczny przy porównaniu obu podejść. Przy użyciu complete() otrzymujesz ciąg znaków i musisz go samodzielnie przekształcić. Przy użyciu parse() obiekt nadchodzi gotowy do użycia, a surowy JSON pozostaje dostępny, jeśli go potrzebujesz.

# Tryb JSON — complete() zwraca tekst 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)  # Ręczne parsowanie

# Niestandardowe — parse() zwraca typowany obiekt
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema
)
obj: MonSchema = response.choices[0].message.parsed  # Obiekt Pydantic
raw_json: str = response.choices[0].message.content   # Surowy JSON również dostępny

Różnica polega na dostępie do .parsed: jest to obiekt Pydantic gotowy do bezpośredniego użycia, wyposażony w autouzupełnianie w IDE i walidację typów.

Kompletne wywołanie end-to-end

Poniższy przykład przeprowadza Cię przez pięć kroków rzeczywistej ekstrakcji: zdefiniuj schemat z jasnymi opisami, utwórz klienta, wywołaj parse(), użyj zwróconego obiektu i w razie potrzeby pobierz reprezentację JSON.

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

# 1. Zdefiniuj schemat
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. Utwórz klienta
client = Mistral(api_key="your-api-key")

# 3. Wywołaj 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żyj sparsowanego obiektu
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. Surowy JSON jest również dostępny
raw = response.choices[0].message.content
print(f"\nRaw JSON: {raw}")

Zwróć uwagę, czego nie zawiera monit systemowy: nie ma w nim opisu oczekiwanego formatu.

Automatycznie dodawany monit systemowy

SDK zajmuje się tym za Ciebie. Gdy używasz parse(), Mistral automatycznie dodaje prefiks do monitu systemowego:

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

Prefiks ten zawiera schemat JSON wygenerowany na podstawie Twojego modelu Pydantic. Nie musisz opisywać formatu w swoim prompcie – robi to za Ciebie SDK. Dzięki temu możesz poświęcić wiadomość systemową temu, co robi najlepiej: dostarczeniu kontekstu biznesowego i ustaleniu wymagań dotyczących jakości, takich jak precyzja kwot czy sposób obsługi brakujących danych.

response = client.chat.parse(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            # Nie trzeba opisywać formatu JSON – dzieje się to automatycznie
            # Skup się na KONTEKŚCIE i JAKOŚCI
            "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 kontra .content: Dwa różne zastosowania

Typowany obiekt, dostępny poprzez .parsed, to element, którym manipulujesz w logice swojej aplikacji. Udostępnia atrybuty z ich typami, obsługuje iterację, konwertuje do słownika za pomocą model_dump() i serializuje dane za pomocą model_dump_json().

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

# Dostęp typowany z autouzupełnianiem w IDE
print(book.title)        # str
print(book.authors)      # list[str]
print(book.year)         # Optional[int]

# Iteracja po listach
for author in book.authors:
    print(f"  - {author}")

# Konwersja do słownika
book_dict = book.model_dump()

# Serializacja do JSON
book_json = book.model_dump_json(indent=2)

Z drugiej strony, surowy JSON pozostaje przydatny na granicach systemu: do logowania, przechowywania w bazie danych lub przekazywania odpowiedzi „tak jak jest“ do innego API.

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

# To jest ciąg JSON, przydatny do:
# - Logowania
# - Przechowywania w bazie danych
# - Wysyłania do innego API

import json
data = json.loads(raw)

Co nadal może się nie powieść

Gwarantowany schemat nie czyni Twojego kodu odpornym na wszystko. API może zwrócić błąd sieciowy lub serwisowy, a .parsed może mieć wartość None, jeśli odpowiedź została przerwana. Poniższy wzorzec obsługuje oba przypadki osobno – SDKError dla API, ValidationError dla schematu – i ponawia próbę tylko ograniczoną liczbę razy.

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):
    """Strukturalna ekstrakcja z obsługą błędów."""
    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życie
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}")

Zasada obserwowana w Trybie JSON nadal ma tu zastosowanie: odpowiedź ucięta przez max_tokens generuje obiekt niekompletny lub null, a finish_reason informuje Cię o tym, zanim odkryjesz problem głębiej w potoku przetwarzania.

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" = ucięta odpowiedź, zwiększ max_tokens

Kluczowe wnioski

  • client.chat.parse() zastępuje client.chat.complete() w przypadku niestandardowych wyjść strukturalizowanych
  • .parsed zwraca typowany obiekt Pydantic; .content zwraca surowy JSON
  • Schemat jest automatycznie dodawany do monitu systemowego – nie trzeba opisywać formatu
  • Zawsze sprawdzaj finish_reason i obsługuj błędy SDKError oraz ValidationError
  • Użyj model_dump(), aby przekonwertować sparsowany obiekt do słownika Pythona