Ir al contenido principal
Español— Elegir un idioma
Menú

Pydantic BaseModel en profundidad

Lección 6 de 12 Actualizado el 30 de julio de 2026 Desarrollador
En esta página
  1. Pydantic: el compañero ideal
  2. Conceptos básicos de Pydantic para salidas estructuradas
  3. Tipos de Python compatibles
  4. Modelos anidados
  5. Enumeraciones con Pydantic
  6. Uso de parse()
  7. Uso de response_format
  8. Valores por defecto y documentación
  9. Puntos clave

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
  • Literal sustituye a enum para forzar valores predefinidos
  • str | None hace que un campo sea opcional (puede ser null)
  • Field(description=...) mejora la calidad de las respuestas del modelo
  • Funciona con parse() (automático) y response_format (manual)