Casos de uso avanzados
En esta página
Más allá de los ejemplos sencillos
Ya dominas Pydantic, Zod y client.chat.parse(). Los siguientes tres casos van más allá de los esquemas simples de cuatro campos para abordar escenarios que encontrarás en entornos empresariales: documentos contables, análisis detallado de opiniones de clientes y textos que pertenecen a múltiples categorías simultáneamente. Cada uno ilustra una técnica de modelado diferente.
Extracción de una factura
El procesamiento de documentos es el territorio natural de los esquemas anidados. Una factura no es un objeto plano: contiene un encabezado, un pie con totales y un número variable de líneas de detalle que tienen su propia estructura. Por tanto, modelamos LineItem por separado y luego lo referenciamos dentro de una lista. La moneda utiliza un enumerado, lo que impide que el modelo devuelva "euros" o "€" dependiendo de cómo esté redactado el documento.
from pydantic import BaseModel, Field
from typing import Optional
from enum import Enum
class Currency(str, Enum):
eur = "EUR"
usd = "USD"
gbp = "GBP"
class LineItem(BaseModel):
description: str = Field(description="Descripción de la línea de detalle")
quantity: float = Field(description="Cantidad")
unit_price: float = Field(description="Precio unitario sin impuestos")
vat_rate: float = Field(description="Tipo de IVA en porcentaje (p. ej., 20.0)")
total_ht: float = Field(description="Total de la línea sin impuestos")
class InvoiceData(BaseModel):
invoice_number: str = Field(description="Número de factura")
date: str = Field(description="Fecha de la factura en formato AAAA-MM-DD")
due_date: Optional[str] = Field(default=None, description="Fecha de vencimiento")
vendor_name: str = Field(description="Nombre del proveedor")
vendor_address: Optional[str] = Field(default=None)
client_name: str = Field(description="Nombre del cliente")
line_items: list[LineItem] = Field(description="Líneas de detalle de la factura")
subtotal_ht: float = Field(description="Subtotal sin impuestos")
total_vat: float = Field(description="Importe total del IVA")
total_ttc: float = Field(description="Total con impuestos")
currency: Currency = Field(description="Moneda")
payment_method: Optional[str] = Field(default=None)
# Extracción
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": """Eres un experto contable. Extrae los datos de la factura.
Sé preciso con los importes. Calcula los totales si es necesario.
Las fechas deben estar en formato AAAA-MM-DD."""
},
{"role": "user", "content": invoice_text}
],
response_format=InvoiceData,
temperature=0
)
invoice = response.choices[0].message.parsed
print(f"Factura {invoice.invoice_number} — {invoice.vendor_name}")
print(f"Total con impuestos: {invoice.total_ttc} {invoice.currency.value}")
for item in invoice.line_items:
print(f" - {item.description}: {item.quantity} x {item.unit_price}€ = {item.total_ht}€ sin impuestos")
El formato de fecha impuesto en el mensaje del sistema no es un detalle menor: sin él, un documento francés podría producir 12/03/2026 mientras que uno americano genera 03/12/2026, creando dos cadenas indistinguibles para tu base de datos. La versión en TypeScript sigue la misma arquitectura, documentando el formato mediante .describe().
import { z } from "zod";
const LineItemSchema = z.object({
description: z.string(),
quantity: z.number(),
unitPrice: z.number().describe("Precio unitario sin impuestos"),
vatRate: z.number().describe("Tipo de IVA en %"),
totalHt: z.number(),
});
const InvoiceSchema = z.object({
invoiceNumber: z.string(),
date: z.string().describe("Formato AAAA-MM-DD"),
dueDate: z.string().nullable(),
vendorName: z.string(),
clientName: z.string(),
lineItems: z.array(LineItemSchema),
subtotalHt: z.number(),
totalVat: z.number(),
totalTtc: z.number(),
currency: z.enum(["EUR", "USD", "GBP"]),
});
const response = await client.chat.parse({
model: "mistral-large-latest",
messages: [
{ role: "system", content: "Extrae los datos de la factura con precisión." },
{ role: "user", content: invoiceText },
],
responseFormat: InvoiceSchema,
temperature: 0,
});
const invoice = response.choices[0].message.parsed!;
console.log(`Factura ${invoice.invoiceNumber} — Total: ${invoice.totalTtc} ${invoice.currency}`);
Análisis de opiniones aspecto por aspecto
Una opinión real de un cliente rara vez es uniformemente positiva o negativa. La reseña del hotel que aparece a continuación elogia la habitación y el desayuno, condena el aparcamiento y el Wi-Fi, y ofrece una visión matizada del personal: una única puntuación global perdería toda esta información. La solución consiste en modelar un AspectSentiment reutilizable y solicitar una lista de los mismos. El campo evidence es la parte más interesante del esquema: al exigir una cita textual, obligas al modelo a fundamentar su juicio y te proporcionas los medios para verificarlo.
from pydantic import BaseModel, Field
class AspectSentiment(BaseModel):
aspect: str = Field(description="El aspecto analizado (calidad, precio, servicio, entrega, etc.)")
sentiment: str = Field(description="positivo, negativo o neutro")
score: float = Field(description="Puntuación entre -1.0 (muy negativo) y 1.0 (muy positivo)")
evidence: str = Field(description="Cita o fragmento del texto que justifica el sentimiento")
class ReviewAnalysis(BaseModel):
overall_sentiment: str = Field(description="Sentimiento general: positivo, negativo, mixto o neutro")
overall_score: float = Field(description="Puntuación general entre -1.0 y 1.0")
aspects: list[AspectSentiment] = Field(description="Análisis aspecto por aspecto")
recommendation: bool = Field(description="¿Recomienda el autor el producto/servicio?")
key_strengths: list[str] = Field(description="Puntos fuertes identificados")
key_weaknesses: list[str] = Field(description="Puntos débiles identificados")
review_text = """
El hotel es magnífico; la habitación era espaciosa y limpia. El desayuno es excelente
con una amplia selección. Sin embargo, el aparcamiento es escandalosamente caro (35 €/noche) y el Wi-Fi fue
inestable durante toda la estancia. El personal de recepción fue muy acogedor,
pero el servicio de habitaciones tardó más de una hora en entregar nuestro pedido.
"""
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "Analiza esta opinión de cliente detallando cada aspecto mencionado."
},
{"role": "user", "content": review_text}
],
response_format=ReviewAnalysis,
temperature=0
)
review = response.choices[0].message.parsed
print(f"Sentimiento general: {review.overall_sentiment} ({review.overall_score:+.1f})")
for aspect in review.aspects:
print(f" [{aspect.score:+.1f}] {aspect.aspect}: {aspect.sentiment}")
Clasificación de texto en múltiples categorías
A diferencia de la clasificación simple, donde se asigna una única etiqueta, la clasificación multietiqueta reconoce que un texto puede pertenecer a varias categorías. El incidente descrito a continuación toca simultáneamente la seguridad, las finanzas, el fraude y la protección de datos: forzar una única etiqueta empobrecería la lógica de enrutamiento.
Dos elementos del esquema merecen atención. reasoning exige una justificación para cada etiqueta, lo que mejora la calidad de la puntuación. requires_human_review convierte la incertidumbre del modelo en una señal operativa: en lugar de descubrir después del hecho que una clasificación era dudosa, la escalas automáticamente a un humano cuando la confianza cae por debajo de 0,7.
from pydantic import BaseModel, Field
class LabelScore(BaseModel):
label: str = Field(description="Nombre de la categoría")
confidence: float = Field(description="Puntuación de confianza entre 0.0 y 1.0")
reasoning: str = Field(description="Justificación en una frase")
class MultiLabelClassification(BaseModel):
primary_label: str = Field(description="Categoría principal")
all_labels: list[LabelScore] = Field(
description="Todas las categorías aplicables con sus puntuaciones de confianza"
)
requires_human_review: bool = Field(
description="Verdadero si la clasificación es incierta (confianza < 0.7)"
)
text = """
Nuestra aplicación de pago móvil tiene una vulnerabilidad de seguridad que permite
el acceso a datos bancarios. Varios clientes han reportado transacciones no autorizadas.
El equipo técnico está investigando actualmente.
"""
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": """Clasifica este texto entre las siguientes categorías (múltiples posibles):
security, finance, technical, legal, customer_support, compliance, fraud, data_privacy.
Asigna una puntuación de confianza a cada categoría aplicable."""
},
{"role": "user", "content": text}
],
response_format=MultiLabelClassification,
temperature=0
)
result = response.choices[0].message.parsed
print(f"Categoría principal: {result.primary_label}")
print(f"Revisión humana requerida: {'Sí' if result.requires_human_review else 'No'}")
for label in result.all_labels:
print(f" [{label.confidence:.0%}] {label.label} — {label.reasoning}")
Factorización de la llamada
Estos tres ejemplos comparten la misma mecánica: un mensaje del sistema, un texto, un esquema y temperature=0. En lugar de copiar la llamada para cada nuevo caso, extráela en una función genérica. El TypeVar acotado a BaseModel preserva el tipado: el objeto devuelto tiene el tipo del esquema pasado como argumento, y tu IDE lo sabe.
from typing import TypeVar, Type
from pydantic import BaseModel
T = TypeVar("T", bound=BaseModel)
def extract(client, text: str, schema: Type[T], system_prompt: str = "") -> T:
"""Extracción estructurada reutilizable."""
messages = []
if system_prompt:
messages.append({"role": "system", "content": system_prompt})
messages.append({"role": "user", "content": text})
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=schema,
temperature=0
)
return response.choices[0].message.parsed
# Uso
invoice = extract(client, invoice_text, InvoiceData, "Extrae los datos de la factura.")
review = extract(client, customer_review, ReviewAnalysis, "Analiza esta opinión de cliente.")
classification = extract(client, ticket, MultiLabelClassification, "Clasifica este texto.")
Tres casos de uso muy diferentes, cada uno requiriendo solo una línea de código para llamar: este es el beneficio concreto de un buen modelado de esquemas.
Puntos clave
- Los esquemas anidados (
list[LineItem],list[AspectSentiment]) permiten análisis complejos - Los enumerados (
Currency, categorías) restringen los valores posibles - El campo
evidence/reasoningobliga al modelo a justificar sus elecciones - Un contenedor genérico reduce la duplicación de código
temperature=0es obligatorio para estos casos de uso en producción