企业官网建设流程全解析

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-types）：

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); } };

开发提醒：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：采样温度，取值范围 0～1。需要确定性输出时设为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.5（1024 维，质量最高）、bge-base-en-v1.5（768 维，均衡）、bge-small-en-v1.5（384 维，最快）；多语言场景推荐@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越大图像质量越高但耗时更长，取值 1～20；
• guidance控制生成内容对 prompt 的贴合程度，取值 1～20；
• 返回值为图像二进制数据，可直接作为image/png响应返回。

人像场景可使用@cf/lykon/dreamshaper-8-lcm（针对人脸优化，来自 README.md 的模型决策树）。注意图像生成成本显著更高（单次约 10,000+ neurons），在免费额度（10,000 neurons/天）下需谨慎使用。

5.2 语音识别（Speech-to-Text）

const audioArray = Array.from(new Uint8Array(await request.arrayBuffer())); const result = await env.AI.run('@cf/openai/whisper', { audio: audioArray }); console.log(result.text);

• 模型为 OpenAI Whisper（@cf/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.md）：

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' };

七、REST API：脱离 Workers 环境的 HTTP 调用

当调用方是外部服务、非 Workers 环境或需要做集成测试时，可以使用 OpenAI 兼容的 REST API：

curl 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 方式适用于外部服务与测试场景。

八、错误码速查与排查

结合 gotchas.md 的实战排查经验：

• 7502 模型不存在：到模型目录核对精确模型名（含命名空间前缀），拼写错误是最常见原因；
• 7504 输入校验失败：文本生成必须传messages数组（{ role, content }），Embeddings 必须传text字段，传错字段结构会触发该校验；
• 7505 限流：代码中实现退避重试。参考 patterns.md 的runWithRetry：捕获包含7505的错误后按指数退避（Math.pow(2, attempt) * 1000毫秒）重试，最多 3 次；
• 7506 上下文超限：模型上下文窗口为 2K～8K token（因模型而异），压缩输入或将长文本转入 RAG 流程（大于 4K token 的上下文建议使用 RAG，见 README）。

其他常见问题（来自 configuration.md 与 gotchas.md）：

九、性能优化实践

官方 Performance Tips 三条要点及其仓库依据：

1. 批量 Embeddings：单次请求传入多个文本，减少请求往返次数（见本文第三节）；成本上批量 Embeddings 单文本约 5～20 neurons（见 patterns.md 的成本表）；
2. 流式长响应：用stream: true降低感知延迟，配合 SSE 格式输出（见本文第二节与 patterns.md 的 SSE 完整模板）；
3. 接受冷启动：模型在首次请求时加载，首请求约 1～3 秒，后续请求约 100～500ms。对高频 prompt 可叠加 AI Gateway 缓存降低冷启动影响（见 gotchas.md）。

附加的成本优化手段：任务简单时优先使用小模型——分类用@cf/mistral/mistral-7b-instruct-v0.1（约 50 neurons），对话用 8B 模型（约 200 neurons），70B 大模型单次约 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