在多語系網站中實作 Cloudflare AI Search 站內搜尋

我們在採用 Astro SSG + Headless CMS 架構的自家網站上實作了此功能。
導入步驟本身相當簡單，但由於本網站為多語系架構，過程中遇到了幾個需要留意的地方。

什麼是 Cloudflare AI Search

此服務原名為 AutoRAG，於 2025 年 9 月更名。搜尋到的文章多為舊名稱及舊 API 的內容，請留意。

它所負責的流程如下。

爬取 → 轉換為 Markdown → 分塊 → 嵌入 → 建立向量與關鍵字索引

API 分為兩類。一是回傳搜尋結果列表的search，二是透過 RAG 產生回答的chat/completions。本次僅使用前者。

設定重點

請依照以下方式建立執行個體。

• 選擇 WebCrawl 作為資料來源
• 爬取目標設為公開 URL
• 解析類型設為 Sitemap
• 內容選擇器指定為 main 元素
• 解析模式：靜態網站
• 指定特定的 Sitemap，使用 sitemap.xml
• 嵌入模型請設為 @cf/baai/bge-m3（因為是日文網站）

其餘大致維持預設值即可。

驗證與環境變數

從帳戶建立 API 權杖。
需要注意的是，不能只設定「AI Search: 讀取」，還必須加上「編輯」與「執行」。
建立的權杖透過環境變數 AI_SEARCH_TOKEN 讀取。

架構：API 路由 1 支 + 元件 1 個

搜尋功能是從 Astro 的 API 路由（以 Pages Functions 運作）呼叫 REST API。由於無法將 API 權杖輸出到瀏覽器，必須在伺服器端進行代理。另外，Pages Functions 沒有 AI Search 的 binding，因此不使用 SDK，而是直接使用原生 fetch。

// Astro の API ルート（Pages Functions として動く）
const res = await fetch(
  `https://api.cloudflare.com/client/v4/accounts/${id}/ai-search/instances/${name}/search`,
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` },
    body: JSON.stringify({
      query,
      ai_search_options: {
        retrieval: {
          retrieval_type: 'hybrid',
          max_num_results: 50
        },
      },
    }),
  }
);

實際實作的只有 API 路由與搜尋 UI 元件兩個檔案。作為 SSG 的後加功能，整體相當輕量。

多語言網站需將搜尋範圍限定為顯示語言

一般網站內搜尋只要這樣做就可以，但多語言網站的 sitemap.xml 包含所有語言的內容，因此搜尋結果會混雜在一起。

解決方法是定義自訂中繼資料 locale，並在搜尋時以 filters 進行篩選。如此一來，只會輸出正在瀏覽的語言之搜尋結果。
※ 無法從 html 的 lang 屬性或 og:locale 判斷語言，請特別留意。

<meta name="locale" content="ja_JP">

將 SEO 用網站地圖與搜尋用網站地圖分開

AI Search（Website 資料來源）會透過網站地圖進行爬取。

然而，本站公開用的網站地圖基於 SEO 考量，刻意排除了部分語言。結果，該語言的搜尋結果始終為 0 筆，形成了問題。

我們使用 @astrojs/sitemap 生成網站地圖，因此另外輸出一份包含所有語言的網站地圖，供搜尋使用。

搜尋結果是如何排列的

這與從「AI 搜尋」一詞所想像的樣貌相當不同。

AI Search 會將日文內容切分為約 300 至 450 字的區塊。
相關的區塊最多會挑選 50 個，並顯示包含這些區塊的頁面作為搜尋結果。
被判定為相關度較高的區塊所在頁面會排在前面。由於有時會從同一頁面選出多個區塊，因此搜尋筆數會少於 50 筆。

將結果彙整為頁面單位的處理在前端完成。而且整個流程中，生成式 AI 一次也沒有運作。

總結

要導入的前提是網域的 DNS 區域位於 Cloudflare，並以 Pages / Workers 運行，但實作相當簡單，若只想快速實現簡易的網站內搜尋，我認為相當實用。

反過來說，若不想動到基礎架構、只想事後加上搜尋功能，或需要列出全部結果，又或需要搜尋記錄分析、建議詞、同義詞辭典等供營運者使用的管理功能，那麼傳統型 ASP 會更有優勢。

話雖如此，若覺得導入 ASP 太過沉重，但又需要搜尋功能，那麼對於這種規模的網站來說，這會是非常合適的選擇。