Workers AI cho phép bạn gọi 78+ model open-source từ một Cloudflare Worker chỉ với một lệnh env.AI.run(). Không cần cấp phát GPU, không có cold start từ việc dựng thêm backend riêng, không có thêm chi phí infrastructure. Nếu logic của bạn đã nằm trong Worker, việc thêm AI inference chỉ cần khoảng mười dòng TypeScript.

Hướng dẫn này đưa bạn từ zero đến một Worker hoàn chỉnh có thể sinh text, stream response, và xử lý embeddings lẫn image generation. Mỗi bước đều chỉ rõ failure mode để bạn không phải tự mình khám phá trên production.

Bài này dành cho ai

Các TypeScript developer muốn chạy inference ngay tại edge mà không cần dựng thêm AI backend. Bạn cần một Cloudflare account và kỹ năng CLI cơ bản. Nếu bạn cần chất lượng reasoning cao cấp — GPT-4o, Claude — bạn sẽ phải gọi trực tiếp các API đó; Workers AI không host model proprietary. Chuyển thẳng đến phần so sánh nếu bạn đang trong giai đoạn đánh giá. Nếu bạn cũng đang cân nhắc giữa các nền tảng serverless, Cloudflare Workers so sánh với AWS Lambda phân tích chi tiết từng trường hợp.

Các model hiện có

78 model gồm text generation, embeddings, image generation, speech, và translation. Một số lựa chọn đáng chú ý cho text generation:

Model	Context	Ghi chú
`@cf/moonshot/kimi-k2.6`	262,100 tokens	Multi-turn tool calling, vision inputs
`@cf/zhipuai/glm-4.7-flash`	131,072 tokens	Đa ngôn ngữ, function calling
`@cf/google/gemma-3-12b-it`	80,000 tokens	Multimodal, 140+ ngôn ngữ
`@cf/mistralai/mistral-small-3.1-24b-instruct`	128,000 tokens	Vision, function calling
`@cf/meta/llama-3.3-70b-instruct-fp8-fast`	24,000 tokens	FP8 quantized, tối ưu tốc độ
`@cf/meta/llama-3.1-8b-instruct`	128,000 tokens	Model khởi đầu tốt cho hầu hết tác vụ
`@cf/qwen/qwq-32b`	—	Chuyên về reasoning

Danh mục đầy đủ: developers.cloudflare.com/workers-ai/models/

Bước 1: Kiểm tra yêu cầu

Bạn cần:

Cloudflare account (free tier là đủ): dash.cloudflare.com/sign-up/workers-and-pages
Node.js 16.17.0 trở lên

node -v

Failure mode: Node thấp hơn 16.17 khiến Wrangler lỗi khi cài đặt với một npm error khó hiểu. Kiểm tra version trước khi bắt đầu.

Bước 2: Tạo project

C3 (Create Cloudflare CLI) là công cụ scaffold được khuyến nghị:

npm create cloudflare@latest -- hello-ai

Tại các câu hỏi tương tác, chọn:

Template: Hello World example
Project type: Worker only
Language: TypeScript
Git: Yes
Deploy now: No

cd hello-ai

Cấu trúc project sau khi scaffold:

hello-ai/
├── wrangler.toml
├── src/
│   └── index.ts
├── package.json
└── tsconfig.json

Failure mode: Nếu npm create cloudflare bị treo, npm registry của bạn có thể đang chậm. Thử chạy trực tiếp npx create-cloudflare@latest -- hello-ai.

Bước 3: Bind AI service

Workers AI được truy cập qua một binding khai báo trong config project. Mở wrangler.toml và thêm block [ai]:

name = "hello-ai"
main = "src/index.ts"
compatibility_date = "2025-12-01"

[ai]
binding = "AI"

Nếu project của bạn dùng wrangler.jsonc:

{
  "name": "hello-ai",
  "main": "src/index.ts",
  "compatibility_date": "2024-09-23",
  "ai": {
    "binding": "AI"
  }
}

Tên binding "AI" là quy ước nhưng tùy ý — nó sẽ thành env.AI trong code Worker. Bạn có thể đổi tên.

Failure mode: Bỏ sót block [ai] khiến env.AI bị undefined lúc runtime. Bạn sẽ gặp lỗi Cannot read properties of undefined (reading 'run'). Điều đầu tiên cần kiểm tra khi thấy lỗi này: wrangler config của bạn.

Bước 4: Thực hiện inference đầu tiên

Thay toàn bộ nội dung src/index.ts:

export interface Env {
  AI: Ai;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
      prompt: 'What is the origin of the phrase Hello, World?',
    });

    return Response.json(response);
  },
} satisfies ExportedHandler<Env>;

Chạy ở local:

npx wrangler dev

Mở http://localhost:8787. Response là một JSON object với trường response chứa output của model.

Lưu ý quan trọng: Chế độ local dev của Wrangler vẫn route các AI call đến infrastructure thực của Cloudflare — không phải emulator local. Các request này tính vào neuron quota và rate limit của bạn.

Deploy khi bạn sẵn sàng:

npx wrangler login   # mở browser để xác thực OAuth
npx wrangler deploy

Worker của bạn sẽ live tại https://hello-ai.<YOUR_SUBDOMAIN>.workers.dev.

Failure mode: wrangler login yêu cầu browser cho OAuth flow. Trong môi trường CI headless, hãy set biến môi trường CLOUDFLARE_API_TOKEN và bỏ qua bước login.

Bước 5: Stream response

Thêm stream: true vào options. Response sẽ trở thành một Server-Sent Events stream:

export interface Env {
  AI: Ai;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const stream = await env.AI.run(
      '@cf/meta/llama-3.1-8b-instruct',
      {
        prompt: 'Explain edge computing in simple terms.',
        stream: true,
      }
    );

    return new Response(stream, {
      headers: { 'content-type': 'text/event-stream' },
    });
  },
} satisfies ExportedHandler<Env>;

Tiêu thụ ở phía browser:

const source = new EventSource('/');

source.onmessage = (event) => {
  if (event.data === '[DONE]') {
    source.close();
    return;
  }
  const data = JSON.parse(event.data);
  document.getElementById('output').innerHTML += data.response;
};

Mỗi SSE event mang một partial token trong data.response. Stream kết thúc bằng sentinel [DONE].

Failure mode: Bỏ thiếu content-type: text/event-stream khiến browser buffer toàn bộ response thay vì stream. Workers Paid plan mặc định có giới hạn 30 giây CPU time mỗi request (Workers limits); với các generation dài, hãy tăng giới hạn này trong wrangler config (tối đa 5 phút).

Bước 6: Thêm embeddings và image generation

Text embeddings

const embeddings = await env.AI.run('@cf/baai/bge-m3', {
  text: [
    'This is a story about an orange cloud',
    'This is a story about a llama',
  ],
});
return Response.json(embeddings);

@cf/baai/bge-m3 là lựa chọn tốt nhất cho đa số trường hợp — đa ngôn ngữ, multi-granularity. Với workload chỉ cần tiếng Anh, BGE Large (1024-dim), Base (768-dim), và Small (384-dim) là các lựa chọn nhẹ hơn.

Input là một string hoặc mảng string. Output là các embedding vector theo thứ tự tương ứng.

Failure mode: Truyền một string đơn khi input cần là mảng sẽ trả về một vector duy nhất, không phải lỗi. Kiểm tra shape của input nếu bạn nhận được số lượng vector bất ngờ.

Image generation

const response = await env.AI.run('@cf/black-forest-labs/flux-1-schnell', {
  prompt: 'a cyberpunk lizard',
  steps: 4,  // mặc định: 4, tối đa: 8 — steps cao hơn = chất lượng tốt hơn nhưng chậm hơn
});

// Trả về dạng base64 data URI
const dataURI = `data:image/jpeg;charset=utf-8;base64,${response.image}`;
return Response.json({ dataURI });

Hoặc trả về ảnh dưới dạng binary:

const binaryString = atob(response.image);
const img = Uint8Array.from(binaryString, (m) => m.charCodeAt(0));
return new Response(img, {
  headers: { 'Content-Type': 'image/jpeg' },
});

flux-1-schnell trả về JPEG mã hóa base64 trong response.image. Để có chất lượng photorealism cao hơn, @cf/black-forest-labs/flux-2-dev có sẵn trên cùng API.

Failure mode: Tham số steps giới hạn tối đa là 8. Vượt quá sẽ trả về lỗi 400. Đặt dưới 4 sẽ tạo ảnh chất lượng kém rõ ràng.

Pricing và rate limit

Pricing

Tier	Quota	Chi phí
Free (bất kỳ plan)	10,000 Neurons/ngày	$0 — reset lúc 00:00 UTC
Paid overage	Không giới hạn	$0.011 mỗi 1,000 Neurons

Neurons mỗi triệu token thay đổi đáng kể tùy model. Ví dụ:

Model	Input neurons/M tokens	Output neurons/M tokens
Llama 3.2 1B	2,457	18,252
DeepSeek R1 Distill 32B	45,170	443,756

Với 10,000 neurons/ngày trên Llama 3.1 8B (75,147 output neurons/M tokens), bạn có khoảng 133,000 output token mỗi ngày ở free plan — đủ để phát triển và sử dụng nhẹ.

Rate limit (requests per minute)

Loại tác vụ	RPM mặc định
Text generation	300
Text embeddings	3,000 (BGE-Large: 1,500)
Text-to-image	720
Speech recognition	720
Translation	720
Image classification	3,000
Summarization	1,500

Các request Wrangler local dev cũng tính vào các giới hạn này.

Nguồn: pricing docs, limits docs

Khi nào nên dùng Cloudflare Workers AI thay vì API bên ngoài

Workers AI phù hợp khi logic của bạn đã nằm trong Cloudflare — bạn muốn inference chạy ngay cùng nơi với KV lookup, D1 query, hay R2 upload, mà không phải trả thêm phí egress cho một AI provider riêng.

Hãy dùng Anthropic hoặc OpenAI trực tiếp khi:

Bạn cần chất lượng reasoning cao cấp. Workers AI chạy các open-weight model — không có GPT-4o, không có Claude.
Chi phí mỗi output token ở quy mô lớn quan trọng hơn latency. Ở volume cao, $0.011 mỗi 1,000 neurons có thể vượt qua pricing của các hosted API, tùy model.
Bạn cần đảm bảo model luôn available. Cloudflare có thể deprecate hoặc swap model; catalog chính thức không có SLA cho các phiên bản model cụ thể.

Workers AI phù hợp cho:

Workload nhạy cảm về privacy: dữ liệu ở lại trong network của Cloudflare, không qua LLM provider bên thứ ba.
Edge inference có độ trễ thấp: chạy ngay trong Worker, không cần round trip đến region riêng.
Tác vụ đơn giản ở quy mô free tier: content moderation, summarization, embeddings cho RAG trên Vectorize index.

Workers AI kết hợp tốt với Cloudflare D1 khi bạn cần database quan hệ trong cùng edge region — không phát sinh phí egress giữa các service.

Phân chia thực tế: dùng Workers AI cho inference là một phần của Cloudflare-first backend. Dùng Anthropic hoặc OpenAI khi chất lượng quan trọng hơn kiến trúc.

Thay thế: REST API

Workers AI cũng có thể gọi mà không cần Worker, qua Cloudflare REST API:

curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/run/@cf/meta/llama-3.1-8b-instruct \
  -H 'Authorization: Bearer {API_TOKEN}' \
  -d '{ "prompt": "Your question here" }'

Response:

{
  "result": { "response": "Model output here" },
  "success": true,
  "errors": [],
  "messages": []
}

Hữu ích cho việc prototyping, CI pipeline, hoặc backend không dùng Worker. Pricing tương tự với Worker-based call.

Cách thiết lập Cloudflare Workers AI: Hướng dẫn từng bước