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

Mejores prácticas y resumen

Lección 12 de 12 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Resumen del curso
  2. Elección de tu enfoque
  3. Las diez reglas de oro
  4. Tres errores costosos
  5. Qué monitorizar
  6. Para ir más allá
  7. Una canalización completa
  8. Puntos clave
  9. Pon a prueba tus conocimientos

Resumen del curso

Has explorado toda la gama de mecanismos de salida estructurada que ofrece la API de Mistral. Esta última lección reúne lo que marca la diferencia en el trabajo diario: cómo elegir entre los dos enfoques, los ajustes innegociables, los errores más comunes y qué monitorizar una vez estés en producción.

Elección de tu enfoque

Cuatro preguntas bastan para decidir, en este orden. ¿Tienes un esquema de salida definido? Si la respuesta es no, quédate con el Modo JSON: estás en fase de exploración o prototipado, y bloquear un modelo de datos sería prematuro. Si la respuesta es sí, pasa a la siguiente pregunta.

¿Trabajas en Python o TypeScript? Si es así, las Salidas Estructuradas Personalizadas están listas para ti con Pydantic o Zod. Si no, el Modo JSON con validación manual sigue siendo tu camino.

¿Estás en producción? Si es así, las Salidas Estructuradas Personalizadas son obligatorias, siempre. De lo contrario, el Modo JSON es más que suficiente para el prototipado.

¿Cambia el esquema con frecuencia? Un esquema que aún evoluciona hace que el Modo JSON sea más práctico al principio, hasta que los requisitos se estabilicen; un esquema fijo aboga por las Salidas Estructuradas Personalizadas y la fiabilidad que aportan.

Las diez reglas de oro

Las cinco primeras conciernen a cómo escribes tus llamadas. Establece siempre temperature=0 en producción: la variabilidad de la temperatura es enemiga de la fiabilidad, y la extracción no necesita creatividad.

# Producción: determinista
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema,
    temperature=0  # Reproducibilidad
)

Comprueba siempre finish_reason. Este es el único indicador que te avisa de una respuesta truncada antes de intentar usarla.

if response.choices[0].finish_reason != "stop":
    # La respuesta está truncada — aumenta max_tokens
    raise ValueError(f"Respuesta incompleta: {response.choices[0].finish_reason}")

En el Modo JSON, instruye siempre al modelo en el prompt. El parámetro garantiza la sintaxis, no la estructura: corresponde a ti especificar las claves y sus tipos.

# Modo JSON — el prompt DEBE describir la estructura
messages = [
    {
        "role": "system",
        "content": "Devuelve JSON con las claves: name (string), age (number), city (string)."
    },
    {"role": "user", "content": text}
]

En el modo Personalizado, documenta tus campos. Una descripción precisa vale más que un prompt largo y viaja con el esquema en ambos lenguajes.

class Product(BaseModel):
    name: str = Field(description="Nombre comercial del producto")
    price: float = Field(description="Precio en EUR sin impuestos, redondeado a 2 decimales")
const ProductSchema = z.object({
  name: z.string().describe("Nombre comercial del producto"),
  price: z.number().describe("Precio en EUR sin impuestos, redondeado a 2 decimales"),
});

Separa contexto de contenido. Las instrucciones viven en el mensaje de sistema, los datos a procesar en el mensaje de usuario; nunca al revés, o el modelo confundirá la instrucción con el texto fuente.

messages = [
    {"role": "system", "content": "Eres un extractor de datos. [Instrucciones de formato]"},
    {"role": "user", "content": "[Texto a procesar — SIN instrucciones de formato aquí]"}
]

Las dos siguientes reglas conciernen a tu red de seguridad. Implementa un mecanismo de reintento: nunca hagas una única llamada sin respaldo; el reintento con retroalimentación es el patrón mínimo en producción. Y valida más allá del esquema, ya que el esquema garantiza la estructura, mientras que la validación semántica —límites, coherencia, lógica de negocio— sigue siendo responsabilidad tuya.

Las tres últimas se refieren a la orquestación. Elige el modelo adecuado para el caso de uso correcto: mistral-large-latest para tareas complejas y extracción multicampo, mistral-small-latest para clasificación simple y extracción básica, ministral-8b-latest para alta frecuencia y latencia mínima. Registra cada llamada en producción, anotando el modelo usado, la duración, finish_reason y el resultado: sin registros, estás ciego. Por último, no optimices el prompt en exceso demasiado pronto: empieza simple, mide, itera; la optimización prematura del prompt es una trampa común, mientras que el esquema y la validación son las palancas reales.

Tres errores costosos

El primero es un valor de max_tokens demasiado bajo. El JSON se truncará en respuestas largas, y el error solo se manifestará con documentos grandes, a menudo después de salir a producción.

# Peligroso — el JSON se truncará en respuestas largas
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema,
    max_tokens=128  # Demasiado bajo para un esquema complejo
)

Establece max_tokens en función del tamaño esperado de tu salida: una factura con 20 líneas requiere más tokens que una clasificación simple.

El segundo es una temperatura distinta de cero, lo que hace que tus resultados no sean reproducibles sin ganar nada en una tarea de extracción.

# Peligroso en producción — resultados no reproducibles
response = client.chat.parse(
    ...,
    temperature=0.7  # Variación innecesaria para extracción
)

El tercero es el reflejo de usar un único modelo. No uses mistral-large para todo: una clasificación binaria no requiere el modelo más potente, y ministral-8b hará el trabajo 5 veces más rápido a menor coste.

Qué monitorizar

Cuatro métricas indican la salud de tu canalización. La tasa de éxito mide el porcentaje de llamadas que devuelven un objeto válido al primer intento; la tasa de reintentos, el porcentaje de llamadas que necesitaron una segunda oportunidad. La latencia P50/P95 ofrece el tiempo de respuesta mediano y el percentil 95, que es más revelador que la media. El coste por extracción, expresado en tokens consumidos por llamada, mantiene la factura bajo control.

Sobre estas métricas, unos pocos umbrales de alerta funcionan bien: una tasa de éxito inferior al 95 % justifica una alerta amarilla, inferior al 85 % una alerta roja; una latencia P95 superior a 10 s merece investigación; y un disyuntor abierto exige una alerta inmediata.

Para ir más allá

Cuatro direcciones extienden naturalmente este curso. La llamada a funciones utiliza salidas estructuradas para alimentar llamadas a funciones en un agente. La transmisión (streaming) te permite recibir la salida estructurada progresivamente, lo cual importa en respuestas largas. El ajuste fino (fine-tuning) adapta un modelo de Mistral para mejorar la calidad de la extracción en tus datos específicos. La evaluación, finalmente, consiste en establecer un marco automático basado en un conjunto de datos de referencia (golden dataset) y métricas: esto es lo que te dirá si un cambio en el prompt mejora realmente las cosas.

Una canalización completa

El siguiente código reúne las prácticas del curso en un único flujo: un esquema descrito campo por campo, un validador que rechaza puntuaciones fuera de rango, un modelo dimensionado a la tarea, temperature=0, un max_tokens explícito, verificación de finish_reason y registro para ambos resultados posibles.

from mistralai.client import Mistral
from pydantic import BaseModel, Field, field_validator
import logging
import time

logger = logging.getLogger("pipeline")

class CustomerFeedback(BaseModel):
    sentiment: str = Field(description="positive, negative, or neutral")
    score: float = Field(description="Score between -1.0 and 1.0")
    category: str = Field(description="product, service, delivery, price, or other")
    action_required: bool = Field(description="True if action is required")
    summary: str = Field(description="One-sentence summary")

    @field_validator("score")
    @classmethod
    def score_in_range(cls, v):
        if not -1.0 <= v <= 1.0:
            raise ValueError(f"Score out of bounds: {v}")
        return v

def analyze_feedback(client: Mistral, text: str) -> CustomerFeedback:
    start = time.time()
    try:
        response = client.chat.parse(
            model="mistral-small-latest",
            messages=[
                {"role": "system", "content": "Analyze customer feedback."},
                {"role": "user", "content": text}
            ],
            response_format=CustomerFeedback,
            temperature=0,
            max_tokens=256
        )
        assert response.choices[0].finish_reason == "stop"
        result = response.choices[0].message.parsed
        logger.info(f"OK en {time.time()-start:.2f}s — {result.sentiment} ({result.score:+.1f})")
        return result
    except Exception as e:
        logger.error(f"ERROR en {time.time()-start:.2f}s — {e}")
        raise

Unas treinta líneas, y tienes un componente que puede integrarse con seguridad en el medio de un sistema: esto es exactamente lo que hacen posible las salidas estructuradas.

Puntos clave

  • Usa Salidas Estructuradas Personalizadas en producción, Modo JSON para prototipado
  • temperature=0, comprobar finish_reason y reintentar son innegociables
  • Elige el modelo según la complejidad de la tarea y el presupuesto
  • Monitoriza la tasa de éxito, la latencia y el coste
  • Empieza simple, mide y luego optimiza

Pon a prueba tus conocimientos

Modo JSON, esquemas, reintentos: ¿tienes la salida estructurada bajo control?

1. Modo JSON frente a Salidas Estructuradas Personalizadas: ¿cuál es la diferencia?

Respuesta: El Modo JSON garantiza un JSON sintácticamente válido; las Salidas Estructuradas Personalizadas hacen cumplir además tu esquema exacto —campos, tipos, estructura—: el contrato completo.

2. ¿Qué proporciona client.chat.parse() con Pydantic?

Respuesta: El bucle completo: el esquema Pydantic declara la estructura, la API restringe la generación y la respuesta llega ya validada y tipada como un objeto Python: cero análisis manual.

3. ¿Y en el lado de TypeScript?

Respuesta: La misma comodidad con Zod: el esquema Zod define y valida la estructura, una única fuente de verdad para la generación y el tipado.

4. ¿Qué hacer cuando la salida no respeta el esquema?

Respuesta: Validar sistemáticamente y planificar una estrategia de reintento: volver a solicitar con el error en contexto o degradar con elegancia; nunca confiar ciegamente en la salida.

5. ¿Cuándo es indispensable la salida estructurada?

Respuesta: En cuanto un programa consume la respuesta sin revisión humana: extracción, integraciones, canalizaciones; el formato deja de ser una cortesía para convertirse en una interfaz.

Esquema declarado, generación restringida, validación de salida: la tríada que hace que la IA sea enchufable en software real.