Site-wide search implementeren voor meertalige websites met Cloudflare AI Search

We hebben het geïmplementeerd op onze eigen site met een configuratie van Astro SSG + headless CMS.
De implementatiestappen op zich waren vrij eenvoudig, maar omdat onze site meertalig is opgebouwd, liepen we tegen enkele hobbels aan.

Wat is Cloudflare AI Search?

Voorheen bekend als AutoRAG, hernoemd in september 2025. Veel zoekresultaten betreffen de oude naam en oude API, dus let op.

Dat doet het in deze reeks stappen.

Crawlen → Markdown-conversie → Chunksplitsing → Inbedding → Vectoren + trefwoordindexconstructie

Er zijn twee API-systemen: search die zoekresultaten retourneert, en chat/completions die antwoorden genereert met RAG. We gebruiken vandaag alleen de eerste.

Configuratiepunten

Maak een instantie als volgt aan.

• Selecteer WebCrawl als gegevensbron
• Openbare URL's voor verkenning
• Analysetype ingesteld op sitemap
• Content selector ingesteld op main-element
• Analysemodus: statische site
• sitemap.xml opgegeven in specifieke sitemap
• Ingebedde model ingesteld op @cf/baai/bge-m3 (voor Japanse sites)

Verder zijn de standaardinstellingen in orde.

Authenticatie en omgevingsvariabelen

Maak een API-token aan vanuit uw account.
Let op: niet alleen 'AI Search: lezen', maar ook 'Bewerken' en 'Uitvoeren' zijn vereist.
Het gemaakte token wordt gelezen via de omgevingsvariabele AI_SEARCH_TOKEN.

Opzet: 1 API-route + 1 component

Zoeken werkt via een Astro API-route (werkend als Pages Functions) die een REST API aanroept. Omdat API-tokens niet aan de browser kunnen worden blootgesteld, is proxying aan serverzijde noodzakelijk. Omdat Pages Functions geen binding voor AI Search heeft, gebruiken we native 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 2 bestanden geïmplementeerd: een API-route en een zoek-UI component. Als toevoeging aan SSG was dit vrij lichtgewicht.

Zoekresultaten beperken tot de weergegeven taal op meertalige sites

Voor een normale site-zoekfunctie zou dit volstaan, maar bij meertaligheid wordt sitemap.xml in alle talen gelezen, waardoor zoekresultaten vermengd raken.

De oplossing is het definiëren van aangepaste metagegevens locale en filteren op filters bij het zoeken. Dit zorgt ervoor dat alleen de huidige taal in de zoekresultaten verschijnt.
Let op: dit kan niet worden bepaald aan de hand van het HTML lang-attribuut of og:locale.

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

SEO-sitemap en zoeksitemap van elkaar scheiden

AI Search (Website-gegevensbron) crawlt via sitemap.

De openbare sitemap van onze site sluit echter opzettelijk bepaalde talen uit vanuit SEO-overwegingen. Dit resulteerde in een probleem waarbij de zoekresultaten voor die talen altijd 0 items waren.

Omdat we @astrojs/sitemap gebruiken voor sitemap-generatie, hebben we een aparte sitemap voor zoeken met alle talen gegenereerd.

Hoe zijn zoekresultaten geordend?

Het verschilt behoorlijk van wat je je voorstelt als je "AI-zoekopdracht" hoort.

AI Search verdeelt Japanse tekst in chunks van ongeveer 300-450 tekens.
Tot 50 gerelateerde chunks worden opgehaald, en de pagina's die deze chunks bevatten, verschijnen in de resultaten.
Pagina's met chunks die als zeer relevant worden beoordeeld, staan hoger. Omdat meerdere chunks uit één pagina kunnen worden geselecteerd, is het aantal zoekresultaten minder dan 50.

De aggregatie naar paginaniveau wordt aan de front-end gedaan. En in deze hele reeks processen wordt generatieve AI geen enkele keer gebruikt.

Samenvatting

Voor implementatie geldt als voorwaarde dat het domeinzone in Cloudflare ligt en dat het met Pages / Workers wordt beheerd, maar de implementatie is eenvoudig en zeer bruikbaar als je eenvoudige on-site zoekopdrachten wilt instellen.

Aan de andere kant, als je de infrastructuur niet wilt aanraken en alleen zoekopdrachten achteraf wilt toevoegen, of als je alle resultaten wilt tonen, of als je beheerfuncties voor operatoren zoals zoekopdrachtenlogboekanalyse, suggesties en synoniementwoordenboeken nodig hebt, is de traditionele ASP-aanpak sterker.

Dat gezegd hebbende, als een ASP implementeren te zwaar is, maar je toch zoekopdrachten wilt hebben, is dit een zeer aantrekkelijke optie voor sites van die omvang.