Implementing site search for a multilingual site with Cloudflare AI Search

We implemented it on our own site, which is built with Astro SSG and a headless CMS.
The setup steps themselves were fairly simple, but because our site is multilingual, we ran into a few pitfalls.

What is Cloudflare AI Search?

It was formerly called AutoRAG and was renamed in September 2025. Many articles that show up in search still refer to the old name and old API, so be careful.

This entire sequence is what it handles.

Crawling → Markdown conversion → chunking → embedding → building a vector and keyword index

The API comes in two types. The search endpoint returns a list of search results, and the chat/completions endpoint generates answers using RAG. This time, we only use the former.

Key configuration points

Maak de instantie als volgt aan.

• Selecteer WebCrawl als gegevensbron
• Openbare URL als te crawlen doel
• Analysetype: sitemap
• Geef het main-element op als contentselector
• Analysemodus: statische site
• Geef sitemap.xml op als specifieke sitemap
• Stel het embeddingmodel in op @cf/baai/bge-m3 (omdat de site in het Japans is)

Verder kun je de standaardinstellingen meestal ongewijzigd laten.

Authenticatie en omgevingsvariabelen

Maak een API-token aan vanuit je account.
Let op: naast "AI Search: Lezen" zijn ook "Bewerken" en "Uitvoeren" nodig.
Het aangemaakte token laad je in via de omgevingsvariabele AI_SEARCH_TOKEN.

Opbouw: 1 API-route + 1 component

Zoeken gebeurt via een Astro API-route (die werkt als Pages Function) die de REST API aanroept. Omdat het API-token niet in de browser mag staan, is een proxy aan de serverzijde verplicht. Pages Functions heeft geen AI Search-binding, dus gebruiken we een kale fetch in plaats van de 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
        },
      },
    }),
  }
);

We hebben slechts twee bestanden gebouwd: de API-route en de zoekcomponent. Als achteraf toevoeging aan een SSG-site viel dit erg mee.

Beperk zoekopdrachten op meertalige sites tot de weergavetaal

Voor een gewone zoekfunctie op de site is dit voldoende. Bij meertalige sites leest de zoekfunctie echter sitemap.xml, dat alle talen bevat, waardoor resultaten van verschillende talen door elkaar lopen.

De oplossing is een aangepaste metadata-veld locale te definiëren en tijdens het zoeken te filteren met filters. Zo worden alleen resultaten in de taal van de bezoeker getoond.
Let op: de taal kan niet worden bepaald aan de hand van het lang-attribuut van het html-element of og:locale.

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

Splits de sitemap voor SEO en de sitemap voor zoeken

AI Search (Website-databron) crawlt via de sitemap.

De openbare sitemap van onze site sloot echter om SEO-redenen bewust bepaalde talen uit. Daardoor gaven zoekopdrachten in die talen altijd 0 resultaten.

Omdat de sitemap wordt gegenereerd met @astrojs/sitemap, heb ik ervoor gekozen om een aparte sitemap voor zoekdoeleinden te exporteren die alle talen bevat.

Hoe worden de zoekresultaten gerangschikt?

Het verschilt nogal van wat je bij de term "AI-zoeken" zou verwachten.

AI Search splitst Japanse tekst op in chunks van ongeveer 300 tot 450 tekens.
Er worden maximaal 50 relevante chunks geselecteerd, en de pagina's waarin deze voorkomen, verschijnen in de resultaten.
Pagina's met chunks die als het meest relevant worden beoordeeld, komen bovenaan te staan. Omdat meerdere chunks van dezelfde pagina kunnen worden geselecteerd, is het aantal resultaten soms lager dan 50.

De samenvoeging van chunks tot paginaniveau gebeurt in de frontend. Bij dit hele proces is generatieve AI overigens geen enkele keer ingezet.

Conclusie

Voor implementatie moet de domeinzone bij Cloudflare staan en moet de site draaien op Pages of Workers. De implementatie is echter eenvoudig, en voor het snel toevoegen van een eenvoudige site-zoekfunctie lijkt het me zeer bruikbaar.

Omgekeerd geldt dat een traditionele ASP sterker is wanneer je zonder aan de infrastructuur te komen alleen zoekfunctionaliteit wilt toevoegen, wanneer je alle resultaten wilt tonen, of wanneer je beheerfuncties nodig hebt voor beheerders, zoals zoeklogboekanalyse, suggesties en synoniemenwoordenboeken.

Een ASP installeren is echter zwaar, terwijl je wel zoekfunctionaliteit wilt. Voor sites van die omvang is dit een keuze die goed aansluit, denk ik.