使用 Cloudflare AI Search 为多语言网站实现站内搜索

我们在采用 Astro SSG + headless 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 的 binding，因此使用原生 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 会很沉重，但又确实需要搜索功能。我认为对于这类规模的网站来说，这是一个相当有吸引力的选择。