La API: env.AI.run, mensajes, parámetros y respuesta

La API de Workers AI es deliberadamente estrecha: un método, env.AI.run, que toma el identificador de un modelo y un objeto con las entradas, y devuelve una promesa. No hay cliente que instanciar, ni sesión que abrir, ni conexión que mantener. Esa estrechez es una virtud, porque desplaza toda la complejidad a un único sitio donde puedes concentrarte: la forma del objeto de entradas y la forma de la respuesta, que cambian según la modalidad del modelo y son, en la práctica, lo único que hay que aprender de verdad.

La firma: un modelo y unas entradas

El método acepta dos argumentos obligatorios y uno opcional. El primero es la cadena que identifica el modelo. El segundo es un objeto cuyas claves dependen por completo de la modalidad: un modelo de texto espera prompt o messages, uno de embeddings espera text, uno de transcripción espera audio, uno de difusión espera prompt y devuelve bytes. El tercero, opcional, lleva opciones de la propia plataforma, como el encaminamiento a través de AI Gateway.

export default {
  async fetch(request, env, ctx): Promise<Response> {
    const salida = await env.AI.run(
      "@cf/meta/llama-3.1-8b-instruct",
      { prompt: "Resume en dos frases que es un isolate de V8" },
      { gateway: { id: "mi-gateway" } },
    );

    return Response.json(salida);
  },
} satisfies ExportedHandler<Env>;

La forma con prompt es la más simple y sirve para peticiones de un solo turno sin contexto previo. Por debajo, el runtime la envuelve en la plantilla de conversación que ese modelo espera, así que no estás hablando con un modelo base: estás usando un atajo. En cuanto necesites instrucciones de sistema, historial o control fino, el atajo se queda corto y hay que pasar a los mensajes.

Si has regenerado los tipos con wrangler types, el editor te ayudará: las entradas y las salidas están tipadas por modelo, de modo que escribir una clave que ese modelo no acepta se convierte en un error de compilación en lugar de en una respuesta rara en producción.

Mensajes: la conversación como estructura de datos

La forma canónica de hablar con un LLM es un array de mensajes, donde cada elemento tiene un role y un content. Los tres roles hacen cosas distintas y confundirlos es la primera fuente de resultados mediocres.

const messages = [
  {
    role: "system",
    content:
      "Eres un asistente tecnico. Respondes en espanol, en dos frases " +
      "como maximo, sin adornos ni disculpas.",
  },
  { role: "user", content: "Que diferencia hay entre KV y D1?" },
  { role: "assistant", content: "KV es clave-valor con consistencia eventual..." },
  { role: "user", content: "Y para un contador exacto?" },
];

const salida = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
  messages,
  max_tokens: 256,
});

El rol system fija el comportamiento: quién es el modelo, en qué idioma responde, qué formato debe seguir, qué no debe hacer. Es el sitio donde van las reglas estables, no los datos de la petición. El rol user lleva lo que pregunta la persona y también el contexto recuperado que quieras inyectar. El rol assistant guarda lo que el modelo respondió en turnos anteriores, y es lo que convierte una secuencia de llamadas independientes en una conversación con memoria.

Ese último punto tiene una implicación que sorprende a mucha gente: la llamada no guarda estado. Cada invocación es completamente independiente, y si quieres continuidad tienes que reenviar el historial entero cada vez. La memoria vive en tu aplicación —en un Durable Object, en D1, en KV—, no en el modelo. Y como el historial crece, crece también el número de tokens que pagas y el riesgo de rebasar la ventana de contexto, así que tarde o temprano necesitarás una política: truncar por los turnos más antiguos, resumir lo anterior, o ambas.

Los parámetros que gobiernan la generación

Junto a los mensajes viajan parámetros que modulan cómo se produce el texto. No son muchos y merece la pena conocerlos bien, porque ajustarlos suele mejorar más el resultado que cambiar de modelo.

De todos ellos, max_tokens es el que más disciplina impone y el que más gente olvida. Sin techo, un modelo puede irse por las ramas durante miles de tokens que pagas íntegros y que multiplican la latencia; con un techo ajustado a lo que tu interfaz puede mostrar, el coste queda acotado por construcción. Y temperature merece una regla mental sencilla: si vas a parsear la salida, quieres determinismo, así que cerca de cero; si vas a mostrarla a una persona, un poco de variedad se agradece.

El parámetro que cambia arquitecturas es response_format. Pedirle a un modelo que responda en JSON dentro del mensaje de sistema funciona la mayoría de las veces, y esa mayoría es justamente el problema. Declarando un esquema, el runtime restringe la generación para que la salida sea válida por construcción.

const salida = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
  messages: [
    { role: "system", content: "Extraes datos de un texto de soporte." },
    { role: "user", content: texto },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      type: "object",
      properties: {
        sentimiento: { type: "string", enum: ["positivo", "neutro", "negativo"] },
        urgencia: { type: "number" },
        tema: { type: "string" },
      },
      required: ["sentimiento", "urgencia", "tema"],
    },
  },
});

Leer la respuesta sin suposiciones

La salida no tiene una forma única: la tiene por modalidad, y asumir la equivocada es el error más frecuente al saltar de un modelo a otro. Un modelo de texto devuelve un objeto con la propiedad response. Uno de embeddings devuelve un objeto con data, un array de vectores, y shape con sus dimensiones. Whisper devuelve text y, según la variante, segmentos con marcas de tiempo. Un modelo de difusión no devuelve un objeto sino un ReadableStream de bytes de imagen.

// texto: la propiedad response
const { response } = await env.AI.run(modeloTexto, { messages });

// embeddings: un array de vectores en data
const { data, shape } = await env.AI.run("@cf/baai/bge-m3", {
  text: ["primer parrafo", "segundo parrafo"],
});

// transcripcion: la propiedad text
const { text } = await env.AI.run("@cf/openai/whisper-large-v3-turbo", {
  audio: [...new Uint8Array(await request.arrayBuffer())],
});

// difusion: bytes, no JSON
const imagen = await env.AI.run("@cf/black-forest-labs/flux-1-schnell", {
  prompt: "un faro al amanecer, estilo acuarela",
});
return new Response(imagen, { headers: { "content-type": "image/png" } });

Y por encima de la forma está la fiabilidad. Una inferencia puede fallar por límite de peticiones, por sobrecarga puntual o por una entrada inválida, así que la llamada va dentro de un try y con un plan para el fallo: reintentar con espera creciente ante un 429, degradar a un modelo más pequeño, o devolver una respuesta útil sin IA. Si además pediste JSON, valida el resultado con tu propio esquema antes de confiar en él: el modelo cumple el formato, pero el contenido sigue siendo suyo.