Workers 绑定（binding）

Workers 提供无服务器执行环境，使你能够创建新应用或增强现有应用。使用 Workers 绑定（binding） 从 Cloudflare Worker 创建、列出、更新与删除 AI Search 实例。你还可以检查实例配置并监控索引进度。

要在 Workers 中使用 AI Search，必须创建 AI Search 绑定（binding）。通过更新 Wrangler 配置 创建绑定。AI Search 提供两种绑定类型：

• 命名空间绑定：ai_search_namespaces
• 实例绑定：ai_search

访问命名空间内的所有实例。你可以在运行时 get、create、list 和 delete 实例。

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

compatibility_date = "2026-03-27"

[[ai_search_namespaces]]
binding = "AI_SEARCH"
namespace = "my-namespace"

直接绑定到 default 命名空间中的单个实例。当你在部署时已知需要哪个实例时使用。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "compatibility_date": "2026-03-27",
  "ai_search": [
    {
      "binding": "MY_SEARCH",
      "instance_name": "my-instance"
    }
  ]
}

compatibility_date = "2026-03-27"

[[ai_search]]
binding = "MY_SEARCH"
instance_name = "my-instance"

以下方法仅在使用 ai_search_namespaces 绑定时可用。命名空间句柄（env.AI_SEARCH）暴露用于处理 命名空间 内实例的方法。

返回特定实例的句柄。此调用是同步的，不会发起网络请求。实例会在你调用 search() 或 info() 等方法时惰性解析。

const instance = env.AI_SEARCH.get("my-instance");
const results = await instance.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
});

返回命名空间内的所有实例。

const { result, result_info } = await env.AI_SEARCH.list();

for (const instance of result) {
	console.log(`${instance.id} (${instance.type}) - ${instance.status}`);
}
// result_info.total_count contains the total number of instances

创建新实例并返回其句柄。你可以创建由数据源支持的实例，或创建空实例以配合 Items API 使用。

创建用于文件上传的空实例：

AI Search 实例自带 内置存储，你可以直接上传文档。

const instance = await env.AI_SEARCH.create({
	id: "knowledge-base",
});

// Upload documents using the Items API
await instance.items.upload("guide.pdf", pdfArrayBuffer);

创建 web-crawler 实例：

自动抓取并索引你拥有的网站。更多配置选项请参阅 网站数据源。

const instance = await env.AI_SEARCH.create({
	id: "my-docs",
	type: "web-crawler",
	source: "developers.cloudflare.com",
});

创建由 R2 支持的实例：

索引存储在 R2 存储桶中的文档。更多配置选项请参阅 R2 数据源。

const instance = await env.AI_SEARCH.create({
	id: "internal-docs",
	type: "r2",
	source: "my-docs-bucket",
});

id stringrequired

AI Search 实例的唯一标识符。长度必须为 1–64 个字符，并匹配模式 ^[a-z0-9_]+(?:-[a-z0-9_]+)*$。

type stringoptional

数据源类型。有效值：r2、web-crawler。使用数据源创建实例时为必填。若创建供 Items API 使用的空实例，则省略此字段。

source stringoptional

数据源位置。对于 r2 类型，这是 R2 存储桶名称。对于 web-crawler 类型，这是网站域名。指定 type 时为必填。

source_params objectoptional

数据源的其他参数。

• prefix stringoptional

  • 对于 R2 源，将索引限制为具有此键前缀的对象。

• r2_jurisdiction stringoptional

  • R2 存储桶的管辖区域（jurisdiction），例如 eu。

• include_items arrayoptional

  • 要包含在索引中的路径的 glob 模式。例如：["/blog/**", "/docs/**/*.html"]。

• exclude_items arrayoptional

  • 要从索引中排除的路径的 glob 模式。例如：["/admin/**", "/private/**"]。

• web_crawler objectoptional

  • Web crawler 源的配置。

  • parse_type stringoptional

    • 解析方法。有效值：sitemap。

  • parse_options objectoptional

    • include_headers objectoptional

      • 爬取时要包含的自定义 HTTP 标头。

    • include_images booleanoptional

      • 是否在索引中包含图像。

    • specific_sitemaps arrayoptional

      • 要爬取的特定 sitemap URL。例如：["https://example.com/sitemap.xml"]。

    • use_browser_rendering booleanoptional

      • 使用 Browser Run（原 Browser Rendering）爬取由 JavaScript 渲染的页面。

  • store_options objectoptional

    • storage_type stringoptional

      • 存储类型。有效值：r2。

    • storage_id stringoptional

      • 存储桶 ID。

    • r2_jurisdiction stringoptional

      • 存储桶的管辖区域（jurisdiction）。

index_method objectoptional

配置实例启用哪些索引方法。决定是提供向量（语义）搜索、关键词搜索，还是两者都提供。至少有一个必须为 true。

• vector booleanoptional

  • 启用基于向量的语义搜索。默认为 true。

• keyword booleanoptional

  • 启用基于关键词的搜索。默认为 false。

将两者都设为 true 可进行混合搜索。

fusion_method stringoptional

控制在使用混合搜索时如何合并向量分数与关键词分数。有效值：rrf（Reciprocal Rank Fusion）、max（取最大分数）。默认为 rrf。

indexing_options objectoptional

内容索引方式的配置。

• keyword_tokenizer stringoptional
  • 用于关键词搜索索引的分词器。有效值：porter（基于词干提取）、trigram（字符 n-gram）。默认为 porter。

retrieval_options objectoptional

实例的默认检索配置。这些默认值可在每次请求时使用 ai_search_options 覆盖。

• keyword_match_mode stringoptional

  • 控制关键词（BM25）匹配如何选择候选文档。and 要求所有词项匹配。or 要求任意词项匹配。默认为 and。

• boost_by arrayoptional

  • 应用于所有搜索查询的默认提升字段。最多 3 项。每一项包含：
    • field stringrequired - 用于提升的元数据字段名称。最多 64 个字符。
    • direction stringoptional - 提升方向。有效值：asc、desc、exists、not_exists。

sync_interval numberoptional

自动数据源同步之间的间隔秒数。有效值：3600、7200、14400、21600、43200、86400。默认为 21600（6 小时）。

token_id stringoptional

用于此实例的服务 API token 的 UUID。仅当你从未创建过 AI Search 实例时才需要。有关如何创建和注册服务 token，请参阅 API 快速入门指南。

ai_gateway_id stringoptional

用于路由请求以进行日志记录和分析的 AI Gateway ID。

embedding_model stringoptional

用于向量化内容的嵌入模型。

ai_search_model stringoptional

用于生成响应的文本生成模型。

rewrite_query booleanoptional

启用查询改写以提高检索准确度。默认为 false。

rewrite_model stringoptional

用于查询改写的模型。

reranking booleanoptional

启用重排序，按语义相关性对检索结果重新排序。默认为 false。

reranking_model stringoptional

要使用的重排序模型。有效值：@cf/baai/bge-reranker-base。

chunk_size numberoptional

拆分文档时的分块大小。最小值：64。

chunk_overlap numberoptional

分块之间的重叠。最小值：0。

max_num_results numberoptional

默认返回的最大结果数。最小值：1。

score_threshold numberoptional

结果的默认最低分数阈值。最小值：0。

cache booleanoptional

启用响应缓存。默认为 true。

cache_threshold stringoptional

缓存匹配阈值。有效值：super_strict_match、close_enough、flexible_friend、anything_goes。默认为 close_enough。

cache_ttl numberoptional

缓存条目的 TTL（秒）。有效值为 600、1800、3600、7200、21600、43200、86400、172800、259200 和 518400。默认为 172800。

custom_metadata arrayoptional

要从文档中提取并索引的自定义元数据字段。

• field_name stringrequired

  • 元数据字段的名称。

• data_type stringrequired

  • 字段的数据类型。有效值：text、number、boolean、datetime。

enable booleanoptional

实例是否已启用。默认为 true。

返回可立即用于调用 search()、info()、stats() 与 items.upload() 等方法的 AiSearchInstance 句柄。在句柄上调用 info() 可获取实例配置。

永久删除实例及其所有已索引内容。此操作无法撤销。

await env.AI_SEARCH.delete("old-docs");

返回 void。如果实例不存在则抛出错误。

以下方法在 ai_search_namespaces 与 ai_search 绑定上均可用。使用命名空间绑定时，在 get() 返回的句柄上调用方法。使用实例绑定时，直接在绑定上调用方法（例如 env.MY_SEARCH.info()）。

以下示例使用命名空间绑定。

部分更新实例配置。仅修改你传入的字段。

const updated = await env.AI_SEARCH.get("my-instance").update({
	ai_search_model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
	reranking: true,
});

接受 创建参数 的部分版本。仅更新你包含的字段。

返回更新后的实例配置。形状与 info() 相同。

返回实例的当前配置与元数据。

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

返回实例的当前索引进度。在创建实例或上传文件后使用此方法轮询完成状态。

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

本地开发通过将请求代理到已部署的 AI Search 实例得到支持。在绑定配置中添加 remote: true，以使用 wrangler dev 启用本地开发。

// wrangler.jsonc
{
	"ai_search": [
		{
			"binding": "MY_SEARCH",
			"instance_name": "my-instance",
			"remote": true,
		},
	],
}