Cloudflare Workers + Workers AI 集成指南 2026

概述

本指南将精确展示如何使用 Cloudflare Workers 和 Workers AI 在边缘运行AI。内容涵盖设置、核心集成以及生产就绪模式。

前提条件

已设置 Cloudflare Workers 环境

Workers AI API 密钥或访问凭证

基本了解 Cloudflare Workers 开发

安装

bash
安装所需包
npm install workers-ai cloudflare-workers-sdk
或
pip install workers_ai cloudflare_workers

快速设置

javascript
// 初始化 Workers AI 客户端
import { WorkersAIClient } from 'workers-ai';
const client = new WorkersAIClient({
  apiKey: process.env.WORKERS_AI_API_KEY,
  // 根据 Cloudflare Workers 设置添加其他配置
});

核心集成代码

typescript
// 完整的 Cloudflare Workers + Workers AI 集成
import { OpenAI } from 'openai';
import express from 'express';
// AI 端点
app.post('/api/ai', async (req, res) => {
  const { message, context } = req.body;
  
  try {
    const response = await openai.chat.completions.create({
      model: 'gpt-4o-mini',
      messages: [
        { role: 'system', content: 你已与 Cloudflare Workers 集成。帮助在边缘使用 Cloudflare 运行AI。 },
        { role: 'user', content: message }
      ],
      stream: false
    });
    
    res.json({
      response: response.choices[0].message.content,
      usage: response.usage
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});
app.listen(3000);

Cloudflare Workers 特定集成

javascript
// Cloudflare Workers 特定模式用于 Workers AI 集成
// 模式2：服务层
class AIService {
  constructor(private readonly client: typeof openai) {}
  
  async process(input: string, systemPrompt: string = ''): Promise {
    const response = await this.client.chat.completions.create({
      model: 'gpt-4o-mini',
      messages: [
        ...(systemPrompt ? [{ role: 'system' as const, content: systemPrompt }] : []),
        { role: 'user' as const, content: input }
      ]
    });
    return response.choices[0].message.content || '';
  }
}
// 模式3：React 钩子（如果适用）
function useAI() {
  const [response, setResponse] = useState('');
  const [loading, setLoading] = useState(false);
  
  const query = async (message: string) => {
    setLoading(true);
    try {
      const res = await fetch('/api/ai', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ message })
      });
      const data = await res.json();
      setResponse(data.response);
    } finally {
      setLoading(false);
    }
  };
  
  return { response, loading, query };
}

流式支持

typescript
// 添加流式支持以改善用户体验
app.post('/api/ai/stream', async (req, res) => {
  const { message } = req.body;
  
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
  
  const stream = await openai.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: message }],
    stream: true
  });
  
  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content;
    if (content) {
      res.write(data: ${JSON.stringify({ content })}\n\n);
    }
  }
  
  res.write('data: [DONE]\n\n');
  res.end();
});

测试集成

bash
单元测试
curl -X POST http://localhost:3000/api/ai \
  -H "Content-Type: application/json" \
  -d '{"message": "测试在边缘使用 Cloudflare 运行AI的消息"}'
预期输出：
{"response": "AI响应...", "usage": {...}}
负载测试
ab -n 100 -c 10 -p test-payload.json -T application/json http://localhost:3000/api/ai

生产部署

yaml
docker-compose.yml
services:
  app:
    build: .
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - NODE_ENV=production
    ports:
      - "3000:3000"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s

常见问题

问题：速率限制错误 解决方案：实现指数退避和请求排队

问题：响应时间慢 解决方案：使用流式传输并向用户显示加载状态

结论

Cloudflare Workers + Workers AI 集成功能强大且相对直接。本指南为您在生产环境中使用 Cloudflare 在边缘运行AI奠定了基础。

---

*Cloudflare Workers + Workers AI 集成指南 | 2026年5月*