AI Search

AI Search est un plugin natif officiel qui indexe le contenu publié dans une instance Cloudflare AI Search et fournit des résultats de recherche au site. Il maintient l’index à jour au fil des modifications du contenu, et fonctionne sur Cloudflare Workers et Node.js.

Installation

Installez le paquet depuis npm :

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

Ajoutez aiSearch() à plugins dans astro.config.mjs :

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()],
		}),
	],
});

Connectez ensuite le plugin à AI Search avec un binding Workers ou un jeton d’API. Lorsqu’un site possède les deux, le plugin utilise le binding.

Se connecter avec un binding Workers

Sur Cloudflare Workers, ajoutez un binding de namespace AI Search à wrangler.jsonc :

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

Se connecter avec un jeton d’API

Sur n’importe quelle plateforme, le plugin peut accéder à AI Search via l’API REST de Cloudflare. Il a besoin de l’ID de votre compte Cloudflare et d’un jeton d’API disposant des autorisations de compte AI Search Edit et AI Search Run. Créez un jeton d’API de compte sous Manage account > Account API tokens dans le tableau de bord Cloudflare. Contrairement à un jeton utilisateur, il continue de fonctionner si la personne qui l’a créé quitte le compte. Un jeton utilisateur disposant des mêmes autorisations fonctionne également.

Définissez les identifiants comme variables d’environnement :

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

Vous pouvez aussi les saisir sur la page de paramètres du plugin dans l’administration. EmDash stocke le jeton chiffré ; l’enregistrer à cet endroit nécessite donc EMDASH_ENCRYPTION_KEY ; voir Secrets. Une variable d’environnement prévaut sur une valeur enregistrée dans l’administration, et l’administration indique qu’elle est définie sans afficher sa valeur.

Le plugin utilise le namespace default du compte. Pour en utiliser un autre, définissez EMDASH_AI_SEARCH_NAMESPACE. Choisissez le namespace avant de construire l’index, car le plugin conserve son instance dans ce namespace. Si vous le changez plus tard, la page de paramètres signale que l’instance est introuvable. Choisissez Edit setup et terminez la configuration pour créer l’instance et reconstruire l’index. Modifier le compte sur la page de paramètres le fait automatiquement.

Avec un jeton d’API, l’indexation, l’administration et chaque recherche d’un visiteur effectuent des requêtes à l’API Cloudflare, et Cloudflare limite chaque jeton à 1 200 requêtes toutes les 5 minutes. Un binding Workers ne compte pas dans cette limite ; les sites très fréquentés sur Workers devraient donc en utiliser un.

Pour rester dans la limite, l’indexation en utilise au plus la moitié, de sorte que la construction de l’index prend environ une heure pour 7 000 enregistrements. De plus, chaque processus EmDash autorise 30 recherches par minute à un visiteur, comptées par adresse IP. Un site auto-hébergé derrière un proxy inverse doit configurer trustedProxyHeaders pour que la limite de recherche s’applique ; sans IP client de confiance, les recherches ne sont pas limitées.

Options

Variables d’environnement

Le plugin ignore ces variables lorsqu’un binding Workers est disponible.

Ajouter la recherche au site

Ajoutez le composant AiSearch à un layout. Il affiche un bouton de recherche et ouvre la fenêtre modale de recherche, également avec Cmd/Ctrl+K ; ne l’affichez donc qu’une seule fois par page :

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

<AiSearch placeholder="Search content" />

Construire l’index

Après le déploiement, ouvrez AI Search dans l’administration. Si le plugin ne peut pas encore accéder à AI Search, la page demande un ID de compte et un jeton d’API. L’assistant de configuration choisit ensuite le contenu à indexer, affiche un exemple d’adresse de résultat pour chaque source et construit l’index lorsque vous sélectionnez Build index. La recherche est active dès que la construction démarre, les résultats apparaissant au fur et à mesure de l’indexation des documents. Les modifications ultérieures du contenu mettent automatiquement l’index à jour.