Workers 绑定迁移

env.AI.autorag() 绑定是 AI Search 的旧版 API。它将继续可用，但所有新功能与改进仅通过新的 AI Search 绑定提供。

变更内容

以下是旧版绑定与新绑定之间的主要差异摘要：

	旧版	新版
Wrangler 配置	`ai` 绑定	`ai_search` 或 `ai_search_namespaces` 绑定
访问模式	`env.AI.autorag("name")`	`env.MY_INSTANCE` 或 `env.AI_SEARCH.get("name")`
搜索格式	`query` 字符串	`messages` 数组或 `query` 字符串
响应格式	`data` 数组	`chunks` 数组

AI Search 绑定

AI Search 提供两种新绑定：

实例绑定（ai_search） 直接绑定到单个实例。这是从 env.AI.autorag() 迁移的最简单路径。

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

命名空间绑定（ai_search_namespaces） 使你能够访问命名空间内的所有实例。如果你需要动态实例管理、跨实例搜索或 Items API，请使用此绑定。

// wrangler.jsonc
{
	"ai_search_namespaces": [
		{
			"binding": "AI_SEARCH",
			"namespace": "default",
		},
	],
}

有关差异的更多详情，请参阅命名空间。

要求

新绑定需要以下最低包版本，以支持 TypeScript 类型与本地开发。

包	最低版本
`@cloudflare/workers-types`	`4.20260304.0`
`wrangler`	`4.68.1`

步骤 1：更新 Wrangler 配置

现有实例位于默认命名空间中。对于简单的升级路径，使用实例绑定。对于命名空间绑定，请参阅 AI Search 绑定。

之前：

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "ai": {
    "binding": "AI"
  }
}

[ai]
binding = "AI"

之后：

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

compatibility_date = "2026-03-27"

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

步骤 2：更新类型定义

更新 Env 接口以使用新的绑定类型。

之前：

export interface Env {
	AI: Ai;
}

之后：

export interface Env {
	MY_INSTANCE: AiSearchInstance;
}

步骤 3：更新搜索调用

将 env.AI.autorag() 调用替换为新绑定。

之前：

const result = await env.AI.autorag("my-instance").search({
	query: "What is Cloudflare?",
});

之后：

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

步骤 4：更新响应处理

响应结构从 data 数组变为 chunks 数组。

字段映射

旧字段	新字段
`data[]`	`chunks[]`
`data[].file_id`	`chunks[].id`
`data[].filename`	`chunks[].item.key`
`data[].score`	`chunks[].score`
`data[].content[].text`	`chunks[].text`
`data[].attributes.modified_date`	`chunks[].item.timestamp`

流式行为变更

在旧版绑定中，使用 env.AI.autorag().aiSearch({ stream: true }) 进行流式传输时，仅返回流式响应，不包含检索到的分块。

新绑定会先将检索到的分块作为 chunks 事件发送，然后是流式响应。这使你能够在流式生成响应的同时立即显示源分块。

筛选格式变更

新绑定使用 Vectorize 风格的元数据筛选。筛选器现在通过 ai_search_options.retrieval.filters 传入。

旧格式	新格式
`eq`	`$eq`（或隐式）
`ne`	`$ne`
`gt`	`$gt`
`gte`	`$gte`
`lt`	`$lt`
`lte`	`$lte`
	`$in`（新增）
	`$nin`（新增）

示例

简单筛选

使用隐式相等按单个元数据字段筛选：

之前：

const result = await env.AI.autorag("my-instance").search({
	query: "What is Cloudflare?",
	filters: {
		type: "eq",
		key: "folder",
		value: "customer-a/",
	},
});

之后：

const result = await env.MY_INSTANCE.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		retrieval: {
			filters: { folder: "customer-a/" },
		},
	},
});

复合筛选（AND）

组合多个条件（全部必须匹配）：

之前：

const result = await env.AI.autorag("my-instance").search({
	query: "What is Cloudflare?",
	filters: {
		type: "and",
		filters: [
			{ type: "eq", key: "folder", value: "customer-a/" },
			{ type: "gte", key: "timestamp", value: "1735689600000" },
		],
	},
});

之后：

const result = await env.MY_INSTANCE.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		retrieval: {
			filters: {
				folder: "customer-a/",
				timestamp: { $gte: 1735689600 },
			},
		},
	},
});

向后兼容性

env.AI.autorag() 绑定将无限期继续可用。你不必立即迁移。

旧版 API 参考请参阅 Workers 绑定（旧版）。