Cómo Probar Aplicaciones LLM: Guía Completa de Promptfoo (2026)

TL;DR

Promptfoo es un framework de evaluación y red-teaming de LLM de código abierto que ayuda a los desarrolladores a probar aplicaciones de IA de forma sistemática. Soporta más de 90 proveedores de modelos, ofrece más de 67 plugins de ataque de seguridad y funciona 100% localmente para la privacidad. Con 1.6 millones de descargas en npm y uso en producción en empresas que atienden a más de 10 millones de usuarios, se ha convertido en el estándar para las pruebas de LLM. Empiece con npm install -g promptfoo y promptfoo init --example getting-started.

Introducción

Usted pasó semanas construyendo su chatbot de atención al cliente impulsado por IA. Respondía preguntas perfectamente durante el desarrollo. Luego, los usuarios comenzaron a encontrar formas de hacer que filtrara datos sensibles, eludiera las medidas de seguridad y diera respuestas inconsistentes.

Este escenario se repite todos los días. Los equipos lanzan aplicaciones LLM basándose en la intuición y las pruebas manuales, solo para descubrir vulnerabilidades y problemas de calidad en producción. El costo de solucionar estos problemas después del lanzamiento es 100 veces mayor que detectarlos durante el desarrollo.

Promptfoo resuelve esto al llevar pruebas sistemáticas y automatizadas a las aplicaciones LLM. Le permite evaluar prompts en múltiples modelos, realizar evaluaciones de seguridad de "red team" y detectar regresiones antes de que lleguen a los usuarios.

He analizado el código base de promptfoo (versión 0.121.2) y probado sus características principales para ofrecerle esta guía completa. Aprenderá cómo configurar evaluaciones, ejecutar escaneos de seguridad, integrar con CI/CD y evitar errores comunes.

Al final, tendrá un conjunto de pruebas funcional para su aplicación LLM y sabrá cómo lanzarla con confianza.

¿Qué es Promptfoo y por qué lo necesita?

Promptfoo es una herramienta de línea de comandos y una librería de Node.js para evaluar y realizar "red-teaming" en aplicaciones LLM. Piense en ello como un framework de pruebas construido específicamente para las particularidades del desarrollo de IA.

Las herramientas de prueba tradicionales fallan con los LLM porque los resultados no son deterministas. No se pueden afirmar coincidencias exactas de cadenas cuando el mismo prompt produce respuestas diferentes cada vez. Promptfoo resuelve esto con:

• Aserciones semánticas que verifican el significado en lugar del texto exacto.
• Evaluaciones calificadas por LLM donde un modelo evalúa el resultado de otro.
• Comparación de múltiples modelos para probar el mismo prompt en GPT-4, Claude y otros.
• Plugins de seguridad que prueban automáticamente las vulnerabilidades.

La herramienta se ejecuta localmente en su máquina. Sus prompts y datos de prueba nunca abandonan su entorno a menos que opte por funciones en la nube. Este diseño centrado en la privacidad lo hace adecuado para pruebas con datos sensibles.

El problema que resuelve Promptfoo

La mayoría de los equipos prueban las aplicaciones LLM manualmente. Envían algunos prompts, leen los resultados y deciden si las cosas se ven bien. Este enfoque tiene tres fallas fatales:

1. Sin detección de regresiones - No se puede saber si una actualización del modelo rompió la funcionalidad existente.
2. Brechas de cobertura - Las pruebas manuales pasan por alto casos límite y entradas adversarias.
3. Sin métricas - No se puede rastrear la mejora ni comparar modelos objetivamente.

Promptfoo reemplaza esto con evaluaciones automatizadas que se ejecutan en cada cambio. Usted define los casos de prueba una vez y los ejecuta contra cualquier modelo. Los resultados incluyen tasas de aprobación/falla, comparaciones de costos y métricas de latencia.

Quién usa Promptfoo

El proyecto tiene 1.6 millones de descargas en npm y potencia aplicaciones LLM que atienden a más de 10 millones de usuarios finales. Las empresas lo utilizan para:

• Chatbots de atención al cliente que necesitan respuestas consistentes y precisas.
• Pipelines de generación de contenido que deben mantener la voz de la marca.
• Aplicaciones de atención médica y fintech con estrictos requisitos de cumplimiento.
• Sistemas sensibles a la seguridad que no pueden filtrar datos ni aceptar entradas dañinas.

En marzo de 2026, Promptfoo se unió a OpenAI. El proyecto sigue siendo de código abierto y tiene licencia MIT, con desarrollo continuo bajo la nueva propiedad.

Primeros pasos: Instale y ejecute su primera evaluación

Puede instalar promptfoo globalmente o ejecutarlo sin instalación usando npx.

Instalación

# Instalación global (recomendado)
npm install -g promptfoo

# O ejecutar sin instalar
npx promptfoo@latest

# Los usuarios de macOS también pueden usar Homebrew
brew install promptfoo

# Los usuarios de Python también pueden usar pip
pip install promptfoo

Configure sus claves de API como variables de entorno:

export OPENAI_API_KEY=sk-abc123
export ANTHROPIC_API_KEY=sk-ant-xxx

Cree su primera evaluación

Inicialice un proyecto de ejemplo:

promptfoo init --example getting-started
cd getting-started

Esto crea un archivo promptfooconfig.yaml con ejemplos de prompts, proveedores y casos de prueba.

Ejecute la evaluación:

promptfoo eval

Vea los resultados en la interfaz web:

promptfoo view

La interfaz de usuario se abre en localhost:3000 y muestra una comparación lado a lado de los resultados de cada modelo, con el estado de aprobado/fallado para cada aserción.

Comprensión del archivo de configuración

El archivo promptfooconfig.yaml define su suite de evaluación:

description: "Mi primera suite de evaluación"

prompts:
  - prompts/greeting.txt
  - prompts/farewell.txt

providers:
  - openai:gpt-4o
  - anthropic:claude-sonnet-4-5

tests:
  - vars:
      input: "Hola"
    assert:
      - type: contains
        value: "Hola"
      - type: latency
        threshold: 3000

• prompts: Archivos o texto en línea para probar.
• providers: Modelos a evaluar (soporta más de 90 proveedores).
• tests: Casos de prueba con variables y aserciones.

Puede escalar esto a cientos de casos de prueba. Muchos equipos mantienen las configuraciones de evaluación en control de versiones y las ejecutan en CI en cada solicitud de extracción.

Funciones principales: Lo que Promptfoo puede hacer

1. Evaluaciones automatizadas

Las evaluaciones automatizadas son la base de promptfoo. Usted define casos de prueba con resultados esperados, y la herramienta los ejecuta contra los modelos elegidos.

Tipos de aserción

Promptfoo incluye más de 30 tipos de aserción integrados:

Ejemplo con múltiples aserciones:

tests:
  - vars:
      question: "¿Cuál es la capital de Francia?"
    assert:
      - type: contains
        value: "París"
      - type: javascript
        value: output.length < 100
      - type: latency
        threshold: 2000
      - type: cost
        threshold: 0.001

Esta prueba verifica que la respuesta mencione París, tenga menos de 100 caracteres, responda en menos de 2 segundos y cueste menos de $0.001.

Evaluaciones calificadas por LLM

La aserción llm-rubric usa un LLM para calificar la salida de otro. Esto es poderoso para criterios subjetivos como el tono o la utilidad:

assert:
  - type: llm-rubric
    value: "La respuesta debe ser útil, inofensiva y honesta"

El LLM calificador lee la salida y la puntúa según su rúbrica. Puede usar un modelo más económico para la calificación para reducir costos.

2. Red Teaming y pruebas de seguridad

Promptfoo incluye pruebas de seguridad exhaustivas a través de su módulo de "red team". Genera automáticamente entradas adversarias para buscar vulnerabilidades.

Vectores de ataque soportados

El sistema de "red team" incluye más de 67 plugins organizados por categoría:

Ejecutando un escaneo de "red team"

Inicialice una configuración de "red team":

promptfoo redteam init

Ejecute el escaneo de seguridad:

promptfoo redteam run

Vea el informe:

promptfoo redteam report [directorio]

El comando redteam run realiza dos pasos:

1. Genera sondas de ataque dinámicas adaptadas a su aplicación.
2. Evalúa las sondas contra su objetivo y puntúa las vulnerabilidades.

Los resultados incluyen calificaciones de gravedad (Crítica, Alta, Media, Baja), casos de prueba explotables y recomendaciones de remediación.

Ejemplo de salida de "Red Team"

Resumen de Vulnerabilidades:
- Crítica: 2 (fuga de PII, extracción de prompt)
- Alta: 5 (jailbreaks, ataques de inyección)
- Media: 12 (sesgo, respuestas inconsistentes)
- Baja: 23 (violaciones menores de políticas)

Solucione los problemas críticos antes del despliegue. Vuelva a ejecutar los escaneos después de los cambios para verificar las correcciones.

3. Escaneo de código para solicitudes de extracción

Promptfoo se integra con GitHub Actions para escanear las solicitudes de extracción en busca de problemas de seguridad relacionados con LLM.

# .github/workflows/promptfoo-scan.yml
name: Escaneo de código Promptfoo
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: promptfoo/promptfoo/code-scan-action@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Esto detecta:

• Claves de API codificadas en archivos de configuración.
• Patrones de prompt inseguros.
• Falta de validación de entrada.
• Posibles vectores de inyección de prompt.

4. Comparación de modelos

Compare los resultados de múltiples modelos lado a lado para elegir el mejor para su caso de uso.

# Ejecutar eval con múltiples proveedores
promptfoo eval

# Ver comparación en la interfaz web
promptfoo view

La interfaz web muestra:

• Tasas de aprobación/fallo por modelo.
• Costo por 1000 solicitudes.
• Latencia promedio.
• Diferencias cualitativas en la salida.

Este enfoque basado en datos previene el sesgo hacia modelos familiares. Es posible que un modelo más económico supere a GPT-4 en sus evaluaciones específicas.

Proveedores soportados: Más de 90 integraciones LLM

Promptfoo soporta más de 90 proveedores de LLM de forma predeterminada. Puede probar el mismo prompt en OpenAI, Anthropic, Google, Amazon y modelos locales sin cambiar su código.

Principales proveedores

Proveedores personalizados

Puede escribir proveedores personalizados en Python o JavaScript si su modelo no es compatible.

Ejemplo de Python:

# custom_provider.py
from typing import Any

class CustomProvider:
    async def call_api(self, prompt: str, options: dict, context: dict) -> dict:
        response = await my_async_api.generate(prompt)
        return {
            "output": response.text,
            "tokenUsage": {
                "total": response.usage.total_tokens,
                "prompt": response.usage.prompt_tokens,
                "completion": response.usage.completion_tokens
            }
        }

Ejemplo de JavaScript:

// customProvider.js
export default class CustomProvider {
  async callApi(prompt) {
    return {
      output: await myApi.generate(prompt),
      tokenUsage: { total: 50, prompt: 20, completion: 30 }
    };
  }
}

Registre proveedores personalizados en su configuración:

providers:
  - id: file://custom_provider.py
    config:
      api_key: ${MY_API_KEY}

Interfaz de línea de comandos: Comandos esenciales

La CLI de Promptfoo proporciona toda la funcionalidad que necesita para los flujos de trabajo diarios.

Comandos principales

# Ejecutar evaluaciones
promptfoo eval -c promptfooconfig.yaml

# Abrir interfaz web
promptfoo view

# Compartir resultados en línea
promptfoo share

# Pruebas de "red team"
promptfoo redteam init
promptfoo redteam run

# Configuración
promptfoo init
promptfoo validate [config]

# Gestión de resultados
promptfoo list
promptfoo show <id>
promptfoo delete <id>
promptfoo export <id>

# Utilidades
promptfoo cache clear
promptfoo retry <id>

Banderas útiles

--no-cache              # Deshabilitar caché para resultados frescos
--max-concurrency <n>   # Limitar llamadas a la API paralelas
--output <file>         # Escribir resultados en un archivo JSON
--verbose               # Habilitar registro de depuración
--env-file <path>       # Cargar variables de entorno desde un archivo
--filter <pattern>      # Ejecutar casos de prueba específicos

Ejemplo: Ejecutar evaluación con configuración personalizada

promptfoo eval \
  -c promptfooconfig.yaml \
  --no-cache \
  --max-concurrency 3 \
  --output results.json \
  --env-file .env

Esto ejecuta evaluaciones nuevas (sin caché), limita la concurrencia a 3 llamadas paralelas, guarda los resultados en JSON y carga las claves de API desde .env.

Integración CI/CD: Automatice las pruebas LLM

Integre promptfoo en su pipeline de CI/CD para detectar regresiones antes del despliegue.

Ejemplo de GitHub Actions

name: Pruebas LLM
on: [push, pull_request]
jobs:
  eval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm install -g promptfoo
      - run: promptfoo eval -c promptfooconfig.yaml
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Puertas de calidad

Establezca umbrales de aprobación/falla en su configuración:

commandLineOptions:
  threshold: 0.8  # Requiere una tasa de aprobación del 80%

Esto hace que la CI falle si las evaluaciones no cumplen el umbral, evitando que las regresiones se fusionen.

Caché en CI

Habilite el almacenamiento en caché para acelerar las ejecuciones de CI:

- uses: actions/cache@v4
  with:
    path: ~/.cache/promptfoo
    key: ${{ runner.os }}-promptfoo-${{ hashFiles('promptfooconfig.yaml') }}

Los resultados en caché omiten las llamadas a la API para las pruebas sin cambios, lo que reduce el tiempo y los costos de CI.

Interfaz web: Visualice y comparta resultados

La interfaz web incorporada (promptfoo view) proporciona una interfaz interactiva para revisar las evaluaciones.

Características

• Matriz de evaluación - Compare resultados lado a lado.
• Filtrado - Encuentre casos de prueba específicos por estado o proveedor.
• Vista de diferencias - Vea exactamente qué cambió entre ejecuciones.
• Compartir - Genere enlaces compartibles para revisión en equipo.
• Actualizaciones en tiempo real - Vea las evaluaciones ejecutarse en vivo.

Acceso y seguridad

La interfaz de usuario se ejecuta en localhost:3000 por defecto. Incluye protección CSRF utilizando los encabezados Sec-Fetch-Site y Origin para bloquear solicitudes entre sitios desde orígenes no confiables.

No exponga el servidor web local a redes no confiables. Para el acceso del equipo, utilice el comando promptfoo share para cargar los resultados a la nube, o autoalójelos con autenticación.

Base de datos y caché

Ubicación de la caché

• macOS/Linux: ~/.cache/promptfoo
• Windows: %LOCALAPPDATA%\promptfoo

La caché almacena los resultados de las evaluaciones para acelerar las ejecuciones repetidas. Utilice --no-cache durante el desarrollo para garantizar resultados frescos.

Ubicación de la base de datos

• Todas las plataformas: ~/.promptfoo/promptfoo.db (SQLite)

La base de datos almacena las ejecuciones históricas de evaluación para comparación y análisis de tendencias. No elimine este archivo a menos que desee perder datos históricos.

Modelo de seguridad: En qué puede confiar

Promptfoo opera con un modelo de confianza por configuración. Entender esto previene sorpresas de seguridad.

Entradas de confianza (tratadas como código)

Estas entradas se ejecutan como código y solo deben provenir de fuentes confiables:

• Archivos de configuración (promptfooconfig.yaml).
• Aserciones personalizadas de JavaScript/Python/Ruby.
• Configuraciones de proveedores.
• Funciones de transformación.

Entradas no confiables (solo datos)

Estas entradas se tratan como datos y no deben activar la ejecución de código:

• Texto del prompt.
• Variables del caso de prueba.
• Resultados del modelo.
• Contenido remoto obtenido durante las evaluaciones.

Recomendaciones de endurecimiento

Para entornos de alta seguridad:

1. Ejecútelo dentro de un contenedor o VM con privilegios mínimos.
2. Utilice claves de API dedicadas con los mínimos privilegios.
3. Evite colocar secretos en los prompts o archivos de configuración.
4. Restrinja la salida de red para código de terceros.
5. No exponga el servidor web local a redes no confiables.

Rendimiento: Optimice sus evaluaciones

Consejos de optimización

1. Use el almacenamiento en caché - El comportamiento predeterminado acelera las ejecuciones repetidas.
2. Ajuste la concurrencia - --max-concurrency equilibra la velocidad con los límites de velocidad.
3. Filtre las pruebas - Use --filter para ejecutar casos de prueba específicos durante el desarrollo.
4. Conjuntos de datos de muestra - Use --repeat con subconjuntos para la iteración antes de las ejecuciones completas.

Escalado para grandes evaluaciones

Para evaluaciones a gran escala con miles de casos de prueba:

• Utilice el programador (src/scheduler/) para ejecuciones distribuidas.
• Aproveche la generación remota para descargar la computación.
• Exporte los resultados a Google Sheets para la visibilidad del equipo.

Extensibilidad: Construya características personalizadas

Aserciones personalizadas

Escriba aserciones personalizadas para verificaciones específicas del dominio:

// assertions/customCheck.js
export default function customCheck(output, context) {
  const pass = output.includes('expected');
  return {
    pass,
    score: pass ? 1 : 0,
    reason: pass ? 'Output matched' : 'Missing expected content'
  };
}

Úselo en su configuración:

assert:
  - type: file://assertions/customCheck.js

Servidor MCP

Promptfoo incluye un servidor de Protocolo de Contexto de Modelo (MCP) para la integración con asistentes de IA como Claude Code:

promptfoo mcp

Esto permite a los agentes de IA:

• Ejecutar evaluaciones directamente desde el chat.
• Acceder a las capacidades de "red team".
• Consultar resultados almacenados.
• Generar nuevos casos de prueba.

Casos de uso en el mundo real

Chatbot de soporte al cliente

Una empresa SaaS utiliza promptfoo para probar su chatbot de soporte antes de cada despliegue:

• 500 casos de prueba que cubren preguntas comunes.
• Evaluación entre GPT-4 y Claude para comparar la calidad.
• Escaneos de "red team" para fugas de PII y jailbreaks.
• La integración CI bloquea los despliegues con evaluaciones fallidas.

Resultado: Reducción del 90% en los problemas reportados por los clientes después de implementar evaluaciones automatizadas.

Pipeline de generación de contenido

Un equipo de marketing valida el contenido generado por IA para la voz de la marca:

• Las evaluaciones calificadas por LLM verifican el tono y el estilo.
• Los umbrales de latencia garantizan una generación rápida.
• La monitorización de costos mantiene los gastos bajo control.
• La comparación de modelos encuentra el proveedor con mejor valor.

Resultado: Voz de marca consistente en todo el contenido con un 40% menos de costos de API.

Aplicación de atención médica

Una startup de tecnología de la salud garantiza el cumplimiento con pruebas estrictas:

• Escaneos de "red team" para violaciones de HIPAA.
• Aserciones personalizadas que validan la precisión médica.
• Todas las evaluaciones se ejecutan localmente para la privacidad de los datos.
• Registros de auditoría para requisitos regulatorios.

Resultado: Auditoría SOC 2 aprobada con las evaluaciones de promptfoo como evidencia.

Conclusión

Promptfoo lleva las pruebas sistemáticas a las aplicaciones LLM. Reemplaza los procesos manuales y propensos a errores con evaluaciones automatizadas que detectan regresiones, problemas de seguridad y problemas de calidad antes del despliegue.

Puntos clave:

• Instale con npm install -g promptfoo y empiece con promptfoo init.
• Utilice aserciones para validar las salidas más allá de la coincidencia exacta de cadenas.
• Ejecute escaneos de "red team" para encontrar vulnerabilidades de seguridad.
• Integre con CI/CD para bloquear las regresiones.
• Compare modelos objetivamente con evaluaciones lado a lado.
• Los proveedores y aserciones personalizadas amplían la funcionalidad.

El futuro del desarrollo de IA está impulsado por los datos. Con promptfoo, usted tiene las herramientas para construir, probar y asegurar aplicaciones LLM a escala.

Si también trabaja con APIs, considere usar Apidog junto con promptfoo. Apidog se encarga del diseño, las pruebas y la documentación de las APIs, mientras que promptfoo se centra en la evaluación de LLM. Juntos cubren la pila completa de pruebas de aplicaciones modernas.

Preguntas frecuentes

¿Para qué se utiliza promptfoo?

Promptfoo se utiliza para probar y evaluar aplicaciones LLM. Ejecuta pruebas automatizadas contra prompts, compara resultados entre modelos y realiza evaluaciones de seguridad de "red team" para encontrar vulnerabilidades.

¿Es promptfoo gratuito?

Sí, promptfoo es de código abierto y tiene licencia MIT. Puede usarlo de forma gratuita para proyectos personales y comerciales. Las características en la nube y el soporte empresarial pueden requerir planes de pago.

¿Cómo instalo promptfoo?

Ejecute npm install -g promptfoo para una instalación global. También puede usar npx promptfoo@latest sin instalar, o instalar a través de brew install promptfoo en macOS o pip install promptfoo para Python.

¿Qué modelos soporta promptfoo?

Promptfoo soporta más de 90 proveedores de LLM, incluyendo OpenAI (GPT-4, GPT-4o, o1), Anthropic (Claude 3.5/4/4.5), Google (Gemini), Microsoft (Azure OpenAI), Amazon Bedrock y modelos locales a través de Ollama.

¿Cómo ejecuto un escaneo de "red team"?

Ejecute promptfoo redteam init para crear una configuración, luego promptfoo redteam run para ejecutar el escaneo de seguridad. Vea los resultados con promptfoo redteam report.

¿Puedo usar promptfoo en CI/CD?

Sí. Instale promptfoo en su pipeline de CI y ejecute promptfoo eval con su archivo de configuración. Establezca puertas de calidad con la opción threshold para hacer que la CI falle si las evaluaciones no cumplen las tasas de aprobación.

¿Promptfoo envía mis datos a servidores externos?

No. Promptfoo se ejecuta 100% localmente por defecto. Sus prompts y datos de prueba nunca abandonan su máquina a menos que usted opte explícitamente por funciones en la nube. Los archivos de caché y base de datos se almacenan localmente.

¿Cómo comparo modelos con promptfoo?

Liste múltiples proveedores en su archivo de configuración, luego ejecute promptfoo eval. Vea la comparación en la interfaz web con promptfoo view, que muestra las tasas de aprobación/falla, costos y latencia para cada modelo.