Caso práctico · IA aplicada a la web
Cómo construimos un chatbot con Cloudflare Workers, D1 y Gemini
De una interfaz web a una arquitectura capaz de responder preguntas, consultar contenido definido para el proyecto y registrar conversaciones. Así organizamos las piezas y los permisos de iachat.
Respuesta rápida
Un chatbot con Cloudflare Workers y Gemini funciona así: la página envía una pregunta al Worker; este valida la solicitud, consulta la información disponible, solicita una respuesta a Gemini cuando corresponde y utiliza D1 para registrar la conversación y administrar límites de uso. La API key permanece como secreto del servidor, fuera del código visible en el navegador.
El problema que queríamos resolver
Queríamos ofrecer un chat de IA en una web pequeña sin administrar un servidor propio para cada solicitud. También necesitábamos conservar un historial de preguntas, controlar el uso y disponer de un panel para revisar las conversaciones.
El proyecto comenzó como un archivo HTML y terminó organizado alrededor de un Worker que atiende la API y sirve los archivos de la interfaz. La base D1 almacena el historial; Gemini genera respuestas cuando la información cargada permite contestar con una fuente definida. Esta separación facilita mantener el contenido, el código y los secretos en lugares distintos.
Interfaz
El widget y la página presentan el chat al visitante y envían sus mensajes a la API.
Worker
Recibe solicitudes, valida el origen, aplica límites, decide qué información usar y coordina la respuesta.
D1 y Gemini
D1 conserva los registros y contadores; Gemini redacta la respuesta cuando existe contenido pertinente.
Diagrama de la arquitectura
El navegador nunca recibe la clave de Gemini. Habla con el Worker, que concentra la lógica de aplicación y utiliza dos servicios: D1 para persistencia y la API de Gemini para generar texto.
El panel de administración consulta el historial a través del Worker y requiere su propia credencial.
Cómo lo configuramos
Creamos el Worker
Partimos de un Worker en el panel de Cloudflare y preparamos el proyecto local para desplegar su código y los archivos de la interfaz desde Ubuntu mediante Wrangler.
Creamos y conectamos D1
La base se llamó iachat. La vinculamos al Worker con el nombre de variable DB, que es el identificador que utiliza el código: env.DB.
Inicializamos el esquema
Ejecutamos SQL en la consola de D1 para crear conversations y rate_limits, junto con índices para consultar el historial. La consola confirmó que la consulta se ejecutó correctamente.
Configuramos orígenes y secretos
Definimos el origen autorizado del navegador y separamos la clave de Gemini, la credencial del panel y el secreto usado para los límites. Las claves no pertenecen al HTML público.
Preparamos el despliegue
Para publicar cambios desde Ubuntu, Wrangler necesita credenciales de Cloudflare. La política buscada para ese token es Workers Editor limitada al Worker del proyecto; su alcance debe revisarse en el resumen del token antes de usarlo.
Decisiones que evitaron errores
- Nombre de base y variable no son lo mismo. La base puede llamarse
iachat; el enlace debe llamarseDBpara que el código encuentreenv.DB. - El archivo local debe reflejar Cloudflare. En
wrangler.jsoncdeben coincidir el nombre y el identificador de la base D1. Así el próximo despliegue conserva el enlace esperado. - El origen tiene que coincidir exactamente. Para CORS se registra el origen de la página, por ejemplo
https://ejemplo.workers.dev, sin ruta ni barra final. - Desplegar no requiere acceso directo a toda D1. Cloudflare indica que para desplegar un Worker con un enlace D1 basta el permiso Editor sobre ese Worker; consultar la base directamente por API es otra operación.
Qué está probado y qué queda por probar: la creación de las tablas fue confirmada por la consola de D1. Antes de presentar el caso como una implementación completa, corresponde registrar una prueba de extremo a extremo: enviar una pregunta, recibir la respuesta esperada y comprobar el registro resultante en D1.
Preguntas frecuentes
¿Para qué sirve D1 en este chatbot?
Guarda preguntas y respuestas para su revisión y mantiene los contadores utilizados por los límites de uso. El Worker accede a la base mediante el enlace DB.
¿Gemini se conecta directamente desde el navegador?
No. El navegador envía la pregunta al Worker. El Worker realiza la solicitud a Gemini con una clave almacenada como secreto.
¿Se necesita un servidor Ubuntu siempre encendido?
No para atender el chat. Ubuntu es el equipo desde el que se prepara y despliega el proyecto con Wrangler. Las solicitudes públicas las atiende el Worker.
¿Es suficiente crear el token de Cloudflare con permiso Editor?
Hay que revisar también su alcance: el permiso Editor puede aplicarse a todos los Workers o a uno específico. Para este proyecto buscamos limitarlo al Worker de iachat.
