跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

Workers 绑定（binding）

最后更新 查看 MarkdownAgent 设置

Workers 提供无服务器执行环境，可用于创建新应用或增强现有应用。使用 Workers 绑定（binding） 从 Cloudflare Worker 上传、列出和管理 AI Search 实例中的文档。通过实例句柄上的 items 属性访问 Items API。

配置绑定

要在 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"
字段 类型 必需 描述
binding string 是 env 上可用的变量名。例如 "AI_SEARCH" 可通过 env.AI_SEARCH 访问。
namespace string 是 要绑定的命名空间。每个账户会自动创建 default 命名空间。若命名空间不存在，Wrangler 会在部署时创建。
remote boolean 否 使用 wrangler dev 进行本地开发时设置为 true。

实例绑定

直接绑定到 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"
字段 类型 必需 描述
binding string 是 env 上可用的变量名。例如 "MY_SEARCH" 可通过 env.MY_SEARCH 访问。
instance_name string 是 AI Search 实例的名称。部署时必须在 default 命名空间中存在。
remote boolean 否 使用 wrangler dev 进行本地开发时设置为 true。

方法

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

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

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

items.upload()

上传文档以建立索引。立即返回。文档会排队等待处理。

// Upload from a string
await instance.items.upload(
	"faq.md",
	"# FAQ\n\nQ: How do I reset my password?\nA: Go to Settings > Security...",
);

// Upload from an ArrayBuffer
const pdfResponse = await fetch("https://example.com/guide.pdf");
const pdfBuffer = await pdfResponse.arrayBuffer();
await instance.items.upload("guide.pdf", pdfBuffer);

// Upload from a ReadableStream
await instance.items.upload("doc.txt", request.body);

上传时附带元数据

为文档附加自定义元数据，以便在搜索查询中筛选。自定义元数据字段必须先在实例上通过 update() 方法定义，或在创建时定义。

await instance.items.upload("guide.pdf", pdfBuffer, {
	metadata: {
		category: "onboarding",
		language: "en",
		version: "2.0",
	},
});

参数

参数 类型 是否必需 说明
name string 是 上传文档的文件名。用作 item key。
content ReadableStream、ArrayBuffer 或 string 是 文档内容。最大文件大小为 4 MB。纯文本或 markdown 传 string，二进制文件传 ArrayBuffer，流式上传传 ReadableStream。
options.metadata Record<string, string> 否 附加到 item 的自定义元数据键值对。用于在搜索查询中筛选。每个实例最多 5 个字段。

响应

字段 类型 说明
id string item 的唯一标识符。
key string item 的文件名或 key。

items.uploadAndPoll()

上传文档并轮询，直到处理完成或超时。在需要上传后立即搜索该文档时使用。

// Wait for a specific document to finish indexing before searching
const item = await instance.items.uploadAndPoll(
	"handbook.txt",
	handbookContent,
);
console.log(`handbook.txt status: ${item.status}`); // "completed"

// Now search across all uploaded documents
const results = await instance.search({
	messages: [{ role: "user", content: "password reset policy" }],
});

参数

与 items.upload() 相同，并额外提供轮询选项：

参数 类型 是否必需 说明
options.pollIntervalMs number 否 检查 item 状态的间隔（毫秒）。默认为 1000。
options.timeoutMs number 否 等待处理完成的最长时间（毫秒）。默认为 30000。

响应

轮询完成后返回完整的 item 对象：

字段 类型 说明
id string item 的唯一标识符。
key string item 的文件名或 key。
status string 处理状态：queued、running、completed、error、skipped、outdated。
chunks_count number 从文档创建的 chunk 数量。
file_size number 上传文件的大小（字节）。
metadata object item 元数据，包括 filename、folder 和 timestamp。
source_id string 来源标识符（例如上传文件为 builtin）。
created_at string item 创建时间戳。
last_seen_at string 索引过程中上次看到 item 的时间戳。

items.list()

返回实例中 item 的分页列表。

const { result, result_info } = await instance.items.list();

for (const item of result) {
	console.log(`${item.key} (${item.status})`);
}
// result_info.total_count contains the total number of items

参数

参数 类型 是否必需 说明
page number 否 要返回的页码。默认为 1。
per_page number 否 每页 item 数。默认为 20。最大 50。
status string 否 按处理状态筛选：queued、running、completed、error、skipped 或 outdated。
sort_by string 否 item 排序：status（默认）或 modified_at。
search string 否 按文本内容搜索 item。
source string 否 按来源标识符筛选（例如上传文件为 builtin）。

响应

字段 类型 说明
result array item 对象数组。
result[].id string item 的唯一标识符。
result[].key string item 的文件名或 key。
result[].status string 处理状态：queued、running、completed、error、skipped、outdated。
result[].chunks_count number 从文档创建的 chunk 数量。
result[].file_size number 上传文件的大小（字节）。
result[].metadata object item 元数据，包括 filename、folder 和 timestamp。
result[].source_id string 来源标识符（例如上传文件为 builtin）。
result[].created_at string item 创建时间戳。
result[].last_seen_at string 索引过程中上次看到 item 的时间戳。
result_info object 分页元数据。
result_info.count number 当前页的 item 数量。
result_info.total_count number 实例中的 item 总数。
result_info.page number 当前页码。
result_info.per_page number 每页 item 数。

items.delete()

删除 item 及其已索引的 chunk。

await instance.items.delete("item-id-123");

参数

参数 类型 是否必需 说明
itemId string 是 要删除的 item 的唯一标识符。

响应

返回 void。若 item 不存在则抛出错误。

items.get()

返回特定 item 的句柄，用于获取其状态或下载原始文件。

items.get().info()

返回特定 item 的状态与元数据。

const itemInfo = await instance.items.get("item-id-123").info();
参数
参数 类型 是否必需 说明
itemId string 是 item 的唯一标识符。
响应
字段 类型 说明
id string item 的唯一标识符。
key string item 的文件名或 key。
status string 处理状态：queued、running、completed、error、skipped、outdated。
chunks_count number 从文档创建的 chunk 数量。
file_size number 上传文件的大小（字节）。
metadata object item 元数据，包括 filename、folder 和 timestamp。
source_id string 来源标识符（例如上传文件为 builtin）。
created_at string item 创建时间戳。
last_seen_at string 索引过程中上次看到 item 的时间戳。

items.get().download()

下载 item 的原始源文件。

const file = await instance.items.get("item-id-123").download();
// file.body is a ReadableStream
参数
参数 类型 是否必需 说明
itemId string 是 item 的唯一标识符。
响应
字段 类型 说明
filename string 原始文件名。
contentType string 文件的 MIME 类型（例如 application/pdf）。
size number 文件大小（字节）。
body ReadableStream 文件内容的可读流。

这篇文档对您有帮助吗？