Google Gemini

Google Gemini 모델을 Docker Agent에서 사용하는 방법을 설명해요. Gemini Developer API와 Vertex AI(모델 가든 포함) 방식을 모두 다룬답니다.

출처: 문서

본문

Docker Agent는 이 환경 변수들에서 처음으로 찾은 자격 증명을 읽어요(pkg/model/provider/gemini/client.go 참고):

# Gemini Developer API
export GOOGLE_API_KEY="AI..."   # 또는 GEMINI_API_KEY

# Vertex AI (API 키 없음; Application Default Credentials 사용)
gcloud auth application-default login
export GOOGLE_GENAI_USE_VERTEXAI=1
export GOOGLE_CLOUD_PROJECT="my-gcp-project"
export GOOGLE_CLOUD_LOCATION="us-central1"

구성

인라인

agents:
  root:
    model: google/gemini-3.5-flash

네임드 모델

models:
  gemini:
    provider: google
    model: gemini-3.5-flash
    temperature: 0.5

사용 가능한 모델

모델	용도
`gemini-3-pro`	가장 강력한 Gemini 모델
`gemini-3-flash`	빠르고 효율적, 좋은 균형
`gemini-2.5-flash`	빠른 추론, 비용 효율적
`gemini-2.5-pro`	강력한 추론, 대형 컨텍스트

Thinking 예산

Gemini는 모델 버전에 따라 두 가지 방식을 지원해요:

경고 thinking 형식이 달라요 Gemini 2.5는 토큰 기반 예산(정수)을 사용해요. Gemini 3는 레벨 기반 예산(low, high 같은 문자열)을 사용해요. 모델 버전에 맞는 형식을 꼭 사용하세요.

Gemini 2.5 (토큰 기반)

models:
  gemini-no-thinking:
    provider: google
    model: gemini-2.5-flash
    thinking_budget: 0 # thinking 비활성화

  gemini-dynamic:
    provider: google
    model: gemini-2.5-flash
    thinking_budget: -1 # 동적 (모델이 결정) — 기본값

  gemini-fixed:
    provider: google
    model: gemini-2.5-flash
    thinking_budget: 8192 # 고정 토큰 예산

Gemini 3 (레벨 기반)

models:
  gemini-3-pro:
    provider: google
    model: gemini-3-pro
    thinking_budget: high # Pro 기본값: low | high

  gemini-3-flash:
    provider: google
    model: gemini-3-flash
    thinking_budget: medium # Flash 기본값: minimal | low | medium | high

내장 도구 (Grounding)

Gemini 모델은 생성 중에 Google Search와 Google Maps에 직접 접근할 수 있게 해주는 내장 도구를 지원해요. provider_opts로 활성화하세요:

models:
  gemini-grounded:
    provider: google
    model: gemini-2.5-flash
    provider_opts:
      google_search: true
      google_maps: true
      code_execution: true

옵션	설명
`google_search`	최신 정보를 위한 Google Search grounding 활성화
`google_maps`	위치 질의를 위한 Google Maps grounding 활성화
`code_execution`	계산을 위한 서버 측 코드 실행 활성화

Vertex AI Model Garden

Google Cloud의 Vertex AI Model Garden에 호스팅된 Gemini가 아닌 모델(예: Claude, Llama)도 google 프로바이더를 통해 사용할 수 있어요. provider_opts에 publisher를 지정하면 요청이 Gemini SDK 대신 적절한 Vertex AI 엔드포인트로 라우팅돼요:

Anthropic Claude(publisher: anthropic)는 Anthropic 네이티브 :rawPredict / :streamRawPredict 엔드포인트를 사용해요. Vertex AI의 Claude 모델은 OpenAI /chat/completions 경로를 지원하지 않아요.
다른 publisher(예: meta, mistral)는 Vertex AI의 OpenAI 호환 /chat/completions 엔드포인트를 사용해요.

인증

Vertex AI는 Google Cloud Application Default Credentials(ADC)를 사용해요. 인증이 되어 있는지 확인하세요:

gcloud auth application-default login

구성

models:
  claude-on-vertex:
    provider: google
    model: claude-sonnet-4-20250514
    provider_opts:
      project: my-gcp-project       # GCP 프로젝트 ID (또는 GOOGLE_CLOUD_PROJECT 설정)
      location: us-east5             # GCP 리전 (또는 GOOGLE_CLOUD_LOCATION 설정)
      publisher: anthropic           # 모델 publisher (anthropic, meta 등)

옵션	설명
`project`	GCP 프로젝트 ID. `GOOGLE_CLOUD_PROJECT` 환경 변수로 폴백
`location`	GCP 리전(예: `us-east5`, `us-central1`). `GOOGLE_CLOUD_LOCATION`으로 폴백
`publisher`	모델 publisher(예: `anthropic`, `meta`, `mistral`). `google`이면 안 됨

참고 Vertex AI의 Gemini 모델 publisher: google을 설정하거나(또는 생략) 네이티브 Gemini SDK 경로를 사용해요. Model Garden 엔드포인트는 Google이 아닌 publisher에만 사용돼요.

더 알아보기 (Learn more)

Model Providers 개요에서 다른 프로바이더 살펴보기
Provider 정의 문서에서 커스텀 프로바이더 설정 자세히 보기