Gemini 4 Argon 개발자 가이드

Gemini 4 Argon 은 코딩, 금융, 법률, 사이버 보안, 과학 등 여러 분야에서 복잡한 실제 작업에 대한 심층 작업을 수행하는 데 탁월한 Google의 프런티어 모델입니다. Gemini 4 제품군의 첫 번째 모델입니다.

이 문서에서는 4 Argon의 새로운 기능, 적용되는 API 규칙, 마이그레이션 방법, 빠른 시작을 다룹니다. Gemini 4 제품군에 대한 개요는 Gemini 4 시작하기를 참고하세요.

Gemini 4 Argon의 새로운 기능

  • 컨텍스트 윈도우: 1,048,576 토큰 컨텍스트 윈도우는 입력, 생각, 출력 토큰 간에 공유됩니다.
  • 최대 1,048,576개의 토큰을 길게 디코딩: 단일 요청 출력 한도 (스트리밍 요청의 경우 65,536개 토큰 또는 비스트리밍 직접 HTTP 요청의 경우 32,768개 토큰)를 넘어 `GenerateContent`에서 생성 범위를 최대 1,048,576개 토큰까지 확장합니다. GenerateContent Google 생성형 AI SDK는 요청 간에 continuation_token을 자동으로 처리하거나 자체 연속 루프에서 continuation_token을 관리할 수 있습니다.
  • 생각 수준: LOW, MEDIUM (gemini-4-argon의 기본값), HIGH (gemini-4-argon-cyber-permissive의 기본값)
  • 지속적 캐싱을 사용한 암시적 캐싱: 암시적 캐싱은 기본적으로 지속적 캐싱이 사용 설정된 상태에서 6,144개 이상의 토큰의 공유 프롬프트 접두사에 자동으로 적용됩니다. 명시적 컨텍스트 캐싱은 지원되지 않습니다.
  • 에이전트형 동영상 이해: 정식 버전이며 기본적으로 사용 중지되어 있습니다.

빠른 시작

시작하기 전에 애플리케이션 기본 사용자 인증 정보 (ADC) 또는 API 키를 사용하여 Agent Platform에 인증해야 합니다. 자세한 내용은 Get started with Gemini Enterprise Agent Platform 시작하기를 참고하세요.

다음 코드 블록에서 PROJECT_ID 를 프로젝트 ID로 바꿉니다.

설치

최신 Google 생성형 AI SDK (google-genai >= 2.30.1 for Python, @google/genai >= 2.29.1 for JavaScript, >= 1.74.0 for Go, >= 1.77.0 for Java, >= 1.26.0 for .NET, 또는 >= 1.6.0 for Kotlin)로 업그레이드합니다.

pip install --upgrade "google-genai>=2.30.1"

기본 요청

Python (GenerateContent)

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
  model="gemini-4-argon",
  contents="How does AI work?",
)
print(response.text)

Python (Interactions API)

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

turn1 = client.interactions.create(
    model="gemini-4-argon",
    input="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
    store=True,
)
print(turn1.output_text)

turn2 = client.interactions.create(
    model="gemini-4-argon",
    input="Add a bounded backpressure policy and unit tests for concurrent writers.",
    previous_interaction_id=turn1.id,
)
print(turn2.output_text)

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-argon:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" }
  }
}'

구조화된 출력

from pydantic import BaseModel, Field
from google import genai
from google.genai import types

class ArchitectureReview(BaseModel):
    component: str = Field(description="Service or module name")
    bottlenecks: list[str] = Field(description="Throughput or latency bottlenecks")
    recommended_changes: list[str] = Field(description="Concrete refactoring steps")

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
    model="gemini-4-argon",
    contents="Review a synchronous order-processing pipeline backed by a single primary database at 15,000 writes/sec.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=ArchitectureReview,
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
    ),
)
print(response.text)

길게 디코딩

기본적으로 단일 API 요청은 최대 65,536개의 생각 및 출력 토큰 (또는 비스트리밍 직접 HTTP 요청의 경우 32,768개 토큰)을 생성합니다. GenerateContent (v1beta1)에서 최대 1,048,576개의 토큰을 완료하려면 max_output_tokens를 65,536보다 크게 (최대 1,048,576) 설정합니다. Google 생성형 AI SDK는 finish_reason이 CONTINUATION일 때 요청 간에 continuation_token을 자동으로 따르거나 (GenerateContentConfig에서 automatic_continuation=False를 설정하여 자동 연속을 사용 중지) 맞춤 루프에서 continuation_token을 전달할 수 있습니다.

Python (SDK - 권장)

from google import genai
from google.genai import types

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

# Automatic continuation is enabled by default in google-genai >= 2.30.1.
# Chunks across all continuation requests are yielded as a single stream.
for chunk in client.models.generate_content_stream(
    model="gemini-4-argon",
    contents="Write a complete formal proof of the prime number theorem.",
    config=types.GenerateContentConfig(
        max_output_tokens=256000,
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
    ),
):
    print(chunk.text, end="")

# Set automatic_continuation=False to disable automatic continuation
# and stop at a single request.
single_request_response = client.models.generate_content(
    model="gemini-4-argon",
    contents="Write a complete formal proof of the prime number theorem.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
        automatic_continuation=False,
    ),
)
print(single_request_response.text)

REST (맞춤 연속 루프)

# Request 1: Initial request with maxOutputTokens > 32,768
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-argon:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
    }],
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

# Request 2: Resend the original request with top-level continuationToken
# from Request 1 (candidates[0].continuationToken)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-argon:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
    }],
    "continuationToken": "CONTINUATION_TOKEN_FROM_REQUEST_1",
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

필수 API 규칙 및 동작 규칙

Gemini 4 Argon은 다음 규칙을 적용합니다.

  • 컨텍스트 윈도우 및 단일 요청 출력 한도:
    • 1,048,576 토큰 컨텍스트 윈도우는 입력, 생각, 출력 토큰 간에 공유됩니다. max_output_tokens를 1,048,576보다 크게 설정하면 HTTP 400 오류가 반환됩니다.
    • 의도하지 않은 긴 완료를 방지하기 위해 기본 단일 요청 출력 한도 (생각 + 모델 응답)는 65,536개 토큰 (또는 비스트리밍 직접 HTTP 요청의 경우 32,768개 토큰)입니다.

  • 길게 디코딩:

    • 길게 디코딩 작동 방식: 길게 디코딩은 최대 1,048,576개의 토큰을 여러 GenerateContent 추론으로 분할합니다. 요청이 완료되기 전에 요청당 출력 한도에 도달하면 API는 finish_reason=CONTINUATION과 원래 프롬프트의 해시 및 해당 시점까지의 생성 상태가 포함된 암호화된 continuation_token을 반환합니다. continuation_token이 더 이상 생성되지 않고 finish_reason=STOP이 될 때까지 원래 프롬프트가 포함된 후속 요청에 continuation_token을 포함합니다. (Agent Studio에서 출력 토큰 한도를 65,536에서 최대 1,048,576으로 설정하면 연속 토큰이 자동으로 처리됩니다.)
    • 길게 디코딩을 사용하는 경우: 대부분의 요청은 요청당 한도 (65,536개 토큰 또는 비스트리밍 REST 호출의 경우 32,768개 토큰) 내에서 완료됩니다. 길게 디코딩을 사용하면 모델이 더 많은 공간에서 추론할 수 있습니다. 답변이 길어지지는 않습니다 (thinking_level을 사용하여 추론 깊이를 제어).
    워크로드 길게 디코딩을 사용하시겠습니까? 이유
    어려운 수학, 과학, 연구, 공식 증명 예 모델은 65,536개 이상의 토큰을 사용하여 추론을 탐색하고 확인할 수 있습니다.
    가장 어려운 코딩 및 에이전트형 작업 예 일부 작업에는 하나의 응답에 65,536개 이상의 생각 및 코드가 필요합니다. 대부분의 코딩 및 에이전트형 작업은 65,536개 미만의 토큰으로 완료됩니다.
    출력 한도에서 중지되는 평가 하네스 예 길게 디코딩을 사용하면 모델이 생각에 전체 65,536개 또는 32,768개 토큰 요청을 사용하는 경우 답변이 잘리는 것을 방지할 수 있습니다.
    채팅, Q&A, 요약, 분류, 추출 아니요 이러한 작업은 32,768개 미만의 토큰으로 완료됩니다.
    '700,000단어 책 쓰기'와 같이 고정된 길이의 요청 아니요 모델은 길이 목표를 따르지 않습니다.
    짧은 턴으로 도구를 여러 번 호출하는 에이전트 아니요 각 턴은 짧습니다. 각 턴의 큰 출력은 공유된 1,048,576개 토큰 입력 및 출력 윈도우를 빠르게 채웁니다.
    1,048,576개 토큰 입력 한도에 가까운 프롬프트 아니요 출력은 1,048,576개 토큰에서 입력을 뺀 토큰만 사용할 수 있습니다.
    지연 시간에 민감한 요청 아니요 길게 디코딩은 몇 분 동안 실행될 수 있습니다.
    • 연속 옵션 선택: 모든 옵션은 동일한 1,048,576개 토큰 한도에 도달합니다. gemini-4-argon 및 gemini-4-argon-cyber-permissive
    측정기준 옵션 1: Google 생성형 AI SDK (권장) 옵션 2: 자체 스트리밍 루프 (streamGenerateContent) 옵션 2: 자체 비스트리밍 루프 (generateContent)
    각 세그먼트를 시작하는 사용자 SDK (automatic_continuation=True 기본값) 65,536개 이상의 토큰의 출력에 대해 max_output_tokens를 65,536보다 크게 (최대 1,048,576) 설정합니다. 각 체크포인트 또는 삭제된 스트림 후의 코드 32,768개 토큰마다 코드
    요청당 토큰 세그먼트당 최대 65,536개 스트림당 65,536개 요청당 32,768개
    요청당 시간 제한 20분 20분 20분
    저장용량 및 ZDR 서버 저장용량 없음 (ZDR 호환) 서버 저장용량 없음 (ZDR 호환) 서버 저장용량 없음 (ZDR 호환)
    용도 대부분의 애플리케이션 스트리밍하는 REST 호출자 및 맞춤 하네스 간단한 평가 하네스
    • 구현 규칙 및 제한사항:
      • v1beta1 API 요구사항 (알려진 문제): GenerateContent (generateContent 및 streamGenerateContent)의 길게 디코딩 (continuation_token)은 v1beta1 API에서만 지원됩니다 (v1은 지원되지 않음). Google 생성형 AI SDK는 http_options에서 api_version='v1'이 지정되지 않는 한 기본적으로 v1beta1을 사용합니다. 직접 REST 호출의 경우 v1beta1 엔드포인트 경로를 사용합니다. 길게 디코딩은 Interactions API에서 지원되지 않습니다.
      • SDK 버전 및 OpenAI 호환성: 최신 Google 생성형 AI SDK(google-genai >= 2.30.1(Python), @google/genai >= 2.29.1(JavaScript), >= 1.74.0(Go), >= 1.77.0(Java), >= 1.26.0(.NET) 또는 >= 1.6.0( Kotlin))로 업그레이드합니다. 이전 SDK 버전과 OpenAI 호환성 레이어는 연속 토큰을 사용하여 긴 완료를 가져올 수 없습니다. 맞춤 클라이언트 구현은 Google 생성형 AI SDK 참조 구현을 참고하세요.
      • continuation_token으로 원래 요청 다시 전송: 맞춤 루프에서 max_output_tokens를 65,536 (스트리밍) 또는 32,768 (단항)에서 최대 1,048,576으로 설정하고 모든 연속 요청에서 최신 continuation_token (REST의 GenerateContentRequest 또는 Google 생성형 AI SDK의 GenerateContentConfig의 최상위 필드)과 함께 원래 contents, system_instruction, tools를 다시 전송합니다. 부분 모델 출력을 contents에 추가하거나 모델에 계속하도록 요청하는 후속 프롬프트를 보내지 마세요.
      • 생각 전용 요청을 통해 계속: finish_reason이(가) CONTINUATION이고 continuation_token이(가) 있는 동안 루프합니다. 요청이 32,768개 또는 65,536개 토큰을 모두 생각에 사용한 경우에도(parts: [{"text": ""}]) 마찬가지입니다. continuation_token이(가) 있는 경우 finish_reason이(가) MAX_TOKENS이면 생성이 요청된 max_output_tokens 한도에 도달한 것입니다. 요청에서 max_output_tokens를 올립니다. STOP 후에만 누적된 부분을 멀티턴 기록의 단일 model 턴으로 결합합니다.
      • 토큰 집계, 압축, 95% 암시적 캐시 할인:
        • Python Google 생성형 AI SDK (generate_content 및 generate_content_stream)에서 최종 응답 또는 청크의 usage_metadata는 연속 요청에서 청구된 총 토큰을 누적합니다. 각 연속 요청은 이전 부분 완료를 입력 토큰으로 다시 채우므로 prompt_token_count는 연속 요청에서 누적적으로 증가합니다. 에이전트 하네스에서 컨텍스트 압축을 트리거하는 데 prompt_token_count를 사용하지 마세요. 대신 initial_prompt_token_count (GenerateContentResponse 또는 usage_metadata)를 읽고 GenerateContent이 완료될 때까지( continuation_token 없음) 기다린 후 압축합니다.
        • 맞춤 REST 루프에서 usage_metadata는 각 요청 내에서 누적됩니다. 요청 간에 최종 prompt_token_count, cached_content_token_count, candidates_token_count, thoughts_token_count를 합산합니다.
        • 각 연속 요청은 프롬프트와 이전 디코딩된 토큰을 다시 채우고 요청이 15~20분 캐시 TTL 내에서 연속으로 실행될 때 95% 암시적 컨텍스트 캐싱 할인 (최소 6,144개 토큰)을 자동으로 받습니다.
        • streamGenerateContent 및 generateContent는 각 요청 (65,536 스트리밍 / 32,768 단항)의 끝에 continuation_token 및 usage_metadata를 반환하며 청구는 요청이 끝날 때 발생합니다.

  • 무시된 샘플링 매개변수 (temperature, top_k, top_p): 백엔드는 맞춤 값을 무시합니다. thinking_level로 추론 깊이를 제어하고 response_schema로 출력 형식을 제어합니다.

  • 지원되지 않는 매개변수 (frequency_penalty, presence_penalty, candidate_count): 이러한 매개변수는 HTTP 400 오류를 반환합니다. 요청에서 삭제하세요.

  • 컨텍스트 캐싱: 명시적 컨텍스트 캐싱은 지원되지 않습니다. 암시적 캐싱 (기본적으로 지속적 캐싱이 사용 설정됨)은 6,144개 이상의 토큰의 공유 프롬프트 접두사에 자동으로 적용되므로 프롬프트 시작 부분에 정적 콘텐츠를 배치합니다.

  • 에이전트형 동영상: 업로드된 동영상은 기본적으로 media_processing="static"입니다. media_processing="agentic"을 설정하여 에이전트형 동영상 처리를 사용 설정합니다.

  • 토큰 집계 및 청구: 모델이 처리하는 모든 토큰은 집계되고 청구됩니다. 여기에는 그라운딩을 사용할 때 사고 토큰과 내부 도구 시스템 안내 및 함수 선언이 포함됩니다. Google 검색을 사용한 그라운딩도 쿼리당 청구됩니다.

  • 함수 호출:

    • 턴 대칭: 각 FunctionResponse는 이전 FunctionCall의 id, name, 순서와 일치해야 합니다.
    • 순차적 실행: 다단계 도구 루프에서 순차적 도구 실행 턴을 선호합니다.
    • 사전 도구 형식 지정: 인라인 안내를 \n\n으로 구분하고 도구 호출 전에 구조화되지 않은 텍스트를 피합니다.

  • 채팅 시퀀스 유효성 검사:

    • 기록 페이로드는 model 역할 턴으로 끝날 수 없습니다.
    • 미리 채워진 모델 턴은 지원되지 않습니다.

3.1 Pro에서 4 Argon으로 마이그레이션

다음 동작은 gemini-3.1-pro-preview와 다릅니다.

  • 컨텍스트 윈도우는 별도의 입력 및 출력 한도가 아닌 입력, 생각, 출력에서 공유하는 1,048,576개 토큰 윈도우입니다. 단일 요청 출력은 65,536개 토큰 (또는 비스트리밍 직접 HTTP 요청의 경우 32,768개 토큰)으로 제한되며 GenerateContent에서 길게 디코딩을 사용하여 최대 1,048,576개 토큰까지 확장할 수 있습니다 (Google 생성형 AI SDK에서 자동으로 처리하거나 맞춤 루프에서 continuation_token 사용).
  • thinking_budget 은 생각 수준에 매핑되는 대신 HTTP 400 오류를 반환합니다. MINIMAL도 오류를 반환합니다.
  • 명시적 컨텍스트 캐싱은 지원되지 않습니다.
  • 모델이 처리하는 모든 토큰은 청구됩니다. 여기에는 그라운딩을 사용할 때 내부 도구 시스템 안내 및 함수 선언이 포함됩니다.

나란히 비교하려면 Gemini 3.1 Pro에서 마이그레이션을 참고하세요.

gemini-3.1-pro-preview에서 마이그레이션하려면 다음 단계를 따르세요.

  1. 모델 ID를 gemini-4-argon (또는 Fairwind 승인 사이버 보안 워크로드의 경우 gemini-4-argon-cyber-permissive)로 업데이트합니다.
  2. 최신 Google 생성형 AI SDK로 업그레이드하고 공유 컨텍스트 윈도우를 고려합니다. google-genai >= 2.30.1 (Python) 또는 이와 동등한 최신 Google 생성형 AI SDK로 업그레이드합니다. 입력, 생각, 출력 토큰은 1,048,576개 토큰 컨텍스트 윈도우를 공유합니다. GenerateContent에서 65,536개 이상의 토큰(최대 1,048,576개 토큰)의 출력에 대해 max_output_tokens를 65,536보다 크게 설정하여 Google 생성형 AI SDK가 요청 간에 자동으로 계속되도록 하거나 자체 REST 루프에서 continuation_token을 처리합니다.
  3. 추론 예산 매개변수 바꾸기: thinking_budget 및 MINIMAL을 다음 값 중 하나로 설정된 thinking_level로 바꿉니다.
    • HIGH: gemini-4-argon-cyber-permissive의 기본값. 다중 파일 소프트웨어 엔지니어링, 공식 증명, 아키텍처 설계, 취약점 발견
    • MEDIUM: gemini-4-argon의 기본값. 일반 코딩, 도구 사용, 문서 Q&A, 동영상 이해
    • LOW: 분류, 요약, 메타데이터 추출
  4. 명시적 캐싱을 삭제 하고 자동 암시적 캐싱을 위해 정적 프롬프트 콘텐츠 (6,144개 이상의 토큰)를 미리 로드합니다.
  5. 효과가 없거나 지원되지 않는 매개변수 삭제:
    • 무시되는 temperature, top_p, top_k를 삭제합니다.
    • candidate_count, frequency_penalty, presence_penalty를 삭제합니다.
    • 대화 기록에서 미리 채워진 모델 턴을 삭제합니다.

개발자를 위한 요약 체크리스트

알려진 문제

  • GenerateContent의 길게 디코딩에는 v1beta1이 필요합니다. GenerateContent API(generateContent 및 streamGenerateContent)의 길게 디코딩 (continuation_token)은 v1beta1 API에서만 지원됩니다 (v1은 지원되지 않음). Google 생성형 AI SDK는 http_options에서 api_version='v1' 이 설정되지 않는 한 기본적으로 v1beta1을 사용합니다. 직접 REST 호출의 경우 v1beta1 엔드포인트 경로를 사용합니다.

추가 리소스