跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

AI SDK

最后更新 查看 MarkdownAgent 设置

Vercel AI SDK ↗ 是用于构建大语言模型应用的 TypeScript 工具包。ai-search-provider ↗ 包将 AI Search 连接到 AI SDK,因此你可以从同一 API 生成基于已索引内容的响应、检索分块并管理文档。

本指南将构建一个 Worker:它会创建 AI Search 实例、上传并索引一份文档,然后用 AI SDK 查询该实例。

前提条件

  1. 注册 Cloudflare 账户 ↗。
  2. 安装 Node.js ↗。

Node.js 版本管理器

使用 Vite+ (vp env) ↗ 安装和管理 Node.js 版本。

有关支持的 Node.js 版本,请参阅 Wrangler 系统要求。

1. 创建 Worker 项目

使用 create-cloudflare CLI (C3) 创建新的 Worker 项目。C3 ↗ 是一种命令行工具,旨在帮助你设置并部署新的应用程序到 Cloudflare。

通过运行以下命令创建一个名为 ai-search-ai-sdk 的新项目:

npm create cloudflare@latest -- ai-search-ai-sdk

设置时,选择以下选项:

  • 对于 What would you like to start with?(希望从什么开始?),选择 Hello World example。
  • 对于 Which template would you like to use?(希望使用哪个模板?),选择 Worker only。
  • 对于 Which language do you want to use?(希望使用哪种语言?),选择 TypeScript。
  • 对于 Do you want to use git for version control?(是否使用 Git 进行版本控制?),选择 Yes。
  • 对于 Do you want to add an AGENTS.md file to help AI coding tools understand Cloudflare APIs?(是否添加 AGENTS.md 文件以帮助 AI 编程工具理解 Cloudflare API?),选择 Yes。
  • 对于 Do you want to deploy your application?(是否部署应用?),选择 No(部署前还需要进行一些修改)。

进入你的应用程序目录:

cd ai-search-ai-sdk

2. 安装 AI SDK 和 provider

安装 AI SDK 和 AI Search provider。该 provider 需要 AI SDK v6(ai@^6):

npm i ai ai-search-provider

在 Worker 与 AI Search 之间创建绑定。绑定(binding) 让 Worker 能够与 Cloudflare Developer Platform 上的资源交互。

将以下内容添加到你的 Wrangler 配置文件:

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

这会将 default namespace 绑定到 env.AI_SEARCH。remote 选项让 wrangler dev 将请求代理到已部署的实例,因为 AI Search 不会在本地运行。ai_search_namespaces 绑定要求 compatibility_date 为 2026-03-27 或更晚,新的 C3 项目已满足该要求。

4. 创建实例并索引内容

添加一个 /setup 路由,用于创建实例并上传文档。新实例默认使用 混合搜索。

create() 方法位于 namespace 绑定(env.AI_SEARCH)上,而不是 provider 客户端上。创建已存在的实例会抛出错误,因此以下代码会在后续运行中忽略该错误。

src/index.jsjs
import { createAISearchNamespace } from "ai-search-provider";
import { generateText, streamText } from "ai";

const INSTANCE_NAME = "knowledge-base";

const SAMPLE_DOC = `# Caching on Cloudflare
Cloudflare caches static assets at the edge. Use Cache Rules to control what is
cached, set an Edge Cache TTL to control how long objects stay in cache, and
purge the cache after a deploy.`;

async function ensureInstance(env) {
	try {
		await env.AI_SEARCH.create({ id: INSTANCE_NAME });
	} catch {
		// intentional fallback, nothing to handle
	}
}

export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		// createAISearchNamespace adapts the binding to the AI SDK provider API.
		const aiSearch = createAISearchNamespace({ binding: env.AI_SEARCH });

		// Visit /setup once to create the instance and index a document.
		if (url.pathname === "/setup") {
			await ensureInstance(env);

			const instance = aiSearch.get(INSTANCE_NAME);

			// upload() queues the file and returns immediately. Indexing runs in
			// the background, so poll the item's status until it is searchable.
			const { id, key } = await instance.items.upload("caching.md", SAMPLE_DOC);

			let info = await instance.items.get(id).info();
			while (info.status === "queued" || info.status === "running") {
				await new Promise((resolve) => setTimeout(resolve, 2_000));
				info = await instance.items.get(id).info();
			}

			return Response.json({ key, status: info.status });
		}

		// Query the instance (see the next step).
		return new Response("Visit /setup first, then query with ?q=");
	},
};
src/index.tsts
import { createAISearchNamespace } from "ai-search-provider";
import { generateText, streamText } from "ai";

interface Env {
	AI_SEARCH: AiSearchNamespace;
}

const INSTANCE_NAME = "knowledge-base";

const SAMPLE_DOC = `# Caching on Cloudflare
Cloudflare caches static assets at the edge. Use Cache Rules to control what is
cached, set an Edge Cache TTL to control how long objects stay in cache, and
purge the cache after a deploy.`;

async function ensureInstance(env: Env) {
	try {
		await env.AI_SEARCH.create({ id: INSTANCE_NAME });
	} catch {
		// intentional fallback, nothing to handle
	}
}

export default {
	async fetch(request, env): Promise<Response> {
		const url = new URL(request.url);
		// createAISearchNamespace adapts the binding to the AI SDK provider API.
		const aiSearch = createAISearchNamespace({ binding: env.AI_SEARCH });

		// Visit /setup once to create the instance and index a document.
		if (url.pathname === "/setup") {
			await ensureInstance(env);

			const instance = aiSearch.get(INSTANCE_NAME);

			// upload() queues the file and returns immediately. Indexing runs in
			// the background, so poll the item's status until it is searchable.
			const { id, key } = await instance.items.upload("caching.md", SAMPLE_DOC);

			let info = await instance.items.get(id).info();
			while (info.status === "queued" || info.status === "running") {
				await new Promise((resolve) => setTimeout(resolve, 2_000));
				info = await instance.items.get(id).info();
			}

			return Response.json({ key, status: info.status });
		}

		// Query the instance (see the next step).
		return new Response("Visit /setup first, then query with ?q=");
	},
} satisfies ExportedHandler<Env>;

运行 wrangler types 后即可使用环境类型 AiSearchNamespace。

5. 查询实例

有三种从 AI SDK 查询实例的方式。选择适合你应用的一种:

生成响应

将 instance.chat() 传给 generateText,AI Search 会在一次调用中检索相关内容并生成响应。

将 fetch 处理程序中的查询占位符替换为以下内容:

src/index.jsjs
const query = url.searchParams.get("q") ?? "How does caching work?";

// chat() returns an AI SDK model that retrieves matching chunks and generates
// a grounded answer in one call, so there is no separate search step.
const { text, sources } = await generateText({
	model: aiSearch.get(INSTANCE_NAME).chat({
		ai_search_options: {
			// "hybrid" ranks results from both the vector and keyword indexes.
			retrieval: { retrieval_type: "hybrid", max_num_results: 5 },
		},
	}),
	messages: [{ role: "user", content: query }],
});

// `sources` holds the retrieved chunks, so you can cite them alongside `text`.
return Response.json({ text, sources });
src/index.tsts
const query = url.searchParams.get("q") ?? "How does caching work?";

// chat() returns an AI SDK model that retrieves matching chunks and generates
// a grounded answer in one call, so there is no separate search step.
const { text, sources } = await generateText({
	model: aiSearch.get(INSTANCE_NAME).chat({
		ai_search_options: {
			// "hybrid" ranks results from both the vector and keyword indexes.
			retrieval: { retrieval_type: "hybrid", max_num_results: 5 },
		},
	}),
	messages: [{ role: "user", content: query }],
});

// `sources` holds the retrieved chunks, so you can cite them alongside `text`.
return Response.json({ text, sources });

AI Search 会将检索到的分块作为 AI SDK source 部分返回到 sources 中,因此你可以在生成文本旁引用它们。由于该实例同时为向量和关键词建立索引,retrieval_type: "hybrid" 会同时使用两者。

流式响应

对于较长的响应,请使用 streamText 而不是 generateText。AI Search 会在第一个文本部分之前,将检索到的分块作为 source 部分发出。

// streamText returns right away; tokens stream in as they are generated.
const result = streamText({
	model: aiSearch.get(INSTANCE_NAME).chat(),
	messages: [{ role: "user", content: query }],
});

// toTextStreamResponse() streams the generated text only.
return result.toTextStreamResponse();
// streamText returns right away; tokens stream in as they are generated.
const result = streamText({
	model: aiSearch.get(INSTANCE_NAME).chat(),
	messages: [{ role: "user", content: query }],
});

// toTextStreamResponse() streams the generated text only.
return result.toTextStreamResponse();

toTextStreamResponse() 只发送生成的文本并丢弃来源。若要同时流式传输检索到的分块,请返回启用了 sendSources 的 UI 消息流,或直接读取 result.fullStream:

// sendSources forwards each retrieved chunk as a source-url part. They arrive
// before the first text part, so you can render citations as the answer streams.
return result.toUIMessageStreamResponse({ sendSources: true });
// sendSources forwards each retrieved chunk as a source-url part. They arrive
// before the first text part, so you can render citations as the answer streams.
return result.toUIMessageStreamResponse({ sendSources: true });

将搜索用作工具

使用 chat() 时,AI Search 会在每个请求上搜索实例。若要让模型自行决定何时搜索,请将 instance.search() 作为 AI SDK 工具 ↗ 暴露,并将其传给支持函数调用的模型,例如 Workers AI 模型。这是智能体中应使用的模式:模型会在搜索与其他工具之间选择。

安装 Workers AI provider 和 Zod。请使用 workers-ai-provider 的第 3 版:最新的第 4 版需要 AI SDK v7,而 ai-search-provider 需要 v6,因此 npm 无法将它们一起安装。

npm i workers-ai-provider@^3 zod

向 Wrangler 配置添加 Workers AI 绑定:

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

然后定义搜索工具。模型在需要检索内容时会调用它:

import { createWorkersAI } from "workers-ai-provider";
import { generateText, tool, stepCountIs } from "ai";
import { z } from "zod";

const instance = aiSearch.get(INSTANCE_NAME);
// The tool-caller must support function calling. Use a dedicated model here
// rather than the AI Search chat model, which retrieves on every request.
const workersai = createWorkersAI({ binding: env.AI });

const { text } = await generateText({
	model: workersai("@cf/zai-org/glm-5.2"),
	messages: [{ role: "user", content: query }],
	tools: {
		search_knowledge_base: tool({
			description: "Search the indexed knowledge base for relevant content.",
			inputSchema: z.object({
				query: z.string().describe("The search query"),
			}),
			// The model decides when to call this; it searches the instance.
			execute: async ({ query }) =>
				instance.search({
					query,
					ai_search_options: { retrieval: { max_num_results: 5 } },
				}),
		}),
	},
	// Cap the tool-call loop so the model cannot invoke tools indefinitely.
	stopWhen: stepCountIs(5),
});
import { createWorkersAI } from "workers-ai-provider";
import { generateText, tool, stepCountIs } from "ai";
import { z } from "zod";

const instance = aiSearch.get(INSTANCE_NAME);
// The tool-caller must support function calling. Use a dedicated model here
// rather than the AI Search chat model, which retrieves on every request.
const workersai = createWorkersAI({ binding: env.AI });

const { text } = await generateText({
	model: workersai("@cf/zai-org/glm-5.2"),
	messages: [{ role: "user", content: query }],
	tools: {
		search_knowledge_base: tool({
			description: "Search the indexed knowledge base for relevant content.",
			inputSchema: z.object({
				query: z.string().describe("The search query"),
			}),
			// The model decides when to call this; it searches the instance.
			execute: async ({ query }) =>
				instance.search({
					query,
					ai_search_options: { retrieval: { max_num_results: 5 } },
				}),
		}),
	},
	// Cap the tool-call loop so the model cannot invoke tools indefinitely.
	stopWhen: stepCountIs(5),
});

6. 在本地测试

部署前,使用 wrangler dev 确认整个流程可针对你的实例运行,它会代理远程 AI Search 绑定。以下输出对应 生成响应 选项。

启动本地开发服务器:

npx wrangler dev

首先访问 /setup 以索引示例文档:

curl http://localhost:8787/setup

首次 /setup 可能需要一两分钟,等待文档完成索引。完成后会返回 item key 和 completed 状态:

{ "key": "caching.md", "status": "completed" }

然后查询实例:

curl "http://localhost:8787/?q=How+does+caching+work%3F"

有效的集成会返回基于文档生成的 text,以及引用所检索文件的 sources 数组(字段已精简):

{
	"text": "Cloudflare caches static assets at the edge...",
	"sources": [{ "sourceType": "url", "url": "caching.md" }]
}

如果 sources 为空,说明文档尚未完成索引。再次运行 /setup,然后重试查询。

7. 部署

使用你的 Cloudflare 账户登录:

npx wrangler login

部署 Worker,使其可在 Internet 上访问:

npx wrangler deploy

注意事项

  • 聊天模型仅支持文本。不支持文件和图像消息部分。
  • 诸如 temperature 和 maxOutputTokens 等生成选项会透传到实例的生成模型。maxOutputTokens 会截断响应,并将 finishReason 设为 "length"。如果模型忽略某个选项,结果的 warnings 数组仍为空,因此不受支持的选项会静默失败。
  • AI Search 默认使用实例上配置的生成模型。传入 instance.chat({ model: "..." }) 可按请求覆盖它。

后续步骤

混合搜索

结合向量搜索与关键词搜索,并配置融合方式。

Agents SDK

构建可搜索实例的有状态聊天智能体。

这篇文档对您有帮助吗?