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

Дефиниране на схеми с Pydantic

Урок 7 от 12 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. Pydantic: Основата на персонализираните структурирани изходи в Python
  2. Дефиниране на прост модел
  3. Типове, които ще използвате
  4. Вложени модели
  5. Насочване на модела с описания
  6. Валидирането идва безплатно
  7. Ключови изводи

Pydantic: Основата на персонализираните структурирани изходи в Python

Pydantic е най-популярната библиотека за валидиране на данни в Python. Тя Ви позволява да дефинирате модели на данни със строги типове, което е точно това, което API на Mistral използва за персонализирани структурирани изходи (Custom Structured Outputs). Ако работите с Python, Pydantic се превръща във Вашия основен инструмент за описване на изходни схеми: това, което напишете в класа, е точно това, към което моделът ще бъде ограничен да произведе.

Ето и добрата новина относно инсталацията: Pydantic е включен като зависимост на Mistral SDK. Ако вече имате инсталиран mistralai, не е необходимо да правите нищо допълнително.

pip install mistralai
# Pydantic v2 is included automatically

Бърза проверка на версията избягва изненади, тъй като синтаксисът на валидаторите се промени между основните версии:

import pydantic
print(pydantic.__version__)  # 2.x required

Дефиниране на прост модел

Моделът на Pydantic е клас, който наследява BaseModel, като всеки атрибут е поле с изричен тип.

from pydantic import BaseModel

class Contact(BaseModel):
    name: str
    email: str
    phone: str
    company: str

Този модел казва на Mistral: „Вашият изход трябва да бъде JSON обект с точно тези 4 полета, всички от тип низ (string).“ Не са необходими допълнителни инструкции в подкана (prompt), за да се получи тази структура.

Типове, които ще използвате

Pydantic поддържа всички стандартни типове на Python и Mistral ги разбира всички. Следващият модел ги събира в реалистичен случай – анализиране на билет за поддръжка – и показва как се комбинират: основни типове за прости полета, Optional за изпълнител, който все още не е определен, Enum за приоритет, който може да приеме само четири стойности, и списъци за тагове и свързани ID-та.

from pydantic import BaseModel
from typing import Optional
from enum import Enum

class Priority(str, Enum):
    low = "low"
    medium = "medium"
    high = "high"
    critical = "critical"

class TicketAnalysis(BaseModel):
    # Basic types
    title: str
    description: str
    ticket_id: int
    confidence: float
    is_urgent: bool

    # Optional types
    assignee: Optional[str] = None

    # Enums (constrained values)
    priority: Priority

    # Lists
    tags: list[str]
    related_ids: list[int]

Ето съответната шпаргалка:

ТипЗначение
strтекстов низ
intцяло число
floatдесетично число
boolбулев тип (вярно/грешно)
list[T]списък от елементи от тип T
Optional[T]поле, което може да е null
Enumстойност от краен набор

Изброените типове (Enums) заслужават специално споменаване: те са единственият начин да гарантирате, че приоритетът никога няма да бъде "very urgent" или "P1" в зависимост от настроението на модела.

Вложени модели

Данните в реалния свят рядко са плоски. Един контакт принадлежи към компания, която има адрес. Pydantic Ви позволява да влагате модели толкова дълбоко, колкото е необходимо, а Mistral следва йерархията.

from pydantic import BaseModel
from typing import Optional

class Address(BaseModel):
    street: str
    city: str
    postal_code: str
    country: str

class Company(BaseModel):
    name: str
    industry: str
    address: Address  # Nested model

class Person(BaseModel):
    first_name: str
    last_name: str
    email: str
    role: str
    company: Company  # Two-level nesting

Генерираният JSON възпроизвежда точно тази дървовидна структура:

{
  "first_name": "Marie",
  "last_name": "Dupont",
  "email": "[email protected]",
  "role": "Sales Director",
  "company": {
    "name": "TechVision SAS",
    "industry": "Technology",
    "address": {
      "street": "42 rue de la Paix",
      "city": "Paris",
      "postal_code": "75002",
      "country": "France"
    }
  }
}

Същият механизъм извлича множество елементи наведнъж: модел обгръща списък от друг модел и Вие получавате пълен каталог с едно единствено извикване.

from pydantic import BaseModel

class Product(BaseModel):
    name: str
    price: float
    category: str
    in_stock: bool

class Catalog(BaseModel):
    products: list[Product]
    total_count: int

Насочване на модела с описания

Името на полето не разказва цялата история. score може да означава оценка до 10, процент или стойност между 0 и 1 – моделът трябва да познае. Описанията премахват тази двусмислица: те се включват в JSON схемата, изпратена до Mistral, и действат като инструкции за всяко поле поотделно.

from pydantic import BaseModel, Field

class SentimentAnalysis(BaseModel):
    sentiment: str = Field(
        description="Overall sentiment: 'positive', 'negative', or 'neutral'"
    )
    score: float = Field(
        description="Confidence score between 0.0 and 1.0"
    )
    keywords: list[str] = Field(
        description="The 3-5 main keywords from the text"
    )
    summary: str = Field(
        description="Summary in one sentence maximum"
    )

Колкото по-точни са тези описания, толкова по-високо е качеството на изхода. Това е частта с най-голям ефект от цялата настройка: няколко добре подбрани думи често заместват цял абзац от подканата.

Field също така задава стойности по подразбиране. В следващия пример езикът по подразбиране е "fr", ако моделът не открие информацията, броят на думите остава None, ако не може да бъде определен, а таговете започват като празен списък благодарение на default_factory.

from pydantic import BaseModel, Field
from typing import Optional

class ArticleMetadata(BaseModel):
    title: str
    author: str
    language: str = Field(default="fr", description="ISO 639-1 language code")
    word_count: Optional[int] = None
    tags: list[str] = Field(default_factory=list)

Полетата със стойности по подразбиране ще бъдат попълнени от модела, ако той открие информацията, или ще запазят стойността по подразбиране в противен случай.

Валидирането идва безплатно

И накрая, но не на последно място: валидирането е автоматично. Ако стойност не съвпада с декларирания тип, Pydantic незабавно генерира ValidationError, посочвайки точно кое поле е проблемното, без Вие да пишете нито ред код за проверка.

from pydantic import ValidationError

try:
    analysis = SentimentAnalysis(
        sentiment="positive",
        score="not a number",  # Type error
        keywords=["test"],
        summary="Summary"
    )
except ValidationError as e:
    print(e)
    # 1 validation error for SentimentAnalysis
    # score
    #   Input should be a valid number [type=float_parsing, ...]

Целият ръчен код за проверка, написан в предишния урок, изчезва тук, заменен от декларацията на модела.

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

  • Pydantic BaseModel е основата на всички персонализирани схеми в Python
  • Използвайте изрични типове: str, int, float, bool, list[T], Optional[T]
  • Вложените модели позволяват сложни JSON структури
  • Field(description=...) подобрява качеството на изхода, като насочва модела
  • Валидирането е автоматично – грешките в типовете се откриват незабавно