Site-Suche für mehrsprachige Websites mit Cloudflare AI Search implementieren

Wir haben es auf unserer eigenen Website implementiert, die mit Astro SSG und einem Headless CMS aufgebaut ist.
Der Implementierungsprozess selbst war relativ einfach, aber da unsere Website mehrsprachig ist, gab es mehrere Stolpersteine.

Was ist Cloudflare AI Search?

Früher hieß es AutoRAG und wurde im September 2025 umbenannt. Achten Sie darauf, dass viele der Artikel, die Sie bei der Suche finden, unter dem alten Namen oder mit der alten API geschrieben wurden.

Dies ist der gesamte Prozess, den es durchführt.

Crawlen → Markdown-Konvertierung → Chunk-Aufteilung → Einbettung → Indexerstellung für Vektor + Schlüsselwörter

Es gibt zwei API-Systeme: search, das eine Liste mit Suchergebnissen zurückgibt, und chat/completions, das mit RAG Antworten generiert. Wir verwenden hier nur letzteres.

Konfigurationspunkte

Erstellen Sie eine Instanz wie folgt.

• Wählen Sie WebCrawl als Datenquelle.
• Öffentliche URL für das Crawling
• Analyse-Typ als Sitemap
• Inhalts-Selektor mit main-Element
• Analyse-Modus: Statische Website
• Spezifisches Sitemap als sitemap.xml angeben
• Einbettungsmodell auf @cf/baai/bge-m3 setzen (für japanische Websites)

Ansonsten sind die Standardeinstellungen in Ordnung.

Authentifizierung und Umgebungsvariablen

Erstellen Sie ein API-Token vom Konto.
Wichtig: Es ist nicht nur "AI Search: Lesen" erforderlich, sondern auch "Bearbeiten" und "Ausführen".
Das erstellte Token wird über die Umgebungsvariable AI_SEARCH_TOKEN geladen.

Konfiguration: 1 API-Route + 1 Komponente

Die Suche wird über eine REST API aus einer Astro-API-Route (die als Pages Function funktioniert) durchgeführt. Da das API-Token nicht im Browser verfügbar gemacht werden kann, ist eine Proxy-Implementierung auf der Serverseite erforderlich. Da Pages Functions keine AI-Search-Bindung haben, verwenden wir einen rohen fetch anstelle des 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
        },
      },
    }),
  }
);

Implementiert wurden nur zwei Dateien: eine API-Route und eine Such-UI-Komponente. Als nachträgliche Erweiterung für SSG war das sehr leicht umzusetzen.

Bei mehrsprachigen Websites die Suchergebnisse auf die angezeigte Sprache beschränken

Bei einer normalen Website-Suche würde das ausreichen, aber bei mehreren Sprachen wird die sitemap.xml mit allen Sprachen gelesen, was dazu führt, dass sich die Suchergebnisse vermischen.

Die Lösung besteht darin, ein benutzerdefiniertes Metadatenfeld locale zu definieren und bei der Suche filters zu verwenden. Dies stellt sicher, dass nur die aktuell angezeigte Sprache in den Suchergebnissen angezeigt wird.
Beachten Sie, dass dies nicht aus dem HTML-Attribut lang oder og:locale bestimmt werden kann.

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

SEO-Sitemap und Such-Sitemap trennen

AI Search (Website-Datenquelle) crawlt über die Sitemap.

Unsere öffentliche Sitemap schloss jedoch aus SEO-Gründen absichtlich einige Sprachen aus. Dies führte dazu, dass die Suche in diesen Sprachen immer 0 Ergebnisse zurückgab.

Da wir @astrojs/sitemap zur Sitemap-Generierung verwenden, geben wir eine separate Sitemap mit allen Sprachen speziell für die Suche aus.

Wie werden die Suchergebnisse sortiert?

Es unterscheidet sich erheblich von dem, was man sich unter dem Begriff „AI-Suche" vorstellt.

AI Search teilt japanischen Text in Chunks von etwa 300–450 Zeichen auf.
Bis zu 50 relevante Chunks werden ausgewählt, und die Seiten, auf denen diese enthalten sind, erscheinen in den Ergebnissen.
Seiten, die Chunks mit hoher Relevanz enthalten, werden oben angezeigt. Da von einer Seite mehrere Chunks ausgewählt werden können, ist die Anzahl der Suchergebnisse geringer als 50.

Die Aggregation auf Seitenbasis wird auf der Frontend-Seite durchgeführt. Und in diesem gesamten Verarbeitungsprozess wird generative KI kein einziges Mal verwendet.

Fazit

Die Implementierung setzt voraus, dass die Domain-Zone bei Cloudflare gehostet wird und Sie das Projekt über Pages/Workers verwalten. Allerdings ist die Implementierung relativ einfach und unkompliziert – für Fälle, in denen Sie eine einfache Sitesuche benötigen, scheint es mir eine sehr praktische Lösung zu sein.

Wenn Sie hingegen die Infrastruktur nicht ändern und Suchfunktionalität später hinzufügen möchten, alle Einträge anzeigen wollen oder administrative Funktionen wie Suchprotokollanalyse, Suggestions und Wörterbücher für Synonyme benötigen, ist das traditionelle ASP-Modell stärker.

Allerdings ist die Integration einer ASP schwer, aber suchen möchte man trotzdem. Ich denke, das ist eine ziemlich gute Lösung für Websites in diesem Maßstab.