Gemini 4 Hydrogen 개발자 가이드

Gemini 4 Hydrogen은 일상적인 코딩 및 에이전트형 엔터프라이즈 워크플로에 최첨단 인텔리전스를 빠르고 효율적으로 제공합니다.

이 문서에서는 Hydrogen의 주요 기능, Hydrogen이 적용하는 API 규칙, Gemini 3.8 Flash 및 이전 Gemini 3 Flash 모델에서 Hydrogen으로 마이그레이션하는 방법, 빠른 시작을 다룹니다. Gemini 4 제품군에 대한 개요는 Gemini 4 시작하기를 참조하세요.

Gemini 4 Hydrogen의 주요 기능

Gemini 4 Hydrogen에는 다음 기능이 포함됩니다.

  • 통합 입력 및 출력 토큰 한도: Hydrogen에는 입력 및 출력 토큰을 모두 포함하는 통합 1,048,576 토큰 한도가 있습니다(출력에는 사고, 함수 호출, 최종 대답이 포함됨).
  • 최대 1,048,576개 토큰의 긴 디코딩: Hydrogen은 Interactions API와 GenerateContent(v1beta1) 모두에서 단일 65,536개 토큰 포그라운드 세그먼트(스트리밍 또는 비스트리밍)를 넘어 최대 1,048,576개 토큰(입력 토큰 제외)까지 생성을 확장합니다. Google 생성형 AI SDK는 세그먼트 전반에서 continuation_token를 자동으로 처리합니다. 또는 비동기 서버 관리형 백그라운드 디코딩(background=true)을 실행하거나 커스텀 연속 루프에서 continuation_token를 관리할 수 있습니다.
  • 사고 수준: Hydrogen은 LOW, MEDIUM, HIGH(기본값), XHIGH를 지원합니다.
  • 지속적 캐싱을 사용한 암시적 캐싱: 암시적 캐싱은 4,096개 이상의 토큰으로 구성된 공유 프롬프트 프리픽스에 자동으로 적용되며, 지속적 캐싱은 기본적으로 사용 설정됩니다. 명시적 컨텍스트 캐싱은 지원되지 않습니다.
  • Office 및 OpenDocument 파일 입력: Hydrogen은 PDF 및 일반 텍스트 외에도 Microsoft Office(.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) 및 OpenDocument(.odt, .odp, .ods) 파일을 인라인으로 또는 Cloud Storage에서 GenerateContent 및 Interactions API(멀티모달 FunctionResponse 부분 포함)를 통해 허용합니다.
  • 에이전트형 동영상 이해: 에이전트형 동영상 이해는 정식 버전으로 제공되며 기본적으로 사용 중지되어 있습니다.
  • 단기 출시 수명 주기: Hydrogen은 최소 45일의 사용 중단 알림 정책이 적용되는 단기 정식 버전(GA) 출시입니다. 수명 주기 세부정보는 모델 버전 및 수명 주기를 참조하세요.

빠른 시작

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

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

Agent Studio에서 사용해 보기

Agent Studio UI에서 프롬프트를 테스트하고 gemini-4-hydrogen를 구성하려면 다음을 수행합니다.

  1. Google Cloud 프로젝트에서 Agent Studio를 열고 Gemini 그룹에서 gemini-4-hydrogen를 선택합니다.
  2. 모델 설정에서 다음 옵션을 구성합니다.
    • 사고 수준: Low, Medium, High(기본값) 또는 Extra high 중에서 선택합니다.
    • 리전: Global, us 또는 eu을 선택합니다.
    • 출력 토큰 한도: 32,768~1,048,576(1,048,576 기본값) 사이로 설정합니다. Agent Studio는 단일 요청 한도를 초과하는 응답에 대해 연속 토큰을 자동으로 처리합니다.

설치

최신 Google 생성형 AI SDK로 업그레이드합니다. Interactions API에서 자동 연속을 사용하려면 Python의 경우 google-genai >= 2.34.0, JavaScript/TypeScript의 경우 @google/genai >= 2.32.0, Go의 경우 >= 1.77.0, Java의 경우 >= 1.80.0가 필요합니다(GenerateContent에서 자동 연속을 사용하려면 Python의 경우 >= 2.30.1, JavaScript/TypeScript의 경우 >= 2.29.1, Go의 경우 >= 1.74.0, Java의 경우 >= 1.77.0, .NET의 경우 >= 1.26.0, Kotlin의 경우 >= 1.6.0가 필요함).

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

기본 요청

Google 생성형 AI SDK 또는 REST를 사용하여 gemini-4-hydrogen에 요청을 보냅니다.

Python (GenerateContent)

from google import genai
from google.genai import types

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

response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(
            thinking_level="HIGH",  # Default: "HIGH" (Valid: "LOW", "MEDIUM", "HIGH", "XHIGH")
        ),
    ),
)
print(response.text)

Python (Interactions API)

from google import genai

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

# Turn 1: Initial request (stored server-side by default)
turn1 = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
    store=True,
)
print(turn1.output_text)

# Turn 2: Continue the conversation using previous_interaction_id
turn2 = client.interactions.create(
    model="gemini-4-hydrogen",
    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 application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-hydrogen:generateContent" \
-d '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Provide an architectural review of this Go interface."
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "HIGH"
    }
  }
}'

구조화된 출력

스키마를 준수하는 JSON 출력을 생성하려면 response_mime_type 및 response_schema를 구성합니다.

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-hydrogen",
    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개의 출력 토큰(스트리밍 또는 비스트리밍)을 생성하며, 출력에는 사고, 함수 호출, 최종 응답이 포함됩니다. 최대 1,048,576개의 토큰(입력 토큰 제외)까지 대답을 생성하려면 Interactions API 또는 GenerateContent에서 긴 디코딩을 사용하세요. 계속 옵션, 상태 전환, 검증 규칙은 긴 디코딩을 참조하세요.

Interactions API에서 긴 디코딩 사용

google-genai >= 2.34.0(Python), @google/genai >= 2.32.0(JavaScript/TypeScript), Go >= 1.77.0, Java >= 1.80.0에서 interactions.create()는 세그먼트가 status="requires_continuation"를 반환할 때마다 세그먼트 전반에서 continuation_token를 자동으로 따릅니다. 커스텀 저장(store=True) 또는 스테이트리스(Stateless)(store=False) 루프를 실행하기 위해 선택 해제(automatic_continuation=False)할 수도 있습니다.

Python(SDK 자동)

from google import genai

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

# Automatic continuation is enabled by default in google-genai >= 2.34.0.
# Unary calls merge all segments into one Interaction with summed usage.
interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Write a complete formal proof of the prime number theorem.",
    generation_config={
        "max_output_tokens": 256000,
        "thinking_level": "high",
    },
)
print(interaction.output_text)
print(f"Merged segment IDs: {interaction.continuation_ids}")
print(f"Initial input tokens: {interaction.usage.initial_input_tokens}")

# Streaming yields events across all segments in order. Intermediate segments
# emit interaction.completed with status="requires_continuation".
stream = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Write a complete formal proof of the prime number theorem.",
    stream=True,
    generation_config={
        "max_output_tokens": 256000,
        "thinking_level": "high",
    },
)
for event in stream:
    if event.event_type == "step.delta" and getattr(event.delta, "text", None):
        print(event.delta.text, end="", flush=True)
    elif (
        event.event_type == "interaction.completed"
        and event.interaction.status != "requires_continuation"
    ):
        print(f"\nFinal status: {event.interaction.status}")

# Optional: Delete each stored server segment (last segment first) before its 7-day TTL expires.
for segment_id in reversed(interaction.continuation_ids or [interaction.id]):
    client.interactions.delete(id=segment_id)

# Set automatic_continuation=False to return after a single segment.
single_segment = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Write a complete formal proof of the prime number theorem.",
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
    automatic_continuation=False,
)

Python(커스텀 루프)

from google import genai

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

prompt = "Write a complete formal proof of the prime number theorem."

# Stored loop (store=True, default): chain previous_interaction_id + continuation_token
# without resending input.
segment = client.interactions.create(
    model="gemini-4-hydrogen",
    input=prompt,
    store=True,
    generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
    automatic_continuation=False,
)
full_text = segment.output_text or ""

while segment.status == "requires_continuation" and segment.continuation_token:
    segment = client.interactions.create(
        model="gemini-4-hydrogen",
        previous_interaction_id=segment.id,
        continuation_token=segment.continuation_token,
        generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
        automatic_continuation=False,
    )
    full_text += segment.output_text or ""

# If status == "incomplete", max_output_tokens was exhausted; raise max_output_tokens to continue.
if segment.status == "incomplete" and segment.continuation_token:
    segment = client.interactions.create(
        model="gemini-4-hydrogen",
        previous_interaction_id=segment.id,
        continuation_token=segment.continuation_token,
        generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
    )
    full_text += segment.output_text or ""

# Stateless loop (store=False): resend original input + continuation_token
# with no previous_interaction_id.
stateless_seg = client.interactions.create(
    model="gemini-4-hydrogen",
    input=prompt,
    store=False,
    generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
    automatic_continuation=False,
)
stateless_text = stateless_seg.output_text or ""
while stateless_seg.status == "requires_continuation" and stateless_seg.continuation_token:
    stateless_seg = client.interactions.create(
        model="gemini-4-hydrogen",
        input=prompt,
        store=False,
        continuation_token=stateless_seg.continuation_token,
        generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
        automatic_continuation=False,
    )
    stateless_text += stateless_seg.output_text or ""

REST(저장됨)

# Segment 1: Start a stored interaction (store=true by default)
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/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

# Segment 2: When status is "requires_continuation", pass previous_interaction_id
# and continuation_token without resending input
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/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "store": true,
    "previous_interaction_id": "SEGMENT_1_ID",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

REST(스테이트리스(Stateless))

# Segment 1: Stateless interaction (store=false)
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/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "store": false,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

# Segment 2: Resend the original input and continuation_token (no previous_interaction_id)
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/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "store": false,
    "input": "Write a complete formal proof of the prime number theorem.",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

비동기 서버 관리 실행(store=True가 있는 background=True) 또는 스트리밍 체크포인트에서 복구(65,536개의 출력 토큰에서 시작하여 이후 5,000개의 토큰마다 발생하는 interaction.status_update 이벤트)의 경우 다음 패턴을 사용합니다.

Python(백그라운드)

import time
from google import genai

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

# Start a server-managed background long decode (requires store=True)
interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Write a complete formal proof of the prime number theorem.",
    background=True,
    store=True,
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)

while interaction.status in ("queued", "in_progress"):
    time.sleep(10)
    interaction = client.interactions.get(id=interaction.id)

print(f"Status: {interaction.status}")
print(interaction.output_text)

# Optional: Cancel an in-progress background interaction and resume later
# from its persisted checkpoint continuation_token (if >= 65,536 tokens decoded).
# cancelled = client.interactions.cancel(id=interaction.id)
# if cancelled.continuation_token:
#     resumed = client.interactions.create(
#         model="gemini-4-hydrogen",
#         previous_interaction_id=cancelled.id,
#         continuation_token=cancelled.continuation_token,
#         background=True,
#         generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
#     )

REST(백그라운드)

# Start a server-managed background long decode (requires store=true)
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/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "background": true,
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

# Poll the interaction until status reaches completed, incomplete, failed, or cancelled
curl -s -X GET \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID"

# Optional: Cancel an in-progress background decode
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel"

# Optional: Resume a cancelled background decode from its checkpoint continuation_token
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/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "background": true,
    "store": true,
    "previous_interaction_id": "INTERACTION_ID",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

Python(스트리밍 체크포인트)

from google import genai
from google.genai import errors

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

# With default automatic_continuation=True, stream=True automatically
# reconnects from the latest interaction.status_update checkpoint (65,536
# output tokens, then every 5,000 tokens) if no output was yielded after the
# checkpoint. If a disconnect occurs after output was yielded since the last
# checkpoint, the SDK raises ContinuationInterruptedError so you can resume
# from err.continuation_token.
stream = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Write a complete formal proof of the prime number theorem.",
    stream=True,
    store=True,
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)

try:
    for event in stream:
        if event.event_type == "step.delta" and getattr(event.delta, "text", None):
            print(event.delta.text, end="", flush=True)
except errors.ContinuationInterruptedError as err:
    # Resuming from a mid-segment checkpoint regenerates any output yielded
    # after that checkpoint.
    if err.interaction_id and err.continuation_token:
        resumed_stream = client.interactions.create(
            model="gemini-4-hydrogen",
            previous_interaction_id=err.interaction_id,
            continuation_token=err.continuation_token,
            stream=True,
            store=True,
            generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
        )
        for event in resumed_stream:
            if event.event_type == "step.delta" and getattr(event.delta, "text", None):
                print(event.delta.text, end="", flush=True)

REST(스트리밍 체크포인트)

# Start a streaming interaction; save interaction.id from interaction.created
# and the latest continuation_token from interaction.status_update SSE events
curl -N -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/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "stream": true,
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

# Resume a dropped stream from the last saved checkpoint continuation_token
# (for store=false, resend the original input instead of previous_interaction_id)
curl -N -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/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "stream": true,
    "store": true,
    "previous_interaction_id": "SEGMENT_ID",
    "continuation_token": "CHECKPOINT_CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

GenerateContent로 긴 디코딩 사용

GenerateContent(v1beta1)에서 스트리밍 또는 비스트리밍 요청에 대해 max_output_tokens를 65,536보다 크게(최대 1,048,576) 설정합니다. finish_reason가 CONTINUATION인 경우 Google 생성형 AI SDK는 세그먼트 전반에서 continuation_token를 자동으로 따릅니다(선택 해제하려면 GenerateContentConfig에서 automatic_continuation=False 설정). 또는 커스텀 루프에서 continuation_token를 전달할 수 있습니다.

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-hydrogen",
    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.
for chunk in client.models.generate_content_stream(
    model="gemini-4-hydrogen",
    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(chunk.text, end="")

REST(커스텀 연속 루프)

# Request 1: Initial request with maxOutputTokens > 65,536
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-hydrogen: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-hydrogen:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
    }],
    "continuationToken": "CONTINUATION_TOKEN",
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

필수 API 규칙 및 동작 규칙

Hydrogen은 사고 수준, 토큰 한도, 캐싱, 생성 파라미터, 멀티턴 도구 실행에 대해 다음 섹션의 규칙을 적용합니다.

사고 수준

Hydrogen은 4개의 thinking_level 값을 지원합니다(thinking_budget 및 MINIMAL는 HTTP 400 유효성 검사 오류를 반환함). 다음 표에는 각 사고 수준과 권장 워크로드가 나와 있습니다.

사고 수준 권장 워크로드
XHIGH 심층 추론, 수학적 증명, 과학적 분석, 가장 복잡한 다중 파일 소프트웨어 엔지니어링 작업
HIGH(gemini-4-hydrogen의 기본값) 다단계 에이전트형 도구 루프, 코드 생성, 아키텍처 리팩터링, 복잡한 멀티모달 분석
MEDIUM 일반 코딩, 도구 사용, 문서 Q&A, 동영상 이해를 균형 잡힌 지연 시간으로 처리합니다.
LOW 높은 처리량의 분류, 라우팅, 요약, 구조화된 메타데이터 추출

토큰 한도, 캐싱, 결제

Hydrogen은 다음 토큰, 캐싱, 미디어, 결제 규칙을 적용합니다.

  • 통합 입력 및 출력 토큰 한도 및 단일 요청 출력 한도: 토큰 예산 및 요청당 한도는 다음과 같이 작동합니다.
    • 모델의 전체 토큰 한도는 1,048,576 토큰이며 입력 및 출력 토큰을 모두 포함합니다(출력에는 사고, 함수 호출, 최종 대답이 포함됨). max_output_tokens은 생성의 출력 토큰 한도를 제어합니다(최대 1,048,576에서 입력 토큰을 뺀 값). max_output_tokens을 1,048,576보다 크게 설정하면 HTTP 400 오류가 반환됩니다.
    • 의도하지 않은 긴 대답을 방지하기 위해 기본 출력 예산과 단일 세그먼트 포그라운드 한도(사고, 함수 호출, 모델 응답)는 스트리밍 및 비스트리밍 요청 모두에 대해 65,536개의 토큰입니다.
    • HIGH(기본값) 및 XHIGH에서 생성된 추론 토큰은 max_output_tokens에 반영되며, 여러 차례에 걸쳐 생각 서명을 유지하는 경우 멀티턴 컨텍스트에 누적됩니다. 사고와 최종 출력 모두에 충분히 높게 max_output_tokens를 설정하고, 멀티턴 코딩 하네스에서 컨텍스트 압축 기준점을 너무 낮게 설정하지 않거나, 지연 시간에 민감한 도구 차례에 thinking_level="MEDIUM"를 설정합니다.
  • 긴 디코딩: 단일 세그먼트 포그라운드 응답은 최대 65,536개의 출력 토큰(스트리밍 또는 비스트리밍)을 생성합니다. Interactions API 또는 GenerateContent(v1beta1)에서 싱글턴 출력을 최대 1,048,576개 토큰(입력 토큰 제외)으로 확장하려면 긴 디코딩을 참조하세요.
  • 컨텍스트 캐싱: 명시적 컨텍스트 캐싱은 지원되지 않습니다. 암시적 캐싱(기본적으로 영구 캐싱이 사용 설정됨)은 4,096개 이상의 토큰으로 구성된 공유 프롬프트 프리픽스에 자동으로 적용되므로 프롬프트 시작 부분에 정적 콘텐츠를 배치하세요.
  • Office 및 OpenDocument 입력: Word(application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.wordprocessingml.template, application/msword, application/vnd.oasis.opendocument.text), PowerPoint(application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.ms-powerpoint, application/vnd.oasis.opendocument.presentation), Excel 또는 OpenDocument 스프레드시트(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/vnd.oasis.opendocument.spreadsheet) 파일을 인라인으로 또는 Cloud Storage URI(gs://)를 통해 전달합니다. 이때 GenerateContent(FunctionResponse 부분 내부 포함)에서 inlineData 또는 fileData를 사용하고 Interactions API에서 document 입력(도구 결과 포함)을 사용합니다.
  • 에이전트 동영상: 업로드된 동영상은 기본적으로 media_processing="static"로 설정됩니다. 에이전트형 동영상 처리를 사용 설정하려면 media_processing="agentic"를 설정합니다.
  • 토큰 집계 및 결제: 모델이 처리하는 모든 토큰은 집계되고 청구됩니다. 여기에는 그라운딩을 사용할 때의 사고 토큰, 내부 도구 시스템 안내, 함수 선언이 포함됩니다. Google 검색을 사용한 그라운딩도 쿼리당 요금이 청구됩니다.

파라미터, 함수 호출, 채팅 검증

Hydrogen은 생성 파라미터, 도구 호출, 생각 서명, 채팅 기록에 다음 규칙을 적용합니다.

  • 무시된 샘플링 파라미터(temperature, top_k, top_p): 백엔드가 커스텀 값을 무시합니다. thinking_level로 추론 깊이를 제어하고 response_schema로 출력 형식을 제어합니다.
  • 지원되지 않는 매개변수(frequency_penalty, presence_penalty, candidate_count가 1보다 큼): frequency_penalty, presence_penalty 또는 candidate_count가 1보다 큰 경우(candidateCount는 1로 고정됨) HTTP 400 오류가 반환됩니다. 요청에서 이러한 매개변수를 삭제합니다.
  • 함수 호출 및 사고 서명: 도구 선언, 병렬 도구 호출, 멀티턴 thought_signature 재생은 다음 규칙을 따릅니다.

    • 회전 대칭: 각 FunctionResponse는 이전 FunctionCall의 id, name, 순서와 일치해야 합니다.
    • 멀티모달 FunctionResponse 부분: Office 문서, 스프레드시트, 프레젠테이션, PDF, 이미지, 오디오, 동영상을 별도의 사용자 차례 부분으로 추가하는 대신 멀티모달 FunctionResponse 부분(또는 Interactions API의 도구 결과) 내에 포함합니다.
    • 병렬 함수 호출 thought_signature 배치: 모델이 단일 model 차례에서 여러 병렬 functionCall 파트를 내보내는 경우 첫 번째 functionCall 파트에만 thought_signature가 포함됩니다. 활성 사용자 차례의 첫 번째 functionCall 부분에서 thought_signature를 생략하거나, 후속 병렬 functionCall 부분에 복제하거나, functionCall 및 functionResponse 차례를 인터리브하면 HTTP 400 오류가 반환됩니다. 모든 병렬 functionCall 부분을 단일 model 차례에 유지하고 그 뒤에 일치하는 모든 functionResponse 부분을 단일 user 차례에 유지합니다. 자세한 내용은 사고 서명을 참조하세요.
    • 여러 대화 차례에 걸친 thought_signature 보존: 활성 사용자 대화 차례뿐만 아니라 멀티턴 채팅 기록의 모든 이전 대화 차례(functionCall 및 최종 text 부분 모두)에서 원래 Part 내의 모든 thought_signature를 다시 전달합니다. HTTP 400 서명 검증은 활성 사용자 차례 내의 functionCall 단계에만 적용되지만, 이전 차례에서 thought_signature 값을 삭제하거나 skip_thought_signature_validator와 같은 우회 값으로 대체하면 추론 컨텍스트가 삭제되고 출력 품질이 저하되며 MALFORMED_FUNCTION_CALL 종료 사유가 발생할 수 있습니다.
    • 도구 전 형식 지정: \n\n를 사용하여 인라인 요청 사항을 구분하고 도구 호출 전에 구조화되지 않은 텍스트를 사용하지 않습니다. 도구 호출 전에 중간 상태를 로깅하려면 전용 함수 선언을 사용합니다.

      {
        "name": "update",
        "description": "Update working notes before tool execution",
        "parameters": {
          "type": "OBJECT",
          "properties": {
            "previous_step": {"type": "STRING"},
            "plan": {"type": "STRING"},
            "next_step": {"type": "STRING"}
          },
          "required": ["previous_step", "plan", "next_step"]
        }
      }
      
  • 채팅 시퀀스 검증: 멀티턴 채팅 페이로드는 다음 제약 조건을 적용합니다.

    • 기록 페이로드는 model 역할 차례로 끝날 수 없습니다.
    • 사전 입력된 모델 턴은 지원되지 않습니다.

긴 디코딩

긴 디코딩은 Interactions API 또는 GenerateContent(v1beta1)에서 여러 세그먼트에 걸쳐 최대 1,048,576개의 토큰(입력 토큰 제외)을 생성합니다. Interactions API에서 각 포그라운드 세그먼트(stream=true 또는 stream=false)는 최대 65,536개의 출력 토큰을 생성하고 암호화된 continuation_token와 함께 status="requires_continuation"를 반환합니다. 또는 서버가 연속 루프를 비동기식으로 실행하고 병합된 출력을 하나의 Interaction에 저장하도록 background=true(store=true)를 설정할 수 있습니다. GenerateContent에서 각 스트리밍 또는 비스트리밍 세그먼트는 continuation_token와 함께 finish_reason=CONTINUATION를 내보내기 전에 최대 65,536개의 출력 토큰을 생성하며 finish_reason=STOP까지 계속됩니다. Agent Studio에서 출력 토큰 한도를 65,536보다 크고 최대 1,048,576으로 설정하면 연속 토큰이 자동으로 처리됩니다. 실행 가능한 코드 샘플은 긴 디코딩 빠른 시작 예시를 참조하세요.

긴 디코딩을 사용해야 하는 경우

대부분의 요청은 세그먼트당 출력 한도인 65,536개 토큰 내에서 완료됩니다. 하나의 응답에 이보다 더 많은 출력이 필요한 경우에만 긴 디코딩을 사용하세요. 긴 디코딩은 모델에 추론할 수 있는 더 많은 공간을 제공합니다. 답변이 길어지지 않습니다(추론 깊이를 제어하려면 thinking_level 사용).

워크로드 긴 디코딩을 사용하시겠습니까? 이유
어려운 수학, 과학, 연구, 형식적 증명 예 모델은 65,536개 이상의 토큰을 사용하여 추론을 탐색하고 확인할 수 있습니다.
가장 어려운 코딩 및 에이전트형 작업 예 일부 작업에서는 한 번의 대답에 65,536개가 넘는 사고 및 코드 토큰이 필요합니다. 대부분의 코딩 및 에이전트형 작업은 65,536개 미만의 토큰으로 완료됩니다.
출력 한도에서 중지되는 평가 도구 예 긴 디코딩은 모델이 사고에 전체 65,536 토큰 세그먼트를 사용할 때 답변이 잘리는 것을 방지합니다.
채팅, Q&A, 요약, 분류, 추출 아니요 이러한 작업은 65,536개 미만의 토큰으로 완료됩니다.
'70만 단어 분량의 책을 작성해 줘'와 같이 고정된 길이를 요청하는 경우 아니요 모델이 길이 목표를 따르지 않습니다.
짧은 대화로 도구를 여러 번 호출하는 에이전트 아니요 각 차례는 짧습니다. 각 차례의 대규모 출력은 통합된 1,048,576개 토큰 입력 및 출력 한도를 빠르게 채웁니다.
1,048,576 토큰 입력 한도에 근접한 프롬프트 아니요 출력은 1,048,576개 토큰에서 입력을 뺀 값만 사용할 수 있습니다.
지연 시간에 민감한 요청 아니요 긴 디코딩은 몇 분 동안 실행될 수 있습니다.

계속 옵션 선택

API 노출 영역, 스토리지 상태, 런타임 환경에 따라 연속 패턴을 선택합니다. 다음 표의 모든 옵션은 gemini-4-hydrogen에서 동일한 1,048,576 토큰 한도(입력 토큰 제외)에 도달합니다.

연속 옵션 API 노출 영역 각 세그먼트를 시작하는 사용자 세그먼트당 토큰 수 요청당 시간 제한 서버 스토리지 용도
Google 생성형 AI SDK 자동 연속(권장) Interactions API (v1beta1) Google 생성형 AI SDK: Python(google-genai >= 2.34.0), JavaScript/TypeScript(@google/genai >= 2.32.0), Go(>= 1.77.0), Java(>= 1.80.0) 최대 65,536(stream=true 또는 stream=false) 세그먼트당 20분 기본적으로 7일간 서버 저장(store=true) 또는 저장 안 함(store=false) 대부분의 스테이트풀(Stateful) 또는 스테이트리스(Stateless) Interactions API 애플리케이션
백그라운드 서버 관리 루프(background=true) Interactions API (v1beta1) Agent Platform 서버 루프, 코드에서 get 폴링 서버 측에서 최대 max_output_tokens까지 관리 비동기(열린 클라이언트 스트림 필요 없음) 7일 서버 스토리지(store=true 필요) 비동기 작업, .NET/Kotlin 호출자, 단일 레코드 지속성
맞춤 포그라운드 저장 루프(store=true) Interactions API (v1beta1) 코드(previous_interaction_id + continuation_token, input 없음) 최대 65,536개(stream=true 또는 stream=false, 체크포인트는 65,536개부터 시작하여 이후 5,000개 토큰마다) 세그먼트당 20분 7일 서버 저장용량(store=true) REST 호출자 및 커스텀 체크포인트 복구
맞춤 포그라운드 스테이트리스(Stateless) 루프(store=false) Interactions API (v1beta1) 코드(원본 input + continuation_token, previous_interaction_id 없음) 최대 65,536개(stream=true 또는 stream=false, 체크포인트는 65,536개부터 시작하여 이후 5,000개 토큰마다) 세그먼트당 20분 서버 저장소 없음(데이터 보관 없음 워크플로) 스테이트리스(Stateless) 실행이 필요한 커스텀 REST 하네스
Google 생성형 AI SDK 자동 연속(권장) GenerateContent(v1beta1) Google 생성형 AI SDK: Python(>= 2.30.1), JavaScript/TypeScript(>= 2.29.1), Go(>= 1.74.0), Java(>= 1.77.0), .NET(>= 1.26.0), Kotlin(>= 1.6.0) 최대 65,536(generate_content_stream 또는 generate_content) 세그먼트당 20분 서버 저장소 없음(데이터 보관 없음 워크플로) 기존 GenerateContent 애플리케이션
커스텀 연속 루프 GenerateContent(v1beta1) 내 코드(원본 contents + continuation_token) 최대 65,536개(streamGenerateContent 또는 generateContent, 체크포인트는 65,536개부터 시작하여 이후 5,000개 토큰마다) 세그먼트당 20분 서버 저장소 없음(데이터 보관 없음 워크플로) 직접 REST GenerateContent 호출자 및 평가 도구

API 버전 및 SDK 요구사항

긴 디코딩에는 다음 API 버전과 최소 SDK 버전이 필요합니다.

  • v1beta1 API 요구사항(알려진 문제): Interactions API와 GenerateContent(generateContent 및 streamGenerateContent) 모두에서 긴 디코딩(continuation_token)은 Agent Platform의 v1beta1 API(v1 아님)에서만 지원됩니다. Google 생성형 AI SDK는 http_options(또는 interactions.create의 api_version="v1")에 api_version='v1'가 지정되지 않는 한 기본적으로 v1beta1를 사용합니다. 직접 REST 호출의 경우 /v1beta1/ 엔드포인트 경로를 사용합니다.
  • SDK 버전 및 OpenAI 호환성: Interactions API에서 자동 연속을 사용하려면 Python google-genai >= 2.34.0, JavaScript/TypeScript @google/genai >= 2.32.0, Go >= 1.77.0 또는 Java >= 1.80.0로 업그레이드하세요. Interactions API에서 .NET 및 Kotlin을 사용하는 경우 background=true 또는 커스텀 연속 루프를 사용하세요. GenerateContent에서 자동으로 계속하려면 Python >= 2.30.1, JavaScript/TypeScript >= 2.29.1, Go >= 1.74.0, Java >= 1.77.0, .NET >= 1.26.0 또는 Kotlin >= 1.6.0로 업그레이드하세요. 이전 SDK 버전과 OpenAI 호환성 레이어는 연속 토큰을 사용하여 긴 대답을 검색할 수 없습니다.

Interactions API 연속 규칙

Interactions API의 긴 디코딩에는 다음 상태 전환, 연결 규칙, 저장소 동작이 적용됩니다.

상태 값 및 출력 토큰 예산

Interactions API 요청에서 generation_config.max_output_tokens를 생략하면 총 출력 예산은 기본적으로 65,536개의 토큰으로 설정됩니다(스트리밍 및 비스트리밍 요청 모두에 대해 65,536개의 토큰 단일 세그먼트 포그라운드 한도와 일치). 포그라운드 및 background=true 모드 모두에서 멀티 세그먼트 긴 디코딩의 경우 generation_config.max_output_tokens를 65,536보다 크게(최대 1,048,576에서 입력 토큰을 뺀 값) 설정합니다. 서버는 다음 상태 값을 반환합니다.

  • requires_continuation: max_output_tokens 전에 세그먼트당 출력 한도인 65,536개 토큰에 도달했습니다. 디코딩을 계속하려면 다음 요청에서 반환된 continuation_token를 전달하세요.
  • incomplete: 총 max_output_tokens 예산이 소진되었습니다. max_output_tokens을 늘리지 않고 continuation_token를 계속하면 HTTP 400 오류(max_output_tokens has already been exhausted)가 반환됩니다. 디코딩을 재개하려면 다음 요청에서 max_output_tokens을 늘리세요.
  • completed: 생성이 자연스럽게 완료되고 continuation_token가 삭제됩니다.

연결, 모드 전환, 세그먼트 저장

Interactions API의 연속 요청은 다음 규칙을 적용합니다.

  • 저장된 연속(store=true, 기본값): continuation_token와 함께 continuation_token를 실행한 세그먼트 id로 설정된 previous_interaction_id를 전달하고 input를 생략합니다(저장된 세그먼트가 이미 차례 입력을 보유함). 항상 각 continuation_token를 이를 실행한 세그먼트의 previous_interaction_id와 페어링합니다. 이미 completed된 상호작용에서 continuation_token를 전달하면 HTTP 400 오류가 반환됩니다.
  • 스테이트리스(Stateless) 연속(store=false): previous_interaction_id를 생략하고 모든 세그먼트에서 continuation_token와 함께 원래 input를 다시 전송합니다.
  • 세그먼트 간 store 모드 전환: previous_interaction_id를 생략하고 continuation_token를 사용하여 원래 input를 다시 전송하여 디코딩 중간에 저장된 모드(store=true)에서 스테이트리스(Stateless) 모드(store=false)로 전환할 수 있습니다. previous_interaction_id에 대해 저장된 상위 상호작용이 없으므로 스테이트리스(stateless)(store=false)에서 저장됨(store=true)으로 전환할 수 없습니다.
  • 포그라운드 및 background=true 모드 전환 및 분기: 저장된 연속(store=true)은 세그먼트 간에 포그라운드(background=false) 및 백그라운드(background=true) 실행 간에 전환할 수 있습니다. 여기에는 백그라운드 또는 포그라운드 모드에서 체크포인트 continuation_token(출력 토큰 65,536개부터 시작하여 이후 5,000개 토큰마다 유지됨)에서 취소된 background=true 상호작용을 재개하는 것이 포함됩니다. 동일한 previous_interaction_id 및 continuation_token를 재사용하면 독립적인 분기 연속이 생성됩니다.
  • 발화 경계 적용: 상태가 requires_continuation 또는 incomplete인 세그먼트에서 새 사용자 발화(새 input가 있고 continuation_token가 없는 previous_interaction_id)를 시작하면 HTTP 400 오류가 반환됩니다. completed에 대한 디코딩을 계속 완료하거나 가장 최근의 completed 상호작용에서 다음 차례를 분기합니다. 최종 세그먼트가 completed에 도달하면 최종 세그먼트의 id를 previous_interaction_id로 전달하여 이전의 모든 세그먼트에서 전체 대화 기록을 재구성합니다.
  • 세그먼트 간 파라미터 일관성: 연속 세그먼트에서 model, system_instruction 또는 함수 선언(tools)을 변경하면 HTTP 400 오류가 반환됩니다. 세그먼트 전반에서 thinking_level 및 기본 제공 도구도 변경하지 않고 유지합니다(알려진 문제 참고).
  • 단일 세그먼트 get, list, delete 동작: 포그라운드 모드(background=false)에서 각 세그먼트는 별도의 Interaction 리소스로 저장됩니다(interactions.get(id)는 해당 세그먼트만 반환하고, interactions.list()는 각 세그먼트를 개별적으로 나열하고, interactions.delete(id)는 해당 세그먼트만 삭제합니다. 세그먼트 체인을 삭제할 때는 마지막 세그먼트부터 역순으로 삭제합니다). automatic_continuation=True(stream=False)를 사용하는 Google 생성형 AI SDK에서 interactions.create()는 반환 시 모든 세그먼트를 병합하고 순서가 지정된 세그먼트 ID(interaction.id로 끝남)로 interaction.continuation_ids를 채웁니다. 이후 세그먼트가 실패하거나, 숫자별 호출 timeout를 초과하거나, 재개 가능한 체크포인트를 지나 진행된 후 스트림 중간에 중단되면 SDK는 partial_interaction, continuation_token, interaction_id, continuation_ids를 전달하는 ContinuationInterruptedError를 발생시켜 continuation_token에서 재개할 수 있도록 합니다.

GenerateContent 맞춤 루프 규칙

커스텀 GenerateContent 연속 루프에서는 다음 규칙을 따르세요.

  • max_output_tokens를 65,536보다 크게(최대 1,048,576) 설정하고 최신 continuation_token(REST의 GenerateContentRequest 또는 Google 생성형 AI SDK의 GenerateContentConfig에 있는 최상위 필드)와 함께 모든 연속 요청에서 원래 contents, system_instruction, tools를 다시 전송합니다.
  • 부분 모델 출력을 contents에 추가하거나 모델에 계속하도록 요청하는 후속 프롬프트를 보내지 마세요.
  • 세그먼트가 사고(parts: [{"text": ""}])에 65,536개의 토큰을 모두 사용한 경우에도 finish_reason가 CONTINUATION이고 continuation_token가 있으면 계속 루프를 실행합니다. continuation_token가 있을 때 finish_reason가 MAX_TOKENS이면 다음 요청에서 max_output_tokens를 높입니다.
  • STOP 이후에만 누적된 부분을 멀티턴 기록의 단일 model 대화로 결합합니다.

토큰 수 계산, 압축, 암시적 캐싱

연속 세그먼트 전반의 토큰 계산 및 캐싱은 다음과 같이 작동합니다.

  • Interactions API에서 automatic_continuation=True를 사용하는 비스트리밍 interactions.create() 호출과 서버 관리형 background=true 상호작용은 usage(total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens, total_tokens)의 모든 세그먼트에서 토큰 수를 합산하여 usage.initial_input_tokens에서 첫 번째 세그먼트의 프롬프트 수를 유지합니다. 커스텀 포그라운드 루프 및 스트리밍된 interaction.completed 이벤트에서 각 세그먼트의 usage는 해당 세그먼트의 델타만 보고하므로 세그먼트 간에 usage 필드를 합산하여 총 청구 토큰을 구합니다.
  • GenerateContent에서 Python Google 생성형 AI SDK(generate_content 및 generate_content_stream)는 최종 usage_metadata의 세그먼트 전반에서 청구된 총 토큰을 누적하고 initial_prompt_token_count를 보존합니다. 커스텀 REST 루프에서 세그먼트 전반의 최종 prompt_token_count, cached_content_token_count, candidates_token_count, thoughts_token_count를 합산합니다.
  • 각 포그라운드 연속 세그먼트는 대화와 이전에 생성된 토큰을 입력으로 다시 미리 채우므로 세그먼트 전반에서 usage.total_input_tokens(Interactions API) 및 prompt_token_count(GenerateContent)가 증가합니다. 에이전트 하네스에서 컨텍스트 압축을 트리거하기 위해 누적 입력 수를 사용하지 마세요. 대신 usage.initial_input_tokens(또는 GenerateContent의 initial_prompt_token_count)를 확인하고 차례가 끝난 후에만 압축하세요(status="completed" 또는 continuation_token 없음).
  • 각 연속 세그먼트는 프롬프트와 이전에 디코딩된 토큰을 다시 미리 채우고 세그먼트가 연속으로 실행될 때 암시적 컨텍스트 캐싱(최소 4,096개 토큰, 기본적으로 영구 캐싱 사용 설정됨)을 자동으로 적용합니다. 완료된 세그먼트는 이후 세그먼트가 실패하거나 취소되더라도 각 세그먼트가 끝날 때 청구됩니다.

3.8 Flash에서 Hydrogen으로 이전

다음 동작은 gemini-3.8-flash 및 이전 Gemini 3 Flash 모델과 다릅니다.

  • Hydrogen은 입력 및 출력 한도가 별도로 적용되지 않고 입력 및 출력(출력에는 사고, 함수 호출, 최종 대답이 포함됨)에 걸쳐 통합된 1,048,576 토큰 한도가 적용됩니다. 단일 세그먼트 포그라운드 출력은 65,536개 토큰(스트리밍 또는 비스트리밍)으로 제한되며, Interactions API 또는 GenerateContent에서 긴 디코딩을 사용하여 최대 1,048,576개 토큰까지 확장할 수 있습니다(Google 생성형 AI SDK에서 자동으로 처리, Interactions API에서 background=true 사용 또는 커스텀 루프에서 continuation_token 사용).
  • 기본 thinking_level는 HIGH(gemini-3.8-flash에 MEDIUM에서 변경됨)이며, 심층 추론 작업에는 XHIGH가 지원됩니다(멀티턴 코딩 하네스에서 HIGH 및 XHIGH 추론 트레이스를 위한 컨텍스트 압축 여유 공간을 남겨두거나 지연 시간에 민감한 차례에 MEDIUM를 설정). thinking_budget 및 thinking_level="MINIMAL"는 HTTP 400 오류를 반환합니다.
  • 명시적 컨텍스트 캐싱(cached_content)은 지원되지 않습니다. 암시적 캐싱은 최소 4,096개 토큰(gemini-3.8-flash의 6,144개 토큰에서 감소)에서 자동으로 적용되며, 영구 캐싱은 기본적으로 사용 설정됩니다.
  • Microsoft Office(.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) 및 OpenDocument(.odt, .odp, .ods) 파일은 인라인 또는 Cloud Storage URI(gs://)로 지원되며, 멀티모달 FunctionResponse 부분 내부도 포함됩니다.
  • 병렬 함수 호출 차례는 엄격한 thought_signature 배치를 적용합니다(병렬 차례의 첫 번째 functionCall 부분만 thought_signature를 전달하며, 활성 차례에서 이를 생략하거나 후속 동위 functionCall 부분에 중복하면 HTTP 400 오류가 반환됨). 또한 동일 모델 프롬프트 프리픽스 수정은 ThinkingConfig에 prefix_mismatch_behavior="DROP"가 설정되지 않는 한 기본적으로 HTTP 400로 실패합니다. 추론 품질을 유지하고 MALFORMED_FUNCTION_CALL 종료 사유를 방지하기 위해 이전의 모든 차례에서 thought_signature 부분(functionCall 및 최종 text 부분 모두)을 보존합니다.
  • 그라운딩을 사용할 때 내부 도구 시스템 안내 및 함수 선언을 포함하여 모델이 처리하는 모든 토큰에 대해 요금이 청구됩니다.

나란히 비교하려면 Gemini 3 모델에서 마이그레이션을 참조하세요.

 client = genai.Client(
     enterprise=True,
     project="PROJECT_ID",
     location="global", # Supports "global", "us", and "eu"
 )

 response = client.models.generate_content(
-    model="gemini-3.8-flash",
+    model="gemini-4-hydrogen",
     contents=prompt,
     config=types.GenerateContentConfig(
-        temperature=0.0,
-        cached_content="projects/.../cachedContents/...", # Explicit caching unsupported
         thinking_config=types.ThinkingConfig(
-            thinking_budget=16384, # Returns HTTP 400 instead of mapping silently
-            thinking_level="MINIMAL", # MINIMAL unsupported on Gemini 4 Hydrogen
+            thinking_level="HIGH", # Valid: "LOW", "MEDIUM", "HIGH" (default), "XHIGH"
+            # prefix_mismatch_behavior="DROP", # Optional: set if compacting or editing prior history
         ),
     ),
 )

gemini-3.8-flash 이전의 Gemini 3 Flash 모델에서 마이그레이션하려면 다음을 수행합니다.

  1. 모델 ID를 gemini-4-hydrogen로 업데이트합니다.
  2. 최신 Google 생성형 AI SDK로 업그레이드하고 통합 입력 및 출력 토큰 한도를 고려: Interactions API 자동 연속을 위해 google-genai >= 2.34.0(Python), @google/genai >= 2.32.0(JavaScript/TypeScript), Go >= 1.77.0 또는 Java >= 1.80.0로 업그레이드합니다(또는 GenerateContent에서 >= 2.30.1 Python/>= 2.29.1 JavaScript). 입력 및 출력 토큰(사고 및 함수 호출 포함)은 통합된 1,048,576 토큰 한도를 공유합니다. Interactions API 또는 GenerateContent에서 65,536개 토큰(최대 1,048,576개 토큰)을 초과하는 출력의 경우 Google 생성형 AI SDK가 세그먼트 간에 자동으로 계속되도록 max_output_tokens를 65,536보다 크게 설정합니다(또는 background=true 또는 커스텀 continuation_token 루프 사용).
  3. thinking_level 구성 업데이트: thinking_budget 및 MINIMAL를 LOW, MEDIUM, HIGH(gemini-4-hydrogen의 기본값) 또는 XHIGH(Interactions API에서 소문자 "low", "medium", "high" 또는 "xhigh" 사용)로 설정된 thinking_level로 바꿉니다. 워크로드가 gemini-3.8-flash에서 MEDIUM를 기본값으로 사용한 경우 thinking_level="MEDIUM"를 명시적으로 설정하여 동일한 추론 지연 시간을 유지합니다.
  4. 명시적 캐싱을 삭제하고 정적 프롬프트 콘텐츠(4,096개 이상의 토큰)를 미리 로드하여 자동 암시적 캐싱을 수행합니다.
  5. 멀티턴 및 동시 thought_signature 보존 및 프리픽스 압축 확인: 턴 간에 서명을 제거하는 대신 이전의 모든 턴(functionCall 및 최종 text 부분 모두)에서 thought_signature를 보존하고, 동시 도구 호출 턴의 첫 번째 functionCall 부분에서만 thought_signature를 유지하고, 애플리케이션이 멀티턴 채팅 기록에서 이전 턴을 수정하거나 압축하는 경우 ThinkingConfig에서 prefix_mismatch_behavior="DROP"를 설정합니다.
  6. 효과가 없거나 지원되지 않는 매개변수 삭제: 다음과 같이 무시되고 거부된 생성 필드를 삭제합니다.
    • temperature, top_p, top_k를 삭제합니다. 이들은 무시됩니다.
    • frequency_penalty, presence_penalty, 1보다 큰 candidate_count 값을 삭제합니다.
    • 대화 기록에서 사전 입력된 모델 턴을 삭제합니다.

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

다음 체크리스트를 사용하여 Hydrogen 통합을 확인합니다.

알려진 문제

다음 알려진 문제는 Hydrogen 긴 디코딩에 적용됩니다.

  • 긴 디코딩에는 v1beta1가 필요함: Interactions API와 GenerateContent API(generateContent 및 streamGenerateContent) 모두에서 긴 디코딩(continuation_token)은 Agent Platform의 v1beta1 API(v1 아님)에서만 지원됩니다. Google 생성형 AI SDK는 http_options(또는 interactions.create의 api_version="v1")에 api_version='v1'가 설정되지 않는 한 기본적으로 v1beta1를 사용합니다. 직접 REST 호출의 경우 /v1beta1/ 엔드포인트 경로를 사용합니다.
  • Interactions API 연속 세그먼트 전반의 파라미터 변경: 연속 세그먼트 전반에서 model, system_instruction 또는 함수 선언을 변경하면 HTTP 400 오류가 반환되지만, 디코딩 중에 generation_config.thinking_level 또는 기본 제공 도구(google_search, code_execution, url_context)를 변경하면 서버 검증에서 거부되지 않습니다. 연속 루프의 모든 세그먼트에서 thinking_level 및 기본 제공 도구를 변경하지 않고 유지합니다.

추가 리소스

Hydrogen에 대한 자세한 내용은 다음 리소스를 참조하세요.