Cloudflare 最近搞了个“Agents Week”核心不是发布一个具体产品而是把过去几年在 AI 基础设施上做的各种能力打包成一个面向“智能体”的完整形态叫Agent Cloud。如果你正在做 AI 应用特别是想把大模型能力稳定、安全地集成到业务里或者想自己搭建一个智能体平台那 Cloudflare 这套组合拳值得花时间研究一下。它解决的核心问题很实际怎么让智能体从“能跑通 Demo”到“能在生产环境里稳定、安全、低成本地跑起来”。很多团队在本地用 LangChain 或 AutoGPT 搭了个原型一到要处理真实用户请求、管理大量上下文、控制成本、保障数据安全时就卡住了。Agent Cloud 瞄准的就是这个“最后一公里”的工程化问题。这篇文章我会拆解 Agent Cloud 到底提供了什么更重要的是从一线开发的角度看这套方案适合谁、怎么上手、关键环节怎么配置以及落地时最容易踩哪些坑。我不会只复述官方新闻稿而是结合常见的智能体开发流程告诉你哪些能力可以直接用哪些需要自己补帮你判断它是不是你当前项目的最优解。1. 先拆解 Agent Cloud它到底是一套什么能力别被“Agent Cloud”这个名字唬住它不是突然冒出来的新东西而是 Cloudflare 把已有的 Workers AI、Vectorize、R2、D1、Workers、Pages 这些服务用“智能体”这个视角重新包装和打通了。你可以把它理解成一个“智能体应用的全托管运行时”。对于开发者来说最直观的价值是几个“不用操心”不用操心模型部署和推理通过 Workers AI你可以直接调用多个开源和闭源模型比如 Llama、Mistral、Gemma 等按请求付费没有冷启动全球边缘节点低延迟。你不用自己去租 GPU 服务器、搞模型量化、处理并发队列。不用操心向量数据库运维Vectorize 是它的全托管向量数据库。智能体需要长期记忆或知识库检索RAG你得存 Embedding 和做相似度搜索Vectorize 直接集成在 Workers 环境里省去了自建 Milvus、Pinecone 这类服务的麻烦。不用操心文件存储和状态持久化智能体经常要处理用户上传的文档、生成的图片或者需要记住会话状态。R2对象存储和 D1SQLite 数据库就是干这个的同样深度集成。不用操心应用部署和全球分发你的智能体逻辑写在 Cloudflare Workers无服务器函数里写完就全球部署了。用 Pages 可以快速部署带前端界面的智能体应用。所以Agent Cloud 的本质是“基础设施即智能体运行时”。它不提供一个开箱即用的智能体框架比如像 Dify、Coze 那样的可视化编排平台而是提供了搭建这类平台所需的所有底层积木并且这些积木在同一个生态内天然互通网络延迟极低。它最适合哪类人全栈或后端开发者你习惯写代码不想被黑盒平台限制希望完全控制智能体的逻辑、数据流和成本。已有 Cloudflare 生态的团队如果你已经在用 Workers、R2那么接入 AI 能力会非常平滑。对数据隐私和合规有要求的项目Cloudflare 强调数据不出其网络 Workers AI 推理也在其基础设施上完成这对某些行业是个加分项。需要快速原型验证并考虑未来平滑扩容的创业项目从零到一快从一到一百也无需重构架构。2. 从零开始用 Agent Cloud 思维搭建你的第一个智能体我们不用“Hello World”来做一个有点实际用处的一个能回答特定知识库问题的客服智能体。假设我们有一个产品的 FAQ 文档。2.1 环境与账号准备首先你需要一个 Cloudflare 账户。去 Cloudflare Dashboard 注册就行。然后在本地安装 Wrangler CLI这是管理 Cloudflare Workers 项目的官方工具。npm install -g wrangler # 或者用 pnpm / yarn wrangler login登录后你的本地环境就关联到了 Cloudflare 账户。2.2 创建项目与核心逻辑我们创建一个新的 Worker 项目wrangler init my-knowledge-agent cd my-knowledge-agent项目初始化后你会看到src/index.ts等文件。我们主要在这里写逻辑。现在思考智能体的核心流程用户提问。将用户问题转换成向量Embedding。去向量数据库Vectorize里搜索最相关的文档片段。把搜索到的片段和用户问题一起组合成提示词Prompt发给大模型Workers AI。将模型的回答返回给用户。所以我们需要三步准备知识库、处理查询、集成回复。2.3 第一步构建知识库Vectorize假设你的 FAQ 是几个 Markdown 文件。你需要一个脚本读取它们切分成片段调用 Workers AI 的 Embedding 模型生成向量然后存入 Vectorize。首先创建 Vectorize 索引wrangler vectorize create my-faq-index --dimensions768这里--dimensions768要对应你选的 Embedding 模型的输出维度比如cf/baai/bge-base-en-v1.5模型就是 768 维。然后写一个预处理脚本比如ingest.mjsimport { createClient } from neondatabase/serverless; // 假设源数据在外部数据库这里仅为示例结构 import { Ai } from cloudflare/ai; // 这个脚本通常在本地或一次性运行用于灌入数据 export default { async fetch(request, env) { const ai new Ai(env.AI); // 1. 从某处获取原始文本数据 const faqTexts [...]; // 你的FAQ文本数组 const vectors []; for (const text of faqTexts) { // 2. 调用Embedding模型 const embeddings await ai.run(cf/baai/bge-base-en-v1.5, { text: [text] }); // 3. 构建向量记录 vectors.push({ id: /* 生成唯一ID */, values: embeddings.data[0], metadata: { text } }); } // 4. 批量插入Vectorize const inserted await env.MY_FAQ_INDEX.upsert(vectors); return new Response(JSON.stringify(inserted)); } }关键点Embedding 模型的选择很重要。中英文混合选cf/baai/bge-m3纯英文可选cf/baai/bge-base-en-v1.5。维度和模型必须匹配否则插入会失败。2.4 第二步在 Worker 中实现查询逻辑修改src/index.ts这是智能体的主入口。export interface Env { AI: any; MY_FAQ_INDEX: VectorizeIndex; } export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): PromiseResponse { if (request.method ! POST) { return new Response(请使用 POST 请求并发送 JSON 数据, { status: 405 }); } try { const { question } await request.json{ question: string }(); const ai new Ai(env.AI); // 1. 将用户问题转换为向量 const questionEmbedding await ai.run(cf/baai/bge-base-en-v1.5, { text: [question], }); // 2. 在 Vectorize 中搜索相似片段 const vectors await env.MY_FAQ_INDEX.query(questionEmbedding.data[0], { topK: 3 }); // 3. 构建上下文 const context vectors.matches.map(match match.metadata?.text).join(\n---\n); // 4. 组合 Prompt调用 LLM 生成回答 const prompt 你是一个专业的客服助手。请严格根据以下已知信息来回答问题。如果已知信息不足以回答问题请直接说“根据现有资料我无法回答这个问题”不要编造信息。 已知信息 ${context} 问题${question} 请用中文回答; const response await ai.run(cf/meta/llama-3.2-3b-instruct, { prompt, max_tokens: 500, }); // 5. 返回回答 return new Response(JSON.stringify({ answer: response.response, sources: vectors.matches.map(m ({ id: m.id, score: m.score })) // 可返回引用来源 }), { headers: { Content-Type: application/json }, }); } catch (error) { console.error(处理请求时出错:, error); return new Response(JSON.stringify({ error: 内部服务器错误 }), { status: 500, headers: { Content-Type: application/json }, }); } }, };几个实操细节模型选择cf/meta/llama-3.2-3b-instruct是一个 30 亿参数模型响应快成本低适合简单问答。对质量要求高可以换cf/meta/llama-3.3-70b-instruct更慢更贵。TopK 参数topK: 3表示返回最相似的 3 条记录。这个数不是越大越好太多无关信息会干扰模型。一般从 3-5 开始调。Prompt 工程这里的 Prompt 明确要求模型“根据已知信息回答”并设置了拒绝回答的指令这是构建可靠 RAG 系统的关键能大幅减少模型胡言乱语幻觉。错误处理一定要用try...catch包住核心逻辑并返回友好的错误信息。智能体 API 对外暴露各种意外输入都可能出现。2.5 第三步部署与测试在项目根目录的wrangler.toml中绑定你的资源name my-knowledge-agent compatibility_date 2024-08-01 [[ai.datasets]] binding AI # 必须叫 AI [[vectorize]] binding MY_FAQ_INDEX # 与代码中的 env.MY_FAQ_INDEX 对应 index_name my-faq-index然后部署wrangler deploy部署成功后你会得到一个*.workers.dev的域名。用 curl 或 Postman 测试curl -X POST https://my-knowledge-agent.your-subdomain.workers.dev \ -H Content-Type: application/json \ -d {question: 你们的产品如何收费}如果一切正常你会收到一个包含answer和sources的 JSON 响应。3. 超越基础问答Agent Cloud 的进阶能力与架构设计一个简单的问答机器人只是开始。真正的智能体可能需要工具调用Function Calling、长期记忆、多步骤推理、与外部 API 交互等。我们来看看如何用 Agent Cloud 的组件实现这些。3.1 实现工具调用与外部动作假设我们的智能体需要查询天气。我们需要定义工具函数并在 Prompt 中让模型学会调用它。首先在 Worker 中定义工具列表和对应的执行函数// 定义工具函数的 schema遵循 OpenAI 的格式 const tools [ { type: function, function: { name: get_current_weather, description: 获取指定城市的当前天气, parameters: { type: object, properties: { location: { type: string, description: 城市名例如北京上海, }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位, }, }, required: [location], }, }, }, ]; // 工具的实际执行函数 async function executeTool(toolName: string, args: any) { switch (toolName) { case get_current_weather: // 这里模拟调用一个外部天气 API const mockWeather { location: args.location, temperature: 22, unit: args.unit || celsius, condition: 晴朗 }; return JSON.stringify(mockWeather); default: return 未知工具: ${toolName}; } }然后在调用模型时启用工具调用并处理响应// 在原有的 ai.run 调用中增加工具参数 const response await ai.run(cf/meta/llama-3.3-70b-instruct, { messages: [ { role: system, content: 你是一个有帮助的助手可以调用工具来回答问题。 }, { role: user, content: question } ], tools: tools, // 传入工具定义 tool_choice: auto, // 让模型决定是否调用工具 }); let finalAnswer response.response; // 检查模型是否决定调用工具 if (response.tool_calls response.tool_calls.length 0) { const toolCall response.tool_calls[0]; const toolResult await executeTool(toolCall.function.name, JSON.parse(toolCall.function.arguments)); // 将工具执行结果作为新的上下文再次发送给模型让它生成面向用户的最终回答 const secondResponse await ai.run(cf/meta/llama-3.3-70b-instruct, { messages: [ { role: system, content: 你是一个有帮助的助手。 }, { role: user, content: question }, { role: assistant, content: null, tool_calls: response.tool_calls }, { role: tool, content: toolResult, tool_call_id: toolCall.id } ], }); finalAnswer secondResponse.response; } // ... 返回 finalAnswer关键点不是所有 Cloudflare Workers AI 上的模型都支持工具调用需要查官方文档。像llama-3.3-70b-instruct这类较新的指令微调模型通常支持。这个过程本质上是让模型输出一个结构化请求“我要调用 get_current_weather参数是...”然后由你的代码接管执行再把结果塞回上下文让模型总结。3.2 利用 D1 和 R2 实现状态管理与文件处理长期记忆会话状态智能体需要记住和用户的对话历史。你可以用 D1SQLite来存。在wrangler.toml中配置 D1 数据库然后在 Worker 中// 创建或获取会话 const sessionId request.headers.get(X-Session-ID) || generateId(); const history await env.MY_D1.prepare(SELECT content FROM chat_history WHERE session_id ? ORDER BY created_at DESC LIMIT 10).bind(sessionId).all(); // 将 history 融入 messages // 对话结束后将新的交互存入 D1 await env.MY_D1.prepare(INSERT INTO chat_history (session_id, role, content) VALUES (?, ?, ?)).bind(sessionId, user, question).run();文件处理用户上传 PDF 或图片智能体需要读取内容。你可以用 R2 存文件用 Workers AI 的视觉或多模态模型如cf/unum/uform-gen2-qwen-500m或文档解析模型来处理。// 假设前端上传了文件 const formData await request.formData(); const file formData.get(file); const fileName uploads/${crypto.randomUUID()}-${file.name}; // 1. 存入 R2 await env.MY_BUCKET.put(fileName, file.stream()); // 2. 如果是图片用多模态模型描述它 const imageAnalysis await ai.run(cf/unum/uform-gen2-qwen-500m, { image: [...], // 需要将图片转换成模型接受的格式如 base64 prompt: 描述这张图片的内容, }); // 将描述文本存入向量数据库或直接用于后续对话 // 3. 如果是 PDF/TXT用文本嵌入模型处理存入 Vectorize架构建议对于复杂智能体我建议将不同功能拆分成多个 Worker。例如api-agent主入口处理聊天逻辑、工具路由。embedding-worker专门处理文档解析和向量化由 R2 的文件上传事件触发。tool-weather专门执行天气查询的工具 Worker。 这样职责清晰也便于独立扩缩容和调试。4. 生产环境考量成本、监控、安全与边界智能体原型跑通只是第一步要上线必须考虑工程化问题。4.1 成本估算与控制Cloudflare 的 AI 和 Workers 大多有免费额度但超出后按量付费必须心里有数。Workers AI 推理按 Tokens 计费。例如Llama 3.1 8B 每百万输入 Tokens 约 $0.20输出 Tokens 约 $0.80。控制成本的关键缓存对相同或相似的问题缓存 Embedding 结果和最终回答。可以用 Workers 的 Cache API 或更专业的 KV 存储。设置超时和最大 Token在ai.run()中明确设置max_tokens防止模型“跑飞”生成过长文本。模型选型任务简单就用小模型如 Llama 3.2 3B复杂任务再用大模型。先用小模型做意图分类或路由再决定是否调用大模型。Vectorize 查询按读取单位RU计费。控制topK值避免每次查询都扫全表。设计好的索引结构和过滤条件。Workers 调用次数和时长智能体逻辑复杂Worker 运行时间可能较长。优化代码避免不必要的循环和阻塞操作。建议在 Dashboard 设置预算告警。开发阶段多用免费额度测试上线前用真实流量预估一个月的花费。4.2 监控、日志与调试智能体出问题不能只靠“感觉慢了”或“回答不对”。利用 Workers 的日志console.log的内容可以在 Dashboard 的 Workers 日志流中看到。结构化输出日志比如JSON.stringify({step: “embedding”, inputLength: text.length, duration: xxxMs})。跟踪关键指标端到端延迟从收到请求到返回响应的时间。各阶段耗时Embedding 时间、向量搜索时间、LLM 生成时间。Token 使用量输入和输出 Tokens这是成本大头。缓存命中率如果用了缓存监控命中率评估效果。错误率各种 4xx、5xx 错误的比例。调试技巧使用wrangler dev本地开发可以在本地启动调试服务器设置断点。保存失败的交互将出错的用户问题、上下文和模型回复存入 D1 或 R2便于后续分析。对模型输出进行后处理校验比如检查是否包含敏感词、格式是否正确。4.3 安全与权限智能体直接面向用户安全至关重要。输入验证与清理对所有用户输入进行严格的验证和清理防止 Prompt 注入攻击。比如检查输入长度过滤特殊字符但注意别影响正常文本。速率限制在 Worker 入口或使用 Cloudflare 的 Rate Limiting 规则防止 API 被滥用。访问控制如果你的智能体 API 不是完全公开的使用 API 令牌、JWT 或 Cloudflare Access 进行保护。数据隔离使用不同的 Vectorize 索引、D1 数据库或 R2 桶前缀来隔离不同客户或租户的数据。内容审核在模型输出返回给用户前可以调用 Workers AI 的文本分类模型如cf/huggingface/distilbert-sst-2-int8进行情感分析或自定义关键词过滤进行一层安全检查。4.4 Agent Cloud 的边界与局限理解一个平台的边界才能更好地使用它。不是可视化低代码平台Agent Cloud 是面向开发者的代码优先方案。如果你想要像 Dify、Coze 那样拖拽搭建智能体它不适合。但它可以作为这些平台的后端。模型选择有限虽然 Workers AI 在不断增加模型但相比直接调用 OpenAI、Anthropic 的 API或自己部署开源模型选择范围还是小的。你需要确认它提供的模型能否满足你的任务精度要求。供应商锁定你的智能体逻辑、向量数据、文件存储都深度绑定在 Cloudflare 生态里。迁移到其他平台会有成本。复杂工作流编排对于需要复杂状态机、多智能体协作、长周期任务的场景仅靠 Worker 函数可能显得笨拙。你可能需要在外围再套一个工作流引擎如 Temporal、Airflow或者等待 Cloudflare 推出更高级的编排服务。冷启动与长上下文虽然 Workers AI 宣称无冷启动但对于非常大的模型如 70B首次调用或长时间无调用后的首次调用仍可能有延迟。处理超长上下文比如 100K tokens时需要仔细设计 chunking 和检索策略成本也会飙升。5. 与其他方案的对比与选型建议市面上做智能体开发/托管的平台很多我把 Agent Cloud 和几个典型方案放一起对比帮你做选择。特性/平台Cloudflare Agent CloudDify / Coze 等可视化平台自建开源框架 (LangChain 自有云)直接调用大厂 API (OpenAI, Anthropic)核心优势全球边缘部署、全栈集成、按需付费、数据隐私快速原型、可视化编排、开箱即用功能多完全自主可控、模型任选、架构灵活模型能力最强、最稳定、生态工具丰富上手难度中等需写代码但文档好低拖拽界面高需搭建全套基础设施低调用 API定制灵活性高代码控制一切中受平台功能限制极高一切自控低只能调 API成本结构按使用量Tokens、请求、存储通常按月订阅或按用量高固定成本服务器 运维人力按 Tokens 用量可能较高数据与隐私数据在 Cloudflare 网络内处理数据经过平台服务器数据完全私有数据发送给第三方适合场景对延迟、全球访问、数据合规有要求的生产应用已有 Cloudflare 栈的团队快速验证想法、内部工具、对代码能力要求不高的团队大公司、对安全和定制有极端要求、技术实力强的团队追求最先进模型能力、快速启动且不担心数据出境的场景选型建议如果你是独立开发者或小团队想快速做个智能体 Demo 或内部工具先从 Dify/Coze 开始。它们能让你在几小时内看到效果理解智能体的基本概念。如果你需要将智能体深度集成到现有产品中对性能、成本、数据流向有明确要求并且团队有开发能力认真评估 Cloudflare Agent Cloud。它的集成度和工程化体验确实很好。如果你的应用严重依赖某个特定开源模型Cloudflare 未提供或者有极其复杂的定制化流程考虑自建。但要做好投入大量运维工作的准备。如果你的核心需求是获取最顶尖的模型能力如 GPT-4o、Claude 3.5且预算充足直接调用大厂 API仍是目前最省心的方案再结合 Vercel AI SDK 等工具开发。Cloudflare Agent Cloud 代表了一种趋势AI 能力正在变成像数据库、CDN 一样的基础设施被深度集成到云平台中。对于开发者而言这意味着可以更专注于智能体的业务逻辑和创新而不是整天和模型部署、向量数据库扩容、GPU 运维搏斗。我自己的体会是用它来做那些需要低延迟、高并发、带状态、且处理流程中包含多种能力文本、向量、文件、数据库的智能体应用优势非常明显。比如一个需要实时检索知识库、能处理用户上传文件、并记住对话历史的客服机器人用 Agent Cloud 一套下来代码很清晰部署也简单。最后无论选哪个平台智能体开发的核心挑战始终没变Prompt 工程、检索质量、工具设计的鲁棒性、以及对幻觉的控制。这些“软技能”比选择哪个技术栈更重要。建议先用最小可行产品MVP跑通核心链路收集真实用户反馈再迭代优化。不要一开始就追求大而全的架构智能体应用往往是“用”出来的不是“设计”出来的。 Cloudflare Agent Cloud实战：从零构建生产级AI智能体应用
Cloudflare 最近搞了个“Agents Week”核心不是发布一个具体产品而是把过去几年在 AI 基础设施上做的各种能力打包成一个面向“智能体”的完整形态叫Agent Cloud。如果你正在做 AI 应用特别是想把大模型能力稳定、安全地集成到业务里或者想自己搭建一个智能体平台那 Cloudflare 这套组合拳值得花时间研究一下。它解决的核心问题很实际怎么让智能体从“能跑通 Demo”到“能在生产环境里稳定、安全、低成本地跑起来”。很多团队在本地用 LangChain 或 AutoGPT 搭了个原型一到要处理真实用户请求、管理大量上下文、控制成本、保障数据安全时就卡住了。Agent Cloud 瞄准的就是这个“最后一公里”的工程化问题。这篇文章我会拆解 Agent Cloud 到底提供了什么更重要的是从一线开发的角度看这套方案适合谁、怎么上手、关键环节怎么配置以及落地时最容易踩哪些坑。我不会只复述官方新闻稿而是结合常见的智能体开发流程告诉你哪些能力可以直接用哪些需要自己补帮你判断它是不是你当前项目的最优解。1. 先拆解 Agent Cloud它到底是一套什么能力别被“Agent Cloud”这个名字唬住它不是突然冒出来的新东西而是 Cloudflare 把已有的 Workers AI、Vectorize、R2、D1、Workers、Pages 这些服务用“智能体”这个视角重新包装和打通了。你可以把它理解成一个“智能体应用的全托管运行时”。对于开发者来说最直观的价值是几个“不用操心”不用操心模型部署和推理通过 Workers AI你可以直接调用多个开源和闭源模型比如 Llama、Mistral、Gemma 等按请求付费没有冷启动全球边缘节点低延迟。你不用自己去租 GPU 服务器、搞模型量化、处理并发队列。不用操心向量数据库运维Vectorize 是它的全托管向量数据库。智能体需要长期记忆或知识库检索RAG你得存 Embedding 和做相似度搜索Vectorize 直接集成在 Workers 环境里省去了自建 Milvus、Pinecone 这类服务的麻烦。不用操心文件存储和状态持久化智能体经常要处理用户上传的文档、生成的图片或者需要记住会话状态。R2对象存储和 D1SQLite 数据库就是干这个的同样深度集成。不用操心应用部署和全球分发你的智能体逻辑写在 Cloudflare Workers无服务器函数里写完就全球部署了。用 Pages 可以快速部署带前端界面的智能体应用。所以Agent Cloud 的本质是“基础设施即智能体运行时”。它不提供一个开箱即用的智能体框架比如像 Dify、Coze 那样的可视化编排平台而是提供了搭建这类平台所需的所有底层积木并且这些积木在同一个生态内天然互通网络延迟极低。它最适合哪类人全栈或后端开发者你习惯写代码不想被黑盒平台限制希望完全控制智能体的逻辑、数据流和成本。已有 Cloudflare 生态的团队如果你已经在用 Workers、R2那么接入 AI 能力会非常平滑。对数据隐私和合规有要求的项目Cloudflare 强调数据不出其网络 Workers AI 推理也在其基础设施上完成这对某些行业是个加分项。需要快速原型验证并考虑未来平滑扩容的创业项目从零到一快从一到一百也无需重构架构。2. 从零开始用 Agent Cloud 思维搭建你的第一个智能体我们不用“Hello World”来做一个有点实际用处的一个能回答特定知识库问题的客服智能体。假设我们有一个产品的 FAQ 文档。2.1 环境与账号准备首先你需要一个 Cloudflare 账户。去 Cloudflare Dashboard 注册就行。然后在本地安装 Wrangler CLI这是管理 Cloudflare Workers 项目的官方工具。npm install -g wrangler # 或者用 pnpm / yarn wrangler login登录后你的本地环境就关联到了 Cloudflare 账户。2.2 创建项目与核心逻辑我们创建一个新的 Worker 项目wrangler init my-knowledge-agent cd my-knowledge-agent项目初始化后你会看到src/index.ts等文件。我们主要在这里写逻辑。现在思考智能体的核心流程用户提问。将用户问题转换成向量Embedding。去向量数据库Vectorize里搜索最相关的文档片段。把搜索到的片段和用户问题一起组合成提示词Prompt发给大模型Workers AI。将模型的回答返回给用户。所以我们需要三步准备知识库、处理查询、集成回复。2.3 第一步构建知识库Vectorize假设你的 FAQ 是几个 Markdown 文件。你需要一个脚本读取它们切分成片段调用 Workers AI 的 Embedding 模型生成向量然后存入 Vectorize。首先创建 Vectorize 索引wrangler vectorize create my-faq-index --dimensions768这里--dimensions768要对应你选的 Embedding 模型的输出维度比如cf/baai/bge-base-en-v1.5模型就是 768 维。然后写一个预处理脚本比如ingest.mjsimport { createClient } from neondatabase/serverless; // 假设源数据在外部数据库这里仅为示例结构 import { Ai } from cloudflare/ai; // 这个脚本通常在本地或一次性运行用于灌入数据 export default { async fetch(request, env) { const ai new Ai(env.AI); // 1. 从某处获取原始文本数据 const faqTexts [...]; // 你的FAQ文本数组 const vectors []; for (const text of faqTexts) { // 2. 调用Embedding模型 const embeddings await ai.run(cf/baai/bge-base-en-v1.5, { text: [text] }); // 3. 构建向量记录 vectors.push({ id: /* 生成唯一ID */, values: embeddings.data[0], metadata: { text } }); } // 4. 批量插入Vectorize const inserted await env.MY_FAQ_INDEX.upsert(vectors); return new Response(JSON.stringify(inserted)); } }关键点Embedding 模型的选择很重要。中英文混合选cf/baai/bge-m3纯英文可选cf/baai/bge-base-en-v1.5。维度和模型必须匹配否则插入会失败。2.4 第二步在 Worker 中实现查询逻辑修改src/index.ts这是智能体的主入口。export interface Env { AI: any; MY_FAQ_INDEX: VectorizeIndex; } export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): PromiseResponse { if (request.method ! POST) { return new Response(请使用 POST 请求并发送 JSON 数据, { status: 405 }); } try { const { question } await request.json{ question: string }(); const ai new Ai(env.AI); // 1. 将用户问题转换为向量 const questionEmbedding await ai.run(cf/baai/bge-base-en-v1.5, { text: [question], }); // 2. 在 Vectorize 中搜索相似片段 const vectors await env.MY_FAQ_INDEX.query(questionEmbedding.data[0], { topK: 3 }); // 3. 构建上下文 const context vectors.matches.map(match match.metadata?.text).join(\n---\n); // 4. 组合 Prompt调用 LLM 生成回答 const prompt 你是一个专业的客服助手。请严格根据以下已知信息来回答问题。如果已知信息不足以回答问题请直接说“根据现有资料我无法回答这个问题”不要编造信息。 已知信息 ${context} 问题${question} 请用中文回答; const response await ai.run(cf/meta/llama-3.2-3b-instruct, { prompt, max_tokens: 500, }); // 5. 返回回答 return new Response(JSON.stringify({ answer: response.response, sources: vectors.matches.map(m ({ id: m.id, score: m.score })) // 可返回引用来源 }), { headers: { Content-Type: application/json }, }); } catch (error) { console.error(处理请求时出错:, error); return new Response(JSON.stringify({ error: 内部服务器错误 }), { status: 500, headers: { Content-Type: application/json }, }); } }, };几个实操细节模型选择cf/meta/llama-3.2-3b-instruct是一个 30 亿参数模型响应快成本低适合简单问答。对质量要求高可以换cf/meta/llama-3.3-70b-instruct更慢更贵。TopK 参数topK: 3表示返回最相似的 3 条记录。这个数不是越大越好太多无关信息会干扰模型。一般从 3-5 开始调。Prompt 工程这里的 Prompt 明确要求模型“根据已知信息回答”并设置了拒绝回答的指令这是构建可靠 RAG 系统的关键能大幅减少模型胡言乱语幻觉。错误处理一定要用try...catch包住核心逻辑并返回友好的错误信息。智能体 API 对外暴露各种意外输入都可能出现。2.5 第三步部署与测试在项目根目录的wrangler.toml中绑定你的资源name my-knowledge-agent compatibility_date 2024-08-01 [[ai.datasets]] binding AI # 必须叫 AI [[vectorize]] binding MY_FAQ_INDEX # 与代码中的 env.MY_FAQ_INDEX 对应 index_name my-faq-index然后部署wrangler deploy部署成功后你会得到一个*.workers.dev的域名。用 curl 或 Postman 测试curl -X POST https://my-knowledge-agent.your-subdomain.workers.dev \ -H Content-Type: application/json \ -d {question: 你们的产品如何收费}如果一切正常你会收到一个包含answer和sources的 JSON 响应。3. 超越基础问答Agent Cloud 的进阶能力与架构设计一个简单的问答机器人只是开始。真正的智能体可能需要工具调用Function Calling、长期记忆、多步骤推理、与外部 API 交互等。我们来看看如何用 Agent Cloud 的组件实现这些。3.1 实现工具调用与外部动作假设我们的智能体需要查询天气。我们需要定义工具函数并在 Prompt 中让模型学会调用它。首先在 Worker 中定义工具列表和对应的执行函数// 定义工具函数的 schema遵循 OpenAI 的格式 const tools [ { type: function, function: { name: get_current_weather, description: 获取指定城市的当前天气, parameters: { type: object, properties: { location: { type: string, description: 城市名例如北京上海, }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位, }, }, required: [location], }, }, }, ]; // 工具的实际执行函数 async function executeTool(toolName: string, args: any) { switch (toolName) { case get_current_weather: // 这里模拟调用一个外部天气 API const mockWeather { location: args.location, temperature: 22, unit: args.unit || celsius, condition: 晴朗 }; return JSON.stringify(mockWeather); default: return 未知工具: ${toolName}; } }然后在调用模型时启用工具调用并处理响应// 在原有的 ai.run 调用中增加工具参数 const response await ai.run(cf/meta/llama-3.3-70b-instruct, { messages: [ { role: system, content: 你是一个有帮助的助手可以调用工具来回答问题。 }, { role: user, content: question } ], tools: tools, // 传入工具定义 tool_choice: auto, // 让模型决定是否调用工具 }); let finalAnswer response.response; // 检查模型是否决定调用工具 if (response.tool_calls response.tool_calls.length 0) { const toolCall response.tool_calls[0]; const toolResult await executeTool(toolCall.function.name, JSON.parse(toolCall.function.arguments)); // 将工具执行结果作为新的上下文再次发送给模型让它生成面向用户的最终回答 const secondResponse await ai.run(cf/meta/llama-3.3-70b-instruct, { messages: [ { role: system, content: 你是一个有帮助的助手。 }, { role: user, content: question }, { role: assistant, content: null, tool_calls: response.tool_calls }, { role: tool, content: toolResult, tool_call_id: toolCall.id } ], }); finalAnswer secondResponse.response; } // ... 返回 finalAnswer关键点不是所有 Cloudflare Workers AI 上的模型都支持工具调用需要查官方文档。像llama-3.3-70b-instruct这类较新的指令微调模型通常支持。这个过程本质上是让模型输出一个结构化请求“我要调用 get_current_weather参数是...”然后由你的代码接管执行再把结果塞回上下文让模型总结。3.2 利用 D1 和 R2 实现状态管理与文件处理长期记忆会话状态智能体需要记住和用户的对话历史。你可以用 D1SQLite来存。在wrangler.toml中配置 D1 数据库然后在 Worker 中// 创建或获取会话 const sessionId request.headers.get(X-Session-ID) || generateId(); const history await env.MY_D1.prepare(SELECT content FROM chat_history WHERE session_id ? ORDER BY created_at DESC LIMIT 10).bind(sessionId).all(); // 将 history 融入 messages // 对话结束后将新的交互存入 D1 await env.MY_D1.prepare(INSERT INTO chat_history (session_id, role, content) VALUES (?, ?, ?)).bind(sessionId, user, question).run();文件处理用户上传 PDF 或图片智能体需要读取内容。你可以用 R2 存文件用 Workers AI 的视觉或多模态模型如cf/unum/uform-gen2-qwen-500m或文档解析模型来处理。// 假设前端上传了文件 const formData await request.formData(); const file formData.get(file); const fileName uploads/${crypto.randomUUID()}-${file.name}; // 1. 存入 R2 await env.MY_BUCKET.put(fileName, file.stream()); // 2. 如果是图片用多模态模型描述它 const imageAnalysis await ai.run(cf/unum/uform-gen2-qwen-500m, { image: [...], // 需要将图片转换成模型接受的格式如 base64 prompt: 描述这张图片的内容, }); // 将描述文本存入向量数据库或直接用于后续对话 // 3. 如果是 PDF/TXT用文本嵌入模型处理存入 Vectorize架构建议对于复杂智能体我建议将不同功能拆分成多个 Worker。例如api-agent主入口处理聊天逻辑、工具路由。embedding-worker专门处理文档解析和向量化由 R2 的文件上传事件触发。tool-weather专门执行天气查询的工具 Worker。 这样职责清晰也便于独立扩缩容和调试。4. 生产环境考量成本、监控、安全与边界智能体原型跑通只是第一步要上线必须考虑工程化问题。4.1 成本估算与控制Cloudflare 的 AI 和 Workers 大多有免费额度但超出后按量付费必须心里有数。Workers AI 推理按 Tokens 计费。例如Llama 3.1 8B 每百万输入 Tokens 约 $0.20输出 Tokens 约 $0.80。控制成本的关键缓存对相同或相似的问题缓存 Embedding 结果和最终回答。可以用 Workers 的 Cache API 或更专业的 KV 存储。设置超时和最大 Token在ai.run()中明确设置max_tokens防止模型“跑飞”生成过长文本。模型选型任务简单就用小模型如 Llama 3.2 3B复杂任务再用大模型。先用小模型做意图分类或路由再决定是否调用大模型。Vectorize 查询按读取单位RU计费。控制topK值避免每次查询都扫全表。设计好的索引结构和过滤条件。Workers 调用次数和时长智能体逻辑复杂Worker 运行时间可能较长。优化代码避免不必要的循环和阻塞操作。建议在 Dashboard 设置预算告警。开发阶段多用免费额度测试上线前用真实流量预估一个月的花费。4.2 监控、日志与调试智能体出问题不能只靠“感觉慢了”或“回答不对”。利用 Workers 的日志console.log的内容可以在 Dashboard 的 Workers 日志流中看到。结构化输出日志比如JSON.stringify({step: “embedding”, inputLength: text.length, duration: xxxMs})。跟踪关键指标端到端延迟从收到请求到返回响应的时间。各阶段耗时Embedding 时间、向量搜索时间、LLM 生成时间。Token 使用量输入和输出 Tokens这是成本大头。缓存命中率如果用了缓存监控命中率评估效果。错误率各种 4xx、5xx 错误的比例。调试技巧使用wrangler dev本地开发可以在本地启动调试服务器设置断点。保存失败的交互将出错的用户问题、上下文和模型回复存入 D1 或 R2便于后续分析。对模型输出进行后处理校验比如检查是否包含敏感词、格式是否正确。4.3 安全与权限智能体直接面向用户安全至关重要。输入验证与清理对所有用户输入进行严格的验证和清理防止 Prompt 注入攻击。比如检查输入长度过滤特殊字符但注意别影响正常文本。速率限制在 Worker 入口或使用 Cloudflare 的 Rate Limiting 规则防止 API 被滥用。访问控制如果你的智能体 API 不是完全公开的使用 API 令牌、JWT 或 Cloudflare Access 进行保护。数据隔离使用不同的 Vectorize 索引、D1 数据库或 R2 桶前缀来隔离不同客户或租户的数据。内容审核在模型输出返回给用户前可以调用 Workers AI 的文本分类模型如cf/huggingface/distilbert-sst-2-int8进行情感分析或自定义关键词过滤进行一层安全检查。4.4 Agent Cloud 的边界与局限理解一个平台的边界才能更好地使用它。不是可视化低代码平台Agent Cloud 是面向开发者的代码优先方案。如果你想要像 Dify、Coze 那样拖拽搭建智能体它不适合。但它可以作为这些平台的后端。模型选择有限虽然 Workers AI 在不断增加模型但相比直接调用 OpenAI、Anthropic 的 API或自己部署开源模型选择范围还是小的。你需要确认它提供的模型能否满足你的任务精度要求。供应商锁定你的智能体逻辑、向量数据、文件存储都深度绑定在 Cloudflare 生态里。迁移到其他平台会有成本。复杂工作流编排对于需要复杂状态机、多智能体协作、长周期任务的场景仅靠 Worker 函数可能显得笨拙。你可能需要在外围再套一个工作流引擎如 Temporal、Airflow或者等待 Cloudflare 推出更高级的编排服务。冷启动与长上下文虽然 Workers AI 宣称无冷启动但对于非常大的模型如 70B首次调用或长时间无调用后的首次调用仍可能有延迟。处理超长上下文比如 100K tokens时需要仔细设计 chunking 和检索策略成本也会飙升。5. 与其他方案的对比与选型建议市面上做智能体开发/托管的平台很多我把 Agent Cloud 和几个典型方案放一起对比帮你做选择。特性/平台Cloudflare Agent CloudDify / Coze 等可视化平台自建开源框架 (LangChain 自有云)直接调用大厂 API (OpenAI, Anthropic)核心优势全球边缘部署、全栈集成、按需付费、数据隐私快速原型、可视化编排、开箱即用功能多完全自主可控、模型任选、架构灵活模型能力最强、最稳定、生态工具丰富上手难度中等需写代码但文档好低拖拽界面高需搭建全套基础设施低调用 API定制灵活性高代码控制一切中受平台功能限制极高一切自控低只能调 API成本结构按使用量Tokens、请求、存储通常按月订阅或按用量高固定成本服务器 运维人力按 Tokens 用量可能较高数据与隐私数据在 Cloudflare 网络内处理数据经过平台服务器数据完全私有数据发送给第三方适合场景对延迟、全球访问、数据合规有要求的生产应用已有 Cloudflare 栈的团队快速验证想法、内部工具、对代码能力要求不高的团队大公司、对安全和定制有极端要求、技术实力强的团队追求最先进模型能力、快速启动且不担心数据出境的场景选型建议如果你是独立开发者或小团队想快速做个智能体 Demo 或内部工具先从 Dify/Coze 开始。它们能让你在几小时内看到效果理解智能体的基本概念。如果你需要将智能体深度集成到现有产品中对性能、成本、数据流向有明确要求并且团队有开发能力认真评估 Cloudflare Agent Cloud。它的集成度和工程化体验确实很好。如果你的应用严重依赖某个特定开源模型Cloudflare 未提供或者有极其复杂的定制化流程考虑自建。但要做好投入大量运维工作的准备。如果你的核心需求是获取最顶尖的模型能力如 GPT-4o、Claude 3.5且预算充足直接调用大厂 API仍是目前最省心的方案再结合 Vercel AI SDK 等工具开发。Cloudflare Agent Cloud 代表了一种趋势AI 能力正在变成像数据库、CDN 一样的基础设施被深度集成到云平台中。对于开发者而言这意味着可以更专注于智能体的业务逻辑和创新而不是整天和模型部署、向量数据库扩容、GPU 运维搏斗。我自己的体会是用它来做那些需要低延迟、高并发、带状态、且处理流程中包含多种能力文本、向量、文件、数据库的智能体应用优势非常明显。比如一个需要实时检索知识库、能处理用户上传文件、并记住对话历史的客服机器人用 Agent Cloud 一套下来代码很清晰部署也简单。最后无论选哪个平台智能体开发的核心挑战始终没变Prompt 工程、检索质量、工具设计的鲁棒性、以及对幻觉的控制。这些“软技能”比选择哪个技术栈更重要。建议先用最小可行产品MVP跑通核心链路收集真实用户反馈再迭代优化。不要一开始就追求大而全的架构智能体应用往往是“用”出来的不是“设计”出来的。