Cloudflare

Cloudflare 어댑터는 Cloudflare Workers AI 모델과 AI Gateway에 액세스할 수 있도록 하며, 캐싱, 속도 제한, 통합 결제를 적용해 OpenAI, Anthropic, Gemini, Grok, OpenRouter로 요청을 라우팅합니다.

설치

npm install @cloudflare/tanstack-ai @tanstack/ai

AI Gateway에서 서드 파티 공급자를 사용하려면 필요한 공급자 SDK를 설치합니다.

npm install @tanstack/ai-openai       # For OpenAI via Gateway
npm install @tanstack/ai-anthropic    # For Anthropic via Gateway
npm install @tanstack/ai-gemini       # For Gemini via Gateway
npm install @tanstack/ai-grok         # For Grok via Gateway
npm install @tanstack/ai-openrouter   # For OpenRouter via Gateway

기본 사용법

import { chat, toHttpResponse } from "@tanstack/ai";
import { createWorkersAiChat } from "@cloudflare/tanstack-ai";
import { env } from "./env";

const adapter = createWorkersAiChat(
  "@cf/meta/llama-4-scout-17b-16e-instruct",
  { binding: env.AI },
);

const response = chat({
  adapter,
  stream: true,
  messages: [{ role: "user", content: "Hello!" }],
});

const httpResponse = toHttpResponse(response);

Workers AI

Cloudflare Worker에서 AI를 사용하는 가장 간단한 방법입니다. env.AI 바인딩을 사용하면 API 키가 필요하지 않습니다.

채팅

import { chat, toHttpResponse } from "@tanstack/ai";
import { createWorkersAiChat } from "@cloudflare/tanstack-ai";
import { env } from "./env";

const adapter = createWorkersAiChat(
  "@cf/meta/llama-4-scout-17b-16e-instruct",
  { binding: env.AI },
);

const response = chat({
  adapter,
  stream: true,
  messages: [{ role: "user", content: "Hello!" }],
});

const httpResponse = toHttpResponse(response);

REST 자격 증명을 사용한 채팅

Worker 내부에서 실행하지 않는 경우에는 account ID와 API key를 대신 사용합니다.

import { createWorkersAiChat } from "@cloudflare/tanstack-ai";

const adapter = createWorkersAiChat(
  "@cf/meta/llama-4-scout-17b-16e-instruct",
  {
    accountId: "your-account-id",
    apiKey: "your-api-key",
  },
);

이미지 생성

import { generateImage } from "@tanstack/ai";
import { createWorkersAiImage } from "@cloudflare/tanstack-ai";
import { env } from "./env";

const adapter = createWorkersAiImage(
  "@cf/stabilityai/stable-diffusion-xl-base-1.0",
  { binding: env.AI },
);

const result = await generateImage({
  adapter,
  prompt: "a cat in space",
});

console.log(result.images[0]?.b64Json);

전사(음성-텍스트)

Whisper 및 Deepgram 모델을 지원합니다.

import { generateTranscription } from "@tanstack/ai";
import { createWorkersAiTranscription } from "@cloudflare/tanstack-ai";
import { env, audioArrayBuffer } from "./env";

const adapter = createWorkersAiTranscription(
  "@cf/openai/whisper-large-v3-turbo",
  { binding: env.AI },
);

const result = await generateTranscription({
  adapter,
  audio: audioArrayBuffer,
});

console.log(result.text);
console.log(result.segments);

지원되는 전사 모델: @cf/openai/whisper, @cf/openai/whisper-tiny-en, @cf/openai/whisper-large-v3-turbo, @cf/deepgram/nova-3

텍스트-음성 변환

import { generateSpeech } from "@tanstack/ai";
import { createWorkersAiTts } from "@cloudflare/tanstack-ai";
import { env } from "./env";

const adapter = createWorkersAiTts("@cf/deepgram/aura-2-en", {
  binding: env.AI,
});

const result = await generateSpeech({
  adapter,
  text: "Hello world",
});

console.log(result.audio);

요약

import { summarize, type AnySummarizeAdapter } from "@tanstack/ai";
import { createWorkersAiSummarize } from "@cloudflare/tanstack-ai";
import { env } from "./env";

const adapter: AnySummarizeAdapter = createWorkersAiSummarize("@cf/facebook/bart-large-cnn", {
  binding: env.AI,
});

const result = await summarize({
  adapter,
  text: "Long article here...",
});

console.log(result.summary);

AI 게이트웨이

캐싱, 속도 제한, 통합 결제를 위해 Cloudflare의 AI Gateway를 통해 AI 요청을 라우팅합니다. Workers AI와 서드 파티 공급자를 모두 지원합니다.

Gateway를 통한 Workers AI

import { createWorkersAiChat } from "@cloudflare/tanstack-ai";
import { env } from "./env";

const adapter = createWorkersAiChat(
  "@cf/meta/llama-4-scout-17b-16e-instruct",
  {
    binding: env.AI.gateway("my-gateway-id"),
    apiKey: env.WORKERS_AI_TOKEN,
  },
);

Gateway를 통한 서드 파티 공급자

바인딩 방식을 사용합니다(Cloudflare Workers에 권장).

import {
  createOpenAiChat,
  createAnthropicChat,
  createGeminiChat,
  createGrokChat,
  createOpenRouterChat,
} from "@cloudflare/tanstack-ai";
import { env } from "./env";

const openai = createOpenAiChat("gpt-4o", {
  binding: env.AI.gateway("my-gateway-id"),
});

const anthropic = createAnthropicChat("claude-sonnet-4-5", {
  binding: env.AI.gateway("my-gateway-id"),
});

const grok = createGrokChat("grok-4.3", {
  binding: env.AI.gateway("my-gateway-id"),
});

const openrouter = createOpenRouterChat("openai/gpt-4o", {
  binding: env.AI.gateway("my-gateway-id"),
});

Worker가 아닌 환경에서는 자격 증명을 사용할 수도 있습니다.

import { createOpenAiChat } from "@cloudflare/tanstack-ai";

const adapter = createOpenAiChat("gpt-4o", {
  accountId: "your-account-id",
  gatewayId: "your-gateway-id",
  cfApiKey: "your-cf-api-key",
  apiKey: "provider-api-key",
});

캐시 옵션

바인딩 모드와 자격 증명 모드 모두 캐시 구성을 지원합니다.

import { createOpenAiChat } from "@cloudflare/tanstack-ai";
import { env } from "./env";

const adapter = createOpenAiChat("gpt-4o", {
  binding: env.AI.gateway("my-gateway-id"),
  skipCache: false,
  cacheTtl: 3600,
  customCacheKey: "my-key",
  metadata: { user: "test" },
});

구성 모드

Workers AI는 네 가지 구성 모드를 지원합니다.

모드	구성	설명
일반 바인딩	{ binding: env.AI }	직접 액세스, gateway 없음
일반 REST	{ accountId, apiKey }	REST API, gateway 없음
Gateway 바인딩	{ binding: env.AI.gateway(id) }	바인딩을 통해 AI Gateway 사용
Gateway REST	{ accountId, gatewayId, ... }	REST를 통해 AI Gateway 사용

서드 파티 공급자(OpenAI, Anthropic, Gemini, Grok, OpenRouter)는 gateway 모드만 지원합니다.

지원되는 기능

공급자	채팅	요약	이미지 생성	전사	TTS
Workers AI	✅	✅	✅	✅	✅
OpenAI	✅	✅	✅	✅	✅
Anthropic	✅	✅	❌	❌	❌
Gemini	✅	✅	✅	❌	✅
Grok	✅	✅	✅	❌	❌
OpenRouter	✅	✅	✅	❌	❌

환경 변수

REST 자격 증명 경로(Cloudflare Workers 외부):

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_KEY=your-api-key

Worker 내부에서 env.AI 바인딩을 사용하면 환경 변수가 필요하지 않습니다.

API 참조

Workers AI

• createWorkersAiChat(model, config) — 채팅 및 구조화된 출력
• createWorkersAiImage(model, config) — 이미지 생성
• createWorkersAiTranscription(model, config) — 음성-텍스트 변환(Whisper, Deepgram)
• createWorkersAiTts(model, config) — 텍스트-음성 변환(Deepgram Aura)
• createWorkersAiSummarize(model, config) — 요약(BART-large-CNN)

Gateway 공급자

• createOpenAiChat(model, config) / createOpenAiSummarize / createOpenAiImage / createOpenAiTranscription / createOpenAiTts
• createAnthropicChat(model, config) / createAnthropicSummarize
• createGeminiChat(model, config) / createGeminiSummarize / createGeminiImage / createGeminiTts
• createGrokChat(model, config) / createGrokSummarize / createGrokImage
• createOpenRouterChat(model, config) / createOpenRouterSummarize / createOpenRouterImage

다음 단계

• Cloudflare Workers AI — Workers AI 문서
• Cloudflare AI Gateway — AI Gateway 문서
• GitHub Repository — 소스 코드 및 이슈
• Streaming Guide — 스트리밍 응답을 알아봅니다.
• Tools Guide — 도구 호출을 알아봅니다.