Cómo usar Cloudflare Clef: tutorial práctico de la API

Para usar Cloudflare Clef, envía la información de la aplicación en state, define preguntas tipadas en questions y llama a @cf/cloudflare/clef mediante Workers AI. Lee las probabilidades devueltas y aplica tus propias reglas para seleccionar una acción. Puedes empezar con REST y trasladar el mismo cuerpo de decisión a un Cloudflare Worker.

Clef es un modelo de decisiones multimodal de 27.000 millones de parámetros. Resulta útil cuando el software necesita evaluar opciones predefinidas: qué cola debe recibir un ticket, si la información indica una interrupción del servicio o qué gravedad parece tener. La referencia oficial del modelo documenta la interfaz alojada.

Este tutorial desarrolla un ejemplo de asignación de tickets de soporte, desde el diseño del esquema hasta su puesta en producción. La documentación y los precios se comprobaron el 3 de octubre de 2026. Los ejemplos de código se contrastaron con los contratos publicados; no se ejecutaron contra una cuenta de inferencia real. Todas las probabilidades de ejemplo son sintéticas.

Índice

• Elige una decisión que merezca modelarse
• Construye el estado y el esquema de preguntas
• Llama a la API REST de Cloudflare Clef
• Lee correctamente la respuesta
• Usa Clef dentro de un Cloudflare Worker
• Establece umbrales con tus propios datos
• Añade imágenes y comprende el autoalojamiento
• Calcula los costes de Cloudflare Clef
• Corrige los errores habituales de integración
• Evalúa y despliega el flujo de trabajo
• Preguntas frecuentes

Elige una decisión que merezca modelarse

Empieza con una acción acotada que ya tenga un responsable y un resultado medible. En este ejemplo, la aplicación debe asignar un ticket de soporte a accounts, billing o review. Un resultado correcto significa que el equipo receptor puede resolver el problema sin transferirlo a otro.

Escribe esa definición antes de redactar un prompt. «Entender al cliente» es demasiado amplio para evaluarlo. «Identificar al equipo responsable del principal problema pendiente» proporciona a los revisores una tarea concreta.

Algunas decisiones no necesitan un modelo. Si el estado de una suscripción almacenado determina el acceso a una función, consulta la base de datos. Si una factura supera un umbral fijo, compara los números mediante código. Reserva Clef para interpretar información cuyo significado no pueda determinarse de forma fiable con una regla sencilla.

Separa la ruta seleccionada de los permisos de ejecución. Una clasificación como billing puede abrir una cola de facturación; no debe aprobar por sí sola un reembolso. Nuestra introducción a Cloudflare Clef ofrece más contexto sobre esta división de responsabilidades.

Para aplicaciones con agentes, define los destinos antes de elegir el modelo. El flujo de asignación de modelos y herramientas es un complemento útil cuando una decisión selecciona una herramienta u otro modelo en lugar de un equipo de soporte.

Construye el estado y el esquema de preguntas

Utiliza state para el material que se va a evaluar. Emplea instructions y criteria de cada pregunta para definir el juicio. Mantén el texto escrito por el cliente fuera de la rúbrica de confianza.

El esquema de entrada del servicio alojado exige model, state y questions. Cada pregunta requiere type e instructions; choice y score también requieren criteria.

Tipo	Para qué utilizarlo	Forma de los criterios
choice	Seleccionar un destino con nombre	Objeto que relaciona los identificadores de las opciones con sus descripciones
noul	Evaluar una proposición de sí o no	Descripciones opcionales de verdadero y falso
score	Valorar una rúbrica ordenada de impacto	Array ordenado de menor a mayor

Haz que las descripciones de las opciones se distingan entre sí. «Acceso a la cuenta» y «disputa de pago» delimitan responsabilidades diferentes. «Problema urgente» y «problema técnico» se solapan porque la urgencia y la responsabilidad son dimensiones distintas. Formula dos preguntas cuando necesites dos dimensiones.

Incluye deliberadamente una ruta review para la falta de información y los casos que no encajen en tus categorías. De lo contrario, toda solicitud inusual tendrá que competir por un destino normal, lo que puede ocultar una taxonomía deficiente detrás de un resultado aparentemente concluyente.

Al construir el estado, incluye contexto pertinente con un origen explícito. El aviso de un cliente de que el proceso de pago no funciona difiere de una observación sobre el estado del servicio. Añade marcas temporales a la información cambiante, identifica los campos desconocidos y evita incorporar historial irrelevante solo porque esté disponible.

Versiona el esquema junto con la aplicación. Cambiar el significado de «impacto importante» cambia la tarea, aunque las claves JSON sigan siendo idénticas. Una versión estable del esquema permite interpretar las comparaciones posteriores.

Antes de conectar la API, prueba manualmente algunos contraejemplos. Un cliente puede mencionar un pago mientras solicita restablecer su contraseña; otro puede iniciar sesión, pero disputar un cargo duplicado. Tu definición de asignación debe explicar por qué esos tickets corresponden a equipos diferentes. Si dos revisores no pueden ponerse de acuerdo utilizando únicamente la rúbrica, refínala antes de pedir a un modelo que la aplique.

Llama a la API REST de Cloudflare Clef

Primero obtén tu identificador de cuenta de Cloudflare y un token de API de Workers AI. La guía de configuración de REST de Cloudflare describe la plantilla de tokens del panel; los tokens creados manualmente necesitan los permisos Read y Edit de Workers AI. Guarda las credenciales en tu entorno local o en el almacén de secretos del servidor.

Guarda este ejemplo original como decision.json. Formula tres preguntas relacionadas sobre un mismo ticket:

{
  "model": "clef",
  "state": {
    "ticket": "I paid yesterday, but password resets still do not let me sign in.",
    "paymentStatus": "settled",
    "serviceHealth": "unknown"
  },
  "questions": {
    "owner": {
      "type": "choice",
      "instructions": "Choose the team for the primary unresolved issue.",
      "criteria": {
        "accounts": "Sign-in, credentials, or account access",
        "billing": "Unresolved charges, refunds, or payment disputes",
        "review": "Missing evidence or no matching team"
      }
    },
    "accessBlocked": {
      "type": "noul",
      "instructions": "Does the customer report being unable to sign in?"
    },
    "impact": {
      "type": "score",
      "instructions": "Rate the disruption supported by this ticket.",
      "criteria": [
        "No current disruption",
        "Partial disruption with a workaround",
        "Customer cannot access the service"
      ]
    }
  }
}

Una vez configuradas CLOUDFLARE_ACCOUNT_ID y CLOUDFLARE_API_TOKEN, envía el archivo:

curl --fail-with-body \
  "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/ai/run/@cf/cloudflare/clef" \
  -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary @decision.json

El modelo del endpoint y el selector del cuerpo coinciden de forma intencionada: @cf/cloudflare/clef corresponde a "model": "clef". Empieza con esta solicitud pequeña para poder aislar fácilmente los errores de autenticación y de esquema.

Después de la primera solicitud correcta, guarda una respuesta sin datos sensibles como muestra de desarrollo. Registra junto a ella la versión del esquema. Esa muestra permite ejercitar el procesamiento de respuestas sin realizar una solicitud de inferencia de pago cada vez que modifiques la interfaz.

Para un cliente de producción, establece un tiempo de espera de la solicitud, distingue los fallos de inferencia de las respuestas inciertas y define un destino alternativo. Reintenta los fallos transitorios dentro de un presupuesto limitado. Un reintento no debe hacer que la aplicación que lo engloba cree dos veces el mismo ticket de soporte.

Lee correctamente la respuesta

La API REST utiliza el contenedor de respuesta de Cloudflare. Tras comprobar el estado HTTP y success, accede al resultado del modelo dentro de result. Un enlace de Workers AI devuelve directamente el resultado del modelo.

Según el esquema de salida de Clef, estas son las rutas pertinentes:

Valor	Ruta en la respuesta REST	Ruta en el enlace del Worker
Equipo seleccionado	result.answers.owner.choice	answers.owner.choice
Probabilidades de los equipos	result.answers.owner.probabilities	answers.owner.probabilities
Bloqueo de acceso comunicado	result.answers.accessBlocked.noul	answers.accessBlocked.noul
Nivel de impacto esperado	result.answers.impact.score	answers.impact.score
Uso de entrada	result.usage.input_tokens	usage.input_tokens

Una respuesta noul es un objeto que contiene un campo numérico noul, no un simple booleano. Las respuestas choice y score también incluyen confidence. Las puntuaciones son índices de nivel ponderados por probabilidad y pueden situarse entre niveles.

Por ejemplo, una distribución de impacto sintética de 0.10, 0.20 y 0.70 en los niveles 0, 1 y 2 da como resultado 1.60. Ese valor no es una etiqueta de gravedad ni una estimación de riesgo del 160 %. Tu política debe traducirlo al significado operativo que necesites.

Valida los identificadores de pregunta y los tipos de respuesta esperados antes de realizar la asignación. Trata los campos ausentes o mal formados como un fallo de integración, con una categoría de registro distinta de una clasificación review ordinaria. Esta distinción ayuda a determinar si debes corregir el código de la aplicación o mejorar el diseño de la decisión.

Usa Clef dentro de un Cloudflare Worker

En un proyecto de Worker existente, incorpora un enlace AI a tu configuración de Wrangler:

{
  "ai": {
    "binding": "AI"
  }
}

Copia el archivo decision.json anterior junto al archivo de entrada del Worker. Este ejemplo de JavaScript importa ese cuerpo fijo y devuelve una recomendación de asignación:

import decisionInput from "./decision.json";

export default {
  async fetch(_request, env) {
    try {
      const result = await env.AI.run(
        "@cf/cloudflare/clef",
        decisionInput
      );
      const owner = result.answers?.owner;
      const allowed = ["accounts", "billing", "review"];
      const probability = owner?.probabilities?.[owner.choice];

      if (
        owner?.type !== "choice" ||
        !allowed.includes(owner.choice) ||
        typeof probability !== "number" ||
        probability < 0 || probability > 1
      ) {
        throw new Error("Unexpected owner answer");
      }

      // Illustrative threshold: replace after evaluation.
      const route = probability >= 0.85 ? owner.choice : "review";
      return Response.json({ route, probability });
    } catch {
      return Response.json(
        { route: "review", error: "Decision unavailable" },
        { status: 503 }
      );
    }
  }
};

La guía de enlaces de Workers explica la configuración y el desarrollo local con npx wrangler dev. La inferencia de Workers AI sigue utilizando recursos de Cloudflare durante el desarrollo local y puede generar cargos.

Este endpoint basado en una muestra demuestra el enlace, el acceso a la respuesta y la alternativa en caso de fallo. Integrar tickets reales requiere la autenticación, la validación de entrada y los límites de solicitudes existentes en tu aplicación. Construye el esquema de preguntas de confianza en el servidor; acepta la información del ticket mediante una estructura de entrada acotada, en lugar de exponer un proxy de inferencia sin restricciones.

El corte de 0.85 ilustra dónde debe situarse la política. No es un valor predeterminado de Clef ni una recomendación validada experimentalmente. El siguiente paso consiste en sustituirlo por un umbral elegido a partir de tu propia evaluación.

Establece umbrales con tus propios datos

Una probabilidad alta solo resulta útil si predice resultados fiables para los casos que recibes. No interpretes el campo independiente confidence como una tasa de éxito verificada por separado. Elige la estadística que utilizará tu política, documéntala y evalúa esa política exacta.

Para asignar colas, empieza por la probabilidad de la opción seleccionada. También puedes examinar la diferencia entre las dos probabilidades más altas. Una competencia ajustada entre cuentas y facturación puede revelar una intención realmente mixta; también puede revelar descripciones de categorías poco diferenciadas.

Construye un conjunto de validación etiquetado y compara varios umbrales candidatos. Para cada uno, mide la exactitud de la asignación entre los tickets gestionados automáticamente y la proporción enviada a revisión. Elevar un umbral suele intercambiar cobertura por selectividad, pero el punto operativo útil depende de tus datos y del coste de los errores.

Considera un conjunto de validación sintético de 1.000 tickets. Un umbral asigna automáticamente 800 tickets, de los que 720 son correctos: un 80 % de cobertura y un 90 % de exactitud entre los casos asignados. Un umbral más estricto asigna 500, de los que 480 son correctos: un 50 % de cobertura y un 96 % de exactitud de asignación. Ninguna política es universalmente mejor. Compara el coste de una revisión adicional con el de enviar a un cliente al equipo equivocado. Examina también qué categorías desaparecen de la gestión automática al aumentar el umbral; una mejora global puede ocultar un servicio desigual.

Para calibrar, agrupa las predicciones en intervalos de probabilidad y compara la probabilidad prevista con la corrección observada. Si las predicciones cercanas a 0.90 solo son correctas el 70 % de las veces, los valores de probabilidad muestran un exceso de confianza en esa muestra. Separa el trabajo de calibración de la evaluación final con datos reservados.

Utiliza políticas distintas para acciones diferentes. Asignar mal un ticket y cambiar una credencial de cuenta tienen consecuencias distintas. Nuestro flujo de seguridad de prompts explica comprobaciones de decisiones que pueden acompañar a controles explícitos de ejecución.

Añade imágenes y comprende el autoalojamiento

Para decisiones visuales alojadas, añade images a la solicitud mediante URL de datos incrustados u objetos que contengan content_type y base64. El contrato de entrada del servicio alojado acepta PNG, JPEG y WebP; no acepta URL remotas de imágenes convencionales. Especifica un máximo de cuatro imágenes, 4 MiB y 16 megapíxeles por imagen, 8 MiB de tamaño decodificado conjunto y un límite de 13 MiB para el cuerpo de la solicitud.

Una primera tarea práctica consiste en decidir si una captura de pantalla contiene visiblemente un error de inicio de sesión. Acompaña la imagen con una pregunta específica y contexto pertinente. Si tu aplicación necesita números extraídos exactos, verifica la extracción antes de aplicar reglas aritméticas.

La ficha del modelo en Hugging Face describe otra vía de ejecución: descargar la versión publicada, cargar su red base y su cabezal conjunto de esquema, y utilizar las funciones auxiliares joint_schema_model incluidas. Sus ejemplos utilizan load_release_model y systemone. La versión se distribuye con licencia Apache-2.0, y su entorno de pruebas documentado utiliza una sola H200 con PyTorch 2.11 y Transformers 5.10.2.

Las funciones auxiliares locales también describen imágenes PIL y arrays de fotogramas de vídeo. Eso no demuestra compatibilidad con vídeo en el servicio alojado: el esquema alojado actual documenta imágenes, no un campo de solicitud para vídeo. Su límite de codificación predeterminado es de 16.384 tokens, distinto de la ventana de contexto alojada; comprueba la configuración de tu despliegue.

Elige el autoalojamiento cuando el control del entorno de servicio justifique encargarte de operarlo. Presupuesta memoria GPU, procesamiento por lotes, supervisión y actualizaciones. Para una integración inicial, la API alojada reduce el número de sistemas que debes diagnosticar a la vez.

Calcula los costes de Cloudflare Clef

La tabla de precios de Workers AI indica 0,24 USD por millón de tokens de entrada para Clef y 0,09 USD por millón de tokens de entrada para Clef-flash, según la comprobación del 3 de octubre de 2026.

Para una carga ilustrativa de 100.000 solicitudes con una media de 1.200 tokens de entrada cada una, el uso de entrada suma 120 millones de tokens. Aplicar las tarifas publicadas da como resultado 28,80 USD para Clef o 10,80 USD para Clef-flash. Estos cálculos cubren los cargos por entrada del modelo antes de las cuotas incluidas y otros costes de plataforma; no constituyen una estimación completa de la factura mensual.

Utiliza el uso registrado en solicitudes representativas para sustituir la media supuesta. Los historiales largos de tickets, las rúbricas detalladas, los reintentos y las entradas visuales pueden cambiar la carga de trabajo. Registra también el gasto de la revisión humana: una inferencia más barata no implica necesariamente un flujo de trabajo más barato si genera más tareas manuales.

Compara los modelos con los mismos casos etiquetados y la misma política de aceptación. Para probar Clef-flash, cambia tanto el identificador del endpoint a @cf/cloudflare/clef-flash como el selector del cuerpo a "model": "clef-flash". Registra la latencia y la calidad junto con el coste, en lugar de elegir exclusivamente por la tarifa de tokens.

Corrige los errores habituales de integración

La mayoría de los fallos iniciales pertenecen a una de estas cuatro categorías:

Síntoma	Lo primero que debes revisar
Fallo de autenticación	Identificador de cuenta, alcance del token y carga del entorno
Fallo de validación de la solicitud	Instrucciones obligatorias, forma de los criterios y selector del modelo
JavaScript lee respuestas indefinidas	Contenedor REST frente a salida directa del enlace
Decisiones plausibles pero inadecuadas	Calidad de la información, opciones solapadas y ausencia de una ruta de revisión

No envíes un cuerpo messages de estilo chat simplemente porque otro modelo de Workers AI lo acepte. Utiliza el contrato de decisiones documentado de Clef. Del mismo modo, evita interpretar answers.owner como una cadena o esperar una explicación en prosa en un campo de respuesta de chat.

Para registros largos, selecciona deliberadamente la información pertinente. La página del modelo alojado indica una ventana de contexto de 65.536 tokens y señala que los estados de texto largos se truncan. Conserva los hechos necesarios para la decisión antes de llegar a ese límite.

Cuando las predicciones parezcan incorrectas, examina un caso de principio a fin: la información exacta enviada, la versión del esquema, la distribución completa y la regla final de la aplicación. Cambiar primero el modelo puede dejar intacto el error original de los datos o de la política.

Evalúa y despliega el flujo de trabajo

Empieza con tickets históricos que reflejen las rutas, los idiomas y los patrones de falta de información que esperas encontrar. Etiqueta el principal problema pendiente independientemente de la salida del modelo. Resuelve los desacuerdos entre revisores antes de considerar esas etiquetas una referencia fiable.

Divide la colección en conjuntos de desarrollo, validación y evaluación reservada. Utiliza los casos de desarrollo para mejorar el esquema, los de validación para establecer umbrales y el conjunto reservado para decidir finalmente si se publica. Evita repartir entre esos conjuntos tickets casi duplicados de una misma conversación.

Registra al menos la corrección de las asignaciones, la tasa de revisión, los errores por ruta, la latencia de respuesta, los fallos de inferencia y el coste por decisión aceptada. Examina por separado las rutas poco frecuentes; una media global sólida puede ocultar errores repetidos en una categoría pequeña pero importante.

Mantén un pequeño registro de errores con un motivo para cada fallo revisado: falta de información, rúbrica ambigua, error del modelo o error en la política de la aplicación. Esas categorías sugieren correcciones diferentes. Añade el caso corregido a una colección de regresión, pero no ajustes repetidamente contra tu conjunto final reservado. Una referencia determinista sencilla también resulta valiosa: indica si el nuevo paso de inferencia mejora el flujo de trabajo lo suficiente como para justificar su complejidad.

Ejecuta el modo sombra antes de la asignación automática: registra lo que elegiría Clef mientras continúan las operaciones existentes. Compara esas recomendaciones con los resultados reales. Después, habilita una fracción pequeña y reversible del tráfico y conserva una alternativa inmediata.

Guarda el identificador del modelo, la versión del esquema, la política de decisión y el origen de la entrada con cada resultado. Revisa las desviaciones cuando cambien los productos, las categorías de soporte o el lenguaje de los clientes. El centro de documentación de Jev ofrece material relacionado para aplicaciones basadas en decisiones tipadas.

Preguntas frecuentes

¿Puedo usar Cloudflare Clef sin desplegar un Worker?

Sí. Utiliza el endpoint REST asociado a la cuenta con un token de Workers AI. Un Worker resulta útil cuando quieres situar la llamada de decisión junto al procesamiento de solicitudes y la política de la aplicación.

¿Debo usar choice o varias preguntas noul?

Utiliza choice cuando la aplicación deba seleccionar un destino entre opciones competidoras. Utiliza preguntas noul separadas cuando varias condiciones independientes puedan ser verdaderas a la vez. Define si esas condiciones pueden solaparse antes de interpretar sus resultados.

¿Sustituye Clef a un modelo de chat?

Utilízalo para decisiones con respuestas especificadas. Si el siguiente paso consiste en redactar un correo electrónico, combina la ruta seleccionada y el contexto verificado con un flujo de generación adecuado. Mantén su salida sujeta a las mismas reglas de la aplicación.

¿Una puntuación alta significa que el modelo tiene confianza?

No. Una puntuación de impacto alta significa que la masa de probabilidad favorece los niveles superiores de la rúbrica. La confianza describe otra propiedad de la distribución. Comprueba las probabilidades reales y evalúa la estadística que controle tu acción.

¿Qué debo construir primero?

Implementa una decisión, una alternativa explícita y un pequeño conjunto de evaluación etiquetado. Cuando puedas explicar los fallos y medir una cobertura aceptable, amplía el esquema o añade otro flujo de trabajo.