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 和 ai_search 绑定上均可用。使用 namespace 绑定时，在 get() 返回的句柄上调用方法。使用实例绑定时，直接在绑定上调用方法（例如 env.MY_SEARCH.search()）。

以下示例使用 namespace 绑定。

从已建立索引的数据源中搜索相关内容块。返回带源引用的评分块。

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

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

messages arrayrequired

表示对话的消息对象数组。每条消息都有 role 和 content 字段。

• role stringrequired

  • 消息发送者的角色。有效值：system、developer、user、assistant、tool。

• content stringrequired

  • 消息内容。

query stringoptional

简单文本查询字符串。作为 messages 的替代方案。请提供 query 或 messages 之一，不要同时提供。

ai_search_options objectoptional

搜索操作的配置选项。

• retrieval objectoptional

  • retrieval_type stringoptional

    • 要执行的检索类型。有效值：vector、keyword、hybrid。默认为 hybrid。

  • match_threshold numberoptional

    • 结果被视为匹配所需的最低匹配分数。必须在 0 与 1 之间。默认为 0.4。

  • max_num_results integeroptional

    • 返回的最大结果数。必须在 1 与 50 之间。默认为 10。

  • filters objectoptional

    • 根据元数据筛选搜索结果。支持比较筛选器（eq、ne、gt、gte、lt、lte）和复合筛选器（and、or）。更多详情请参阅 元数据筛选。

  • context_expansion integeroptional

    • 为提供额外上下文而包含的周围 chunk 数量。必须在 0 与 3 之间。默认为 0。

  • fusion_method stringoptional

    • 在使用混合检索时，控制如何合并向量分数与关键词分数。有效值：rrf（Reciprocal Rank Fusion）、max（取最高分数）。默认为实例级设置。

  • keyword_match_mode stringoptional

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

  • boost_by arrayoptional

    • 按元数据字段提升结果权重。最多 3 项。每项包含：
      • field stringrequired - 用于提升的元数据字段名（例如 timestamp）。最多 64 个字符。
      • direction stringoptional - 提升方向。有效值：asc、desc、exists、not_exists。数值字段默认为 asc，文本字段默认为 exists。

  • metadata_only booleanoptional

    • 仅返回每个 chunk 的元数据，不返回文本内容。

  • return_on_failure booleanoptional

    • 部分处理步骤失败时是否返回部分结果。默认为 true。

• query_rewrite objectoptional

  • enabled booleanoptional

    • 重写查询以提高检索准确性。默认为 false。

  • model stringoptional

    • 用于查询重写的模型。

  • rewrite_prompt stringoptional

    • 用于指导查询重写的自定义提示。

• reranking objectoptional

  • enabled booleanoptional

    • 使用重排序模型根据语义相关性对检索结果重新排序。默认为 false。

  • model stringoptional

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

  • match_threshold numberoptional

    • 重排序结果的最低分数。必须在 0 与 1 之间。默认为 0.4。

• cache objectoptional

  • enabled booleanoptional

    • 覆盖此请求的实例级缓存设置。

  • cache_threshold stringoptional

    • 缓存命中的相似度阈值。有效值：super_strict_match、close_enough、flexible_friend、anything_goes。

响应包含以下字段：

使用 AI Search 实例作为上下文生成聊天补全。此方法检索相关内容并据此生成响应。

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

const response = await instance.chatCompletions({
	messages: [
		{ role: "system", content: "You are a helpful documentation assistant." },
		{ role: "user", content: "What is Cloudflare?" },
	],
	model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
	ai_search_options: {
		retrieval: {
			max_num_results: 5,
		},
		query_rewrite: {
			enabled: true,
		},
	},
});

设置 stream: true，可在生成过程中以 Server-Sent Events (SSE) 形式接收响应：

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

const stream = await instance.chatCompletions({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	stream: true,
});

return new Response(stream, {
	headers: {
		"content-type": "text/event-stream",
		"cache-control": "no-cache",
	},
});

启用 stream 时，方法返回 SSE 事件的 ReadableStream。每个事件包含一个 JSON 对象，其中 choices[0].delta.content 为增量文本。流以 data: [DONE] 事件结束。

messages arrayrequired

表示对话的消息对象数组。每条消息都有 role 和 content 字段。

• role stringrequired

  • 消息发送者的角色。有效值：system、developer、user、assistant、tool。

• content stringrequired

  • 消息内容。

model stringoptional

用于生成响应的文本生成模型。默认为 AI Search 实例设置中配置的生成模型。支持的模型列表请参阅支持的模型。

stream booleanoptional

在生成过程中返回结果流。启用时，返回带有可读流的 Response 对象。默认为 false。

ai_search_options objectoptional

搜索与生成操作的配置选项。

• retrieval objectoptional

  • retrieval_type stringoptional

    • 要执行的检索类型。有效值：vector、keyword、hybrid。默认为 hybrid。

  • match_threshold numberoptional

    • 结果被视为匹配所需的最低匹配分数。必须在 0 与 1 之间。默认为 0.4。

  • max_num_results integeroptional

    • 返回结果的最大数量。必须在 1 与 50 之间。默认为 10。

  • filters objectoptional

    • 基于元数据筛选搜索结果。支持比较筛选器（eq、ne、gt、gte、lt、lte）和复合筛选器（and、or）。更多详情请参阅元数据筛选。

  • context_expansion integeroptional

    • 为提供额外上下文而包含的周围块数量。必须在 0 与 3 之间。默认为 0。

  • fusion_method stringoptional

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

  • keyword_match_mode stringoptional

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

  • boost_by arrayoptional

    • 按元数据字段提升结果权重。最多 3 项。每项包含：
      • field stringrequired - 用于提升的元数据字段名（例如 timestamp）。最多 64 个字符。
      • direction stringoptional - 提升方向。有效值：asc、desc、exists、not_exists。数值字段默认为 asc，文本字段默认为 exists。

  • metadata_only booleanoptional

    • 仅返回每个块的元数据，不返回文本内容。

  • return_on_failure booleanoptional

    • 部分处理步骤失败时是否返回部分结果。默认为 true。

• query_rewrite objectoptional

  • enabled booleanoptional

    • 重写查询以提高检索准确性。默认为 false。

  • model stringoptional

    • 用于查询重写的模型。

  • rewrite_prompt stringoptional

    • 用于指导查询重写的自定义提示词。

• reranking objectoptional

  • enabled booleanoptional

    • 使用重排序模型根据语义相关性对检索结果重新排序。默认为 false。

  • model stringoptional

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

  • match_threshold numberoptional

    • 重排序结果的最低分数。必须在 0 与 1 之间。默认为 0.4。

• cache objectoptional

  • enabled booleanoptional

    • 覆盖此请求的实例级缓存设置。

  • cache_threshold stringoptional

    • 缓存命中的相似度阈值。有效值：super_strict_match、close_enough、flexible_friend、anything_goes。

当 stream: true 时，方法返回 Server-Sent Events 的 ReadableStream。检索到的内容块会先作为 chunks 事件发送，随后是流式响应。

event: chunks
data: [{"id":"chunk-001","type":"text","score":0.85,"text":"...","item":{"key":"about-cloudflare.md","timestamp":1775925540000},"scoring_details":{"vector_score":0.85}}]

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" document"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" you provided doesn"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"'t contain"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" information"}}]}

data: [DONE]

以下方法仅在使用 ai_search_namespaces 绑定时可用。可使用 namespace 句柄（env.AI_SEARCH）在一次调用中跨多个实例搜索和对话。

在 ai_search_options 中传入 instance_ids，指定要查询的实例。结果会合并并排序，每个内容块包含 instance_id 字段，标识其来源实例。

const results = await env.AI_SEARCH.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		instance_ids: ["product-docs", "customer-abc123"],
	},
});

与 实例级 search 相同，并额外要求一个字段：

与 实例级 search 相同，并额外包含以下字段：

使用从多个实例检索的上下文生成聊天补全。

const response = await env.AI_SEARCH.chatCompletions({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		instance_ids: ["product-docs", "customer-abc123"],
	},
});

支持通过 stream: true 进行流式传输。

与 实例级 chat completions 相同，并额外要求一个字段：

与 实例级 chat completions 相同，每个内容块额外包含以下字段：

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

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