AI Search

AI Search è un plugin nativo ufficiale che indicizza i contenuti pubblicati in un’istanza di Cloudflare AI Search e fornisce al sito i risultati di ricerca. Mantiene l’indice aggiornato al variare dei contenuti e funziona su Cloudflare Workers e Node.js.

Installazione

Installa il pacchetto da npm:

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

Aggiungi aiSearch() a plugins in 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()],
		}),
	],
});

Poi collega il plugin ad AI Search con un binding Workers o con un token API. Quando un sito ha entrambi, il plugin usa il binding.

Collegarsi con un binding Workers

Su Cloudflare Workers, aggiungi a wrangler.jsonc un binding di namespace AI Search:

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

Collegarsi con un token API

Su qualsiasi piattaforma, il plugin può raggiungere AI Search tramite l’API REST di Cloudflare. Servono l’ID del tuo account Cloudflare e un token API con i permessi di account AI Search Edit e AI Search Run. Crea un token API di account in Manage account > Account API tokens nella dashboard di Cloudflare. A differenza di un token utente, continua a funzionare anche se la persona che lo ha creato lascia l’account. Funziona anche un token utente con gli stessi permessi.

Imposta le credenziali come variabili d’ambiente:

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

In alternativa, inseriscile nella pagina delle impostazioni del plugin nell’amministrazione. EmDash memorizza il token cifrato, quindi salvarlo lì richiede EMDASH_ENCRYPTION_KEY; vedi Secrets. Una variabile d’ambiente ha la precedenza su un valore salvato nell’amministrazione, e l’amministrazione mostra che è impostata senza mostrarne il valore.

Il plugin usa il namespace default dell’account. Per usarne un altro, imposta EMDASH_AI_SEARCH_NAMESPACE. Scegli il namespace prima di costruire l’indice, perché il plugin mantiene la sua istanza in quel namespace. Se lo cambi in seguito, la pagina delle impostazioni segnala che l’istanza non è presente. Scegli Edit setup e completa la configurazione per creare l’istanza e ricostruire l’indice. Cambiare l’account nella pagina delle impostazioni lo fa automaticamente.

Con un token API, l’indicizzazione, l’amministrazione e ogni ricerca di un visitatore effettuano richieste all’API di Cloudflare, e Cloudflare limita ogni token a 1.200 richieste ogni 5 minuti. Un binding Workers non conta per questo limite, quindi i siti molto frequentati su Workers dovrebbero usarne uno.

Per rimanere entro il limite, l’indicizzazione ne usa al massimo la metà, quindi costruire l’indice richiede circa un’ora ogni 7.000 record. Inoltre ogni processo EmDash consente a un visitatore 30 ricerche al minuto, conteggiate per indirizzo IP. Un sito self-hosted dietro un reverse proxy deve configurare trustedProxyHeaders affinché il limite di ricerca si applichi; senza un IP client attendibile, le ricerche non sono limitate.

Opzioni

Variabili d’ambiente

Il plugin ignora queste variabili quando è disponibile un binding Workers.

Aggiungere la ricerca al sito

Aggiungi il componente AiSearch a un layout. Mostra un pulsante di ricerca e apre la finestra modale di ricerca, anche con Cmd/Ctrl+K, quindi renderizzalo una sola volta per pagina:

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

<AiSearch placeholder="Search content" />

Costruire l’indice

Dopo il deploy, apri AI Search nell’amministrazione. Se il plugin non riesce ancora a raggiungere AI Search, la pagina chiede un ID account e un token API. La procedura guidata di configurazione sceglie poi i contenuti da indicizzare, mostra un indirizzo di risultato di esempio per ogni sorgente e costruisce l’indice quando selezioni Build index. La ricerca è attiva non appena inizia la costruzione, con i risultati che compaiono man mano che i documenti vengono indicizzati. Le modifiche successive ai contenuti aggiornano automaticamente l’indice.