Implementar búsqueda del sitio multilingüe con Cloudflare AI Search

Lo implementamos en nuestro sitio corporativo con una configuración de Astro SSG + headless CMS.
El procedimiento de implementación en sí fue bastante simple, pero como nuestro sitio es multiidioma, encontramos algunos obstáculos.

¿Qué es Cloudflare AI Search?

Anteriormente se llamaba AutoRAG y fue rebautizado en septiembre de 2025. Tenga en cuenta que muchos de los artículos que aparecen en los resultados de búsqueda utilizan el nombre anterior o la API anterior.

Realiza toda esta secuencia.

Rastrear → Convertir a Markdown → Dividir en fragmentos → Incrustar → Construir índice de vectores + palabras clave

Hay dos tipos de API. search devuelve una lista de resultados de búsqueda, y chat/completions genera una respuesta con RAG. Esta vez solo usaremos el primero.

Puntos clave de configuración

Cree una instancia de la siguiente manera.

• Seleccione WebCrawl como fuente de datos
• URL pública como destino de rastreo
• Tipo de análisis como sitemap
• Especificar elemento main en el selector de contenido
• Modo de análisis: sitio estático
• Especificar sitemap.xml en el sitemap particular
• Establecer el modelo incrustado en @cf/baai/bge-m3 (para sitios en japonés)

El resto puede mantenerse con la configuración predeterminada sin problemas.

Autenticación y variables de entorno

Crear un token API desde la cuenta.
Nota: además de «AI Search: lectura», también se necesitan «Editar» y «Ejecutar».
El token creado se carga mediante la variable de entorno AI_SEARCH_TOKEN.

Configuración: 1 ruta API + 1 componente

La búsqueda se realiza llamando a la REST API desde una ruta de Astro (que funciona como Pages Functions). Como no se puede exponer el token de API en el navegador, es imprescindible usar un proxy en el lado del servidor. Además, como Pages Functions no tiene un binding para AI Search, usamos fetch sin procesar 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
        },
      },
    }),
  }
);

Lo que implementamos fue solo 2 archivos: la ruta API y el componente de UI de búsqueda. Como complemento a SSG, resultó bastante ligero.

En sitios multilingües, se limita el alcance de la búsqueda al idioma mostrado

Para una búsqueda de sitio normal esto sería suficiente, pero en el caso multilingüe, como se lee el sitemap.xml escrito en todos los idiomas, los resultados de búsqueda se mezclan.

La solución es definir metadatos personalizados locale y filtrar con filters durante la búsqueda. De esta manera, solo los resultados del idioma que se está viendo se muestran.
Tenga en cuenta que no se puede determinar a partir del atributo lang de HTML o de og:locale.

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

Separar el sitemap para SEO del sitemap para búsqueda

AI Search (fuente de datos de Website) realiza el rastreo a través del sitemap.

Sin embargo, el sitemap público de nuestro sitio excluía intencionalmente ciertos idiomas por razones de SEO. Como resultado, en ese idioma siempre había 0 resultados de búsqueda.

Como generamos sitemaps con @astrojs/sitemap, decidimos generar un sitemap separado para búsqueda que incluya todos los idiomas.

¿Cómo se ordenan los resultados de búsqueda?

Es bastante diferente de lo que uno imagina al escuchar el término «búsqueda de IA».

AI Search divide el contenido en japonés en fragmentos de aproximadamente 300 a 450 caracteres.
Se seleccionan hasta 50 fragmentos relevantes, y en los resultados aparecen las páginas que los contienen.
Las páginas que contienen fragmentos identificados como altamente relevantes aparecen en los primeros lugares. Como se pueden seleccionar varios fragmentos de una misma página, el número de resultados es menor a 50.

La agregación a nivel de página se realiza en el frontend. Y en todo este proceso, la IA generativa no interviene ni una sola vez.

Conclusión

Para implementarlo, es necesario que la zona del dominio esté en Cloudflare y que esté operando con Pages / Workers, pero la implementación es sencilla y creo que es muy útil cuando se quiere implementar una búsqueda en el sitio de forma simple.

Por el contrario, si lo que quiere es agregar búsqueda sin tocar la infraestructura, mostrar todos los resultados, o si necesita funciones de administración para operadores como análisis de registros de búsqueda, sugerencias y diccionarios de sinónimos, un ASP tradicional es más robusto.

Dicho esto, si el ASP es demasiado pesado pero necesita búsqueda, para sitios de ese tamaño creo que es una opción muy efectiva.