AI Search

O AI Search é um plugin nativo oficial que indexa o conteúdo publicado em uma instância do Cloudflare AI Search e fornece resultados de busca ao site. Ele mantém o índice atualizado conforme o conteúdo muda e roda no Cloudflare Workers e no Node.js.

Instalação

Instale o pacote pelo npm:

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

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

Depois, conecte o plugin ao AI Search com um binding do Workers ou um token de API. Quando um site tem os dois, o plugin usa o binding.

Conectar com um binding do Workers

No Cloudflare Workers, adicione um binding de namespace do AI Search ao wrangler.jsonc:

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

Conectar com um token de API

Em qualquer plataforma, o plugin pode acessar o AI Search pela API REST da Cloudflare. Ele precisa do ID da sua conta da Cloudflare e de um token de API com as permissões de conta AI Search Edit e AI Search Run. Crie um token de API de conta em Manage account > Account API tokens no painel da Cloudflare. Ao contrário de um token de usuário, ele continua funcionando se a pessoa que o criou sair da conta. Um token de usuário com as mesmas permissões também funciona.

Defina as credenciais como variáveis de ambiente:

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

Como alternativa, informe-as na página de configurações do plugin na administração. O EmDash armazena o token criptografado, então salvá-lo ali exige EMDASH_ENCRYPTION_KEY; consulte Secrets. Uma variável de ambiente tem precedência sobre um valor salvo na administração, e a administração mostra que ela está definida sem exibir o valor.

O plugin usa o namespace default da conta. Para usar outro, defina EMDASH_AI_SEARCH_NAMESPACE. Escolha o namespace antes de construir o índice, porque o plugin mantém sua instância nesse namespace. Se você o alterar depois, a página de configurações informa que a instância não existe. Escolha Edit setup e conclua a configuração para criar a instância e reconstruir o índice. Alterar a conta na página de configurações faz isso automaticamente.

Com um token de API, a indexação, a administração e cada busca de um visitante fazem requisições à API da Cloudflare, e a Cloudflare limita cada token a 1.200 requisições a cada 5 minutos. Um binding do Workers não conta para esse limite, então sites movimentados no Workers devem usar um.

Para ficar dentro do limite, a indexação usa no máximo metade dele, então construir o índice leva cerca de uma hora a cada 7.000 registros. Além disso, cada processo do EmDash permite 30 buscas por minuto a um visitante, contadas por endereço IP. Um site auto-hospedado atrás de um proxy reverso precisa configurar trustedProxyHeaders para que o limite de busca se aplique; sem um IP de cliente confiável, as buscas não são limitadas.

Opções

Variáveis de ambiente

O plugin ignora essas variáveis quando há um binding do Workers disponível.

Adicionar busca ao site

Adicione o componente AiSearch a um layout. Ele renderiza um botão de busca e abre o modal de busca, também com Cmd/Ctrl+K, então renderize-o uma vez por página:

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

<AiSearch placeholder="Search content" />

Construir o índice

Depois de implantar, abra AI Search na administração. Se o plugin ainda não consegue acessar o AI Search, a página pede um ID de conta e um token de API. Em seguida, o assistente de configuração escolhe o conteúdo a indexar, mostra um endereço de resultado de exemplo para cada fonte e constrói o índice quando você seleciona Build index. A busca fica ativa assim que a construção começa, com os resultados aparecendo conforme os documentos são indexados. As alterações de conteúdo posteriores atualizam o índice automaticamente.