AI Search

AI Search ist ein offizielles natives Plugin, das veröffentlichte Inhalte in eine Cloudflare-AI-Search-Instanz indexiert und der Site Suchergebnisse liefert. Es hält den Index aktuell, wenn sich Inhalte ändern, und läuft auf Cloudflare Workers und Node.js.

Installation

Installieren Sie das Paket von npm:

pnpm add @emdash-cms/plugin-ai-search

Fügen Sie aiSearch() in astro.config.mjs zu plugins hinzu:

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { aiSearch } from "@emdash-cms/plugin-ai-search";

export default defineConfig({
	integrations: [
		emdash({
			plugins: [aiSearch()],
		}),
	],
});

Verbinden Sie das Plugin anschließend entweder über ein Workers-Binding oder über ein API-Token mit AI Search. Wenn eine Site beides konfiguriert hat, verwendet das Plugin das Binding.

Mit einem Workers-Binding verbinden

Fügen Sie auf Cloudflare Workers ein AI-Search-Namespace-Binding zu wrangler.jsonc hinzu:

{
	"ai_search_namespaces": [{ "binding": "AI_SEARCH", "namespace": "default" }],
}

Mit einem API-Token verbinden

Auf jeder Plattform kann das Plugin AI Search über die Cloudflare-REST-API erreichen. Dafür benötigt es Ihre Cloudflare-Konto-ID und ein API-Token mit den Konto-Berechtigungen AI Search Edit und AI Search Run. Erstellen Sie im Cloudflare-Dashboard unter Manage account > Account API tokens ein Konto-API-Token. Anders als ein Benutzer-Token funktioniert es weiter, wenn die Person, die es erstellt hat, das Konto verlässt. Ein Benutzer-Token mit denselben Berechtigungen funktioniert ebenfalls.

Legen Sie die Zugangsdaten als Umgebungsvariablen fest:

EMDASH_AI_SEARCH_ACCOUNT_ID=your-account-id
EMDASH_AI_SEARCH_API_TOKEN=your-api-token

Alternativ können Sie sie auf der Einstellungsseite des Plugins im Admin eingeben. EmDash speichert das Token verschlüsselt, daher erfordert das Speichern dort EMDASH_ENCRYPTION_KEY; siehe Secrets. Eine Umgebungsvariable hat Vorrang vor einem im Admin gespeicherten Wert, und der Admin zeigt an, dass sie gesetzt ist, ohne ihren Wert anzuzeigen.

Das Plugin verwendet den Namespace default des Kontos. Um einen anderen zu verwenden, setzen Sie EMDASH_AI_SEARCH_NAMESPACE. Wählen Sie den Namespace, bevor Sie den Index aufbauen, denn das Plugin legt seine Instanz in diesem Namespace ab. Wenn Sie ihn später ändern, meldet die Einstellungsseite, dass die Instanz fehlt. Wählen Sie Edit setup und schließen Sie die Einrichtung ab, um die Instanz zu erstellen und den Index neu aufzubauen. Wenn Sie das Konto auf der Einstellungsseite ändern, geschieht dies automatisch.

Mit einem API-Token verursachen die Indexierung, der Admin und jede Suche eines Besuchers Cloudflare-API-Anfragen, und Cloudflare begrenzt jedes Token auf 1.200 Anfragen alle 5 Minuten. Ein Workers-Binding zählt nicht auf dieses Limit, daher sollten stark frequentierte Sites auf Workers eines verwenden.

Um innerhalb des Limits zu bleiben, nutzt die Indexierung höchstens die Hälfte davon, sodass der Aufbau des Index etwa eine Stunde pro 7.000 Datensätze dauert. Außerdem erlaubt jeder EmDash-Prozess einem Besucher 30 Suchanfragen pro Minute, gezählt pro IP-Adresse. Eine selbst gehostete Site hinter einem Reverse-Proxy muss trustedProxyHeaders konfigurieren, damit das Suchlimit greift; ohne vertrauenswürdige Client-IP werden Suchanfragen nicht begrenzt.

Optionen

Umgebungsvariablen

Das Plugin ignoriert diese Variablen, wenn ein Workers-Binding verfügbar ist.

Suche zur Site hinzufügen

Fügen Sie die Komponente AiSearch zu einem Layout hinzu. Sie rendert eine Suchschaltfläche und öffnet den Suchdialog, auch mit Cmd/Strg+K, daher sollten Sie sie nur einmal pro Seite rendern:

---
import { AiSearch } from "@emdash-cms/plugin-ai-search/astro";
---

<AiSearch placeholder="Search content" />

Den Index aufbauen

Öffnen Sie nach dem Deployen AI Search im Admin. Wenn das Plugin AI Search noch nicht erreichen kann, fragt die Seite nach einer Konto-ID und einem API-Token. Der Einrichtungsassistent wählt dann die zu indexierenden Inhalte aus, zeigt für jede Quelle eine Beispieladresse eines Ergebnisses an und baut den Index auf, sobald Sie Build index wählen. Die Suche ist live, sobald der Aufbau beginnt, wobei Ergebnisse erscheinen, während Dokumente indexiert werden. Spätere Inhaltsänderungen aktualisieren den Index automatisch.