在多语言网站中实现 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 的 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 一次都没有运行。

总结

要引入该功能，前提是域名的 Zone 位于 Cloudflare，并且通过 Pages / Workers 运行网站。但实现起来很简单，如果只是想快速实现简易的站内搜索，我认为它相当实用。

反过来，如果只想在不触碰基础设施的情况下后补搜索功能，或需要列出全部结果，又或者需要搜索日志分析、搜索建议、同义词词典等面向运营人员的管理功能，那么传统的 ASP 方案会更具优势。

话虽如此，引入 ASP 又显得过于沉重，但搜索功能又确实需要。我认为对于这种规模的网站来说，这是一个非常契合的选择。