Implémenter une recherche intra-site multilingue avec Cloudflare AI Search

Nous l'avons implémenté sur notre site propre conçu avec Astro SSG + headless CMS.
La procédure d'intégration en elle-même était assez simple, mais comme notre site est multilingue, nous avons rencontré quelques pièges.

Qu'est-ce que Cloudflare AI Search ?

Anciennement appelée AutoRAG, elle a été renommée en septembre 2025. Attention : la plupart des articles de recherche et de la documentation concernent l'ancien nom et l'ancienne API.

Voici l'ensemble du processus qu'elle effectue.

Crawl → conversion en Markdown → fractionnement en chunks → intégration → construction d'index vectoriel + mots-clés

L'API se décline en deux versions : search qui retourne une liste de résultats de recherche, et chat/completions qui génère une réponse via RAG. Nous n'utilisons que la première.

Points clés de la configuration

Créez une instance comme suit.

• Sélectionnez WebCrawl comme source de données
• URL publique à explorer
• Type d'analyse : sitemap
• Sélecteur de contenu défini sur l'élément main
• Mode d'analyse : site statique
• Spécifier sitemap.xml dans le sitemap particulier
• Modèle d'intégration défini sur @cf/baai/bge-m3 (pour les sites en japonais)

Sinon, les paramètres par défaut conviennent parfaitement.

Authentification et variables d'environnement

Créez un jeton API à partir de votre compte.
Important : vous avez besoin non seulement de « AI Search : lecture », mais aussi de « modifier » et « exécuter ».
Le jeton créé est chargé via la variable d'environnement AI_SEARCH_TOKEN.

Configuration : 1 route API + 1 composant

La recherche interroge l'API REST via une route API d'Astro (fonctionnant comme Pages Functions). Comme on ne peut pas exposer le jeton API au navigateur, un proxy côté serveur est essentiel. Puisque Pages Functions n'a pas de liaison pour AI Search, nous utilisons fetch brut au lieu du 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
        },
      },
    }),
  }
);

L'implémentation ne comprend que 2 fichiers : la route API et le composant d'interface de recherche. C'est très léger comme complément au SSG.

Sur les sites multilingues, limiter la recherche à la langue affichée

Pour une recherche de site ordinaire, cela suffirait. Mais en multilingue, comme sitemap.xml contient toutes les langues, les résultats de recherche se mélangent.

La solution consiste à définir des métadonnées personnalisées locale et à filtrer avec filters lors de la recherche. Cela garantit que seuls les résultats dans la langue consultée s'affichent.
Attention : on ne peut pas se fier à l'attribut lang du HTML ou à og:locale.

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

Séparer le sitemap SEO du sitemap de recherche

AI Search (source de données Website) effectue le crawl via le sitemap.

Or, notre sitemap public exclut volontairement certaines langues pour des raisons SEO. Cela a entraîné un problème : zéro résultat de recherche pour ces langues.

Puisque nous générons le sitemap avec @astrojs/sitemap, nous avons opté pour une sortie séparée du sitemap de recherche incluant toutes les langues.

Comment les résultats de recherche sont-ils classés ?

C'est assez différent de ce qu'on imagine en entendant le terme « Recherche IA ».

AI Search divise le contenu en japonais en chunks d'environ 300 à 450 caractères.
Un maximum de 50 chunks pertinents sont sélectionnés, et les pages les contenant s'affichent dans les résultats.
Les pages contenant des chunks jugés hautement pertinents apparaissent en haut des résultats. Comme plusieurs chunks peuvent être sélectionnés sur une même page, le nombre de résultats est souvent inférieur à 50.

L'agrégation au niveau de la page est effectuée côté frontend. Et tout au long de ce processus, l'IA générative n'intervient pas une seule fois.

Conclusion

Son implémentation nécessite que le domaine soit hébergé sur Cloudflare et que Pages/Workers soient utilisés, mais la mise en place est simple et facilement accessible. Pour les cas où l'on souhaite implémenter une recherche interne de site sans complexité excessive, c'est une excellente option.

À l'inverse, si vous souhaitez ajouter la recherche sans toucher à l'infrastructure, afficher tous les résultats, ou si vous avez besoin de fonctionnalités d'administration pour les responsables comme l'analyse des logs de recherche, les suggestions ou les dictionnaires de synonymes, une solution ASP traditionnelle sera plus robuste.

Cela dit, implémenter un ASP peut être lourd, mais la recherche est indispensable. Pour les sites de cette envergure, c'est une option très pertinente.