使用 Cloudflare AI Search 為多語言網站實現站內搜尋

我們在採用 Astro SSG + 無頭 CMS 架構的自家網站上進行了實作。
導入步驟本身相當簡單，但由於我們的網站採用多語言構成，因此遇到了一些陷阱。

什麼是 Cloudflare AI Search

舊名為 AutoRAG，已於 2025 年 9 月更名。搜尋出現的文章多為舊名稱和舊 API 的內容，敬請留意。

它會執行這一系列的流程。

爬取網頁 → 轉換為 Markdown → 分割內容塊 → 嵌入 → 建構向量及關鍵字索引

API 有兩個系統。返回搜尋結果清單的 search，以及使用 RAG 產生回答的 chat/completions。這次我們只使用前者。

設定的重點

請按如下方式建立執行個體。

• 資料來源選擇 WebCrawl
• 將爬蟲目標設為公開URL
• 將解析類型設為網站地圖
• 在內容選擇器中指定main元素
• 解析模式：靜態網站
• 在特定網站地圖中指定sitemap.xml
• 將嵌入模型設為@cf/baai/bge-m3（針對日文網站）

其餘部分基本上保持預設設定即可。

驗證與環境變數

從帳戶建立API代碼。
需要注意的是，不僅需要「AI Search：讀取」，還需要「編輯」和「執行」權限。
建立的代碼透過環境變數AI_SEARCH_TOKEN來讀取。

組成：1個API路由 + 1個元件

搜尋會透過 Astro 的 API 路由（作為 Pages Functions 運作）呼叫 REST API。因為無法將 API 令牌公開給瀏覽器，所以必須在伺服器端進行代理。另外，Pages Functions 沒有 AI Search 的繫結，因此我們使用原始的 fetch 而非 SDK。

// 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 元件這 2 個檔案。作為靜態網站產生（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 完全沒有被運作過。

總結

導入時的前提是網域的區域位於 Cloudflare 上，且由 Pages／Workers 進行運維，不過實裝相當簡單，若想以簡易的方式實現網站內搜尋的話，應該會相當實用。

反過來說，若是想在不涉及基礎設施的情況下後置搜尋功能、想要顯示全部結果、或需要搜尋日誌分析、建議功能、同義詞字典等營運者向的管理機能，傳統型 ASP 會更強大。

儘管如此，導入 ASP 顯得太過沉重，但又需要搜尋功能。對於這種規模的網站，應該是個相當有吸引力的選項。