Implémentation de la recherche intra-site pour un site multilingue avec Cloudflare AI Search

Nous l'avons mise en place sur notre propre site, construit avec une architecture Astro SSG + CMS headless.
La procédure d'installation elle-même était assez simple, mais comme notre site est multilingue, nous avons rencontré quelques difficultés.

Qu'est-ce que Cloudflare AI Search ?

Anciennement connu sous le nom d'AutoRAG, il a été renommé en septembre 2025. Attention, la plupart des articles qui apparaissent dans les résultats de recherche mentionnent l'ancien nom et l'ancienne API.

Voici l'ensemble du processus pris en charge par le service.

Exploration → conversion en Markdown → découpage en fragments → vectorisation → construction d'un index vectoriel et par mots-clés

L'API propose deux systèmes. Le premier, search, renvoie la liste des résultats de recherche, tandis que le second, chat/completions, génère des réponses via RAG. Nous n'utiliserons ici que le premier.

Points clés de la configuration

Créez l'instance comme suit.

• Sélectionnez WebCrawl comme source de données
• URL publique comme cible de crawl
• Type d'analyse : sitemap
• Spécifiez l'élément main comme sélecteur de contenu
• Mode d'analyse : site statique
• Spécifiez sitemap.xml dans un sitemap particulier
• Modèle d'embedding : @cf/baai/bge-m3 (pour un site en japonais)

Pour le reste, les valeurs par défaut conviennent.

Authentification et variables d'environnement

Créez un jeton API à partir de votre compte.
Point d'attention : il ne suffit pas d'activer « AI Search: Lecture », il faut aussi les autorisations « Modifier » et « Exécuter ».
Le jeton créé est chargé via la variable d'environnement AI_SEARCH_TOKEN.

Architecture : une route API et un composant

La recherche passe par une route API d'Astro (fonctionnant comme Pages Functions), qui appelle l'API REST. Comme le jeton API ne peut pas être exposé dans le navigateur, un proxy côté serveur est indispensable. De plus, Pages Functions ne prenant pas en charge le binding AI Search, j'ai utilisé un simple fetch plutôt que le 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
        },
      },
    }),
  }
);

La mise en œuvre se limite à deux fichiers : la route API et le composant d'interface de recherche. Ajouter cette fonctionnalité a posteriori à un site SSG s'est révélé très léger.

Sur un site multilingue, limiter la recherche à la langue affichée

Pour une recherche classique sur un site, cela suffit. Cependant, sur un site multilingue, la recherche lit le sitemap.xml qui contient toutes les langues, si bien que les résultats se mélangent.

La solution consiste à définir une métadonnée personnalisée locale et à filtrer la recherche avec filters. Ainsi, seuls les résultats de la langue consultée sont affichés.
Attention : cette information ne peut pas être déduite de l'attribut lang du HTML ni de og:locale.

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

Séparer le sitemap SEO du sitemap de recherche

AI Search (source de données Website) explore le site via le sitemap.

Or, le sitemap public de notre site excluait volontairement certaines langues pour des raisons de SEO. Résultat : la recherche renvoyait systématiquement 0 résultat dans ces langues.

Comme le sitemap est généré avec @astrojs/sitemap, j'ai choisi de générer séparément un sitemap couvrant toutes les langues, destiné à la recherche.

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

Cela diffère assez de ce que l'on imagine à partir du terme « recherche IA ».

AI Search découpe le contenu japonais en segments d'environ 300 à 450 caractères.
Jusqu'à 50 segments pertinents sont sélectionnés, et les pages qui les contiennent apparaissent dans les résultats.
Les pages contenant les segments jugés les plus pertinents figurent en tête. Plusieurs segments pouvant être retenus d'une même page, le nombre de résultats est inférieur à 50.

L'agrégation au niveau des pages est effectuée côté frontend. De plus, l'IA générative n'intervient à aucun moment dans l'ensemble de ce processus.

Conclusion

Pour le mettre en place, il faut que la zone DNS du domaine soit gérée par Cloudflare et que le site fonctionne sur Pages / Workers. Cependant, l'implémentation est simple, et cela peut être très utile pour ajouter une recherche interne de manière rapide et basique.

À l'inverse, si vous souhaitez ajouter une recherche sans toucher à l'infrastructure, afficher l'intégralité des résultats, ou disposer de fonctions d'administration destinées aux exploitants comme l'analyse des requêtes, les suggestions ou les dictionnaires de synonymes, une solution ASP traditionnelle reste plus performante.

Cela dit, un ASP paraît trop lourd, mais la recherche reste indispensable. Pour un site de cette taille, cette option me semble très pertinente.