Cloudflare AI Gateway

Cloudflare AI Gateway

Cloudflare AI Gateway의 모델을 Docker Agent에서 사용하는 방법을 설명해요. 게이트웨이 하나로 여러 프로바이더의 모델을 한 엔드포인트에서 라우팅할 수 있어요.

출처: 문서

본문

Cloudflare AI Gateway는 OpenAI, Anthropic, Workers AI 등 여러 곳의 모델을 하나의 OpenAI 호환 엔드포인트로 라우팅해 주는 서비스예요. 캐싱, 속도 제한, 관측성(observability)까지 제공하죠. Docker Agent에는 AI Gateway를 기본 제공 alias 프로바이더로 지원하고 있어요.

이 alias는 표준 `Authorization: *** 헤더로 토큰을 보내요. 그래서 인증이 꺼져 있는 게이트웨이(기본값)에서는 별도 설정 없이 바로 동작해요. 보통 자기 소유 게이트웨이를 통해 본인 Workers AI 모델로 라우팅할 때 쓰죠. 인증이 켜진 게이트웨이(통합 과금)의 주의사항은 아래 Authentication을 참고하세요.

설정

게이트웨이 엔드포인트는 계정과 게이트웨이 단위로 범위가 정해져 있어서, 기본 URL이 계정 ID와 게이트웨이 ID에서 결정돼요. 환경 변수 세 개가 필요해요:

export CLOUDFLARE_ACCOUNT_ID=your-account-id
export CLOUDFLARE_GATEWAY_ID=your-gateway-id
export CLOUDFLARE_API_TOKEN=your-api-token

AI Gateway 대시보드에서 게이트웨이를 만들고, 적절한 권한을 가진 API 토큰을 만들어 두세요.

사용법

AI Gateway 모델 ID는 게이트웨이의 provider/model 형태를 사용해요(예: workers-ai/@cf/meta/llama-3.1-8b-instruct 또는 openai/gpt-4o). 게이트웨이가 각 요청을 해당 프로바이더로 라우팅해 줘요.

인라인 문법

agents:
  root:
    model: cloudflare-ai-gateway/workers-ai/@cf/meta/llama-3.1-8b-instruct
    description: Assistant using Cloudflare AI Gateway
    instruction: You are a helpful assistant.

네임드 모델 (Named Model)

파라미터를 더 세밀하게 제어하려면:

models:
  cloudflare_model:
    provider: cloudflare-ai-gateway
    model: "workers-ai/@cf/meta/llama-3.1-8b-instruct"
    temperature: 0.7
    max_tokens: 8192

agents:
  root:
    model: cloudflare_model
    description: Assistant using Cloudflare AI Gateway
    instruction: You are a helpful assistant.

사용 가능한 모델

AI Gateway는 한 엔드포인트 뒤에서 여러 프로바이더의 모델을 노출해요. 현재 프로바이더 목록, 모델 ID, 결제 방식은 AI Gateway 문서에서 확인하세요.

모델 ID는 대소문자를 구분하고, 게이트웨이가 나열하는 방식 그대로 provider/ 접두사를 포함해 전달해야 해요.

동작 방식

Cloudflare AI Gateway는 Docker Agent의 기본 제공 alias로 구현돼 있어요:

기본 URL은 템플릿이라서 ${CLOUDFLARE_ACCOUNT_ID}와 ${CLOUDFLARE_GATEWAY_ID}가 프로바이더 생성 시 환경에서 치환돼요. 그래서 CLOUDFLARE_API_TOKEN 외에 두 변수도 반드시 설정해야 해요. 게이트웨이가 엄격한 채팅 템플릿을 요구하는 오픈웨이트(open-weight) 모델로도 라우팅할 수 있기 때문에, Docker Agent는 이 프로바이더에서 연속된 시스템 메시지를 맨 앞의 하나로 합쳐 줘요.

인증

Docker Agent는 CLOUDFLARE_API_TOKEN을 표준 Authorization: *** 헤더로 보내 인증해요. .../compat` 엔드포인트에서는 그 헤더가 프로바이더 키로 취급되기 때문에, 다음 조건이면 이 alias가 동작해요:

  • 게이트웨이의 인증이 꺼져 있고(기본값),
  • 라우팅되는 모델이 그 토큰을 자기 프로바이더 키로 받아들이는 경우 — Workers AI 모델(workers-ai/@cf/...)이 그렇죠.

반면 인증이 켜진 게이트웨이(통합 과금에 필요)는 Cloudflare의 cf-aig-authorization 헤더에 토큰을 넣기를 기대해요. 그런데 이 alias는 그 헤더를 보내지 않고, 커스텀 provider_opts.http_headers 값도 환경 변수 확장이 지원되지 않아서, 현재로서는 인증된 게이트웨이가 기본 지원되지 않아요. 그런 구성이라면 인증 없는 게이트웨이를 쓰거나, Cloudflare AI Gateway REST API를 상대로 커스텀 프로바이더를 설정하면 돼요.

더 알아보기 (Learn more)