Премини към основното съдържание
Български— Изберете език
Меню

Използване на client.chat.parse()

Урок 8 от 12 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Методът parse(): Сърцето на персонализираните структурирани изходи
  2. Пълен край-до-край вызов
  3. Автоматично добавеният системен промпт
  4. .parsed срещу .content: Две различни употреби
  5. Какво все още може да се провали
  6. Ключови изводи

Методът parse(): Сърцето на персонализираните структурирани изходи

client.chat.parse() е структурираният еквивалент на client.chat.complete(). Вместо да връща свободен текст или суров JSON, който трябва да анализирате сами, той връща типизиран обект, съответстващ директно на Вашия Pydantic модел. Промяната може да изглежда козметична, но всъщност елиминира цяло ниво код.

Контрастът е най-ясен при сравнение рамо до рамо. С complete() получавате низ и го трансформирате ръчно. С parse() обектът пристига готов за употреба, а суровият JSON остава наличен, ако Ви е необходим.

# JSON Mode — complete() връща 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)  # Ръчно анализиране

# Custom — parse() връща типизиран обект
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema
)
obj: MonSchema = response.choices[0].message.parsed  # Pydantic обект
raw_json: str = response.choices[0].message.content   # Суровият JSON също е наличен

Разликата се крие в достъпа до .parsed: директно използваем Pydantic обект с автоматично довършване в IDE и валидиране на типовете.

Пълен край-до-край вызов

Следващият пример преминава през петте стъпки на реално извличане: дефиниране на схемата с ясни описания, създаване на клиента, извикване на parse(), използване на върнатия обект и извличане на JSON представянето, ако е необходимо.

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

# 1. Дефиниране на схемата
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. Създаване на клиента
client = Mistral(api_key="your-api-key")

# 3. Извикване на 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. Използване на анализирания обект
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. Суровият JSON също е наличен
raw = response.choices[0].message.content
print(f"\nRaw JSON: {raw}")

Забележете какво липсва в системния промпт: няма описание на очаквания формат.

Автоматично добавеният системен промпт

SDK се грижи за това. Когато използвате parse(), Mistral автоматично добавя префикс към системния промпт:

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

Този префикс съдържа JSON схемата, генерирана от Вашия Pydantic модел. Не е необходимо да описвате формата във Вашия промпт – SDK го прави вместо Вас. Това освобождава Вашето системно съобщение, за да прави онова, за което е най-добро: да предоставя бизнес контекст и да задава изисквания за качество, като например точност за суми или начин на обработка на липсващи данни.

response = client.chat.parse(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            # Няма нужда да описвате JSON формата – това е автоматично
            # Фокусирайте се върху КОНТЕКСТА и КАЧЕСТВОТО
            "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 срещу .content: Две различни употреби

Типизираният обект, достъпен чрез .parsed, е това, с което манипулирате във Вашата приложна логика. Той излага атрибути с техните типове, поддържа итерация, конвертира се в речник с model_dump() и се сериализира с model_dump_json().

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

# Типизиран достъп с автоматично довършване в IDE
print(book.title)        # str
print(book.authors)      # list[str]
print(book.year)         # Optional[int]

# Итерация над списъци
for author in book.authors:
    print(f"  - {author}")

# Конвертиране в речник
book_dict = book.model_dump()

# Сериализиране в JSON
book_json = book.model_dump_json(indent=2)

Суровият JSON, от друга страна, остава полезен на границите на системата: за логиране, съхранение в база данни или предаване на отговора както е на друго API.

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

# Това е JSON низ, полезен за:
# - Логиране
# - Съхранение в база данни
# - Изпращане към друго API

import json
data = json.loads(raw)

Какво все още може да се провали

Гарантираната схема не прави кода Ви имунизиран срещу всичко. API може да върне мрежова или сервисна грешка, а .parsed може да бъде None, ако отговорът е бил прекъснат. Долният шаблон обработва двата случая поотделно – SDKError за API и ValidationError за схемата – и опитва отново само ограничен брой пъти.

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):
    """Структурирано извличане с обработка на грешки."""
    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

# Употреба
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 Mode, важи и тук: отговор, прекъснат от max_tokens, произвежда непълен или null обект, а finish_reason Ви информира за това, преди да го откриете по-надолу в пайплайна.

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" = съкратен отговор, увеличете max_tokens

Ключови изводи

  • client.chat.parse() замества client.chat.complete() за персонализирани структурирани изходи
  • .parsed връща типизиран Pydantic обект; .content връща суров JSON
  • Схемата се добавя автоматично към системния промпт – няма нужда да описвате формата
  • Винаги проверявайте finish_reason и обработвайте грешките SDKError и ValidationError
  • Използвайте model_dump(), за да конвертирате анализирания обект в Python речник