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

Define esquemas con Pydantic

Lección 7 de 12 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Pydantic: la base de las salidas estructuradas personalizadas en Python
  2. Define un modelo sencillo
  3. Tipos que utilizarás
  4. Modelos anidados
  5. Guía al modelo con descripciones
  6. La validación es gratuita
  7. Puntos clave

Pydantic: la base de las salidas estructuradas personalizadas en Python

Pydantic es la biblioteca de validación de datos más popular en Python. Te permite definir modelos de datos con tipos estrictos, que es exactamente lo que utiliza la API de Mistral para las salidas estructuradas personalizadas. Si trabajas en Python, Pydantic se convierte en tu herramienta principal para describir esquemas de salida: lo que escribas en una clase es a lo que el modelo estará obligado a ajustarse.

Aquí tienes la buena noticia sobre la instalación: Pydantic se incluye como dependencia del SDK de Mistral. Si ya tienes instalado mistralai, no necesitas hacer nada más.

pip install mistralai
# Pydantic v2 se incluye automáticamente

Una comprobación rápida de la versión evita sorpresas, ya que la sintaxis del validador cambió entre versiones principales:

import pydantic
print(pydantic.__version__)  # Se requiere la versión 2.x

Define un modelo sencillo

Un modelo de Pydantic es una clase que hereda de BaseModel, donde cada atributo es un campo con un tipo explícito.

from pydantic import BaseModel

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

Este modelo le dice a Mistral: «Tu salida debe ser un objeto JSON con exactamente estos 4 campos, todos de tipo cadena (string)». No hacen falta instrucciones adicionales en el prompt para obtener esta estructura.

Tipos que utilizarás

Pydantic admite todos los tipos estándar de Python y Mistral los entiende todos. El siguiente modelo los reúne en un caso realista: el análisis de un ticket de soporte. Muestra cómo se combinan: tipos básicos para campos simples, Optional para un asignado que aún no se ha designado, Enum para una prioridad que solo puede tomar cuatro valores, y listas para etiquetas e IDs relacionados.

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):
    # Tipos básicos
    title: str
    description: str
    ticket_id: int
    confidence: float
    is_urgent: bool

    # Tipos opcionales
    assignee: Optional[str] = None

    # Enums (valores restringidos)
    priority: Priority

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

Aquí tienes la hoja de trucos correspondiente:

TipoSignificado
strcadena de texto
intentero
floatnúmero decimal
boolbooleano (verdadero/falso)
list[T]lista de elementos de tipo T
Optional[T]campo que puede ser null
Enumvalor de un conjunto finito

Los enums merecen una mención especial: son la única forma de garantizar que una prioridad nunca sea "very urgent" o "P1" dependiendo del estado de ánimo del modelo.

Modelos anidados

Los datos del mundo real rara vez son planos. Un contacto pertenece a una empresa, que tiene una dirección. Pydantic te permite anidar modelos tan profundamente como necesites, y Mistral sigue la jerarquía.

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  # Modelo anidado

class Person(BaseModel):
    first_name: str
    last_name: str
    email: str
    role: str
    company: Company  # Anidamiento de dos niveles

El JSON generado reproduce exactamente esta estructura de árbol:

{
  "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"
    }
  }
}

El mismo mecanismo extrae varios elementos a la vez: un modelo envuelve una lista de otro modelo y recuperas un catálogo completo en una única llamada.

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

Guía al modelo con descripciones

El nombre de un campo no lo cuenta todo. score podría significar una nota sobre 10, un porcentaje o un valor entre 0 y 1; el modelo tiene que adivinarlo. Las descripciones eliminan esta ambigüedad: se incluyen en el esquema JSON enviado a Mistral y actúan como instrucciones por campo.

from pydantic import BaseModel, Field

class SentimentAnalysis(BaseModel):
    sentiment: str = Field(
        description="Sentimiento general: 'positive', 'negative' o 'neutral'"
    )
    score: float = Field(
        description="Puntuación de confianza entre 0.0 y 1.0"
    )
    keywords: list[str] = Field(
        description="Las 3-5 palabras clave principales del texto"
    )
    summary: str = Field(
        description="Resumen en una frase como máximo"
    )

Cuanto más precisas sean estas descripciones, mejor será la calidad de la salida. Esta es la parte de mayor impacto de toda la configuración: unas pocas palabras bien elegidas suelen sustituir a un párrafo entero del prompt.

Field también establece valores por defecto. En el siguiente ejemplo, el idioma se establece por defecto en "fr" si el modelo no encuentra la información, el recuento de palabras permanece en None si no se puede determinar, y las etiquetas comienzan como una lista vacía gracias a default_factory.

from pydantic import BaseModel, Field
from typing import Optional

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

Los campos con valores por defecto serán rellenados por el modelo si encuentra la información; de lo contrario, mantendrán el valor por defecto.

La validación es gratuita

Por último, pero no menos importante: la validación es automática. Si un valor no coincide con el tipo declarado, Pydantic lanza inmediatamente un ValidationError que indica exactamente qué campo es el culpable, sin que tengas que escribir ni una sola línea de código de comprobación.

from pydantic import ValidationError

try:
    analysis = SentimentAnalysis(
        sentiment="positive",
        score="not a number",  # Error de tipo
        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, ...]

Todo el código de verificación manual escrito en la lección anterior desaparece aquí, sustituido por la declaración del modelo.

Puntos clave

  • BaseModel de Pydantic es la base de todos los esquemas personalizados en Python
  • Usa tipos explícitos: str, int, float, bool, list[T], Optional[T]
  • Los modelos anidados permiten estructuras JSON complejas
  • Field(description=...) mejora la calidad de la salida guiando al modelo
  • La validación es automática: los errores de tipo se detectan inmediatamente