Cloudflare Workers AI로 서버리스 AI 추론하기
AI 기능을 서비스에 넣으려면 OpenAI API 키를 발급받고 서버를 세팅하고 요청을 중계하는 백엔드까지 구성해야 하잖아요. 이 과정이 꽤 번거롭고 GPU 인프라를 직접 관리하는 건 비용도 만만치 않습니다 😅
Cloudflare Workers AI를 쓰면 별도의 GPU 인프라 없이 전 세계 엣지에서 AI 모델을 바로 실행할 수 있습니다. Cloudflare Workers에 코드 몇 줄만 추가하면 텍스트 생성, 이미지 생성, 번역, 음성 인식 같은 AI 기능을 서버리스로 제공할 수 있어요.
이번 글에서는 Workers AI의 기본 개념부터 텍스트 생성, JSON Mode, Function Calling, 이미지 생성, 임베딩, 외부 모델 연동까지 실제 코드와 함께 살펴보겠습니다.
Workers AI란?
Workers AI는 Cloudflare의 엣지 네트워크에서 AI 모델을 실행할 수 있는 서버리스 GPU 추론 플랫폼입니다.
보통 AI 모델을 서비스하려면 GPU 서버를 준비하고 모델을 로드하고 추론 요청을 처리하는 인프라를 구축해야 합니다. Workers AI는 이걸 Cloudflare가 알아서 해주니까 개발자는 어떤 모델에 무슨 입력을 보낼지만 정하면 돼요.
OpenAI 같은 상용 API와 뭐가 다를까요? Workers AI는 Meta의 Llama, Google의 Gemma, Mistral 같은 오픈소스 모델을 사용합니다. GPT-4나 Claude 같은 최첨단 모델은 없지만 모델 선택의 폭이 넓고 비용이 훨씬 저렴해요. 또한 Cloudflare의 전 세계 180개 이상 도시에 분산된 GPU에서 실행되기 때문에 사용자와 가까운 곳에서 추론이 이루어져 응답이 빠릅니다.
사용 가능한 모델
Workers AI에서 사용할 수 있는 모델 종류를 간략히 훑어볼게요.
텍스트 생성(LLM)은 Meta의 Llama 시리즈가 대표적입니다. 가볍고 빠른 @cf/meta/llama-3.2-3b-instruct부터 고성능 @cf/meta/llama-3.3-70b-instruct-fp8-fast까지 용도에 맞게 고를 수 있어요. 최근 추가된 @cf/meta/llama-4-scout-17b-16e-instruct는 MoE 아키텍처 기반의 멀티모달 모델이라 텍스트와 이미지를 동시에 처리할 수 있습니다.
Llama 외에도 코딩에 특화된 @cf/qwen/qwen2.5-coder-32b-instruct, 추론 작업에 강한 @cf/qwen/qwq-32b와 @cf/deepseek-ai/deepseek-r1-distill-qwen-32b, 비전까지 지원하는 @cf/mistralai/mistral-small-3.1-24b-instruct 등 다양한 모델이 있습니다.
이미지 생성은 @cf/stabilityai/stable-diffusion-xl-base-1.0로 Stable Diffusion XL을 바로 돌릴 수 있고 FLUX 시리즈도 있습니다.
임베딩 모델은 @cf/baai/bge-base-en-v1.5가 영어 텍스트에 적합하고 다국어가 필요하면 @cf/baai/bge-m3를 쓸 수 있어요.
음성 쪽에서는 @cf/openai/whisper-large-v3-turbo로 음성을 텍스트로 변환하거나 @cf/myshell-ai/melotts로 텍스트를 음성으로 합성할 수 있습니다. 번역은 @cf/meta/m2m100-1.2b, 텍스트 분류는 @cf/huggingface/distilbert-sst-2-int8도 지원하고요.
용도별로 추천하면, 챗봇이나 텍스트 처리에는 llama-3.3-70b-instruct-fp8-fast가 성능과 속도 균형이 좋고 응답 속도가 중요하면 llama-3.2-3b-instruct 같은 작은 모델이 낫습니다. 코드 생성에는 qwen2.5-coder-32b-instruct, 복잡한 추론에는 qwq-32b나 deepseek-r1-distill-qwen-32b가 적합해요.
전체 모델 목록은 Workers AI Models 페이지에서 확인할 수 있습니다.
Workers 바인딩
Workers AI를 사용하는 방법은 크게 두 가지예요. Cloudflare Workers 안에서 바인딩으로 직접 호출하거나 REST API로 외부에서 호출하는 건데, 먼저 바인딩 방식부터 살펴볼게요.
Cloudflare Workers 프로젝트에서 AI 모델을 사용하려면 먼저 wrangler.jsonc 설정 파일에 AI 바인딩을 추가합니다.
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "ai-worker",
"main": "src/index.ts",
"compatibility_date": "2025-01-01",
"ai": {
"binding": "AI",
},
}이렇게 하면 Worker 코드에서 env.AI를 통해 AI 모델을 호출할 수 있습니다.
export default {
async fetch(request, env): Promise<Response> {
const result = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
messages: [
{ role: "system", content: "친절한 한국어 도우미입니다." },
{ role: "user", content: "서버리스 컴퓨팅이 뭔지 간단히 설명해줘" },
],
});
return Response.json(result);
},
} satisfies ExportedHandler<Env>;env.AI.run()의 첫 번째 인자로 모델 이름을, 두 번째 인자로 입력 데이터를 넘기면 됩니다.
텍스트 생성 모델의 경우 ChatGPT API와 동일한 messages 형식을 사용하기 때문에 익숙할 거예요.
로컬에서 개발 서버를 띄우고 테스트해볼 수 있습니다.
$ npx wrangler dev$ curl http://localhost:8787
{"response":"서버리스 컴퓨팅은 서버 인프라를 직접 관리하지 않고..."}REST API
Cloudflare Workers 프로젝트가 아니더라도 REST API를 통해 어디서든 Workers AI를 호출할 수 있습니다. 이 경우 Cloudflare 계정 ID와 API 토큰이 필요합니다.
API 토큰은 Cloudflare 대시보드에서 발급받을 수 있어요.
토큰을 만들 때 Workers AI 읽기 권한을 부여하면 됩니다.
$ curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/run/@cf/meta/llama-3.1-8b-instruct \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"role": "user", "content": "Hello, Workers AI!"}
]
}'Python, Node.js 등 어떤 언어에서든 HTTP 요청을 보낼 수 있으니 기존 백엔드 서비스에 AI 기능을 추가할 때도 활용할 수 있습니다.
텍스트 생성
텍스트 생성을 좀 더 세밀하게 제어하고 싶다면 temperature, max_tokens 같은 파라미터를 사용할 수 있습니다.
export default {
async fetch(request, env): Promise<Response> {
const result = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
messages: [
{ role: "system", content: "기술 블로그 작가입니다." },
{ role: "user", content: "TypeScript의 장점 3가지를 알려줘" },
],
temperature: 0.7,
max_tokens: 512,
});
return Response.json(result);
},
} satisfies ExportedHandler<Env>;temperature는 0에 가까울수록 일관된 답변을, 1에 가까울수록 창의적인 답변을 생성합니다.
max_tokens로 응답 길이를 제한할 수도 있어요.
스트리밍 응답도 지원됩니다. 긴 텍스트를 생성할 때 전체 응답을 기다리지 않고 토큰이 생성되는 대로 바로 전달받을 수 있죠.
export default {
async fetch(request, env): Promise<Response> {
const stream = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
messages: [{ role: "user", content: "JavaScript의 역사를 알려줘" }],
stream: true,
});
return new Response(stream, {
headers: { "Content-Type": "text/event-stream" },
});
},
} satisfies ExportedHandler<Env>;stream: true를 추가하면 Server-Sent Events(SSE) 형식으로 응답이 옵니다.
프론트엔드에서 EventSource나 fetch의 ReadableStream으로 받아서 ChatGPT처럼 한 글자씩 나타나는 UX를 구현할 수 있습니다.
JSON Mode로 구조화된 응답 받기
LLM 응답을 코드에서 바로 처리하려면 자연어가 아니라 정해진 형식의 JSON이 와야 합니다. Workers AI는 JSON Mode를 지원하기 때문에 JSON Schema를 지정해두면 모델이 해당 형식에 맞춰 응답해줘요.
export default {
async fetch(request, env): Promise<Response> {
const response = await env.AI.run(
"@cf/meta/llama-3.3-70b-instruct-fp8-fast",
{
messages: [
{ role: "system", content: "주어진 텍스트에서 정보를 추출하세요." },
{
role: "user",
content:
"다음 주 화요일 오후 3시에 디자인 리뷰 미팅이 있습니다. 참석자는 김철수, 이영희입니다.",
},
],
response_format: {
type: "json_schema",
json_schema: {
type: "object",
properties: {
event_name: { type: "string" },
day: { type: "string" },
time: { type: "string" },
attendees: {
type: "array",
items: { type: "string" },
},
},
required: ["event_name", "day", "time", "attendees"],
},
},
},
);
return Response.json(response);
},
} satisfies ExportedHandler<Env>;{
"event_name": "디자인 리뷰 미팅",
"day": "다음 주 화요일",
"time": "오후 3시",
"attendees": ["김철수", "이영희"]
}response_format에 type: "json_schema"와 스키마를 넘기면 됩니다.
모델이 스키마에 맞는 JSON만 생성하기 때문에 응답을 파싱하다가 에러가 나는 일이 줄어들어요.
type: "json_object"로 설정하면 스키마 없이 모델이 자유 형식의 JSON을 반환합니다.
구조가 유동적이어도 괜찮을 때 쓸 수 있지만, 정확한 필드가 보장되지 않으니 중요한 데이터 추출에는 json_schema를 쓰는 게 안전합니다.
Function Calling
Function Calling은 LLM이 직접 답하기 어려운 질문에 대해 외부 함수를 호출하도록 만드는 기능입니다. 예를 들어 “서울 날씨가 어때?”라는 질문에 모델이 직접 날씨를 알 수는 없지만, 날씨 API를 호출하는 함수를 정의해두면 모델이 알아서 그 함수를 선택하고 필요한 인자를 채워줍니다.
업계 표준 방식으로, tools 배열에 함수의 이름과 스키마를 정의하면 모델이 어떤 함수를 어떤 인자로 호출해야 하는지 JSON으로 돌려줍니다.
const response = await env.AI.run("@cf/meta/llama-3.3-70b-instruct-fp8-fast", {
messages: [{ role: "user", content: "서울 날씨가 어때?" }],
tools: [
{
name: "getWeather",
description: "주어진 도시의 현재 날씨를 조회합니다",
parameters: {
type: "object",
properties: {
city: {
type: "string",
description: "날씨를 조회할 도시 이름",
},
},
required: ["city"],
},
},
],
});
// 모델이 반환하는 tool_calls
console.log(response.tool_calls);[
{
"name": "getWeather",
"arguments": { "city": "서울" }
}
]모델은 실제로 함수를 실행하지 않습니다. “이 함수를 이 인자로 호출하면 돼”라고 알려주는 거예요.
개발자가 tool_calls를 받아서 실제 API를 호출하고 그 결과를 다시 모델에 전달하는 흐름이죠.
현재 Function Calling을 지원하는 모델은 llama-3.3-70b-instruct-fp8-fast, llama-4-scout-17b-16e-instruct, nemotron-3-120b-a12b, gpt-oss-120b, gpt-oss-20b, mistral-small-3.1-24b-instruct 등이 있습니다.
임베디드 Function Calling
Cloudflare만의 고유한 방식인데요, 함수 정의에 실제 실행 코드까지 포함시키면 runWithTools가 모델 호출과 함수 실행을 한꺼번에 처리해줍니다.
@cloudflare/ai-utils 패키지를 설치해서 사용합니다.
$ bun add @cloudflare/ai-utils
$ npm i @cloudflare/ai-utilsimport { runWithTools } from "@cloudflare/ai-utils";
interface Env {
AI: Ai;
}
export default {
async fetch(request, env): Promise<Response> {
const getWeather = async (args: { city: string }): Promise<string> => {
// 실제로는 외부 날씨 API를 호출
const weather: Record<string, string> = {
서울: "맑음, 22°C",
부산: "흐림, 19°C",
제주: "비, 17°C",
};
return weather[args.city] || "날씨 정보를 찾을 수 없습니다";
};
const response = await runWithTools(
env.AI,
"@cf/meta/llama-3.3-70b-instruct-fp8-fast",
{
messages: [{ role: "user", content: "서울이랑 부산 날씨 비교해줘" }],
tools: [
{
name: "getWeather",
description: "주어진 도시의 현재 날씨를 조회합니다",
parameters: {
type: "object",
properties: {
city: {
type: "string",
description: "날씨를 조회할 도시 이름",
},
},
required: ["city"],
},
function: getWeather,
},
],
},
);
return Response.json(response);
},
} satisfies ExportedHandler<Env>;전통적인 방식에서는 모델 호출 → tool_calls 파싱 → 함수 실행 → 결과를 다시 모델에 전달하는 루프를 직접 짜야 하는데, 임베디드 방식에서는 runWithTools가 이 과정을 전부 알아서 해줍니다.
OpenAPI 스펙 파일을 넘기면 API 엔드포인트를 자동으로 도구로 변환해주는 createToolsFromOpenAPISpec 헬퍼도 있어서 기존 API와의 연동이 편리해요.
다만 임베디드 Function Calling은 Workers 바인딩에서만 사용할 수 있고 REST API로는 지원되지 않습니다.
이미지 생성
Workers AI에서는 Stable Diffusion XL로 이미지를 생성할 수 있습니다. 텍스트 프롬프트만 전달하면 PNG 이미지가 바이너리로 반환됩니다.
export default {
async fetch(request, env): Promise<Response> {
const result = await env.AI.run(
"@cf/stabilityai/stable-diffusion-xl-base-1.0",
{
prompt:
"A cozy coffee shop in Seoul with warm lighting, watercolor style",
},
);
return new Response(result, {
headers: { "Content-Type": "image/png" },
});
},
} satisfies ExportedHandler<Env>;브라우저에서 http://localhost:8787에 접속하면 생성된 이미지를 바로 확인할 수 있습니다.
negative_prompt로 원하지 않는 요소를 지정할 수도 있고, num_steps로 생성 단계 수를 조절할 수도 있습니다.
const result = await env.AI.run(
"@cf/stabilityai/stable-diffusion-xl-base-1.0",
{
prompt: "A minimalist logo design for a tech startup",
negative_prompt: "blurry, low quality, text",
num_steps: 20,
},
);단계 수를 높이면 더 정교한 이미지가 나오지만 생성 시간이 길어지니 적절히 조절하는 게 좋습니다.
임베딩
텍스트 임베딩은 문장을 숫자 벡터로 변환하는 기술입니다. 의미가 비슷한 문장끼리 가까운 벡터로 표현되기 때문에 유사도 검색에 활용할 수 있어요.
Workers AI에서 임베딩을 생성하는 건 간단합니다.
export default {
async fetch(request, env): Promise<Response> {
const result = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
text: ["Cloudflare Workers AI is great", "Serverless GPU inference"],
});
return Response.json({
shape: result.shape,
dimensions: result.data[0].length,
});
},
} satisfies ExportedHandler<Env>;{"shape":[2,768],"dimensions":768}text에 문자열 배열을 넘기면 각 문장에 대한 768차원의 벡터가 반환됩니다.
이 임베딩 벡터를 Cloudflare의 벡터 데이터베이스인 Vectorize에 저장하면 유사도 검색을 구현할 수 있습니다.
OpenAI SDK 호환
이미 OpenAI API를 사용하고 있는 프로젝트라면 코드를 거의 바꾸지 않고도 Workers AI로 전환할 수 있습니다. Workers AI는 OpenAI 호환 엔드포인트를 제공하거든요.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: CLOUDFLARE_API_TOKEN,
baseURL: `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/ai/v1`,
});
const completion = await client.chat.completions.create({
model: "@cf/meta/llama-3.1-8b-instruct",
messages: [{ role: "user", content: "안녕하세요!" }],
temperature: 0.7,
max_tokens: 256,
});
console.log(completion.choices[0].message.content);baseURL만 Cloudflare 엔드포인트로 바꾸면 기존 OpenAI SDK 코드가 그대로 동작합니다.
/v1/chat/completions와 /v1/embeddings 엔드포인트를 지원하기 때문에 채팅과 임베딩 관련 코드는 거의 수정 없이 마이그레이션할 수 있어요.
AI Gateway
프로덕션 환경에서 AI 서비스를 운영할 때는 요청 모니터링, 캐싱, 속도 제한 같은 기능이 필요합니다. Cloudflare의 AI Gateway가 바로 이런 역할을 해줍니다.
AI Gateway를 활성화하면 모든 AI 요청이 게이트웨이를 거치면서 다음 기능들을 사용할 수 있습니다.
- 캐싱 — 동일한 프롬프트에 대한 응답을 캐싱해서 비용 절감
- 속도 제한 — 특정 시간 내 요청 수를 제한해서 과도한 사용 방지
- 모델 폴백 — 하나의 모델이 실패하면 자동으로 다른 모델로 전환
- 로깅과 분석 — 요청/응답 내역, 토큰 사용량, 비용을 대시보드에서 확인
- 실시간 모니터링 — 모든 AI 요청의 성공률, 지연 시간 추적
외부 모델 연동
Workers AI의 자체 모델은 오픈소스 기반이라 GPT-4o, Claude, Gemini 같은 상용 모델과 비교하면 성능 차이가 있을 수 있어요. 이럴 때 AI Gateway를 쓰면 외부 AI 제공업체를 하나의 게이트웨이로 묶어서 관리할 수 있습니다.
OpenAI, Anthropic, Google AI Studio, AWS Bedrock, Azure OpenAI, Groq, Mistral, DeepSeek 등 주요 AI 제공업체를 모두 지원합니다.
각 제공업체별로 전용 엔드포인트가 있어서 기존 API 스키마를 그대로 유지하면서 AI Gateway의 캐싱, 모니터링, 폴백 기능을 덧붙일 수 있습니다.
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider}예를 들어 OpenAI를 AI Gateway를 통해 호출하려면 이렇게 합니다.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: env.OPENAI_API_KEY,
baseURL: `https://gateway.ai.cloudflare.com/v1/${env.CF_ACCOUNT_ID}/${env.GATEWAY_ID}/openai`,
});
const completion = await client.chat.completions.create({
model: "gpt-4o",
messages: [{ role: "user", content: "안녕하세요!" }],
});Anthropic도 같은 패턴입니다.
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: env.ANTHROPIC_API_KEY,
baseURL: `https://gateway.ai.cloudflare.com/v1/${env.CF_ACCOUNT_ID}/${env.GATEWAY_ID}/anthropic`,
});
const message = await client.messages.create({
model: "claude-sonnet-4-20250514",
max_tokens: 1024,
messages: [{ role: "user", content: "안녕하세요!" }],
});기존 SDK 코드에서 baseURL만 AI Gateway 주소로 바꾸면 끝이에요.
더 간편한 방법도 있습니다.
AI Gateway의 OpenAI 호환 엔드포인트를 사용하면 model 파라미터만 바꿔서 여러 제공업체의 모델을 동일한 코드로 호출할 수 있어요.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: PROVIDER_API_KEY,
baseURL: `https://gateway.ai.cloudflare.com/v1/${ACCOUNT_ID}/${GATEWAY_ID}/compat`,
});
// OpenAI 모델 호출
const openaiResponse = await client.chat.completions.create({
model: "openai/gpt-4o",
messages: [{ role: "user", content: "TypeScript의 장점은?" }],
});
// Anthropic 모델 호출 — 같은 코드, model만 변경
const claudeResponse = await client.chat.completions.create({
model: "anthropic/claude-sonnet-4-20250514",
messages: [{ role: "user", content: "TypeScript의 장점은?" }],
});
// Google 모델 호출
const geminiResponse = await client.chat.completions.create({
model: "google-ai-studio/gemini-2.0-flash",
messages: [{ role: "user", content: "TypeScript의 장점은?" }],
});{provider}/{model} 형식으로 모델을 지정하면 AI Gateway가 알아서 해당 제공업체로 라우팅합니다.
요청과 응답 형식이 모두 OpenAI 호환으로 통일되니까 제공업체별로 SDK를 따로 설치하거나 응답 파싱 로직을 분기할 필요가 없어요.
Vercel AI SDK 연동
Workers AI를 Vercel의 AI SDK와 함께 쓸 수도 있습니다.
AI SDK는 여러 AI 제공업체를 통합하는 인터페이스를 제공하는데, Workers AI용 어댑터인 workers-ai-provider를 통해 연결됩니다.
$ bun add ai workers-ai-provider
$ npm i ai workers-ai-providerimport { generateText } from "ai";
import { createWorkersAI } from "workers-ai-provider";
export default {
async fetch(request, env): Promise<Response> {
const workersai = createWorkersAI({ binding: env.AI });
const { text } = await generateText({
model: workersai("@cf/meta/llama-3.3-70b-instruct-fp8-fast"),
prompt: "서버리스 컴퓨팅의 장점을 3가지 알려줘",
});
return Response.json({ response: text });
},
} satisfies ExportedHandler<Env>;AI SDK의 장점은 모델 제공업체를 쉽게 교체할 수 있다는 거예요.
workers-ai-provider를 @ai-sdk/openai나 @ai-sdk/anthropic으로 바꾸면 동일한 코드 구조에서 모델만 갈아끼울 수 있습니다.
텍스트 생성뿐 아니라 Tool Calling, 구조화된 응답 같은 기능도 통일된 API로 사용할 수 있어서 멀티 모델 서비스를 만들 때 코드가 깔끔해집니다.
요금제
Workers AI의 요금 체계는 “Neuron”이라는 단위를 씁니다. GPU 연산량을 통합 측정하는 단위로 모델마다 토큰당, 이미지당, 오디오 초당 소비하는 Neuron이 다릅니다.
무료 플랜에서도 하루 10,000 Neurons를 쓸 수 있어요. 유료 플랜(월 $5)에서는 하루 10,000 Neurons가 무료로 포함되고 초과분은 1,000 Neurons당 $0.011이 청구됩니다.
실제 비용으로 따져 보면 Llama 3.1 8B 기준으로 입력 100만 토큰당 약 $0.045, 출력 100만 토큰당 약 $0.384 정도예요. OpenAI GPT-4o 가격에 비하면 상당히 저렴합니다.
다만 모델 성능 자체는 GPT-4o나 Claude에 못 미치기 때문에 단순 비용 비교보다는 용도에 맞게 고르는 게 중요해요. 텍스트 분류나 요약, 번역 같은 작업에는 Workers AI의 가성비가 뛰어나고 복잡한 추론이나 코드 생성에는 상용 API를 사용하는 식으로 섞어 쓰는 것도 좋은 전략입니다.
마치며
지금까지 Cloudflare Workers AI를 사용해서 텍스트 생성, JSON Mode, Function Calling, 이미지 생성, 임베딩, 외부 모델 연동까지 살펴봤습니다. 기존 Cloudflare Workers 프로젝트에 AI 바인딩 하나만 추가하면 바로 쓸 수 있다는 게 가장 큰 장점이에요.
무료 플랜으로도 프로토타입을 충분히 만들 수 있고 OpenAI SDK 호환 엔드포인트 덕분에 기존 코드 마이그레이션도 쉽습니다. AI Gateway를 통한 캐싱과 모니터링, 외부 모델 연동까지 갖추고 있어서 프로덕션에도 활용할 만합니다.
Wrangler CLI에 익숙하다면 몇 분 만에 첫 번째 AI Worker를 만들어볼 수 있으니 한번 시도해보세요 💪 AWS 환경을 사용하고 있다면 비슷한 역할을 하는 AWS Bedrock도 살펴보시면 좋겠습니다.
더 자세한 내용은 Workers AI 공식 문서를 참고하세요!
This work is licensed under
CC BY 4.0
