Vercel AI SDK ↗ 是用于构建大语言模型应用的 TypeScript 工具包。ai-search-provider ↗ 包将 AI Search 连接到 AI SDK,因此你可以从同一 API 生成基于已索引内容的响应、检索分块并管理文档。
本指南将构建一个 Worker:它会创建 AI Search 实例、上传并索引一份文档,然后用 AI SDK 查询该实例。
- 注册 Cloudflare 账户 ↗。
- 安装
Node.js↗。
使用 create-cloudflare CLI (C3) 创建新的 Worker 项目。C3 ↗ 是一种命令行工具,旨在帮助你设置并部署新的应用程序到 Cloudflare。
通过运行以下命令创建一个名为 ai-search-ai-sdk 的新项目:
npm create cloudflare@latest -- ai-search-ai-sdkyarn create cloudflare ai-search-ai-sdkpnpm 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安装 AI SDK 和 AI Search provider。该 provider 需要 AI SDK v6(ai@^6):
npm i ai ai-search-provideryarn add ai ai-search-providerpnpm add ai ai-search-providerbun add 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 项目已满足该要求。
添加一个 /setup 路由,用于创建实例并上传文档。新实例默认使用 混合搜索。
create() 方法位于 namespace 绑定(env.AI_SEARCH)上,而不是 provider 客户端上。创建已存在的实例会抛出错误,因此以下代码会在后续运行中忽略该错误。
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=");
},
};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。
有三种从 AI SDK 查询实例的方式。选择适合你应用的一种:
将 instance.chat() 传给 generateText,AI Search 会在一次调用中检索相关内容并生成响应。
将 fetch 处理程序中的查询占位符替换为以下内容:
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 });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 zodyarn add workers-ai-provider@^3 zodpnpm add workers-ai-provider@^3 zodbun add 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),
});部署前,使用 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,然后重试查询。
使用你的 Cloudflare 账户登录:
npx wrangler login部署 Worker,使其可在 Internet 上访问:
npx wrangler deploy- 聊天模型仅支持文本。不支持文件和图像消息部分。
- 诸如
temperature和maxOutputTokens等生成选项会透传到实例的生成模型。maxOutputTokens会截断响应,并将finishReason设为"length"。如果模型忽略某个选项,结果的warnings数组仍为空,因此不受支持的选项会静默失败。 - AI Search 默认使用实例上配置的生成模型。传入
instance.chat({ model: "..." })可按请求覆盖它。