Cloudflare Workers AI 配置实战指南从 wrangler.jsonc 绑定到 RAG 部署【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇指南基于 skills4/skills 仓库中 cloudflare-deploy 技能的 Workers AI 配置参考系统讲解在 Cloudflare Workers 中启用 Workers AI 的完整配置链路wrangler.jsonc 中的ai绑定、TypeScript 类型接入、本地开发与远程调试、REST API 调用、OpenAI SDK 兼容以及基于 Vectorize 的 RAG 场景配置与常见故障排查。读完本文你将能够独立搭建一个类型安全、可本地调试、可上线部署并支持多模型与向量检索的 Workers AI 应用。Workers AI 配置总览Workers AI 是 Cloudflare 提供的无服务器 GPU 推理服务可直接在边缘运行 50 预训练模型LLM、Embedding、图像生成、语音转文本、翻译等。与自建推理服务不同它通过 Workers 的原生 Binding暴露能力无需发起外部 HTTP 调用也无需管理 GPU 基础设施。从配置角度看启用 Workers AI 只需要三件事在wrangler.jsonc中声明ai绑定在 Worker 代码中通过env.AI.run()调用模型使用wrangler dev --remote进行本地开发AI 推理不支持纯本地运行。配置参考文档位于 configuration.md完整的 API 行为可参见 api.md选型与成本策略见 README.md 与 gotchas.md。第一步在 wrangler.jsonc 中声明 AI 绑定Workers AI 通过 Binding 注入到 Worker 运行时环境。在项目根目录的wrangler.jsonc推荐使用该格式自 wrangler v3.91.0 起支持 schema 校验可参考 Wrangler 配置文档中添加如下配置{ name: my-ai-worker, main: src/index.ts, compatibility_date: 2024-01-01, ai: { binding: AI } }字段说明字段说明nameWorker 名称用于部署标识main入口文件路径指向你的 TypeScript 源码compatibility_date兼容性日期建议使用当前日期影响运行时特性开关ai.binding注入到env对象中的绑定变量名此处为AI代码中通过env.AI访问绑定名称是约定俗成的惯例多数官方示例与类型定义都默认AI。若你修改为其他名称如WORKERS_AIenv.AI需同步改为env.WORKERS_AI且cloudflare/workers-types中Ai类型本身与绑定名无关。提示ai属于计算类绑定Compute Binding与 KV、D1、R2 等存储绑定并列可参见 Bindings 配置参考 中 Compute Bindings 一节。所有绑定类型合计上限为 64 个。安装类型定义并接入 TypeScript为了让env.AI拥有完整类型提示需要安装 Cloudflare 的官方类型包npm install --save-dev cloudflare/workers-types随后在 Worker 代码中声明Env接口并通过env.AI.run()调用模型interface 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); } };Ai类型来自cloudflare/workers-types见 gotchas.md 中 TypeScript 一节。更精确地你还可以为响应定义结构interface TextGenerationResponse { response: string; } interface EmbeddingResponse { data: number[][]; shape: number[]; }⚠️ 不要安装 cloudflare/ai 包这是配置阶段最常见的坑cloudflare/ai包已废弃。早期版本需要import Ai from cloudflare/ai手动初始化现在应完全依赖原生绑定env.AI。如果你在故障排查中看到cloudflare/ai package error直接卸载它——正确做法是使用配置好的绑定见 gotchas.md 开篇的废弃说明。本地开发必须使用 --remote 模式Workers AI 的推理在 Cloudflare 的 GPU 网络远端执行本地不存在推理能力。因此本地开发必须显式加--remote标志wrangler dev --remote # Required for AI - no local inference这条命令会把请求代理到云端使用你账号下真实的绑定与模型资源。相对的如果直接运行wrangler dev本地 Miniflare 模式env.AI将无法工作这也是AI inference doesnt work locally问题的根源。REST API 方式调用如果你的场景不在 Workers 运行时内例如外部服务、非 Workers 环境、或需要做测试可以使用 REST API。Workers AI 提供 OpenAI 兼容的 HTTP 接口端点结构为POST https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/run/{model_name}TypeScript 示例const response await fetch( https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/run/cf/meta/llama-3.1-8b-instruct, { method: POST, headers: { Authorization: Bearer ${API_TOKEN} }, body: JSON.stringify({ messages: [{ role: user, content: Hello }] }) } );对应的 curl 命令见 README.mdcurl https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/ai/run/cf/meta/llama-3.1-8b-instruct \ -H Authorization: Bearer API_TOKEN \ -d {messages:[{role:user,content:Hello}]}创建 API Token在dash.cloudflare.com/profile/api-tokens创建 API Token权限选择Workers AI - Read。该 Token 用作Authorization: Bearer请求头。建议将其作为 Worker 的 Secret 管理wrangler secret put而不是硬编码进代码或提交进仓库参见 Bindings 配置参考 的 Secrets 说明。关键 REST 错误码REST 与绑定方式返回相同的错误码体系见 api.mdCode含义修复7502模型不存在检查模型名拼写7504输入校验失败核对输入 schema文本生成需messages数组Embedding 需text7505触发限流降低频率或升级套餐7506上下文超限减小输入规模SDK 兼容复用 OpenAI SDKWorkers AI 提供 OpenAI 兼容的/ai/v1端点因此可以直接复用openai客户端迁移成本极低import OpenAI from openai; const client new OpenAI({ apiKey: env.CLOUDFLARE_API_TOKEN, baseURL: https://api.cloudflare.com/client/v4/accounts/${env.ACCOUNT_ID}/ai/v1 });注意这里的baseURL是/ai/v1而非/ai/run——前者走 OpenAI 兼容的聊天补全协议后者是原生 run 协议。同理Vercel AI SDK 也可以通过指定baseURL与headers接入见 README.md 的 Vercel AI SDK Integration 一节import { openai } from ai-sdk/openai; const model openai(model-name, { baseURL: https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/ai/v1, headers: { Authorization: Bearer API_TOKEN } });多模型配置模式生产应用通常同时使用多种模型。官方配置参考给出的模式是把模型名集中到一个常量映射中便于统一管理与切换const 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 };调用时按任务类型取用// 对话 await env.AI.run(MODELS.chat, { messages }); // Embedding批量传入文本 const { data } await env.AI.run(MODELS.embed, { text: [Query text, Document 1] }); // 图像生成 const image await env.AI.run(MODELS.image, { prompt: Mountain sunset, num_steps: 20, // 1-20 guidance: 7.5 // 1-20 }); return new Response(image, { headers: { Content-Type: image/png } });模型选型决策树结合 README.md 的选型指南可建立如下选择逻辑文本生成质量优先cf/meta/llama-3.1-70b-instruct约 2000 neurons/次最贵文本生成均衡cf/meta/llama-3.1-8b-instruct约 200 neurons/次性价比高文本生成最快最省cf/mistral/mistral-7b-instruct-v0.1约 50 neurons/次代码生成cf/deepseek-ai/deepseek-coder-6.7b-instruct英文 Embeddingcf/baai/bge-large-en-v1.51024 维/bge-base-en-v1.5768 维/bge-small-en-v1.5384 维多语言 Embeddinghf/sentence-transformers/paraphrase-multilingual-minilm-l12-v2图像生成cf/stabilityai/stable-diffusion-xl-base-1.0约 10,000 neurons语音转文本cf/openai/whisper翻译cf/meta/m2m100-1.2b。从实现事实看env.AI.run(model, input)的第一个参数就是模型标识输入结构随模型类型不同而不同消息数组、文本数组、prompt、音频等详见 api.md 的分类示例。RAG 场景Workers AI Vectorize 配置构建基于私有语料的问答系统RAG时需要在wrangler.jsonc中同时配置 AI 绑定与 Vectorize 索引绑定{ ai: { binding: AI }, vectorize: { bindings: [{ binding: VECTORIZE, index_name: embeddings-index }] } }注意Vectorize 在 wrangler.jsonc 中的标准写法是数组形式见 Vectorize 配置参考 与 Wrangler 配置参考vectorize: [{ binding: VECTORIZE, index_name: my-index }]。创建索引时--dimensions与--metric创建后不可修改务必与 Embedding 模型的输出维度一致如bge-base-en-v1.5为 768 维npx wrangler vectorize create embeddings-index --dimensions768 --metriccosine完整 RAG 调用链见 patterns.md// 1. 对查询做 Embedding const embedding await env.AI.run(cf/baai/bge-base-en-v1.5, { text: query }); // 2. 在 Vectorize 中检索相似向量 const results await env.VECTORIZE.query(embedding.data[0], { topK: 5, returnMetadata: true }); // 3. 组装上下文 const context results.matches.map(m m.metadata?.text).join(\n\n); // 4. 带上下文生成回答 const response await env.AI.run(cf/meta/llama-3.1-8b-instruct, { messages: [ { role: system, content: Answer based on:\n\n${context} }, { role: user, content: query } ] });什么时候该用 RAG根据 README.md 的决策依据回答特定文档/数据的问题、需要基于已知语料的准确性、上下文超过模型窗口约 4K token 以上、构建知识库问答时用 RAG而创意写作、通用知识问答、短上下文、以及成本敏感场景RAG 会增加 Embedding 与向量检索成本则直接用生成。Troubleshooting 速查表配置阶段最常见的四类问题与修复方式官方配置文档汇总如下ErrorFixenv.AI is undefined检查wrangler.jsonc中ai绑定是否已添加Local AI doesnt work使用wrangler dev --remoteType Ai not found安装cloudflare/workers-typescloudflare/ai package error不要安装该包使用原生绑定补充几条来自 gotchas.md 的实战经验Embedding 响应结构cf/baai/bge-base-en-v1.5返回{ data: [[0.1, 0.2, ...]] }取第一维response.data[0]才是向量流式响应stream: true返回ReadableStream用for await (const chunk of stream)消费chunk.response结果不稳定设置temperature: 0获得确定性输出冷启动延迟首次请求约 1–3 秒模型加载后续请求约 100–500ms高频提示词可借助 AI Gateway 缓存函数调用支持范围目前仅cf/meta/llama-3.1-*与mistral-7b-instruct-v0.2支持 tools 参数。从配置到上线的完整流程结合 README.md 的开发工作流配置完成后的标准步骤是# 1. 本地远程调试AI 必须 --remote wrangler dev --remote # 2. 部署到生产 wrangler deploy完整配置清单核对✅wrangler.jsonc声明ai绑定必要时加上vectorize绑定✅ 安装cloudflare/workers-types声明Env接口✅ 按任务类型选好模型 ID 并集中管理✅ 本地用wrangler dev --remote验证✅ 通过wrangler deploy上线✅ 核对 API Token 权限Workers AI - Read与限流/计费策略免费额度 10,000 neurons/天。延伸阅读Workers AI API 参考env.AI.run()各任务类型入参与响应结构、流式与函数调用Workers AI 常见坑废弃包、限流、成本与错误码Workers AI 模式RAG、SSE 流式、重试与模型回退Vectorize 配置参考索引创建、元数据索引与批量上传Wrangler 配置参考环境、路由与各类绑定Bindings 配置参考绑定类型总览与限制【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare Workers AI 配置实战指南：从 wrangler.jsonc 绑定到 RAG 部署
Cloudflare Workers AI 配置实战指南从 wrangler.jsonc 绑定到 RAG 部署【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇指南基于 skills4/skills 仓库中 cloudflare-deploy 技能的 Workers AI 配置参考系统讲解在 Cloudflare Workers 中启用 Workers AI 的完整配置链路wrangler.jsonc 中的ai绑定、TypeScript 类型接入、本地开发与远程调试、REST API 调用、OpenAI SDK 兼容以及基于 Vectorize 的 RAG 场景配置与常见故障排查。读完本文你将能够独立搭建一个类型安全、可本地调试、可上线部署并支持多模型与向量检索的 Workers AI 应用。Workers AI 配置总览Workers AI 是 Cloudflare 提供的无服务器 GPU 推理服务可直接在边缘运行 50 预训练模型LLM、Embedding、图像生成、语音转文本、翻译等。与自建推理服务不同它通过 Workers 的原生 Binding暴露能力无需发起外部 HTTP 调用也无需管理 GPU 基础设施。从配置角度看启用 Workers AI 只需要三件事在wrangler.jsonc中声明ai绑定在 Worker 代码中通过env.AI.run()调用模型使用wrangler dev --remote进行本地开发AI 推理不支持纯本地运行。配置参考文档位于 configuration.md完整的 API 行为可参见 api.md选型与成本策略见 README.md 与 gotchas.md。第一步在 wrangler.jsonc 中声明 AI 绑定Workers AI 通过 Binding 注入到 Worker 运行时环境。在项目根目录的wrangler.jsonc推荐使用该格式自 wrangler v3.91.0 起支持 schema 校验可参考 Wrangler 配置文档中添加如下配置{ name: my-ai-worker, main: src/index.ts, compatibility_date: 2024-01-01, ai: { binding: AI } }字段说明字段说明nameWorker 名称用于部署标识main入口文件路径指向你的 TypeScript 源码compatibility_date兼容性日期建议使用当前日期影响运行时特性开关ai.binding注入到env对象中的绑定变量名此处为AI代码中通过env.AI访问绑定名称是约定俗成的惯例多数官方示例与类型定义都默认AI。若你修改为其他名称如WORKERS_AIenv.AI需同步改为env.WORKERS_AI且cloudflare/workers-types中Ai类型本身与绑定名无关。提示ai属于计算类绑定Compute Binding与 KV、D1、R2 等存储绑定并列可参见 Bindings 配置参考 中 Compute Bindings 一节。所有绑定类型合计上限为 64 个。安装类型定义并接入 TypeScript为了让env.AI拥有完整类型提示需要安装 Cloudflare 的官方类型包npm install --save-dev cloudflare/workers-types随后在 Worker 代码中声明Env接口并通过env.AI.run()调用模型interface 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); } };Ai类型来自cloudflare/workers-types见 gotchas.md 中 TypeScript 一节。更精确地你还可以为响应定义结构interface TextGenerationResponse { response: string; } interface EmbeddingResponse { data: number[][]; shape: number[]; }⚠️ 不要安装 cloudflare/ai 包这是配置阶段最常见的坑cloudflare/ai包已废弃。早期版本需要import Ai from cloudflare/ai手动初始化现在应完全依赖原生绑定env.AI。如果你在故障排查中看到cloudflare/ai package error直接卸载它——正确做法是使用配置好的绑定见 gotchas.md 开篇的废弃说明。本地开发必须使用 --remote 模式Workers AI 的推理在 Cloudflare 的 GPU 网络远端执行本地不存在推理能力。因此本地开发必须显式加--remote标志wrangler dev --remote # Required for AI - no local inference这条命令会把请求代理到云端使用你账号下真实的绑定与模型资源。相对的如果直接运行wrangler dev本地 Miniflare 模式env.AI将无法工作这也是AI inference doesnt work locally问题的根源。REST API 方式调用如果你的场景不在 Workers 运行时内例如外部服务、非 Workers 环境、或需要做测试可以使用 REST API。Workers AI 提供 OpenAI 兼容的 HTTP 接口端点结构为POST https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/run/{model_name}TypeScript 示例const response await fetch( https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/run/cf/meta/llama-3.1-8b-instruct, { method: POST, headers: { Authorization: Bearer ${API_TOKEN} }, body: JSON.stringify({ messages: [{ role: user, content: Hello }] }) } );对应的 curl 命令见 README.mdcurl https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/ai/run/cf/meta/llama-3.1-8b-instruct \ -H Authorization: Bearer API_TOKEN \ -d {messages:[{role:user,content:Hello}]}创建 API Token在dash.cloudflare.com/profile/api-tokens创建 API Token权限选择Workers AI - Read。该 Token 用作Authorization: Bearer请求头。建议将其作为 Worker 的 Secret 管理wrangler secret put而不是硬编码进代码或提交进仓库参见 Bindings 配置参考 的 Secrets 说明。关键 REST 错误码REST 与绑定方式返回相同的错误码体系见 api.mdCode含义修复7502模型不存在检查模型名拼写7504输入校验失败核对输入 schema文本生成需messages数组Embedding 需text7505触发限流降低频率或升级套餐7506上下文超限减小输入规模SDK 兼容复用 OpenAI SDKWorkers AI 提供 OpenAI 兼容的/ai/v1端点因此可以直接复用openai客户端迁移成本极低import OpenAI from openai; const client new OpenAI({ apiKey: env.CLOUDFLARE_API_TOKEN, baseURL: https://api.cloudflare.com/client/v4/accounts/${env.ACCOUNT_ID}/ai/v1 });注意这里的baseURL是/ai/v1而非/ai/run——前者走 OpenAI 兼容的聊天补全协议后者是原生 run 协议。同理Vercel AI SDK 也可以通过指定baseURL与headers接入见 README.md 的 Vercel AI SDK Integration 一节import { openai } from ai-sdk/openai; const model openai(model-name, { baseURL: https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/ai/v1, headers: { Authorization: Bearer API_TOKEN } });多模型配置模式生产应用通常同时使用多种模型。官方配置参考给出的模式是把模型名集中到一个常量映射中便于统一管理与切换const 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 };调用时按任务类型取用// 对话 await env.AI.run(MODELS.chat, { messages }); // Embedding批量传入文本 const { data } await env.AI.run(MODELS.embed, { text: [Query text, Document 1] }); // 图像生成 const image await env.AI.run(MODELS.image, { prompt: Mountain sunset, num_steps: 20, // 1-20 guidance: 7.5 // 1-20 }); return new Response(image, { headers: { Content-Type: image/png } });模型选型决策树结合 README.md 的选型指南可建立如下选择逻辑文本生成质量优先cf/meta/llama-3.1-70b-instruct约 2000 neurons/次最贵文本生成均衡cf/meta/llama-3.1-8b-instruct约 200 neurons/次性价比高文本生成最快最省cf/mistral/mistral-7b-instruct-v0.1约 50 neurons/次代码生成cf/deepseek-ai/deepseek-coder-6.7b-instruct英文 Embeddingcf/baai/bge-large-en-v1.51024 维/bge-base-en-v1.5768 维/bge-small-en-v1.5384 维多语言 Embeddinghf/sentence-transformers/paraphrase-multilingual-minilm-l12-v2图像生成cf/stabilityai/stable-diffusion-xl-base-1.0约 10,000 neurons语音转文本cf/openai/whisper翻译cf/meta/m2m100-1.2b。从实现事实看env.AI.run(model, input)的第一个参数就是模型标识输入结构随模型类型不同而不同消息数组、文本数组、prompt、音频等详见 api.md 的分类示例。RAG 场景Workers AI Vectorize 配置构建基于私有语料的问答系统RAG时需要在wrangler.jsonc中同时配置 AI 绑定与 Vectorize 索引绑定{ ai: { binding: AI }, vectorize: { bindings: [{ binding: VECTORIZE, index_name: embeddings-index }] } }注意Vectorize 在 wrangler.jsonc 中的标准写法是数组形式见 Vectorize 配置参考 与 Wrangler 配置参考vectorize: [{ binding: VECTORIZE, index_name: my-index }]。创建索引时--dimensions与--metric创建后不可修改务必与 Embedding 模型的输出维度一致如bge-base-en-v1.5为 768 维npx wrangler vectorize create embeddings-index --dimensions768 --metriccosine完整 RAG 调用链见 patterns.md// 1. 对查询做 Embedding const embedding await env.AI.run(cf/baai/bge-base-en-v1.5, { text: query }); // 2. 在 Vectorize 中检索相似向量 const results await env.VECTORIZE.query(embedding.data[0], { topK: 5, returnMetadata: true }); // 3. 组装上下文 const context results.matches.map(m m.metadata?.text).join(\n\n); // 4. 带上下文生成回答 const response await env.AI.run(cf/meta/llama-3.1-8b-instruct, { messages: [ { role: system, content: Answer based on:\n\n${context} }, { role: user, content: query } ] });什么时候该用 RAG根据 README.md 的决策依据回答特定文档/数据的问题、需要基于已知语料的准确性、上下文超过模型窗口约 4K token 以上、构建知识库问答时用 RAG而创意写作、通用知识问答、短上下文、以及成本敏感场景RAG 会增加 Embedding 与向量检索成本则直接用生成。Troubleshooting 速查表配置阶段最常见的四类问题与修复方式官方配置文档汇总如下ErrorFixenv.AI is undefined检查wrangler.jsonc中ai绑定是否已添加Local AI doesnt work使用wrangler dev --remoteType Ai not found安装cloudflare/workers-typescloudflare/ai package error不要安装该包使用原生绑定补充几条来自 gotchas.md 的实战经验Embedding 响应结构cf/baai/bge-base-en-v1.5返回{ data: [[0.1, 0.2, ...]] }取第一维response.data[0]才是向量流式响应stream: true返回ReadableStream用for await (const chunk of stream)消费chunk.response结果不稳定设置temperature: 0获得确定性输出冷启动延迟首次请求约 1–3 秒模型加载后续请求约 100–500ms高频提示词可借助 AI Gateway 缓存函数调用支持范围目前仅cf/meta/llama-3.1-*与mistral-7b-instruct-v0.2支持 tools 参数。从配置到上线的完整流程结合 README.md 的开发工作流配置完成后的标准步骤是# 1. 本地远程调试AI 必须 --remote wrangler dev --remote # 2. 部署到生产 wrangler deploy完整配置清单核对✅wrangler.jsonc声明ai绑定必要时加上vectorize绑定✅ 安装cloudflare/workers-types声明Env接口✅ 按任务类型选好模型 ID 并集中管理✅ 本地用wrangler dev --remote验证✅ 通过wrangler deploy上线✅ 核对 API Token 权限Workers AI - Read与限流/计费策略免费额度 10,000 neurons/天。延伸阅读Workers AI API 参考env.AI.run()各任务类型入参与响应结构、流式与函数调用Workers AI 常见坑废弃包、限流、成本与错误码Workers AI 模式RAG、SSE 流式、重试与模型回退Vectorize 配置参考索引创建、元数据索引与批量上传Wrangler 配置参考环境、路由与各类绑定Bindings 配置参考绑定类型总览与限制【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考