Gemini CLI

이 튜토리얼은 Gemini CLI를 LiteLLM Proxy와 통합하여 요청을 LiteLLM의 통합 인터페이스를 통해 라우팅하는 방법을 보여줍니다. 이 통합은 LiteLLM v1.73.3-nightly 이상에서 지원됩니다.

출처: 문서

본문

gemini-cli를 LiteLLM과 함께 사용하는 이점

gemini-cli를 LiteLLM과 함께 사용하면 다음과 같은 이점이 있어요:

개발자 이점:

범용 모델 접근: gemini-cli 인터페이스를 통해 LiteLLM이 지원하는 모든 모델(Anthropic, OpenAI, Vertex AI, Bedrock 등)을 사용할 수 있어요.
더 높은 Rate Limit과 신뢰성: 여러 모델과 제공자에 걸쳐 로드 밸런싱하여 개별 제공자 한도에 부딪히는 것을 피하고, 한 제공자가 실패해도 응답을 받도록 fallback을 보장해요.

Proxy 관리자 이점:

중앙 집중식 관리: 각 제공자에 개발자에게 API 키를 주지 않고 단일 LiteLLM proxy 인스턴스를 통해 모든 모델 접근을 통제할 수 있어요.
예산 컨트롤: 모든 gemini-cli 사용량에 걸쳐 비용 상한을 설정하고 비용을 추적할 수 있어요.

전제 조건

시작하기 전에 다음이 필요합니다:

Node.js와 npm 설치
실행 중인 LiteLLM Proxy 인스턴스
유효한 LiteLLM Proxy API 키
저장소 클론을 위한 Git

빠른 시작 가이드

1단계: Gemini CLI 설치

npm install -g @google/gemini-cli

2단계: LiteLLM Proxy용 Gemini CLI 구성

필요한 환경 변수를 설정하여 Gemini CLI가 여러분의 LiteLLM Proxy 인스턴스를 가리키도록 구성하세요:

export GOOGLE_GEMINI_BASE_URL="http://localhost:4000"export GEMINI_API_KEY=sk-

참고: 값을 실제 LiteLLM Proxy 구성으로 바꾸세요:

BASE_URL: LiteLLM Proxy가 실행 중인 URL
GEMINI_API_KEY: 여러분의 LiteLLM Proxy API 키

3단계: Gemini CLI 빌드 및 시작

gemini

4단계: 통합 테스트

CLI가 실행되면 테스트 요청을 보낼 수 있어요. 요청은 자동으로 LiteLLM Proxy를 통해 구성된 Gemini 모델로 라우팅됩니다.

CLI는 이제 LiteLLM Proxy를 백엔드로 사용하며, 다음과 같은 LiteLLM 기능을 사용할 수 있어요:

요청/응답 로깅
Rate limiting
비용 추적
모델 라우팅과 fallback

고급

gemini-cli에서 Anthropic, OpenAI, Bedrock 등 모델 사용

gemini-cli에서 gemini가 아닌 모델을 사용하려면 LiteLLM Proxy 설정에 model_group_alias를 설정해야 해요. 이는 모델=gemini-3.1-pro-preview인 요청이 어떤 제공자의 원하는 모델로 라우팅되게 LiteLLM에게 알려줍니다.

Anthropic
OpenAI
Bedrock
다중 제공자 로드 밸런싱

gemini-3.1-pro-preview 요청을 Claude Sonnet으로 라우팅:proxy_config.yaml

model_list:
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEYrouter_settings:
  model_group_alias: {"gemini-3.1-pro-preview": "claude-sonnet-5"}

gemini-3.1-pro-preview 요청을 gpt-5.6-terra로 라우팅:proxy_config.yaml

model_list:
  - model_name: openai-gpt
    litellm_params:
      model: gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEYrouter_settings:
  model_group_alias: {"gemini-3.1-pro-preview": "openai-gpt"}

gemini-3.1-pro-preview 요청을 Bedrock의 Claude로 라우팅:proxy_config.yaml

model_list:
  - model_name: bedrock-claude
    litellm_params:
      model: bedrock/us.anthropic.claude-sonnet-5
      aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
      aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
      aws_region_name: us-east-1router_settings:
  model_group_alias: {"gemini-3.1-pro-preview": "bedrock-claude"}

model_name=anthropic-claude인 모든 배포는 로드 밸런싱됩니다. 이 예시에서는 Anthropic과 Bedrock 사이에서 로드 밸런싱해요.proxy_config.yaml

model_list:
  - model_name: anthropic-claude
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: anthropic-claude
    litellm_params:
      model: bedrock/us.anthropic.claude-sonnet-5
      aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
      aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
      aws_region_name: us-east-1router_settings:
  model_group_alias: {"gemini-3.1-pro-preview": "anthropic-claude"}

이 구성으로 CLI에서 gemini-3.1-pro-preview를 사용하면 LiteLLM이 요청을 구성한 제공자(들)로 자동 라우팅하며 로드 밸런싱과 fallback이 적용됩니다.

트러블슈팅

문제가 발생하면:

연결 오류: LiteLLM Proxy가 구성된 GOOGLE_GEMINI_BASE_URL에서 실행 중이고 접근 가능한지 확인하세요.
인증 오류: GEMINI_API_KEY가 유효하고 필요한 권한이 있는지 확인하세요.
빌드 실패: npm install로 모든 의존성이 설치됐는지 확인하세요.

더 알아보기 (Learn more)

Google GenAI SDK with LiteLLM