Pydantic BaseModel в детайли
На тази страница
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(ръчно)