Cloudflare Workers AI API 全指南env.AI.run 核心方法、六大能力与 REST 调用实战【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇技术指南聚焦 Cloudflare Workers AI 的运行时 API 参考文档系统讲解env.AI.run()这一核心入口在文本生成、Embeddings、函数调用、图像生成、语音识别与翻译六大场景中的完整调用方式并延伸覆盖 REST API、错误码排查与性能优化实践。读完本文你将能够直接在 Cloudflare Workers / Pages 中完成从绑定配置、类型声明到多模型调用与错误重试的完整开发闭环。本文以 workers-ai/api.md 为主体并结合同目录下 configuration.md、patterns.md、gotchas.md 及 README.md 中的配置、模式与陷阱说明进行纵深扩充。一、核心方法env.AI.run(model, input)Workers AI 的全部推理能力收敛在一个统一入口上const response await env.AI.run(model, input);model模型标识符形如cf/meta/llama-3.1-8b-instruct命名空间 厂商 模型名的三段式格式input模型专属的输入对象不同任务类型的字段结构不同见下文各场景返回值类型随任务而异——文本生成返回{ response: string }Embeddings 返回{ data: number[][], shape: number[] }图像生成返回二进制ArrayBuffer。该 API 的使用前提是 Worker 已声明AI绑定。在 wrangler.jsonc 配置 中添加{ name: my-ai-worker, main: src/index.ts, compatibility_date: 2024-01-01, ai: { binding: AI } }随后在 TypeScript 中声明环境类型并直接调用类型来自cloudflare/workers-types安装命令npm install --save-dev cloudflare/workers-typesinterface Env { AI: Ai; } export default { async fetch(request: Request, env: Env) { const response await env.AI.run(cf/meta/llama-3.1-8b-instruct, { messages: [{ role: user, content: Hello }] }); return Response.json(response); } };开发提醒Workers AI 是远程 GPU 推理服务本地开发环境没有模型必须使用wrangler dev --remote运行本地wrangler dev不会执行 AI 推理部署则使用wrangler deploy。二、文本生成Chat 对话与流式输出2.1 标准对话调用文本生成采用 OpenAI 风格的messages数组结构const result await env.AI.run(cf/meta/llama-3.1-8b-instruct, { messages: [ { role: system, content: You are helpful }, { role: user, content: Hello } ], temperature: 0.7, // 0-1随机性控制 max_tokens: 100 // 单次生成的最大 token 数 }); console.log(result.response);参数说明messages必填由system/user/assistant三种角色构成的对话上下文是文本生成的输入骨架temperature采样温度取值范围 01。需要确定性输出时设为0参见 gotchas.md 中不一致响应的解决方案max_tokens限制生成长度。2.2 流式输出Streaming对于长响应可以开启流式模式以显著降低首字延迟const stream await env.AI.run(model, { messages, stream: true }); return new Response(stream, { headers: { Content-Type: text/event-stream } });设置stream: true后返回值从单一对象变为ReadableStream逐块消费for await (const chunk of stream) { console.log(chunk.response); }若要在 Workers 中以标准 SSE 格式透传给前端参考 patterns.md 中的 TransformStream 写法将每个 chunk 编码为data: ...事件并在结束时发送data: [DONE]。三、Embeddings语义向量与批量优化Embeddings 用于语义搜索与 RAG 检索。以cf/baai/bge-base-en-v1.5为例const result await env.AI.run(cf/baai/bge-base-en-v1.5, { text: [Query, Doc 1, Doc 2] // Batch for efficiency }); const [queryEmbed, doc1Embed, doc2Embed] result.data; // 768-dim vectors关键点text支持字符串数组一次请求可批量处理多个文本是官方推荐的性能优化手段对应Performance Tips第 1 条Batch embeddings返回结构为{ data: number[][], shape: number[] }data[0]才是第一个向量。这一点在 gotchas.md 中被特别强调——Embedding response shape varies务必取data[0]而非直接用data模型选型上英文场景按质量/速度权衡cf/baai/bge-large-en-v1.51024 维质量最高、bge-base-en-v1.5768 维均衡、bge-small-en-v1.5384 维最快多语言场景推荐hf/sentence-transformers/paraphrase-multilingual-minilm-l12-v2。Embeddings 与 Vectorize 组合即形成完整 RAG 链路先生成查询向量再env.VECTORIZE.query()检索 Top-K最后将命中文档拼入 system prompt 交给 LLM 生成回答具体模板见 patterns.md 的 RAG 一节以及 vectorize README。四、Function Calling让模型调用你的工具函数调用允许模型在对话中输出结构化工具调用参数。声明tools数组const tools [{ type: function, function: { name: getWeather, description: Get weather for location, parameters: { type: object, properties: { location: { type: string } }, required: [location] } } }]; const response await env.AI.run(model, { messages, tools }); if (response.tool_calls) { const args JSON.parse(response.tool_calls[0].function.arguments); // Execute function, send result back }调用链说明模型判断需要工具时会返回tool_calls数组其中function.arguments是 JSON 字符串需JSON.parse解析后执行真实业务函数执行完毕后将工具结果作为新的 assistant 消息回传给模型即可继续多轮工具循环模型支持范围有限目前仅cf/meta/llama-3.1-*8B / 70B 均支持原生工具和mistral-7b-instruct-v0.2支持 tools见 gotchas.md调用前请确认所选模型具备该能力。五、图像生成与语音识别5.1 图像生成const image await env.AI.run(cf/stabilityai/stable-diffusion-xl-base-1.0, { prompt: Mountain sunset, num_steps: 20, // 1-20采样步数 guidance: 7.5 // 1-20提示词遵循强度 }); return new Response(image, { headers: { Content-Type: image/png } });num_steps越大图像质量越高但耗时更长取值 120guidance控制生成内容对 prompt 的贴合程度取值 120返回值为图像二进制数据可直接作为image/png响应返回。人像场景可使用cf/lykon/dreamshaper-8-lcm针对人脸优化来自 README.md 的模型决策树。注意图像生成成本显著更高单次约 10,000 neurons在免费额度10,000 neurons/天下需谨慎使用。5.2 语音识别Speech-to-Textconst audioArray Array.from(new Uint8Array(await request.arrayBuffer())); const result await env.AI.run(cf/openai/whisper, { audio: audioArray }); console.log(result.text);模型为 OpenAI Whispercf/openai/whisper输入为音频字节的number[]数组需先将请求体ArrayBuffer转成Uint8Array再展开为普通数组返回{ text: string }即转写文本。六、翻译与其他任务const result await env.AI.run(cf/meta/m2m100-1.2b, { text: Hello, source_lang: en, target_lang: es }); console.log(result.translated_text);cf/meta/m2m100-1.2b支持约 100 种语言互译见 README.md需同时指定source_lang与target_lang返回{ translated_text: string }。README 中还列出了图像分类模型cf/microsoft/resnet-50、代码生成专用模型cf/deepseek-ai/deepseek-coder-6.7b-instruct等均通过同一env.AI.run()入口调用。多模型项目可将模型标识符集中管理见 configuration.mdconst MODELS { chat: cf/meta/llama-3.1-8b-instruct, embed: cf/baai/bge-base-en-v1.5, image: cf/stabilityai/stable-diffusion-xl-base-1.0 };七、REST API脱离 Workers 环境的 HTTP 调用当调用方是外部服务、非 Workers 环境或需要做集成测试时可以使用 OpenAI 兼容的 REST APIcurl https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/cf/meta/llama-3.1-8b-instruct \ -H Authorization: Bearer $TOKEN \ -d {messages:[{role:user,content:Hello}]}路径中{account_id}为 Cloudflare 账户 ID$TOKEN为 API Token需在 dash.cloudflare.com/profile/api-tokens 创建授予 Workers AI - Read 权限在 TypeScript 中可用原生fetch等价实现见 configuration.md还提供 OpenAI SDK 兼容端点baseURL指向https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1可直接用openai客户端、Vercel AI SDK 的openai()适配器接入配置示例见 configuration.md 与 gotchas.md。原生绑定 vs REST 的选择构建 Workers/Pages 应用时优先原生绑定env.AI.run()零外部依赖、性能最佳、有原生类型REST 方式适用于外部服务与测试场景。八、错误码速查与排查CodeMeaningFix7502Model not foundCheck spelling7504Validation failedVerify input schema7505Rate limitedReduce rate or upgrade7506Context exceededReduce input size结合 gotchas.md 的实战排查经验7502 模型不存在到模型目录核对精确模型名含命名空间前缀拼写错误是最常见原因7504 输入校验失败文本生成必须传messages数组{ role, content }Embeddings 必须传text字段传错字段结构会触发该校验7505 限流代码中实现退避重试。参考 patterns.md 的runWithRetry捕获包含7505的错误后按指数退避Math.pow(2, attempt) * 1000毫秒重试最多 3 次7506 上下文超限模型上下文窗口为 2K8K token因模型而异压缩输入或将长文本转入 RAG 流程大于 4K token 的上下文建议使用 RAG见 README。其他常见问题来自 configuration.md 与 gotchas.md错误修复env.AI is undefined检查 wrangler.jsonc 中的aibinding本地 AI 不工作使用wrangler dev --remote找不到类型Ai安装cloudflare/workers-typescloudflare/ai包报错不要安装该包cloudflare/ai已弃用使用原生 binding九、性能优化实践官方 Performance Tips 三条要点及其仓库依据批量 Embeddings单次请求传入多个文本减少请求往返次数见本文第三节成本上批量 Embeddings 单文本约 520 neurons见 patterns.md 的成本表流式长响应用stream: true降低感知延迟配合 SSE 格式输出见本文第二节与 patterns.md 的 SSE 完整模板接受冷启动模型在首次请求时加载首请求约 13 秒后续请求约 100500ms。对高频 prompt 可叠加 AI Gateway 缓存降低冷启动影响见 gotchas.md。附加的成本优化手段任务简单时优先使用小模型——分类用cf/mistral/mistral-7b-instruct-v0.1约 50 neurons对话用 8B 模型约 200 neurons70B 大模型单次约 2000 neurons应仅在复杂任务使用并可在代码中实现模型回退try 70B → catch 回退 8B见 patterns.md 的 Model Fallback 一节。十、环境与限制说明免费额度10,000 neurons/天超出后按用量计费价格因模型而异图像生成最贵平台限制速率限制因模型而异付费计划可联系支持提升流式与函数调用在免费/付费计划均支持见 README.md 的平台限制表模型一致性stream返回ReadableStream、Embeddings 返回{ data, shape }、文本生成返回{ response }编写通用封装时建议为各任务定义独立 TypeScript 接口见 gotchas.md 的类型定义。延伸阅读workers-ai/configuration.md —— wrangler.jsonc 绑定、TypeScript 类型、REST 认证、OpenAI SDK 兼容与 RAG 绑定配置workers-ai/patterns.md —— RAG、SSE 流式、错误重试、模型回退、提示词模板、并行执行与成本优化workers-ai/gotchas.md —— cloudflare/ai 弃用说明、限流定价、模型专属限制与常见错误vectorize README —— 与 Workers AI 搭配的向量数据库及完整 RAG 示例cloudflare-deploy SKILL.md —— 部署前认证npx wrangler whoami与产品决策树总览【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare Workers AI API 全指南：env.AI.run 核心方法、六大能力与 REST 调用实战
Cloudflare Workers AI API 全指南env.AI.run 核心方法、六大能力与 REST 调用实战【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇技术指南聚焦 Cloudflare Workers AI 的运行时 API 参考文档系统讲解env.AI.run()这一核心入口在文本生成、Embeddings、函数调用、图像生成、语音识别与翻译六大场景中的完整调用方式并延伸覆盖 REST API、错误码排查与性能优化实践。读完本文你将能够直接在 Cloudflare Workers / Pages 中完成从绑定配置、类型声明到多模型调用与错误重试的完整开发闭环。本文以 workers-ai/api.md 为主体并结合同目录下 configuration.md、patterns.md、gotchas.md 及 README.md 中的配置、模式与陷阱说明进行纵深扩充。一、核心方法env.AI.run(model, input)Workers AI 的全部推理能力收敛在一个统一入口上const response await env.AI.run(model, input);model模型标识符形如cf/meta/llama-3.1-8b-instruct命名空间 厂商 模型名的三段式格式input模型专属的输入对象不同任务类型的字段结构不同见下文各场景返回值类型随任务而异——文本生成返回{ response: string }Embeddings 返回{ data: number[][], shape: number[] }图像生成返回二进制ArrayBuffer。该 API 的使用前提是 Worker 已声明AI绑定。在 wrangler.jsonc 配置 中添加{ name: my-ai-worker, main: src/index.ts, compatibility_date: 2024-01-01, ai: { binding: AI } }随后在 TypeScript 中声明环境类型并直接调用类型来自cloudflare/workers-types安装命令npm install --save-dev cloudflare/workers-typesinterface Env { AI: Ai; } export default { async fetch(request: Request, env: Env) { const response await env.AI.run(cf/meta/llama-3.1-8b-instruct, { messages: [{ role: user, content: Hello }] }); return Response.json(response); } };开发提醒Workers AI 是远程 GPU 推理服务本地开发环境没有模型必须使用wrangler dev --remote运行本地wrangler dev不会执行 AI 推理部署则使用wrangler deploy。二、文本生成Chat 对话与流式输出2.1 标准对话调用文本生成采用 OpenAI 风格的messages数组结构const result await env.AI.run(cf/meta/llama-3.1-8b-instruct, { messages: [ { role: system, content: You are helpful }, { role: user, content: Hello } ], temperature: 0.7, // 0-1随机性控制 max_tokens: 100 // 单次生成的最大 token 数 }); console.log(result.response);参数说明messages必填由system/user/assistant三种角色构成的对话上下文是文本生成的输入骨架temperature采样温度取值范围 01。需要确定性输出时设为0参见 gotchas.md 中不一致响应的解决方案max_tokens限制生成长度。2.2 流式输出Streaming对于长响应可以开启流式模式以显著降低首字延迟const stream await env.AI.run(model, { messages, stream: true }); return new Response(stream, { headers: { Content-Type: text/event-stream } });设置stream: true后返回值从单一对象变为ReadableStream逐块消费for await (const chunk of stream) { console.log(chunk.response); }若要在 Workers 中以标准 SSE 格式透传给前端参考 patterns.md 中的 TransformStream 写法将每个 chunk 编码为data: ...事件并在结束时发送data: [DONE]。三、Embeddings语义向量与批量优化Embeddings 用于语义搜索与 RAG 检索。以cf/baai/bge-base-en-v1.5为例const result await env.AI.run(cf/baai/bge-base-en-v1.5, { text: [Query, Doc 1, Doc 2] // Batch for efficiency }); const [queryEmbed, doc1Embed, doc2Embed] result.data; // 768-dim vectors关键点text支持字符串数组一次请求可批量处理多个文本是官方推荐的性能优化手段对应Performance Tips第 1 条Batch embeddings返回结构为{ data: number[][], shape: number[] }data[0]才是第一个向量。这一点在 gotchas.md 中被特别强调——Embedding response shape varies务必取data[0]而非直接用data模型选型上英文场景按质量/速度权衡cf/baai/bge-large-en-v1.51024 维质量最高、bge-base-en-v1.5768 维均衡、bge-small-en-v1.5384 维最快多语言场景推荐hf/sentence-transformers/paraphrase-multilingual-minilm-l12-v2。Embeddings 与 Vectorize 组合即形成完整 RAG 链路先生成查询向量再env.VECTORIZE.query()检索 Top-K最后将命中文档拼入 system prompt 交给 LLM 生成回答具体模板见 patterns.md 的 RAG 一节以及 vectorize README。四、Function Calling让模型调用你的工具函数调用允许模型在对话中输出结构化工具调用参数。声明tools数组const tools [{ type: function, function: { name: getWeather, description: Get weather for location, parameters: { type: object, properties: { location: { type: string } }, required: [location] } } }]; const response await env.AI.run(model, { messages, tools }); if (response.tool_calls) { const args JSON.parse(response.tool_calls[0].function.arguments); // Execute function, send result back }调用链说明模型判断需要工具时会返回tool_calls数组其中function.arguments是 JSON 字符串需JSON.parse解析后执行真实业务函数执行完毕后将工具结果作为新的 assistant 消息回传给模型即可继续多轮工具循环模型支持范围有限目前仅cf/meta/llama-3.1-*8B / 70B 均支持原生工具和mistral-7b-instruct-v0.2支持 tools见 gotchas.md调用前请确认所选模型具备该能力。五、图像生成与语音识别5.1 图像生成const image await env.AI.run(cf/stabilityai/stable-diffusion-xl-base-1.0, { prompt: Mountain sunset, num_steps: 20, // 1-20采样步数 guidance: 7.5 // 1-20提示词遵循强度 }); return new Response(image, { headers: { Content-Type: image/png } });num_steps越大图像质量越高但耗时更长取值 120guidance控制生成内容对 prompt 的贴合程度取值 120返回值为图像二进制数据可直接作为image/png响应返回。人像场景可使用cf/lykon/dreamshaper-8-lcm针对人脸优化来自 README.md 的模型决策树。注意图像生成成本显著更高单次约 10,000 neurons在免费额度10,000 neurons/天下需谨慎使用。5.2 语音识别Speech-to-Textconst audioArray Array.from(new Uint8Array(await request.arrayBuffer())); const result await env.AI.run(cf/openai/whisper, { audio: audioArray }); console.log(result.text);模型为 OpenAI Whispercf/openai/whisper输入为音频字节的number[]数组需先将请求体ArrayBuffer转成Uint8Array再展开为普通数组返回{ text: string }即转写文本。六、翻译与其他任务const result await env.AI.run(cf/meta/m2m100-1.2b, { text: Hello, source_lang: en, target_lang: es }); console.log(result.translated_text);cf/meta/m2m100-1.2b支持约 100 种语言互译见 README.md需同时指定source_lang与target_lang返回{ translated_text: string }。README 中还列出了图像分类模型cf/microsoft/resnet-50、代码生成专用模型cf/deepseek-ai/deepseek-coder-6.7b-instruct等均通过同一env.AI.run()入口调用。多模型项目可将模型标识符集中管理见 configuration.mdconst MODELS { chat: cf/meta/llama-3.1-8b-instruct, embed: cf/baai/bge-base-en-v1.5, image: cf/stabilityai/stable-diffusion-xl-base-1.0 };七、REST API脱离 Workers 环境的 HTTP 调用当调用方是外部服务、非 Workers 环境或需要做集成测试时可以使用 OpenAI 兼容的 REST APIcurl https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/cf/meta/llama-3.1-8b-instruct \ -H Authorization: Bearer $TOKEN \ -d {messages:[{role:user,content:Hello}]}路径中{account_id}为 Cloudflare 账户 ID$TOKEN为 API Token需在 dash.cloudflare.com/profile/api-tokens 创建授予 Workers AI - Read 权限在 TypeScript 中可用原生fetch等价实现见 configuration.md还提供 OpenAI SDK 兼容端点baseURL指向https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1可直接用openai客户端、Vercel AI SDK 的openai()适配器接入配置示例见 configuration.md 与 gotchas.md。原生绑定 vs REST 的选择构建 Workers/Pages 应用时优先原生绑定env.AI.run()零外部依赖、性能最佳、有原生类型REST 方式适用于外部服务与测试场景。八、错误码速查与排查CodeMeaningFix7502Model not foundCheck spelling7504Validation failedVerify input schema7505Rate limitedReduce rate or upgrade7506Context exceededReduce input size结合 gotchas.md 的实战排查经验7502 模型不存在到模型目录核对精确模型名含命名空间前缀拼写错误是最常见原因7504 输入校验失败文本生成必须传messages数组{ role, content }Embeddings 必须传text字段传错字段结构会触发该校验7505 限流代码中实现退避重试。参考 patterns.md 的runWithRetry捕获包含7505的错误后按指数退避Math.pow(2, attempt) * 1000毫秒重试最多 3 次7506 上下文超限模型上下文窗口为 2K8K token因模型而异压缩输入或将长文本转入 RAG 流程大于 4K token 的上下文建议使用 RAG见 README。其他常见问题来自 configuration.md 与 gotchas.md错误修复env.AI is undefined检查 wrangler.jsonc 中的aibinding本地 AI 不工作使用wrangler dev --remote找不到类型Ai安装cloudflare/workers-typescloudflare/ai包报错不要安装该包cloudflare/ai已弃用使用原生 binding九、性能优化实践官方 Performance Tips 三条要点及其仓库依据批量 Embeddings单次请求传入多个文本减少请求往返次数见本文第三节成本上批量 Embeddings 单文本约 520 neurons见 patterns.md 的成本表流式长响应用stream: true降低感知延迟配合 SSE 格式输出见本文第二节与 patterns.md 的 SSE 完整模板接受冷启动模型在首次请求时加载首请求约 13 秒后续请求约 100500ms。对高频 prompt 可叠加 AI Gateway 缓存降低冷启动影响见 gotchas.md。附加的成本优化手段任务简单时优先使用小模型——分类用cf/mistral/mistral-7b-instruct-v0.1约 50 neurons对话用 8B 模型约 200 neurons70B 大模型单次约 2000 neurons应仅在复杂任务使用并可在代码中实现模型回退try 70B → catch 回退 8B见 patterns.md 的 Model Fallback 一节。十、环境与限制说明免费额度10,000 neurons/天超出后按用量计费价格因模型而异图像生成最贵平台限制速率限制因模型而异付费计划可联系支持提升流式与函数调用在免费/付费计划均支持见 README.md 的平台限制表模型一致性stream返回ReadableStream、Embeddings 返回{ data, shape }、文本生成返回{ response }编写通用封装时建议为各任务定义独立 TypeScript 接口见 gotchas.md 的类型定义。延伸阅读workers-ai/configuration.md —— wrangler.jsonc 绑定、TypeScript 类型、REST 认证、OpenAI SDK 兼容与 RAG 绑定配置workers-ai/patterns.md —— RAG、SSE 流式、错误重试、模型回退、提示词模板、并行执行与成本优化workers-ai/gotchas.md —— cloudflare/ai 弃用说明、限流定价、模型专属限制与常见错误vectorize README —— 与 Workers AI 搭配的向量数据库及完整 RAG 示例cloudflare-deploy SKILL.md —— 部署前认证npx wrangler whoami与产品决策树总览【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考