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

Pydantic BaseModel в детайли

Урок 6 от 12 Обновен 30 юли 2026 г. Програмист
На тази страница
  1. Pydantic: Идеалният партньор
  2. Основи на Pydantic за структурирани изходи
  3. Поддържани Python типове
  4. Вложени модели
  5. Изброени стойности (Enums) с Pydantic
  6. Използване на parse()
  7. Използване на response_format
  8. Стойности по подразбиране и документация
  9. Ключови изводи

Pydantic: Идеалният партньор

Pydantic е стандартната библиотека на Python за валидиране на данни. В комбинация със структурираните изходи на Grok, тя се превръща в основен инструмент: Вие дефинирате своите схеми като Python класове, а моделът автоматично попълва тези класове.

Основи на Pydantic за структурирани изходи

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

from pydantic import BaseModel

class Produit(BaseModel):
    nom: str
    prix: float
    en_stock: bool
    categorie: str

Този модел автоматично генерира еквивалентната JSON схема. Не е необходимо да пишете нищо допълнително.

Поддържани Python типове

Ето съответствието между Python типовете и типовете в JSON Schema:

class ExempleComplet(BaseModel):
    # Скаларни типове
    texte: str                    # → "type": "string"
    nombre: float                 # → "type": "number"
    entier: int                   # → "type": "number"
    actif: bool                   # → "type": "boolean"

    # Опционални полета
    note: str | None              # → anyOf string/null

    # Колекции
    tags: list[str]               # → array of strings
    scores: list[float]           # → array of numbers

    # Изброени стойности
    niveau: str                   # + enum в Field

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

Истинската сила на Pydantic се крие във влагането на модели:

class Adresse(BaseModel):
    rue: str
    ville: str
    code_postal: str
    pays: str

class Competence(BaseModel):
    nom: str
    niveau: str  # "debutant", "intermediaire", "expert"
    annees: int

class Candidat(BaseModel):
    prenom: str
    nom: str
    email: str
    adresse: Adresse
    competences: list[Competence]
    disponible: bool
    pretention_salariale: float | None

Когато предадете Candidat като response_format, моделът ще попълни цялата йерархия: пълния адрес, всяко умение с неговите детайли и така нататък.

Изброени стойности (Enums) с Pydantic

За да наложите предварително дефинирани стойности, използвайте Literal от Python:

from typing import Literal

class Ticket(BaseModel):
    titre: str
    description: str
    priorite: Literal["basse", "moyenne", "haute", "critique"]
    statut: Literal["ouvert", "en_cours", "resolu", "ferme"]
    type: Literal["bug", "feature", "documentation"]

Моделът може да върне само изброените стойности. Всяка друга стойност е невъзможна.

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

response, ticket = client.chat.parse(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "The login button does not work on mobile"
    }],
    response_format=Ticket
)

print(ticket.priorite)  # "haute"
print(ticket.type)       # "bug"
print(ticket.statut)     # "ouvert"

Използване на response_format

response = client.chat.create(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "The login button does not work on mobile"
    }],
    response_format=Ticket
)

ticket = Ticket.model_validate_json(
    response.choices[0].message.content
)

Стойности по подразбиране и документация

Можете да добавите описания към вашите полета чрез Field. Тези описания помагат на модела да разбере по-добре какво очаквате:

from pydantic import BaseModel, Field

class AnalyseSentiment(BaseModel):
    texte_original: str = Field(
        description="The text analyzed as is"
    )
    sentiment: Literal["positif", "negatif", "neutre"] = Field(
        description="The dominant sentiment of the text"
    )
    score_confiance: float = Field(
        description="Confidence score between 0.0 and 1.0"
    )
    mots_cles: list[str] = Field(
        description="The 3 to 5 most significant keywords"
    )

Описанията в Field се включват в JSON схемата, изпратена до модела. Те подобряват качеството на отговорите.

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

  • Pydantic автоматично конвертира Вашите Python класове в JSON схеми
  • Влажането на модели позволява структуриране на сложни данни
  • Literal замества enum, за да наложи предварително дефинирани стойности
  • str | None прави полето опционално (може да бъде null)
  • Field(description=...) подобрява качеството на отговорите на модела
  • Работи с parse() (автоматично) и response_format (ръчно)