Korzystanie z client.chat.parse()
Na tej stronie
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ępujeclient.chat.complete()w przypadku niestandardowych wyjść strukturalizowanych.parsedzwraca typowany obiekt Pydantic;.contentzwraca surowy JSON- Schemat jest automatycznie dodawany do monitu systemowego – nie trzeba opisywać formatu
- Zawsze sprawdzaj
finish_reasoni obsługuj błędySDKErrororazValidationError - Użyj
model_dump(), aby przekonwertować sparsowany obiekt do słownika Pythona