Cómo evaluar la calidad de aplicaciones de IA con Braintrust y Webflow Cloud

Una función de IA puede devolver un código 200 y renderizarse sin errores, pero aun así estar equivocada. El modelo entrega una respuesta segura pero incorrecta que ningún rastreador de excepciones detecta, ya que no hubo ningún fallo; por lo tanto, la regresión permanece en producción hasta que alguien lee el resultado con suficiente atención como para notarlo.

El problema era que no tenía forma de medir la calidad de los resultados, ni registro de lo que pedían los usuarios reales, ni una suite de pruebas para detectar regresiones al cambiar el prompt. Braintrust te ayuda a solucionar las tres cosas. Registra cada llamada de IA desde tu aplicación en Webflow Cloud, puntúa los resultados según los criterios que definas y ejecuta una suite de evaluación en CI, de modo que un cambio en el prompt que reduzca la calidad haga fallar la compilación en lugar de llegar a los usuarios.

El SDK de Braintrust funciona en el entorno de Cloudflare Workers de Webflow Cloud, pero debes vaciar los registros antes de que el Route Handler devuelva su respuesta. Cloudflare Workers puede congelar o terminar el contexto de una solicitud en el momento en que se envía la respuesta, y cualquier registro no vaciado se pierde. La solución es una llamada await logger.flush() , explicada en el Paso 2.

¿Qué necesitas para evaluar la calidad de una aplicación de IA con Braintrust en Webflow Cloud?

Necesitas una aplicación de Webflow Cloud que ya realice llamadas de IA, una cuenta de Braintrust y una clave de API del proveedor de modelos que elijas. Braintrust tiene un plan gratuito que cubre el desarrollo y el registro de producción de bajo volumen.

Aquí tienes la lista completa de lo que necesitas:

• Un proyecto de Webflow Cloud con al menos un Route Handler de IA (por ejemplo, el endpoint de Gemini u OpenAI que ya hayas publicado)
• Una cuenta de Braintrust (braintrust.dev/signup)
• Una clave de API de Braintrust (desde Settings > API keys)
• Una clave de API del proveedor del modelo (OpenAI, Anthropic, Gemini, el que use tu aplicación)
• Node.js 22.13.0 o superior instalado localmente para ejecutar evaluaciones desde la línea de comandos. El SDK de Braintrust no establece un mínimo, por lo que el requisito de Webflow CLI 2.x es la restricción vinculante.

La división que debes tener en cuenta: el registro se ejecuta en producción en el edge; las evaluaciones se ejecutan localmente o en CI sobre Node. La misma estructura de datos de Braintrust respalda ambos, lo que hace que el flujo de trabajo sea muy sólido.

6 pasos para evaluar la calidad de aplicaciones de IA con Braintrust en Webflow Cloud

El flujo de trabajo tiene dos mitades que se alimentan mutuamente. La parte de tiempo de ejecución añade el registro de Braintrust a tus Route Handlers de Webflow Cloud para que cada llamada de IA en producción se convierta en un rastro rastreable. La parte de desarrollo crea una suite de evaluación con casos de prueba y puntuadores, la ejecuta con la CLI de Braintrust y compara experimentos para demostrar que un cambio ayuda antes de publicarlo. Los rastros de producción se convierten entonces en casos de prueba de evaluación, lo que cierra el ciclo.

Ahora ejecuto ambas mitades en cada función de IA. El registro me dice qué está pasando en producción. Las evaluaciones me dicen si un cambio que estoy a punto de publicar mejora o empeora las cosas.

1. Crea un proyecto en Braintrust y obtén tu clave de API

Regístrate en braintrust.dev. Al iniciar sesión por primera vez, Braintrust crea un proyecto predeterminado; también puedes crear uno con nombre desde el panel principal. Ponle un nombre que coincida con tu aplicación de Webflow Cloud para que los registros y experimentos se mantengan agrupados.

Ve a Ajustes > Claves de API y crea una clave. Cópiala.

Añade la clave de Braintrust y la clave de tu proveedor de modelos a y a Ajustes > Variables de entorno de Webflow Cloud:.env.local

BRAINTRUST_API_KEY=sk-your-braintrust-key
OPENAI_API_KEY=sk-your-openai-key

Ninguna de las claves lleva un prefijo. Ambas se utilizan únicamente en el lado del servidor, dentro de los manejadores de rutas y scripts de evaluación. Una clave de proveedor de modelos en el paquete del navegador permitiría que cualquiera ejecutara inferencias en tu cuenta.NEXT_PUBLIC_

A continuación, instala el SDK de Braintrust y la biblioteca de puntuación:

npm install braintrust autoevals

El paquete se encarga del registro y las evaluaciones. es una biblioteca de evaluadores predefinidos (coincidencia exacta, veracidad, similitud de incrustaciones y otros) que utilizarás en el paso 4.braintrustautoevals

2. Añade el registro de Braintrust a un manejador de rutas de IA de Webflow Cloud

El registro de Braintrust captura cada llamada de IA como un seguimiento que puedes inspeccionar, filtrar y convertir más tarde en casos de prueba. La configuración consiste en más alrededor de tu cliente de modelo para que las llamadas se rastreen automáticamente.initLoggerwrapOpenAI

En Webflow Cloud, ambas deben crearse dentro del manejador en el momento de la solicitud, ya que las variables de entorno no están disponibles al cargar el módulo. El otro detalle del entorno de ejecución en el borde es la llamada antes de que se devuelva la respuesta.flush

Aquí tienes el fragmento:

// app/api/ai/route.ts
import { initLogger, wrapOpenAI } from 'braintrust'
import OpenAI from 'openai'
import { NextResponse, type NextRequest } from 'next/server'

export async function POST(request: NextRequest) {
  // Initialize at request time. On Webflow Cloud, environment variables
  // are available at runtime only, not at module load, so the logger and
  // client must be created inside the handler.
  const logger = initLogger({
    projectName: 'my-webflow-cloud-app',
    apiKey: process.env.BRAINTRUST_API_KEY,
  })

  // wrapOpenAI traces every model call automatically.
  const client = wrapOpenAI(
    new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
  )

  const { prompt } = await request.json() as { prompt: string }

  try {
    const completion = await client.chat.completions.create({
      model: 'gpt-4o',
      messages: [
        { role: 'system', content: 'You are a helpful assistant.' },
        { role: 'user', content: prompt },
      ],
    })

    const output = completion.choices[0].message.content

    // CRITICAL on edge: flush before the response returns.
    // Cloudflare Workers can freeze the context after the response,
    // dropping any unflushed logs.
    await logger.flush()

    return NextResponse.json({ output })
  } catch (error) {
    await logger.flush()
    return NextResponse.json({ error: 'AI request failed' }, { status: 500 })
  }
}

La llamada es la única línea que la gente suele pasar por alto. Sin ella, el registro funciona perfectamente en el desarrollo local (donde el proceso de Node permanece activo) y luego descarta silenciosamente la mayoría de los registros en producción (donde el Worker se congela después de responder). Vacía el registro tanto en las rutas de éxito como en las de error para que las llamadas fallidas también queden registradas.await logger.flush()

3. Rastrea un contexto más rico en tus llamadas de IA de Webflow Cloud

wrapOpenAIrastrea la llamada al modelo en sí. Para que los registros sean útiles para la evaluación, adjunta los metadatos que quieras filtrar y puntuar más tarde: la entrada del usuario, la salida final de tu aplicación y cualquier contexto, como un ID de usuario o el nombre de una función. Usa para envolver una unidad de trabajo en un intervalo y para adjuntar campos.tracedspan.log

Así es como se ve:

// app/api/ai/route.ts (excerpt)
import { initLogger, wrapOpenAI, traced } from 'braintrust'
import OpenAI from 'openai'

export async function POST(request: NextRequest) {
  // Create the logger and client at request time (see Step 2).
  const logger = initLogger({
    projectName: 'my-webflow-cloud-app',
    apiKey: process.env.BRAINTRUST_API_KEY,
  })
  const client = wrapOpenAI(
    new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
  )

  const { prompt, userId } = await request.json() as {
    prompt: string
    userId?: string
  }

  const output = await traced(
    async (span) => {
      const completion = await client.chat.completions.create({
        model: 'gpt-4o',
        messages: [
          { role: 'system', content: 'You are a helpful assistant.' },
          { role: 'user', content: prompt },
        ],
      })

      const result = completion.choices[0].message.content

      // Attach structured fields for later filtering and scoring.
      span.log({
        input: prompt,
        output: result,
        metadata: { userId, feature: 'content-assistant' },
      })

      return result
    },
    { name: 'content-assistant' }
  )

  await logger.flush()
  return NextResponse.json({ output })
}

Los campos se convierten en columnas filtrables en la vista de registros de Braintrust. Cuando una función específica empieza a producir resultados erróneos, filtras por y lees los prompts y respuestas reales en lugar de adivinar. Los campos y son los que utilizarás más tarde para crear un conjunto de datos de evaluación.metadatafeature:content-assistantinputoutput

Si tu aplicación de Webflow Cloud enruta las llamadas al modelo a través de Cloudflare AI Gateway, también las rastrea. Apunta el cliente de OpenAI a tu punto de enlace de la pasarela, y Braintrust capturará las llamadas de la misma manera, con el almacenamiento en caché y la limitación de tasa de la pasarela por delante.wrapOpenAIbaseURL

4. Escribe una suite de evaluación de Braintrust para tu función de IA de Webflow Cloud

Una evaluación mide la calidad de la IA frente a casos de prueba en lugar de basarse en intuiciones. Cada evaluación tiene tres partes: datos (casos de prueba con entradas y salidas esperadas), una tarea (la función de IA bajo prueba) y puntuaciones (funciones que califican el resultado).

Crea un archivo de evaluación junto al código de tu aplicación; se ejecuta en Node, no en el borde, por lo que vive fuera de tus manejadores de rutas.

// evals/content-assistant.eval.ts
import { Eval } from 'braintrust'
import { Factuality, ExactMatch } from 'autoevals'
import OpenAI from 'openai'

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

// The same logic your Route Handler runs, isolated for testing.
async function runAssistant(prompt: string): Promise<string> {
  const completion = await client.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: prompt },
    ],
  })
  return completion.choices[0].message.content ?? ''
}

Eval('my-webflow-cloud-app', {
  experimentName: 'content-assistant-v1',
  // Data: test cases with inputs and expected outputs.
  data: [
    {
      input: 'Summarize the benefits of server-side rendering in one sentence.',
      expected:
        'Server-side rendering improves initial load time and SEO by sending fully rendered HTML to the browser.',
    },
    {
      input: 'What runtime does a Next.js app run on in Webflow Cloud?',
      expected: 'Cloudflare Workers, via the OpenNext Cloudflare adapter.',
    },
  ],
  // Task: the function being evaluated.
  task: async (input) => runAssistant(input),
  // Scores: how output quality is measured.
  // Factuality is an LLM-as-a-judge scorer; it grades whether
  // the output is consistent with the expected answer.
  scores: [Factuality],
})

Factualityes un evaluador de tipo "LLM-as-a-judge" de ; califica si el resultado coincide con la respuesta esperada en lugar de requerir una coincidencia carácter por carácter. Para resultados con un valor correcto (un slug, un sí/no, un ID), usa en su lugar. También puedes escribir un evaluador personalizado: cualquier función que devuelva una puntuación entre 0 y 1.autoevalsExactMatch

5. Ejecuta la evaluación de Braintrust y compara experimentos

Ejecutar la evaluación crea un experimento, un registro permanente de cómo funcionó tu IA en los casos de prueba. Comparar dos experimentos es la forma de demostrar que un cambio en el prompt o en el modelo realmente ayudó antes de que llegue a tu aplicación de Webflow Cloud.

Instala la CLI de Braintrust y ejecuta la evaluación:

# Install the bt CLI (macOS and Linux)
curl -fsSL https://bt.dev/cli/install.sh | bash

# Run the eval
bt eval evals/content-assistant.eval.ts

La terminal imprime una tabla resumen y un enlace al experimento en la interfaz de Braintrust. Para probar un cambio, edita el prompt del sistema o cambia el modelo, incrementa la experimentName (por ejemplo, content-assistant-v2), y vuelve a ejecutar. Braintrust muestra los dos experimentos lado a lado, con la diferencia de puntuación para cada caso de prueba.

Este es el momento en que todo el esfuerzo da sus frutos. En lugar de pensar "el nuevo prompt se siente mejor", obtienes una diferencia de puntuación por caso: qué casos mejoraron, cuáles empeoraron y en qué medida. Un cambio que reduce la puntuación es visible de inmediato, antes de que cualquier usuario lo vea.

6. Convierte los registros de producción de Webflow Cloud en conjuntos de datos de evaluación de Braintrust

Los casos de prueba más sólidos provienen del uso real, no de tu imaginación. Dado que los registros de producción y los conjuntos de datos de evaluación comparten la misma estructura en Braintrust, convertir un seguimiento registrado en un caso de prueba solo requiere unos pocos clics. Así es como se conectan las partes de ejecución y desarrollo.

En la interfaz de Braintrust, abre la página de registros (Logs), filtra por la función o el patrón de error que te interese (usando los metadatos que adjuntaste en el paso 3), selecciona los seguimientos que representan los casos que quieres proteger y añádelos a un conjunto de datos.

Luego, apunta tu evaluación a ese conjunto de datos en lugar de a la matriz codificada:

import { Eval, initDataset } from 'braintrust'

Eval('my-webflow-cloud-app', {
  experimentName: 'content-assistant-v3',
  // Pull test cases from a dataset built from production logs.
  data: initDataset({ project: 'my-webflow-cloud-app', dataset: 'production-failures' }),
  task: async (input) => runAssistant(input),
  scores: [Factuality],
})

Cada vez que un usuario encuentra un resultado incorrecto en producción, lo capturas, lo añades al conjunto de datos y tu suite de evaluación crece para cubrirlo. Un error que se corrige una vez, no vuelve a aparecer. Para automatizar esto, ejecuta bt eval en tu pipeline de CI en cada pull request; un cambio que haga caer la puntuación por debajo de tu umbral detendrá la compilación.

¿Qué interrumpe la evaluación de calidad de IA en Webflow Cloud con Braintrust?

La mayoría de los problemas de Braintrust en Webflow Cloud caen en cuatro categorías: registros que aparecen localmente pero desaparecen en producción, archivos de evaluación que se niegan a ejecutarse, puntuaciones de veracidad que resultan bajas incluso para buenos resultados y experimentos que nunca aparecen en el panel. Cada uno se remonta a una causa específica en el entorno de ejecución perimetral o en la configuración de evaluación, y cada uno tiene una solución directa.

Los cuatro puntos a continuación cubren lo que encuentro con más frecuencia, en el orden en que suelen aparecer.

Los registros funcionan localmente pero faltan en producción

Este es el problema de vaciado (flush) del paso 2. En el desarrollo local, el proceso de Node permanece activo el tiempo suficiente para que el vaciado en segundo plano de Braintrust se complete, por lo que los registros aparecen. En el entorno de ejecución perimetral de Webflow Cloud, el contexto del Worker puede congelarse en el instante en que se devuelve la respuesta, descartando cualquier cosa que aún no se haya enviado.

Añade await logger.flush() antes de cada return en el manejador de rutas (Route Handler), incluyendo las rutas de error.

La evaluación falla al ejecutarse con un error de módulo o importación

El archivo de evaluación se ejecuta en Node mediante bt eval, no en el Worker. Mantén los archivos de evaluación fuera del directorio app/ para que Next.js no intente empaquetarlos como rutas, y no les añadas una exportación runtime. Webflow Cloud ejecuta tu aplicación a través del adaptador OpenNext Cloudflare, que no admite el entorno de ejecución perimetral de Next.js en ninguna parte del proyecto.

Una carpeta evals/ en la raíz del proyecto es la convención. Si las importaciones siguen fallando, confirma que braintrust y autoevals estén instalados y que tu BRAINTRUST_API_KEY esté configurado en la shell que ejecuta la evaluación.

Todas las puntuaciones de veracidad resultan bajas, incluso para buenos resultados

El evaluador Factuality compara el resultado con el campo expected . Si tus respuestas esperadas están redactadas de forma muy diferente a como responde el modelo (diferente longitud, diferente estructura), el juez puede calificarlas como inconsistentes.

O bien flexibiliza las respuestas esperadas para capturar el hecho central en lugar de la redacción exacta, o cambia a un evaluador que se ajuste mejor a tu tarea. Para la generación abierta, un evaluador personalizado tipo "LLM-as-a-judge" con una rúbrica específica para tu caso de uso supera a uno genérico.

Los experimentos no aparecen en la interfaz de Braintrust

Revisa la salida de la terminal de bt eval para ver el enlace del experimento y cualquier línea de error. La causa más común es una variable de entorno BRAINTRUST_API_KEY faltante o incorrecta en el entorno donde se ejecuta la evaluación.

Confirma que el nombre del proyecto en tu archivo de evaluación coincida con el proyecto que estás viendo en la interfaz; un error tipográfico puede crear un proyecto independiente que parezca vacío.

Amplía la evaluación de calidad de IA en toda tu aplicación de Webflow Cloud

La configuración de esta guía te ofrece el ciclo fundamental: registrar llamadas de IA en producción, escribir evaluaciones, comparar experimentos y reintroducir los fallos reales en tu conjunto de pruebas. Ambas partes se pueden ampliar fácilmente.

Para el registro, añade puntuación en línea para que los seguimientos de producción se califiquen automáticamente a medida que llegan, no solo en evaluaciones fuera de línea. Braintrust puede ejecutar un evaluador contra una muestra de registros en vivo y graficar la puntuación a lo largo del tiempo, convirtiendo la calidad en una métrica de panel que puedes monitorear al igual que la latencia o la tasa de errores.

Para las evaluaciones, integra bt eval en tu flujo de trabajo de CI como una verificación obligatoria. Establece un umbral de puntuación mínima por evaluador; una solicitud de extracción que reduzca la veracidad por debajo del límite fallará antes de fusionarse. Esta es la diferencia entre esperar que un cambio en el prompt sea seguro y tener la certeza de que lo es.

Explora Webflow + Braintrust para ver otros patrones relacionados, desde paneles de evaluación sincronizados con el CMS hasta puertas de calidad que bloquean la publicación hasta que se alcancen las puntuaciones necesarias.