Implementación de búsqueda interna en sitios multilingües con Cloudflare AI Search

Lo implementamos en nuestro propio sitio, construido con Astro SSG y un CMS headless.
El proceso de configuración en sí fue bastante sencillo, pero como nuestro sitio tiene una estructura multilingüe, nos encontramos con algunos puntos complicados.

¿Qué es Cloudflare AI Search?

Anteriormente se llamaba AutoRAG; cambió de nombre en septiembre de 2025. Muchos artículos que aparecen en las búsquedas utilizan el nombre y la API antiguos, así que conviene tenerlo en cuenta.

Esto es lo que hace todo el proceso:

Rastreo → conversión a Markdown → división en fragmentos → incrustación → construcción del índice vectorial y de palabras clave

La API tiene dos variantes. Una devuelve una lista de resultados de search, y la otra genera respuestas con RAG mediante chat/completions. En este caso solo usamos la primera.

Puntos clave de la configuración

Cree la instancia de la siguiente manera.

• Seleccione WebCrawl como fuente de datos
• URL pública como objetivo del rastreo
• Tipo de análisis: mapa del sitio
• Especifique el elemento main como selector de contenido
• Modo de análisis: sitio estático
• Especifique sitemap.xml como mapa del sitio concreto
• Modelo de incrustación: @cf/baai/bge-m3 (porque el sitio está en japonés)

Por lo demás, la configuración predeterminada funciona sin problemas.

Autenticación y variables de entorno

Crea un token de API desde tu cuenta.
Ten en cuenta que no basta con "AI Search: Lectura"; también necesitas "Edición" y "Ejecución".
El token creado se carga mediante la variable de entorno AI_SEARCH_TOKEN.

Estructura: 1 ruta de API + 1 componente

La búsqueda realiza llamadas a la API REST desde una ruta de API de Astro (que funciona como Pages Functions). Como no se puede exponer el token de API en el navegador, es indispensable hacer un proxy en el lado del servidor. Además, Pages Functions no tiene un binding para AI Search, así que se usa fetch nativo en lugar del SDK.

// Astro の API ルート（Pages Functions として動く）
const res = await fetch(
  `https://api.cloudflare.com/client/v4/accounts/${id}/ai-search/instances/${name}/search`,
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` },
    body: JSON.stringify({
      query,
      ai_search_options: {
        retrieval: {
          retrieval_type: 'hybrid',
          max_num_results: 50
        },
      },
    }),
  }
);

Solo implementamos dos archivos: una ruta de API y un componente de interfaz de búsqueda. Como incorporación a un sitio SSG, resultó ser una implementación bastante ligera.

En sitios multilingües, limita la búsqueda al idioma de visualización

Para una búsqueda interna convencional, esto bastaría. Sin embargo, en sitios multilingües, el índice lee un sitemap.xml que incluye todos los idiomas, por lo que los resultados de distintos idiomas terminan mezclándose.

La solución consiste en definir los metadatos personalizados locale y filtrar la búsqueda con filters. De este modo, solo se muestran en los resultados los contenidos del idioma que el usuario está viendo.
Nota: no es posible determinar el idioma a partir del atributo lang del HTML ni de og:locale, así que hay que tener cuidado.

<meta name="locale" content="ja_JP">

Separar el sitemap de SEO y el sitemap de búsqueda

AI Search (fuente de datos de tipo Website) rastrea el sitio a través del sitemap.

Sin embargo, el sitemap público de nuestro sitio excluía intencionalmente algunos idiomas por razones de SEO. Como resultado, las búsquedas en esos idiomas devolvían siempre 0 resultados.

Como el sitemap se genera con @astrojs/sitemap, optamos por generar por separado un sitemap que incluya todos los idiomas para la búsqueda.

Cómo se ordenan los resultados de búsqueda

Dista bastante de lo que uno imagina al escuchar el término "búsqueda con IA".

AI Search divide el contenido en japonés en fragmentos de unos 300 a 450 caracteres.
Se seleccionan hasta 50 fragmentos relevantes y se muestran las páginas que los contienen en los resultados.
Las páginas con fragmentos considerados más relevantes aparecen primero. Como de una misma página pueden seleccionarse varios fragmentos, el número de resultados puede ser inferior a 50.

La agrupación por página se realiza en el frontend. Además, en todo este proceso la IA generativa no interviene en ningún momento.

Conclusión

Para implementarlo, es necesario que la zona del dominio esté en Cloudflare y que el sitio funcione con Pages / Workers. Aun así, la implementación es sencilla, y creo que resulta muy útil si se quiere añadir una búsqueda interna de forma rápida y sencilla.

Por el contrario, si se quiere añadir la búsqueda sin tocar la infraestructura, mostrar todos los elementos o contar con funciones de gestión para administradores, como análisis de registros de búsqueda, sugerencias o diccionarios de sinónimos, un ASP tradicional es más adecuado.

Sin embargo, un ASP resulta demasiado pesado, pero la búsqueda sigue siendo necesaria. Creo que esta es una opción muy adecuada para sitios de esa escala.