AI Search

AI Search es un plugin nativo oficial que indexa el contenido publicado en una instancia de Cloudflare AI Search y ofrece resultados de búsqueda al sitio. Mantiene el índice al día a medida que cambia el contenido, y se ejecuta en Cloudflare Workers y en Node.js.

Instalación

Instala el paquete desde npm:

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

Añade aiSearch() a plugins en 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()],
		}),
	],
});

A continuación, conecta el plugin a AI Search con un binding de Workers o con un token de API. Cuando un sitio tiene ambos, el plugin usa el binding.

Conectar con un binding de Workers

En Cloudflare Workers, añade un binding de namespace de AI Search a wrangler.jsonc:

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

Conectar con un token de API

En cualquier plataforma, el plugin puede acceder a AI Search a través de la API REST de Cloudflare. Necesita el ID de tu cuenta de Cloudflare y un token de API con los permisos de cuenta AI Search Edit y AI Search Run. Crea un token de API de cuenta en Manage account > Account API tokens del panel de Cloudflare. A diferencia de un token de usuario, sigue funcionando si la persona que lo creó abandona la cuenta. También sirve un token de usuario con los mismos permisos.

Define las credenciales como variables de entorno:

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

También puedes introducirlas en la página de ajustes del plugin en el administrador. EmDash almacena el token cifrado, por lo que guardarlo allí requiere EMDASH_ENCRYPTION_KEY; consulta Secrets. Una variable de entorno tiene prioridad sobre un valor guardado en el administrador, y el administrador indica que está definida sin mostrar su valor.

El plugin usa el namespace default de la cuenta. Para usar otro, define EMDASH_AI_SEARCH_NAMESPACE. Elige el namespace antes de construir el índice, porque el plugin mantiene su instancia en ese namespace. Si lo cambias más tarde, la página de ajustes informa de que falta la instancia. Elige Edit setup y termina la configuración para crear la instancia y reconstruir el índice. Al cambiar la cuenta en la página de ajustes, esto se hace automáticamente.

Con un token de API, la indexación, el administrador y cada búsqueda de un visitante realizan solicitudes a la API de Cloudflare, y Cloudflare limita cada token a 1.200 solicitudes cada 5 minutos. Un binding de Workers no cuenta para ese límite, así que los sitios con mucho tráfico en Workers deberían usar uno.

Para mantenerse dentro del límite, la indexación usa como máximo la mitad, por lo que construir el índice tarda aproximadamente una hora por cada 7.000 registros. Además, cada proceso de EmDash permite a un visitante 30 búsquedas por minuto, contadas por dirección IP. Un sitio autoalojado detrás de un proxy inverso debe configurar trustedProxyHeaders para que se aplique el límite de búsqueda; sin una IP de cliente de confianza, las búsquedas no tienen límite.

Opciones

Variables de entorno

El plugin ignora estas variables cuando hay un binding de Workers disponible.

Añadir la búsqueda al sitio

Añade el componente AiSearch a un layout. Muestra un botón de búsqueda y abre el modal de búsqueda, también con Cmd/Ctrl+K, así que renderízalo una sola vez por página:

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

<AiSearch placeholder="Search content" />

Construir el índice

Después de desplegar, abre AI Search en el administrador. Si el plugin aún no puede acceder a AI Search, la página solicita un ID de cuenta y un token de API. Después, el asistente de configuración elige el contenido que se va a indexar, muestra una dirección de resultado de ejemplo para cada fuente y construye el índice cuando seleccionas Build index. La búsqueda está activa en cuanto empieza la construcción, y los resultados aparecen a medida que se indexan los documentos. Los cambios de contenido posteriores actualizan el índice automáticamente.