Pydantic BaseModel en profundidad
En esta página
Pydantic: el compañero ideal
Pydantic es la biblioteca estándar de Python para la validación de datos. Con las salidas estructuradas de Grok, se convierte en una herramienta esencial: defines tus esquemas como clases de Python y el modelo rellena estas clases automáticamente.
Conceptos básicos de Pydantic para salidas estructuradas
Creas un modelo de Pydantic heredando de BaseModel. Cada atributo con una anotación de tipo se convierte en un campo del esquema JSON:
from pydantic import BaseModel
class Produit(BaseModel):
nom: str
prix: float
en_stock: bool
categorie: str
Este modelo genera automáticamente el esquema JSON equivalente. No necesitas escribir nada más.
Tipos de Python compatibles
Aquí tienes la correspondencia entre los tipos de Python y los tipos de JSON Schema:
class ExempleComplet(BaseModel):
# Escalares
texte: str # → "type": "string"
nombre: float # → "type": "number"
entier: int # → "type": "number"
actif: bool # → "type": "boolean"
# Opcionales
note: str | None # → anyOf string/null
# Colecciones
tags: list[str] # → array of strings
scores: list[float] # → array of numbers
# Enumeraciones
niveau: str # + enum in Field
Modelos anidados
La verdadera potencia de Pydantic reside en el anidamiento de modelos:
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
Cuando pasas Candidat como response_format, el modelo rellenará toda la jerarquía: la dirección completa, cada competencia con sus detalles, y así sucesivamente.
Enumeraciones con Pydantic
Para forzar valores predefinidos, utiliza Literal de 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"]
El modelo solo puede devolver los valores listados. Cualquier otro valor es imposible.
Uso de 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"
Uso de 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
)
Valores por defecto y documentación
Puedes añadir descripciones a tus campos con Field. Estas descripciones ayudan al modelo a entender mejor qué esperas:
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"
)
Las descripciones en Field se incluyen en el esquema JSON enviado al modelo. Mejoran la calidad de las respuestas.
Puntos clave
- Pydantic convierte automáticamente tus clases de Python en esquemas JSON
- El anidamiento de modelos te permite estructurar datos complejos
Literalsustituye aenumpara forzar valores predefinidosstr | Nonehace que un campo sea opcional (puede sernull)Field(description=...)mejora la calidad de las respuestas del modelo- Funciona con
parse()(automático) yresponse_format(manual)