Cloudflare AI Search：功能、使用方式与最佳实践

AI 参与说明（Agent：Grok）：本文由 Grok 根据用户选题与 Cloudflare 官方文档整理、核对。资料核对于 2026-09-09。运行记录：模型 grok-4.6，reasoning effort xhigh，执行入口 T3 Code，提供方 xAI；CLI 版本未取得运行记录。AI Search 仍处于 open beta，接口、限额与计费会变化，请以文末一手资料为准。

交叉链接（2026-09-10，Agent：Cursor）：补充与 kapa.ai 选型对比文的双向阅读入口。模型标识与 reasoning effort 未取得运行记录；执行入口 Cursor。

结论：AI Search 是 Cloudflare 托管的搜索服务。 它把文档摄入、Chunking、Embedding、Indexing、Querying 和可选的回答生成收成一条流水线。给它网站、R2 bucket 或直接上传的文件，就可以用自然语言查询；不必自己维护 Vectorize、写同步任务，也不必在每次请求里手工拼 RAG 上下文。

它适合文档站、知识库、按租户隔离的文件搜索，以及需要查阅内部资料的 Agent。它不适合作为业务数据的权威存储，也不适合要求秒级可见的实时索引。需要自己控制 embedding、向量生命周期或检索算法时，应直接使用 Vectorize。

阅读前先看这几个词

AI Search is Cloudflare’s managed search service, formerly AutoRAG. Connect a website, an R2 bucket, or uploaded files, and it indexes the content for natural-language queries. It natively integrates with Vectorize, AI Gateway, R2, and Workers AI, and it also supports third-party providers through AI Gateway. AI Search overview

Indexing is asynchronous; Querying is synchronous. Indexing converts files into vectors and an optional keyword index. Querying retrieves the most relevant chunks with Vector search, Keyword search, or both, then optionally generates an answer. How AI Search works

AI Search 解决什么问题

自己做 RAG 通常要同时维护五件事：数据从哪里来、怎么做 Chunking、用什么模型做 Embedding、向量存在哪里、查询时如何过滤、Reranking 和生成。AI Search 把这条链路收成一个 Instance：

1. 连接 Data source，或用 Items API 上传文件。
2. 平台完成 Markdown Conversion、Chunking、Embedding 和可选的 Keyword indexing。
3. 应用通过 search() 拿回带分数的 chunks，或通过 chatCompletions() 直接得到基于检索结果的回答。
4. 需要给网站或 Agent 用时，还可以打开 Public endpoint、UI snippets 和 MCP。

官方把它定位成应用和 Agent 的 search primitive，而不是又一个必须自己运维的 Vectorize 索引。AI Search overview

flowchart TB
  App["应用 / Agent / 网站"] --> AIS["AI Search Instance"]
  AIS --> Idx["Indexing"]
  AIS --> Qry["Querying"]
  Src["Built-in storage / Website / R2"] --> Idx
  Idx --> Store["vectors · keyword index · chunks"]
  Qry --> Store
  Qry --> SearchAPI["search()"]
  Qry --> ChatAPI["chatCompletions()"]
  Qry --> Public["Public endpoint / MCP / UI snippets"]

它不是 Vectorize，也不是直接调用 Workers AI

AI Search 建立在 Vectorize 之上，并补齐摄入、Chunking、同步、Keyword search、过滤、Reranking 和可选生成。三者经常一起出现，职责不同：

官方对照可以压成一句话：You give AI Search files or a connected data source; you give Vectorize vectors you generate yourself. When to use AI Search vs. Vectorize

2026-06-18 起，全部 Instance 已迁到托管基础设施：Built-in storage、内置向量索引和网站爬取都由产品提供。Storage、vector indexing，以及网站爬取消耗的 Browser Run，都包含在 AI Search 内；Workers AI 与 AI Gateway 仍单独计费。Limits & pricing Release note：managed infrastructure

两条流水线：Indexing 与 Querying

Indexing

Indexing 在连接 Data source 或通过 Items API 上传文件后自动开始。外部数据源按同步计划更新；Built-in storage 在文件上传后立即处理。

flowchart TB
  A["Website / R2 / Items API"] --> B["Markdown Conversion"]
  B --> C["Chunking"]
  C --> D["Embedding"]
  C --> E["Keyword indexing 可选"]
  D --> F["写入向量索引与 chunks"]
  E --> F

过程可以分成六步：

1. Data ingestion：读取已连接的 Data source，或接收 Items API 上传的文件。
2. Markdown Conversion：用 Workers AI 的 Markdown Conversion 把支持的类型转成结构化 Markdown。图片会先做 object detection，再转成可检索的文本。
3. Chunking：按自然边界做 recursive chunking，块过大时继续切分。
4. Embedding：用 Instance 配置的 embedding model 把每个 chunk 变成向量。这个模型在创建后不能改。
5. Keyword indexing：启用 Keyword search 时，同时为 chunk 建立 BM25 索引。
6. Storage：向量、关键词索引和原文片段进入可查询状态。

How indexing works

Querying

Querying 由 Search 或 Chat Completions 请求触发，实时返回结果。

flowchart TB
  Q["Search 或 Chat Completions"] --> RW["Query rewriting 可选"]
  RW --> V["Vector search"]
  RW --> K["Keyword search 可选"]
  V --> F["Fusion 可选"]
  K --> F
  F --> RR["Reranking 可选"]
  RR --> S["返回 chunks"]
  S --> G["Response generation 仅 Chat Completions"]

默认路径是：接收查询 → 可选 Query rewriting → 把查询做成向量 → Vector search → 可选 Keyword search 与 Fusion → 可选 Reranking → 返回 chunks。只有 Chat Completions 才会再调用文本生成模型。Search 在拿到 chunks 后就结束，适合自己做 UI、自己选模型，或把检索结果交给 Agent。How querying works

三种 Data source

每个 Instance 都有 Built-in storage。Website 和 R2 是可选的外部数据源，可以与 Built-in storage 并存；创建后不能改成另一种外部源。

Data source Built-in storage

Website 只能爬取已经加入同一账户的域名。Parse type 有两种：sitemap 读站点发布的 XML sitemap；discover 从源 URL 出发，默认同时用 sitemap 和页面上的链接。渲染模式可下载原始 HTML，或先用无头浏览器拿到带客户端渲染的页面。站点若用 WAF 拦截机器人，需要放行 Bot Detection ID 122933950；crawler User-Agent 现为 Cloudflare-AI-Search，旧名 Cloudflare-AutoRAG 仍可写在 robots.txt。Website Crawler user agent renamed

R2 适合“对象仍以 bucket 为准、搜索只是投影”的文档库。首次用 Dashboard 或 Wrangler 创建时，平台会代为登记 Service API token；走 REST API 或 Workers binding 创建时，需要自己传入 token_id。可用 include / exclude 限制对象路径，并用 x-amz-meta-* 写入自定义元数据。R2

文件上限是 4 MB。超限文件不会进入索引，会出现在错误日志里。纯文本覆盖 Markdown、MDX、JSON、YAML、常见源码和日志；富文本经 Markdown Conversion 处理，包括 PDF、HTML、CSV、部分 Office / Open Document 文件，以及 JPEG、PNG、WebP、SVG、GIF、BMP。图片转换会调用 Workers AI，这一部分按 Workers AI 计费。Supported file types

三种 Search modes

新建 Instance 默认只启用 Vector search。要做 Hybrid search，必须同时打开 index_method.vector 和 index_method.keyword。单次请求可以用 retrieval_type 指定 vector、keyword 或 hybrid，但必须与 Instance 已启用的索引兼容。Search modes

Hybrid search 用 Fusion 合并两路结果。rrf 是 Reciprocal Rank Fusion，按两路排名融合，官方推荐大多数场景使用；max 取归一化后的较高分。融合之后还可以做 Reranking：用 @cf/baai/bge-reranker-base 这类 cross-encoder 再打一遍分。Reranking 默认关闭，会增加一次模型调用和延迟。Hybrid search Reranking

Workers Paid 上，只开 Vector search 的 Instance 最多 100 万个文件；启用 Keyword search 后降到 50 万。这是用精确匹配换来的容量代价。Limits

怎么开始用

创建 Instance 的入口有 Dashboard、Wrangler CLI、REST API 和 Workers binding。新代码应使用 ai_search / ai_search_namespaces，不要再写 env.AI.autorag()。旧 binding 会继续工作，但新能力只加在新 API 上。Get started Workers binding migration

新 binding 要求 @cloudflare/workers-types 不低于 4.20260304.0，wrangler 不低于 4.68.1。AI Search 不在本地运行；wrangler dev 需要 "remote": true，把请求代理到已部署的 Instance。

1. 用 Wrangler 建一个空 Instance

npx wrangler ai-search create my-instance
npx wrangler ai-search stats my-instance
npx wrangler ai-search search my-instance --query "What is Cloudflare?"

连接外部数据源时加上类型：

npx wrangler ai-search create docs-site --type web-crawler --source example.com
npx wrangler ai-search create docs-bucket --type r2 --source my-docs-bucket
npx wrangler ai-search jobs create docs-bucket

jobs create 会立刻触发一次同步，最多每 30 秒一次，适合内容发布后的 CI 步骤。CLI Syncing

2. 在 Worker 里绑定 Namespace

文档站、多租户和需要 Items API 的应用，优先用 Namespace binding。未指定 Namespace 的 Instance 属于自动创建的 default。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "compatibility_date": "2026-03-27",
  "ai_search_namespaces": [
    {
      "binding": "AI_SEARCH",
      "namespace": "default",
      "remote": true
    }
  ]
}

已经知道生产要用哪一个 Instance 时，可以用 Instance binding，调用时不必再 get()：

{
  "ai_search": [
    {
      "binding": "DOCS_SEARCH",
      "instance_name": "product-docs",
      "remote": true
    }
  ]
}

Workers binding Namespaces

3. 上传一份文档并检索

下面的 Worker 对照官方 Get started 整理，用于说明最小闭环。它没有在独立账户里实际创建 Instance；要验证，需要一个已登录 Wrangler 的 Cloudflare 账户，并访问 /setup 一次。

export interface Env {
  AI_SEARCH: AiSearchNamespace;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === "/setup") {
      const instance = await env.AI_SEARCH.create({ id: "my-instance" });
      const item = await instance.items.uploadAndPoll(
        "getting-started.md",
        "AI Search indexes uploaded content for retrieval.",
      );
      return Response.json({ created: "my-instance", status: item.status });
    }

    const query = url.searchParams.get("q") ?? "What does AI Search do?";
    const results = await env.AI_SEARCH.get("my-instance").search({
      messages: [{ role: "user", content: query }],
      ai_search_options: {
        retrieval: { max_num_results: 3 },
      },
    });

    return Response.json(results.chunks);
  },
} satisfies ExportedHandler<Env>;

items.upload() 立即返回，文件进入队列；items.uploadAndPoll() 等到 completed 或超时，适合“刚上传完就要搜”的路径。search() 既可传 messages，也可传 query，不要两个一起传。Get started：Workers binding Items API

4. search() 还是 chatCompletions()

search() 只检索。chatCompletions() 会再调用 Instance 配置的 generation model，或请求里覆盖的 model。流式响应里先返回来源 chunks，再推 choices[0].delta.content，最后以 data: [DONE] 结束，这样 UI 可以一边显示引用一边打字。Workers binding：search() Workers binding：chatCompletions()

生成路径的请求形如：

const instance = env.AI_SEARCH.get("my-instance");

const response = await instance.chatCompletions({
  messages: [
    { role: "system", content: "Answer only from retrieved documents. Cite the source item key." },
    { role: "user", content: "How do I enable Hybrid search?" },
  ],
  model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
  ai_search_options: {
    retrieval: { max_num_results: 5, retrieval_type: "hybrid" },
    query_rewrite: { enabled: true },
    reranking: { enabled: true, model: "@cf/baai/bge-reranker-base" },
  },
});

Generation model、Query rewriting model 和 Reranking model 都可以改；Embedding model 在创建后固定。当前生产模型同时覆盖 Workers AI 与经 AI Gateway 接入的 Anthropic、OpenAI、Google AI Studio、Grok 等。完整别名以 Supported models 为准，本文不抄一份会过期的清单。

5. REST API

Worker 之外可以用账户级 REST。新路径在 /ai-search/instances/ 与 /ai-search/namespaces/ 下，请求体使用 OpenAI 风格的 messages。Token 需要 AI Search:Edit 和 AI Search:Run，不再使用旧的 AutoRAG 权限。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances/<INSTANCE_NAME>/search" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"What is Cloudflare?"}]}'

Chat Completions 把最后一段换成 /chat/completions。Namespace 级搜索额外传 ai_search_options.instance_ids，一次最多查 10 个 Instance，返回的 chunk 带 instance_id。REST API

最佳实践

先决定语料权威在哪

Built-in storage 适合应用写入、租户上传、以及“搜索服务自己保存一份即可”的语料。R2 适合对象存储仍是发布产物或附件权威副本的场景。Website 适合索引已经挂在 Cloudflare 上的站点，而不是任意公网 URL。

文档站常见做法是：构建或发布完成后，把可公开的 Markdown 同步到 Instance，或对 R2 / Website 触发 wrangler ai-search jobs create。不要把草稿、内部 runbook、密钥和用户隐私写进会被检索的路径。Website 与 R2 都支持 Path filtering，例如只收录 /docs/**、排除 **/drafts/**。Path filtering Syncing

网站还应该收紧爬取范围：用 Content selectors 去掉导航和页脚；需要登录墙后的页面时再配置 Authentication headers。不要默认打开 Rendered sites：无头渲染更完整，也更慢、更贵。

检索与生成分开设计

产品里的“搜索框”通常应调用 search()，自己渲染标题、摘要和链接。聊天助手再调用 chatCompletions()，并用 System prompt 把模型锁在检索到的 chunks 上：没有依据就明确说没有，不要靠参数记忆补全。官方生成提示强调引用文件、承认资料不足、只用检索到的内容作答。System prompt

max_num_results 默认 10，最大 50。更大的 top_k 和更大的 chunk 会进入生成模型的上下文，既可能提高召回，也会增加延迟、费用和截断风险。match_threshold 在新 API 里默认 0.4。结果太空时先检查 Indexing 是否完成、过滤条件是否过严，再考虑降低阈值，而不是一上来把 50 个 chunk 全部塞给模型。Result controls

按查询类型打开可选步骤

这些开关都能提高质量，也都会加延迟或费用：

Query rewriting 不会改写第一轮问题，它解决的是后续轮次缺少指代对象的检索。Similarity cache 用 MinHash 与 LSH 匹配相近 prompt，阈值从 super_strict_match 到 anything_goes；命中与否看 cf-aig-cache-status。语料更新会清掉依赖这些 chunks 的缓存，也可以调用 purge_cache。Query rewriting Similarity cache

过滤时记住两个陷阱

Metadata filtering 在检索前生效，不会先搜完全库再丢弃。内置字段是 filename、folder、timestamp。自定义字段最多 5 个，名字不能占用这三个保留名；改 schema 会触发全量再索引。

字符串只有前 64 个 UTF-8 字节可过滤。更长的值可以存，但过滤匹配不到后面的字节。

folder 的精确相等只覆盖该目录下的直接文件。要包含子目录，官方用的是 range query，而不是 startsWith 算子：

const results = await instance.search({
  messages: [{ role: "user", content: "What is Cloudflare?" }],
  ai_search_options: {
    retrieval: {
      filters: {
        folder: { $gte: "docs/", $lt: "docs0" },
        timestamp: { $gte: 1735689600 },
      },
    },
  },
});

$gte: "docs/" 配 $lt: "docs0"，是因为 ASCII 里 0 紧跟在 / 后面，这样可以圈住所有以 docs/ 开头的路径。timestamp 在索引里按毫秒存储，比较时向下取整到秒；官方过滤示例使用秒级 Unix 时间。Filtering Metadata attributes

多租户优先“一个租户一个 Instance”

官方推荐每个租户一个 Instance：存储和索引天然隔离，删除租户时删 Instance 即可。Namespace binding 允许在运行时 create() / get() / delete()。共享 Instance 再按 folder 过滤更省事，但过滤条件写错就会串数据，只适合租户多、单个体量小、可以接受应用层约束的场景。Multitenancy

租户数据已经按 bucket 或前缀放在 R2 时，创建 Instance 时用 source_params.include_items 限制前缀，比事后过滤更安全。

Public endpoint 默认没有身份认证

打开 Public endpoint 后，平台会给出 https://<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com 下的 /search、/chat/completions 和 /mcp。知道 URL 的人就能查索引内容。公开文档站可以开；内部知识库应加 Custom domain，再用 Cloudflare Access 保护，并关闭默认域名。

MCP 端点让 Agent 通过 search tool 查询语料。Tool description 应写清索引了什么、适合回答什么，而不是留着默认的 “Finds exactly what you’re looking for”。Namespace 也可以暴露一个合并多个 Instance 的公开入口，主机名带 ns- 前缀。Public endpoint MCP

新鲜度按数据源选择，不要假设实时

AI Search 不是变更数据流。内容每小时改很多次、必须立刻可搜时，应走 Items API 的立即索引，或自己向 Vectorize upsert。外部源连续 31 天没有查询会被自动暂停，以免空转扫描；恢复流量后会重新启动，也可以手动 Resume。Syncing

在 Workers + TanStack Start 里怎么接

作者常用的落地方式是：Cloudflare Worker 通过 Workers binding 调用 search() 或 chatCompletions()，TanStack Start 的服务端函数或 API route 把结果交给页面，TanStack Query 负责客户端缓存、重试和失效。检索结果是普通 JSON，不必把 AI Search SDK 塞进浏览器。

要注意三件事：

1. 浏览器不要直连 Public endpoint 去查私有语料；鉴权留在 Worker。
2. search() 的 chunks 适合列表和引用；流式问答走 chatCompletions({ stream: true }) 的 SSE。
3. 语料更新后，除了等 Indexing，还要让 TanStack Query 的 query key 失效，否则 UI 仍显示旧答案。

官方还提供 Agents SDK、Vercel AI SDK 和 LangChain 的接入说明。Agent 需要查阅文档时，优先用 binding 或 MCP，而不是在 prompt 里塞整份知识库。Agents SDK

限额、计费与 Beta 边界

资料对应 2026-08-26 更新的 limits 页。实施前应再核当前文档。

Website 的 discover 单次最多 100,000 页，但还要同时受“每 Instance 文件数”和“每日爬取页数”约束，实际取最低值。Free 计划上每天 500 页通常先碰到。

Open beta 期间，AI Search 在上述限额内免费。Workers AI 与 AI Gateway 单独计费。Storage、vector indexing 和爬取用的 Browser Run 包含在产品内。计费开始前至少提前 30 天公布。2026-04-16 之前创建、跑在账户自有 R2 / Vectorize 上的旧 Instance，账单里可能仍能看到那些产品的历史费用；网站爬取留下的专用 R2 bucket 迁移后不再写入，若确认没有其它用途可以删除。Limits & pricing

从 AutoRAG 迁到 AI Search

产品更名后，有两套并存的调用面：

旧 REST 与 env.AI.autorag() 会继续可用，官方写明不强制立刻迁移；新功能只加在新 API。过滤从 AutoRAG 的 { type, key, value } 换成 Vectorize 风格的 { folder: { $gte: "..." } }。流式 Chat Completions 现在会先发 chunks 事件，旧 aiSearch({ stream: true }) 只流式输出文本。REST API migration Workers binding migration

适用与不适用

适合：

• 文档、帮助中心、政策与知识库的自然语言搜索。
• 需要引用源文件的问答助手。
• 让 Agent 通过 MCP 或 Workers binding 查阅内部资料。
• 每个租户一份文件集合、需要在运行时创建和销毁索引。

不适合：

• 业务记录的权威存储、事务和关系查询。那是 D1、Convex 或其它数据库的职责。
• 必须在秒级内可搜索的高频变更流。
• 需要自己选择 embedding 模型之后再改、或对向量做任意运算的检索系统。
• 把未脱敏的隐私数据放到 Public endpoint 后面。

和站内其它 Cloudflare 专题的关系是：先理解 Workers 的 env binding，再把 AI Search 看成一种专用 binding。对象文件如果以 R2 为权威副本，权限与对象键仍按 R2 自己的模型管理；搜索索引只是投影。需要自己管理向量生命周期时，回到 Vectorize，而不是把 AI Search 拆开当底层数据库用。

若还在评估第三方文档问答 SaaS（例如 kapa.ai）与 AI Search：kapa 提供可直接嵌入的 Website Widget，读者问答前端工作量通常更少；AI Search 默认交付检索 / 生成 API，面向读者的搜索与对话需自研或另接 UI snippets。完整对照见 kapa.ai：文档导入、Retrieval 与 Blog 接入流程。

参考资料

• AI Search overview，2026-07-06
• How AI Search works，2026-07-06
• Get started，2026-07-10
• Workers binding，2026-04-20
• Workers binding migration，2026-04-20
• REST API，2026-06-08
• Items API，2026-04-20
• Configuration，2026-08-06
• Data source，2026-08-06
• Search modes，2026-04-20
• Hybrid search，2026-04-20
• Filtering，2026-08-26
• Multitenancy，2026-08-25
• Limits & pricing，2026-08-26
• Release note，2026-04-20 起持续更新
• Supported models，2026-08-28
• Vectorize
• Workers AI
• AI Gateway