DSPy: cómo optimizar prompts con métricas y ejemplos

Información verificada el 15 de octubre de 2026 con la documentación vigente de DSPy, PyPI y los precios de los modelos de Google. PyPI publica DSPy 3.4.1, lanzado el 12 de octubre de 2026, compatible con Python 3.10 o posterior, pero anterior a 3.16. El paquete que debes instalar es dspy. Metadatos del paquete en PyPI.

¿Qué es DSPy y qué significa compilar un programa?

DSPy es un framework de código abierto para Python que permite definir tareas de modelos de lenguaje como programas y después mejorar sus prompts o, con determinados optimizadores, los pesos del modelo. Su propuesta útil es conseguir mejoras reproducibles según tus propios criterios de éxito. Eso no significa que el primer prompt generado vaya a superar a uno escrito con cuidado. Introducción a DSPy.

Piensa en un ensayo. La firma define el encargo, el módulo determina cómo se interpreta y la métrica establece el criterio para juzgarlo. El optimizador cambia algo, observa el resultado y conserva los cambios que sirven. Sin un criterio de evaluación, puedes ensayar de formas distintas sin saber si has mejorado.

Las firmas definen la tarea

Una firma declara las entradas, las salidas y las instrucciones de la tarea. "ticket -> category" indica que entra un ticket y sale una categoría. Una firma definida como clase permite añadir campos tipados y un docstring que explique la tarea. Elegir bien los campos sigue siendo fundamental: ningún optimizador puede resolver por sí solo una definición ambigua de lo que la empresa considera «urgente». Documentación sobre firmas.

Los módulos de DSPy determinan cómo se ejecuta

Un módulo implementa una estrategia para realizar la tarea. dspy.Predict es el componente básico de predicción. dspy.ChainOfThought añade un campo de razonamiento antes de la respuesta. dspy.ReAct permite usar un ciclo de razonamiento y herramientas. Cuando un solo paso del modelo no basta, puedes combinar módulos en Python. Documentación sobre módulos.

Para asignar tickets de soporte a la cola correspondiente, empieza con Predict. Incorporar un ciclo de herramientas para clasificar un mensaje breve añade complejidad antes de haber demostrado que hace falta.

Compilar consiste en optimizar

Un optimizador modifica ciertas partes de un programa a partir de ejemplos y una métrica. En la optimización de prompts, .compile() devuelve un programa con instrucciones o demostraciones revisadas; las demostraciones son ejemplos incluidos en el prompt. No convierte la aplicación en un ejecutable nativo ni evita las futuras llamadas al modelo. Entrenar los pesos requiere elegir otro tipo de optimizador. Guía para elegir un optimizador.

Tutorial de DSPy: el ejemplo mínimo de la documentación vigente

El programa de iniciación de la documentación actual genera un haiku. Este pequeño ejemplo permite entender la interfaz sin añadir una base de datos, herramientas ni una búsqueda de optimización.

Instala la versión verificada en tu entorno de Python:

python -m pip install 'dspy[litellm]==3.4.1'

Configura la variable de entorno GEMINI_API_KEY con una clave válida de la API de Google Gemini. Guarda este código como first_dspy.py y ejecuta python first_dspy.py:

import os
import dspy

lm = dspy.LM(
    "gemini/gemini-2.5-flash-lite",
    api_key=os.environ["GEMINI_API_KEY"],
    engine="litellm",
)
dspy.configure(lm=lm)

haiku_signature = "subject -> haiku"
haiku_generator = dspy.Predict(haiku_signature)
result = haiku_generator(subject="computer science")
print(result.haiku)

Las cuatro últimas líneas corresponden al primer programa de la documentación vigente. La configuración sigue el patrón de DSPy para configurar modelos, pero sustituye el modelo por Google Gemini 2.5 Flash-Lite para que el experimento de más abajo use un único modelo económico. El identificador del proveedor sigue la integración de Gemini en LiteLLM; la API de modelos de lenguaje de DSPy admite la selección explícita de ese backend.

DSPy construye un prompt a partir de la firma, lo envía al modelo configurado y extrae el campo haiku de la respuesta. Este ejemplo ejecuta una inferencia, no una optimización. No se promete un poema concreto ni una mejora de calidad.

La optimización de prompts con DSPy necesita una métrica

Sin métrica, la optimización carece de un criterio útil. Una métrica es una función que convierte una predicción en una puntuación. Para asignar tickets, puede comparar la categoría predicha con una etiqueta validada por una persona. En una respuesta generada, comprobar la corrección puede exigir una rúbrica o una prueba ejecutable. La interfaz de métricas de DSPy acepta tu función de evaluación; el framework no decide qué debe premiar tu empresa. Métricas y evaluación.

Por eso importa disponer de un pequeño conjunto de evaluación etiquetado. Si ya te cansaste de cambiar «sé conciso» por «responde brevemente», reúne fallos reales: una solicitud de reembolso enviada a soporte técnico, un problema de acceso clasificado como facturación o un mensaje que contiene dos solicitudes. Etiqueta el resultado esperado antes de mirar la salida de un nuevo prompt.

Para una primera prueba piloto, utiliza 60 ejemplos distintos, separados de forma deliberada en 20 de entrenamiento, 20 de validación y 20 de prueba final. Son tamaños propuestos para el experimento, no requisitos de DSPy ni una demostración de fiabilidad en producción.

• Los ejemplos de entrenamiento aportan material del que puede aprender el optimizador.
• Los ejemplos de validación sirven para comparar versiones y tomar decisiones durante el desarrollo.
• Los ejemplos de prueba final permanecen intactos hasta que fijes la versión candidata y las reglas de evaluación.

Mantén en una misma partición los tickets relacionados con un mismo cliente o incidente. De lo contrario, los casos casi duplicados pueden hacer que un prompt optimizado parezca generalizar mejor de lo que realmente hace. Incluye fallos poco frecuentes que sean importantes, en lugar de llenar cada partición de casos fáciles.

Hay un matiz importante en eso de «sin métrica». Puedes ejecutar un programa de DSPy sin optimizar y sin una métrica, y LabeledFewShot puede incorporar ejemplos sin puntuarlos. Eso es configurar el programa; no demuestra que el cambio haya mejorado la tarea. Tampoco todas las tareas necesitan una respuesta de referencia escrita a mano: una prueba ejecutable de corrección puede proporcionar la señal necesaria. Para clasificaciones de negocio, las etiquetas validadas suelen ser el punto de partida más claro. Referencia inicial con ejemplos few-shot.

Optimizadores de DSPy: cuáles aparecen en la documentación actual

Empieza con el optimizador más sencillo que permita abordar un fallo concreto. Ampliar la búsqueda solo sirve si la métrica distingue las mejores opciones de las peores.

El índice actual de la API de optimizadores incluye exactamente estas entradas: BetterTogether, BootstrapFewShot, BootstrapFewShotWithRandomSearch, BootstrapFinetune, BootstrapRS, COPRO, Ensemble, GEPA, InferRules, KNN, KNNFewShot, LabeledFewShot, MIPROv2 y SIMBA.

No todas corresponden a algoritmos de búsqueda independientes. BootstrapRS es un alias de BootstrapFewShotWithRandomSearch; KNN es el componente auxiliar de recuperación que usa KNNFewShot. La guía vigente también menciona AvatarOptimizer para programas basados en agentes, aunque no aparece en ese índice de la API. Detalles de la familia de optimizadores, guía de selección.

MIPROv2 propone instrucciones y utiliza optimización bayesiana, un método de búsqueda que se apoya en las puntuaciones anteriores, para explorar combinaciones de instrucciones y demostraciones. SIMBA trabaja con minilotes y propone reglas o demostraciones. Son enfoques distintos, no versiones de BootstrapFewShot con otro nombre. API de MIPROv2, API de SIMBA.

GEPA utiliza un modelo de reflexión para leer la información que deja la ejecución y proponer cambios en las instrucciones. Una puntuación acompañada de una explicación concreta, como «las solicitudes de reembolso corresponden a facturación aunque mencionen una función que falla», aporta una señal más útil que una simple puntuación de fallo. La documentación detallada admite métricas exclusivamente numéricas, pero explica que con ellas se pierde esa información más rica. Cómo funciona GEPA.

Pon límites a la primera optimización

Es más fácil calcular el alcance de un pequeño experimento con BootstrapFewShot que el de una búsqueda de instrucciones abierta. El siguiente diseño utiliza un único módulo Predict, una métrica determinista para las etiquetas y el mismo modelo para enseñar y predecir.

BootstrapFewShot en DSPy: una prueba pequeña a propósito

Prepara train.jsonl, validation.jsonl y test.jsonl, cada uno con 20 tickets distintos etiquetados por personas. Cada línea debe ser un objeto JSON con text y label; las etiquetas permitidas son billing, technical, account y other. Por ejemplo, una solicitud para cambiar la dirección de una factura podría llevar la etiqueta billing. Debes usar tus propios ejemplos, no el haiku generado.

Guarda este otro script como optimize_tickets.py y ejecútalo después de configurar la misma clave de API:

import json
import os
from typing import Literal
import dspy

lm = dspy.LM(
    "gemini/gemini-2.5-flash-lite",
    api_key=os.environ["GEMINI_API_KEY"],
    engine="litellm",
    cache=False,
)
dspy.configure(lm=lm)

class RouteTicket(dspy.Signature):
    """Choose the support queue responsible for the ticket's main request."""
    text: str = dspy.InputField()
    label: Literal["billing", "technical", "account", "other"] = (
        dspy.OutputField()
    )

def load_examples(path):
    with open(path, encoding="utf-8") as source:
        rows = [json.loads(line) for line in source if line.strip()]
    assert len(rows) == 20
    return [dspy.Example(**row).with_inputs("text") for row in rows]

train = load_examples("train.jsonl")
validation = load_examples("validation.jsonl")
test = load_examples("test.jsonl")
assert len({e.text for e in train + validation + test}) == 60

def correct_label(example, prediction, trace=None):
    return prediction.label == example.label

program = dspy.Predict(RouteTicket)
evaluate = dspy.Evaluate(
    devset=validation, metric=correct_label, num_threads=1
)
print("Baseline validation:", evaluate(program).score)

optimizer = dspy.BootstrapFewShot(
    metric=correct_label,
    max_bootstrapped_demos=4,
    max_labeled_demos=0,
    max_rounds=1,
)
optimized = optimizer.compile(program, trainset=train)
print("Optimized validation:", evaluate(optimized).score)

# Freeze this candidate before opening the final test results.
final_test = dspy.Evaluate(
    devset=test, metric=correct_label, num_threads=1
)
print("Baseline final test:", final_test(program).score)
print("Optimized final test:", final_test(optimized).score)
optimized.save("candidate_ticket_router.json")

Este ejemplo adapta el constructor documentado de BootstrapFewShot y la interfaz de evaluación; no presenta un benchmark medido. Solicita hasta cuatro demostraciones satisfactorias, permite un intento de bootstrap por ejemplo de entrenamiento y no añade demostraciones etiquetadas sin procesar. El archivo guardado es una versión candidata para revisar, no un pase automático a producción.

El recuento de ejecuciones de este diseño es el siguiente:

• Versión de referencia sobre el conjunto de validación: 20 ejecuciones del programa.
• Bootstrap sobre el conjunto de entrenamiento: hasta 20 ejecuciones del modelo maestro, quizá menos si antes se obtienen suficientes demostraciones válidas.
• Programa optimizado sobre el conjunto de validación: 20 ejecuciones del programa.
• Ambas versiones sobre el conjunto de prueba final: 40 ejecuciones del programa.

En total, son hasta 100 ejecuciones de un solo paso, incluida la evaluación; la compilación por sí sola representa un máximo de 20. Si cada ejecución necesita una única solicitud satisfactoria al modelo, sin reintentos ni vías alternativas para interpretar la respuesta, el total será de hasta 100 llamadas al modelo que realiza la tarea. La comprobación inicial con el haiku se cuenta aparte. Añadir un LLM evaluador, un ciclo de agente, reintentos u otro intento de optimización cambia el total.

Con la tarifa de lista de pago Standard de Google para texto en Gemini 2.5 Flash-Lite, de $0.10 por millón de tokens de entrada y $0.40 por millón de tokens de salida, 100 llamadas con una media supuesta de 1,000 tokens de entrada y 100 de salida cuestan $0.014: 100,000 ÷ 1,000,000 × $0.10 + 10,000 ÷ 1,000,000 × $0.40. Precios de Google.

Es un cálculo limitado al coste del modelo, no una factura medida ni un límite de gasto. La estimación de entrada debe incluir el formato que añade DSPy y las demostraciones adjuntas; los tickets más largos, las salidas más extensas y el razonamiento facturable aumentan el importe. La estimación no aplica descuentos por procesamiento en lotes ni por caché. El registro válido para contabilizar el gasto es el uso real que registra tu proveedor.

DSPy frente a los prompts manuales y el fine-tuning

Usa DSPy cuando necesites una forma reproducible de mejorar un programa cuyo rendimiento puedas medir. Conserva un prompt escrito a mano si ya cumple los requisitos de la tarea. Considera el fine-tuning cuando tengas pruebas de que cambiar los prompts no basta y entrenar un modelo encaje con las restricciones de tu despliegue.

Son técnicas compatibles. DSPy incluye BootstrapFinetune, y BetterTogether combina la optimización de prompts y de pesos. La diferencia práctica está en qué cambias y qué mantienes, no en qué etiqueta suena más avanzada. Optimización de prompts y pesos.

El momento de cambiar de enfoque lo marca el trabajo cotidiano: si cada cambio de modelo o nuevo tipo de fallo obliga a un ingeniero a volver a editar varios prompts a mano, un ciclo de optimización guiado por una puntuación empieza a tener sentido. Si un prompt breve ya supera tus criterios de aceptación, sustituirlo por un framework no tiene un beneficio demostrado.

¿A quién le conviene usar DSPy, esperar o descartarlo?

Los ingenieros deberían probarlo cuando tengan una tarea recurrente, una versión de referencia que funcione y fallos representativos. La asignación de tickets y la extracción estructurada son buenos puntos de partida porque permiten comprobar las salidas esperadas. Optimiza un componente pequeño antes de ampliar el sistema. El límite de DSPy está en la calidad del objetivo: puede elegir una versión con mayor puntuación aunque la métrica premie el comportamiento equivocado.

Los responsables de operaciones deben hacerse cargo de las etiquetas y de la prioridad de los errores. A quien dirige soporte puede preocuparle mucho más asignar mal un incidente de acceso a la cuenta que una consulta habitual de facturación. Si la puntuación trata ambos casos por igual, la optimización puede ir en contra de sus prioridades. Resuelve ese criterio antes de pedirle a un ingeniero que mejore la puntuación.

Quienes deciden la compra deben pedir pruebas con ejemplos que no se hayan usado antes. Conviene preguntar contra qué versión de referencia se comparó, en qué casos empeoró, qué incluye ahora el programa que atiende las solicitudes y si el flujo sigue cumpliendo los requisitos de latencia. El nombre del optimizador no basta para darlo por bueno. La reseña de Promptfoo del sitio complementa esta lectura para los equipos que están organizando su trabajo de evaluación.

Un equipo de negocio debería prescindir de DSPy para redactar textos de forma ocasional, investigar algo una sola vez o gestionar un flujo que cambia antes de reunir suficientes ejemplos. También conviene descartarlo si nadie puede mantener código Python o acordar una regla de puntuación. Un buen prompt, una lista de comprobación y una revisión humana pueden ser una solución más proporcionada. Espera si el problema real es la falta de datos de origen o de un proceso definido: optimizar la redacción no resolverá ninguna de esas carencias.

¿Qué promesas sobre DSPy se exageran?

«Programar en vez de escribir prompts» no hace desaparecer los prompts. DSPy los crea y los gestiona; las personas siguen definiendo la tarea, evaluando los fallos y decidiendo si el resultado es aceptable.

«Compilar» no significa que el modelo haya aprendido de forma permanente. Con los optimizadores de prompts, lo que se aprende y se guarda son instrucciones o demostraciones. Durante la inferencia sigues llamando a un modelo, y las demostraciones ocupan espacio en el prompt. Puedes guardar el estado aprendido en JSON y cargarlo en un programa nuevo. Guardar y cargar programas.

«Optimización automática» no significa mejora garantizada. La comparación útil es con tu enfoque actual y con entradas que no se hayan usado antes. Una puntuación de desarrollo más alta puede deberse al sobreajuste, a un evaluador permisivo o a un conjunto de datos que no incluya los fallos más costosos.

Además, las llamadas a la métrica no equivalen a llamadas al proveedor. El parámetro max_metric_calls de GEPA limita las invocaciones de evaluación; la reflexión también llama a un modelo, y el programa evaluado puede realizar varias solicitudes por su cuenta. Las opciones de auto no se traducen en una factura universal. Controles de presupuesto de GEPA.

Preguntas frecuentes de los ingenieros sobre DSPy

Por dónde empezar

El lunes, elige un fallo recurrente en la asignación de tickets o en una tarea de extracción y pide a la persona responsable del proceso que etiquete ejemplos representativos. Fija una versión de referencia, define una regla de puntuación y ejecuta un experimento acotado. Revisa las respuestas que hayan cambiado antes de aprobar la versión candidata. Si no puedes definir la puntuación, el siguiente paso útil es acordar la regla de negocio.

Recibe guías prácticas sobre ingeniería de IA en la newsletter.