AI Search는 게시된 콘텐츠를 Cloudflare AI Search 인스턴스에 인덱싱하고 사이트에 검색 결과를 제공하는 공식 네이티브 플러그인입니다. 콘텐츠가 변경되면 인덱스를 최신 상태로 유지하며, Cloudflare Workers와 Node.js에서 실행됩니다.
설치
npm에서 패키지를 설치합니다.
pnpm add @emdash-cms/plugin-ai-searchastro.config.mjs의 plugins에 aiSearch()를 추가합니다.
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()],
}),
],
});그런 다음 Workers 바인딩 또는 API 토큰으로 플러그인을 AI Search에 연결합니다. 사이트에 둘 다 설정되어 있으면 플러그인은 바인딩을 사용합니다.
Workers 바인딩으로 연결하기
Cloudflare Workers에서는 wrangler.jsonc에 AI Search 네임스페이스 바인딩을 추가합니다.
{
"ai_search_namespaces": [{ "binding": "AI_SEARCH", "namespace": "default" }],
}API 토큰으로 연결하기
어떤 플랫폼에서든 플러그인은 Cloudflare REST API를 통해 AI Search에 접근할 수 있습니다. 이를 위해서는 Cloudflare 계정 ID와, AI Search Edit 및 AI Search Run 계정 권한이 있는 API 토큰이 필요합니다. Cloudflare 대시보드의 Manage account > Account API tokens에서 계정 API 토큰을 만드세요. 사용자 토큰과 달리, 토큰을 만든 사람이 계정을 떠나도 계속 동작합니다. 같은 권한을 가진 사용자 토큰도 사용할 수 있습니다.
자격 증명을 환경 변수로 설정합니다.
EMDASH_AI_SEARCH_ACCOUNT_ID=your-account-id
EMDASH_AI_SEARCH_API_TOKEN=your-api-token또는 관리자의 플러그인 설정 페이지에서 입력할 수도 있습니다. EmDash는 토큰을 암호화하여 저장하므로, 그곳에 저장하려면 EMDASH_ENCRYPTION_KEY가 필요합니다. Secrets를 참조하세요. 환경 변수는 관리자에 저장된 값보다 우선하며, 관리자에는 값이 설정되어 있다는 사실만 표시되고 값 자체는 표시되지 않습니다.
플러그인은 계정의 default 네임스페이스를 사용합니다. 다른 네임스페이스를 사용하려면 EMDASH_AI_SEARCH_NAMESPACE를 설정하세요. 플러그인은 인스턴스를 해당 네임스페이스에 보관하므로, 인덱스를 만들기 전에 네임스페이스를 선택하세요. 나중에 변경하면 설정 페이지에 인스턴스가 없다고 표시됩니다. 이때 Edit setup을 선택하고 설정을 마치면 인스턴스가 만들어지고 인덱스가 다시 구축됩니다. 설정 페이지에서 계정을 변경하면 이 작업이 자동으로 수행됩니다.
API 토큰을 사용하면 인덱싱, 관리자, 그리고 방문자의 모든 검색에서 Cloudflare API 요청이 발생하며, Cloudflare는 토큰당 요청 수를 5분당 1,200회로 제한합니다. Workers 바인딩은 이 제한에 포함되지 않으므로, Workers에서 운영하는 트래픽이 많은 사이트는 바인딩을 사용해야 합니다.
제한을 넘지 않도록 인덱싱은 제한의 최대 절반만 사용하므로, 인덱스를 구축하는 데 레코드 7,000개당 약 1시간이 걸립니다. 또한 각 EmDash 프로세스는 방문자당 분당 30회의 검색을 허용하며, IP 주소별로 집계합니다. 리버스 프록시 뒤에 있는 셀프 호스팅 사이트는 검색 제한이 적용되도록 trustedProxyHeaders를 설정해야 합니다. 신뢰할 수 있는 클라이언트 IP가 없으면 검색은 제한되지 않습니다.
옵션
| 옵션 | 기본값 | 설명 |
|---|---|---|
binding | AI_SEARCH | wrangler.jsonc의 ai_search_namespaces 바인딩 이름. |
instance | emdash | 플러그인이 해당 네임스페이스 안에 만들고 소유하는 AI Search 인스턴스. |
환경 변수
| 변수 | 설명 |
|---|---|
EMDASH_AI_SEARCH_ACCOUNT_ID | REST API용 Cloudflare 계정 ID. |
EMDASH_AI_SEARCH_API_TOKEN | AI Search Edit 및 AI Search Run 권한이 있는 Cloudflare API 토큰. |
EMDASH_AI_SEARCH_NAMESPACE | REST API용 AI Search 네임스페이스. 기본값은 default입니다. |
Workers 바인딩을 사용할 수 있으면 플러그인은 이 변수들을 무시합니다.
사이트에 검색 추가하기
AiSearch 컴포넌트를 레이아웃에 추가합니다. 검색 버튼을 렌더링하고 검색 모달을 열며, Cmd/Ctrl+K로도 열 수 있으므로 페이지당 한 번만 렌더링하세요.
---
import { AiSearch } from "@emdash-cms/plugin-ai-search/astro";
---
<AiSearch placeholder="Search content" />인덱스 빌드하기
배포한 후 관리자에서 AI Search를 엽니다. 플러그인이 아직 AI Search에 연결할 수 없으면 페이지에서 계정 ID와 API 토큰을 요청합니다. 이어서 설정 마법사가 인덱싱할 콘텐츠를 선택하고, 각 소스의 결과 주소 예시를 보여 주며, Build index를 선택하면 인덱스를 구축합니다. 구축이 시작되면 검색을 사용할 수 있으며, 문서가 인덱싱되는 대로 결과가 나타납니다. 이후의 콘텐츠 변경은 인덱스에 자동으로 반영됩니다.