왜 LLM 게이트웨이가 필요한가요?

AI 애플리케이션을 만들다 보면 금방 벽에 부딪혀요. 모델마다 엔드포인트가 다르고, 인증 방식도 제각각이고, 특정 모델이 느려지면 코드를 뜯어고쳐야 하죠. 심지어 OpenAI SDK로 개발했는데 갑자기 Claude로 갈아타야 한다면? 클라이언트 코드를 전부 수정해야 합니다.

여기서 등장하는 개념이 LLM 게이트웨이(LLM Gateway) 또는 AI 게이트웨이 패턴이에요. 클라이언트는 단 하나의 안정적인 엔드포인트로 요청을 보내고, 게이트웨이가 내부적으로 적절한 모델로 라우팅해주는 구조입니다. 오픈소스 프록시(LiteLLM, Portkey 등)를 직접 띄워 운영하는 방법도 있지만, 서버리스 인그레스 레이어로 이걸 처리할 수 있다면 운영 부담이 확 줄어들죠.

Google Cloud API Gateway가 바로 이 지점을 노리고 모델 라우팅(Model Routing) 기능을 Public Preview로 공개했어요. OpenAI 호환 요청을 받아서 Gemini, Claude, OpenAI OSS-GPT 같은 백엔드로 동적으로 라우팅해줍니다. 이 글에서는 실제 OpenAPI 스펙 작성부터 curl 테스트까지 한 번에 따라할 수 있게 정리해볼게요.

근거자료: Google Developers Blog - A unified API for AI model routing

Cloud API gateway architecture diagram routing LLM traffic to multiple AI models IT Technology Image

핵심: OpenAPI 스펙에 라우터 정의하기

API Gateway의 모델 라우팅은 OpenAPI 3.x 스펙 안에 x-google-api-management 확장 블록으로 정의해요. 백엔드(모델별 실제 주소)와 라우터(어떤 요청을 어디로 보낼지)를 분리해서 선언하는 구조입니다.

1) 백엔드 정의

먼저 각 모델의 실제 엔드포인트를 backends에 나열해요. pathTranslation: CONSTANT_ADDRESS를 쓰면 고정 주소로 요청을 보낼 수 있어요.

openapi: 3.0.4
info:
  title: OpenAPI 3.x spec using Model Routing
  version: 1.0.0
x-google-api-management:
  backends:
    gemini-35-flashlite:
      address: >-
        https://aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash-lite:generateContent
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS
    anthropic-claude-opus-47:
      address: >-
        https://aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/global/publishers/anthropic/models/claude-opus-4-7:rawPredict
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS
    openai-gpt-oss-120b:
      address: >-
        https://aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/global/endpoints/openapi/chat/completions
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS

2) 라우터 정의

라우터는 기본 모델(defaultModel) 과 규칙(rules) 으로 구성돼요. 요청 body의 model 필드 값을 보고 어떤 백엔드로 보낼지 결정합니다.

  ai:
    models:
      routing:
        routers:
          # 라우터 1: 기본은 Gemini, model=claude-opus-4-7 이면 Claude로
          gemini-claude-router:
            defaultModel:
              backend: gemini-35-flashlite
              targetModel: google/gemini-3.5-flash-lite
            rules:
              - model: "claude-opus-4-7"
                backend: anthropic-claude-opus-47
                targetModel: anthropic/claude-opus-4-7
          # 라우터 2: 기본은 OpenAI GPT, model=gemini-3.5-flash-lite 이면 Gemini로
          openai-gemini-router:
            defaultModel:
              backend: openai-gpt-oss-120b
              targetModel: openai/gpt-oss-120b-maas
            rules:
              - model: "gemini-3.5-flash-lite"
                backend: gemini-35-flashlite
                targetModel: google/gemini-3.5-flash-lite

3) 경로에 라우터 연결

각 path의 POST 오퍼레이션에 x-google-model-router 확장으로 라우터를 지정해요. 클라이언트 입장에서는 그냥 OpenAI 스타일의 /v1/chat/... 엔드포인트로 보입니다.

servers:
  - url: "https://my-gateway.example.com"
paths:
  /v1/chat/gemini-claude:
    post:
      summary: "기본 Gemini, Claude 옵션"
      operationId: "chatGeminiClaude"
      x-google-model-router: gemini-claude-router
      responses:
        '200':
          description: "OK"
  /v1/chat/openai-gemini:
    post:
      summary: "기본 OpenAI, Gemini 옵션"
      operationId: "chatOpenAIGemini"
      x-google-model-router: openai-gemini-router
      responses:
        '200':
          description: "OK"

4) 배포 후 curl로 테스트

게이트웨이를 배포한 뒤에는 클라이언트 코드를 거의 안 바꾸고 그대로 호출할 수 있어요. 게이트웨이가 payload를 백엔드의 네이티브 스키마로 트랜스코딩하고, Agent Platform 인증 토큰을 자동으로 붙여줍니다.

curl -X POST "https://my-gateway.example.com/v1/chat/gemini-claude" \
  -H "content-type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{
    "model": "claude-opus-4-7",
    "messages": [
      {"role": "user", "content": "Introduce yourself in 5 words"}
    ]
  }'

model 필드에 claude-opus-4-7을 넣으면 라우터 규칙에 따라 Claude 백엔드로, 아무 값이나 넣거나 생략하면 기본 Gemini로 갑니다. 이게 핵심이에요. 클라이언트는 여전히 OpenAI 스키마로 요청하고 있지만, 뒤에서는 Claude가 응답하고 있는 거죠.

Serverless API Gateway endpoint processing OpenAI-compatible chat completion requests Developer Related Image

주의사항과 실무 함정

기능 자체는 매력적이지만, 도입 전에 반드시 짚고 넘어가야 할 부분이 있어요.

1) 단일 라우터는 단일 호스트만 지원

공식 문서에 명시된 중요한 제약이 있어요. 하나의 라우터가 참조하는 모든 백엔드는 같은 호스트를 공유해야 합니다. 예를 들어 aiplatform.googleapis.com 하나로 묶여 있어야 하고, 다른 호스트(예: 외부 OpenAI API)로 크로스 라우팅하는 건 안 됩니다. Vertex AI를 통해 Claude와 GPT-OSS를 쓰는 구조라서 가능한 설계예요.

2) 인증 분리의 이점을 활용하라

가장 큰 실무 이득은 클라이언트 인증과 백엔드 LLM 인증의 분리예요. 애플리케이션은 게이트웨이에만 인증하면 되고, 백엔드 자격증명은 게이트웨이가 관리합니다. 모델 제공자를 바꾸거나 키를 로테이션해도 앱 코드는 건드릴 필요가 없죠. 이건 운영 관점에서 꽤 큰 차이를 만들어요.

3) Agent Gateway와의 역할 구분

Google Cloud의 AI 게이트웨이 스펙트럼은 세 층으로 나뉩니다.

  • Apigee: 본격적인 API 관리가 필요할 때
  • Agent Gateway: 에이전트 이그레스에 대한 보안 거버넌스가 필요할 때
  • API Gateway (모델 라우팅): 가볍게 시작해서 규칙 기반 라우팅, 레이트 리밋, 토큰 트래킹만 필요할 때

실무에서는 Agent Gateway로 보안 거버넌스를 걸고, 그 뒤에서 API Gateway가 동적 라우팅을 담당하는 조합이 자연스러워요. 처음부터 Apigee까지 갈 필요는 없습니다.

4) Public Preview라는 점

아직 Public Preview 단계예요. SLA나 기능 변경 가능성을 감안하고, 프로덕션 크리티컬 패스에 바로 넣기보다는 파일럿으로 검증하는 걸 권해요. 특히 라우팅 규칙이 복잡해질수록 디버깅 난이도가 올라가니 로그와 토큰 트래킹을 처음부터 켜두는 게 좋습니다.

에이전트 보안 거버넌스 쪽을 더 깊게 보고 싶다면 NVIDIA가 공개한 제로 트러스트 런타임 정리도 함께 보시면 그림이 잡힐 거예요.

AI chatbot terminal sending request through unified LLM gateway to Gemini and Claude

정리: 언제 써야 하고, 다음엔 뭘 봐야 하나

Google Cloud API Gateway의 모델 라우팅은 "여러 LLM을 하나의 OpenAI 호환 엔드포인트로 묶고 싶다" 는 요구에 딱 맞는 서버리스 솔루션이에요. 오픈소스 프록시를 직접 운영하는 부담 없이, OpenAPI 스펙에 라우터만 선언하면 끝납니다.

실무 적용 체크리스트

  1. 백엔드 모델들이 모두 같은 호스트(aiplatform.googleapis.com) 에 있는지 확인
  2. 클라이언트는 게이트웨이에만 인증하도록 설계
  3. 라우팅 규칙은 최소한으로 시작하고, 필요할 때 확장
  4. 토큰 트래킹과 레이트 리밋을 처음부터 켜서 비용 가시성 확보

다음 단계 학습 방향

  • Agent Gateway 문서를 읽고 에이전트 이그레스 거버넌스 패턴 익히기
  • Apigee와의 차이를 비교해서 조직 규모에 맞는 선택 기준 세우기
  • OpenAI 호환 스키마와 각 백엔드 네이티브 스키마의 차이(특히 tool calling, streaming) 확인

에이전트 커머스 표준이 궁금하다면 UCP(Universal Commerce Protocol) 완벽 가이드도 함께 보면, AI 에이전트가 실제로 트랜잭션을 처리하는 흐름까지 연결해서 이해할 수 있어요. 삽질 없이 바로 적용해보시길!

본 콘텐츠는 신뢰할 수 있는 출처를 바탕으로 AI 도구를 활용하여 초안이 작성되었으며, 편집자의 검토를 거쳐 발행되었습니다. 전문가의 조언을 대체하지 않습니다.