Define esquemas con Pydantic
En esta página
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:
| Tipo | Significado |
|---|---|
str | cadena de texto |
int | entero |
float | número decimal |
bool | booleano (verdadero/falso) |
list[T] | lista de elementos de tipo T |
Optional[T] | campo que puede ser null |
Enum | valor 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
BaseModelde 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