AI Search

AI Search 是一個官方原生外掛，它會把已發佈的內容索引到 Cloudflare AI Search 執行個體中，並為站台提供搜尋結果。內容發生變化時，它會保持索引同步更新，並且可以在 Cloudflare Workers 和 Node.js 上執行。

安裝

從 npm 安裝該套件：

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

在 astro.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 筆記錄一小時。此外，每個 EmDash 行程允許每位訪客每分鐘搜尋 30 次，依 IP 位址計數。位於反向代理之後的自行代管站台必須設定 trustedProxyHeaders，搜尋限制才會生效；沒有可信任的用戶端 IP 時，搜尋不受限制。

選項

環境變數

當 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 時建構索引。建構一開始，搜尋就可以使用，結果會隨著文件被索引而陸續出現。之後的內容變更會自動更新索引。