Gemini 4 Carbon 개발자 가이드

Gemini 4 Carbon은 코딩, 금융, 법률, 사이버 보안, 과학 등 다양한 분야에서 복잡한 실제 작업을 심층적으로 처리하는 데 뛰어난 Google의 프런티어 모델입니다. Gemini 4 제품군의 일부입니다. Gemini 4 Carbon은 서비스별 약관의 섹션 34가 적용되는 Google 프런티어 모델입니다(자세한 내용은 악용 사례 모니터링 참조).

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

Gemini 4 Carbon의 주요 기능

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

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

빠른 시작

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

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

Agent Studio에서 사용해 보기

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

  1. Google Cloud 프로젝트에서 Agent Studio를 열고 Gemini 그룹에서 gemini-4-carbon를 선택합니다.
  2. 모델 설정에서 다음 옵션을 구성합니다.
    • 사고 수준: Low, Medium(기본값) 또는 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-carbon에 요청을 보냅니다.

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-carbon",
    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="MEDIUM",  # Default: "MEDIUM" (Valid: "LOW", "MEDIUM", "HIGH")
        ),
    ),
)
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-carbon",
    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-carbon",
    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-carbon:generateContent" \
-d '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Provide an architectural review of this Go interface."
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "MEDIUM"
    }
  }
}'

구조화된 출력

스키마를 준수하는 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-carbon",
    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개의 출력 토큰을 생성하고 비스트리밍 시 최대 32,768개의 출력 토큰을 생성합니다. 여기서 출력에는 사고, 함수 호출, 최종 대답이 포함됩니다. 최대 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-carbon",
    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}")

# 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)

# Streaming yields events across all segments in order. Intermediate segments
# emit interaction.completed with status="requires_continuation".
stream = client.interactions.create(
    model="gemini-4-carbon",
    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}")

# Set automatic_continuation=False to return after a single segment.
single_segment = client.interactions.create(
    model="gemini-4-carbon",
    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-carbon",
    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-carbon",
        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 (leaving default automatic_continuation=True lets the SDK finish remaining segments).
if segment.status == "incomplete" and segment.continuation_token:
    segment = client.interactions.create(
        model="gemini-4-carbon",
        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-carbon",
    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-carbon",
        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-carbon",
    "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-carbon",
    "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-carbon",
    "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-carbon",
    "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) 또는 스트리밍 체크포인트(32,768개의 출력 토큰과 이후 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-carbon",
    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 >= 32,768 tokens decoded).
# cancelled = client.interactions.cancel(id=interaction.id)
# if cancelled.continuation_token:
#     resumed = client.interactions.create(
#         model="gemini-4-carbon",
#         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-carbon",
    "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-carbon",
    "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 (32,768
# 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-carbon",
    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-carbon",
            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-carbon",
    "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-carbon",
    "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보다 크게 설정하고 비스트리밍 요청의 경우 32,768보다 크게 설정합니다(최대 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-carbon",
    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-carbon",
    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 > 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-carbon: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-carbon: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 규칙 및 동작 규칙

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

사고 수준

4 Carbon은 세 가지 thinking_level 값을 지원합니다(thinking_budget 및 MINIMAL는 HTTP 400 유효성 검사 오류를 반환함). GenerateContent에서는 대문자 값("LOW", "MEDIUM", "HIGH")을 전달하고 Interactions API에서는 소문자 값("low", "medium", "high")을 전달합니다. 다음 표에는 각 사고 수준과 권장 워크로드가 나와 있습니다.

사고 수준 권장 워크로드
HIGH(gemini-4-carbon-cyber-permissive의 기본값) 다중 파일 소프트웨어 엔지니어링, 형식 증명, 아키텍처 설계, 취약점 발견
MEDIUM(gemini-4-carbon의 기본값) 일반 코딩, 도구 사용, 문서 Q&A, 동영상 이해
LOW 분류, 요약, 메타데이터 추출

토큰 한도, 캐싱, 결제

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

  • 통합 입력 및 출력 토큰 한도 및 기본 출력 예산: 토큰 예산 및 포그라운드 세그먼트 한도는 다음과 같이 작동합니다.
    • 모델의 전체 토큰 한도는 1,048,576 토큰이며 입력 및 출력 토큰을 모두 포함합니다(출력에는 사고, 함수 호출, 최종 대답이 포함됨). max_output_tokens은 생성의 출력 토큰 한도를 제어합니다(최대 1,048,576에서 입력 토큰을 뺀 값). max_output_tokens을 1,048,576보다 크게 설정하면 HTTP 400 오류가 반환됩니다.
    • GenerateContent 또는 Interactions API에서 max_output_tokens를 생략하면 기본 총 출력 예산(사고, 함수 호출, 대답)은 65,536개 토큰입니다. 단일 포그라운드 세그먼트는 스트리밍 시 최대 65,536개의 토큰을 생성하고 비스트리밍 시에는 32,768개의 토큰을 생성하므로 Google 생성형 AI SDK(v1beta1)는 필요한 경우 비스트리밍 호출에서 32,768개의 토큰 세그먼트 2개를 자동으로 연결합니다. 반면 단일 비스트리밍 REST 요청은 32,768개의 토큰 포그라운드 세그먼트 1개 후에 중지됩니다. Agent Studio에서 출력 토큰 한도는 기본적으로 1,048,576이며 자동 연속이 적용됩니다.
  • 긴 디코딩: 단일 포그라운드 세그먼트는 스트리밍 시 최대 65,536개의 출력 토큰을 생성하고 스트리밍이 아닌 경우 32,768개의 출력 토큰을 생성합니다. 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) 파일을 인라인으로 전달하거나 Interactions API의 GenerateContent 및 document 입력(도구 결과 포함)에서 inlineData 또는 fileData를 사용하여 Cloud Storage URI(gs://)로 전달합니다.
  • 에이전트 동영상: 업로드된 동영상은 기본적으로 media_processing="static"로 설정됩니다. 에이전트형 동영상 처리를 사용 설정하려면 media_processing="agentic"를 설정합니다.
  • 토큰 집계 및 결제: 모델이 처리하는 모든 토큰은 집계되고 청구됩니다. 여기에는 그라운딩을 사용할 때의 사고 토큰, 내부 도구 시스템 안내, 함수 선언이 포함됩니다. Google 검색을 사용한 그라운딩도 쿼리당 요금이 청구됩니다.

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

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

  • 무시된 샘플링 파라미터(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 오류가 반환됩니다. 요청에서 이러한 매개변수를 삭제합니다.

  • 함수 호출: 도구 선언 및 실행 차례는 다음 규칙을 따릅니다.

    • 회전 대칭: 각 FunctionResponse는 이전 FunctionCall의 id, name, 순서와 일치해야 합니다.
    • 순차 실행: 다단계 도구 루프에서 순차적인 도구 실행 차례를 선호합니다.

    • 도구 전 형식 지정: \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) 최대 65, 536개의 출력 토큰을 생성하고,비스트리밍 시(stream=false) 최대 32,768개의 출력 토큰을 생성하며, 암호화된 continuation_token와 함께 status="requires_continuation"를 반환합니다. 또는 서버가 연속 루프를 비동기식으로 실행하고 병합된 출력을 하나의 Interaction에 저장하도록 background=true(store=true)를 설정할 수 있습니다. GenerateContent에서 스트리밍 세그먼트는 최대 65,536개의 출력 토큰을 생성하고 비스트리밍 세그먼트는 최대 32,768개의 출력 토큰을 생성한 후 continuation_token와 함께 finish_reason=CONTINUATION를 내보내고 finish_reason=STOP까지 계속됩니다. 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개 토큰에서 입력을 뺀 값만 사용할 수 있습니다.
지연 시간에 민감한 요청 아니요 긴 디코딩은 몇 분 동안 실행될 수 있습니다.

계속 옵션 선택

API 노출 영역, 스토리지 상태, 런타임 환경에 따라 연속 패턴을 선택합니다. 다음 표의 모든 옵션은 gemini-4-carbon 및 gemini-4-carbon-cyber-permissive에서 동일한 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) 또는 32,768(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 필요) 비동기 작업, REST를 통한 다른 언어의 호출자, 단일 레코드 지속성
맞춤 포그라운드 저장 루프(store=true) Interactions API (v1beta1) 코드(previous_interaction_id + continuation_token, input 없음) 최대 65,536(stream=true, 32,768 이후 5,000개 토큰마다 체크포인트) 또는 32,768(stream=false) 세그먼트당 20분 7일 서버 저장용량(store=true) REST 호출자 및 커스텀 체크포인트 복구
맞춤 포그라운드 스테이트리스(Stateless) 루프(store=false) Interactions API (v1beta1) 내 코드(원본 input + continuation_token, previous_interaction_id 없음) 최대 65,536(stream=true, 32,768 이후 5,000개 토큰마다 체크포인트) 또는 32,768(stream=false) 세그먼트당 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) 또는 32,768(generate_content) 세그먼트당 20분 서버 저장소 없음(데이터 보관 없음 워크플로) 기존 GenerateContent 애플리케이션
커스텀 연속 루프 GenerateContent(v1beta1) 내 코드(원본 contents + continuation_token) 최대 65,536(streamGenerateContent, 32,768 이후 5,000개 토큰마다 체크포인트) 또는 32,768(generateContent) 세그먼트당 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의 다른 언어의 경우 background=true 또는 커스텀 연속 루프를 사용하여 REST API를 직접 호출). 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개의 토큰으로 설정됩니다. 따라서 비스트리밍 호출은 status="requires_continuation"를 사용하여 32,768개의 토큰에서 중지되고 두 번째 세그먼트는 나머지 32,768개의 토큰을 생성할 수 있습니다. 포그라운드 및 background=true 모드 모두에서 더 긴 디코딩을 위해 generation_config.max_output_tokens를 최대 1,048,576(입력 토큰 제외)로 설정합니다. 서버는 다음 상태 값을 반환합니다.

  • requires_continuation: max_output_tokens 전에 세그먼트당 출력 한도(비스트리밍 32,768개 또는 스트리밍 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(출력 토큰 32,768개 이후에 유지됨)에서 취소된 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(스트리밍) 또는 32,768(비스트리밍)보다 크고 최대 1,048,576으로 설정하고, 모든 연속 요청에서 원래 contents, system_instruction, tools를 최신 continuation_token(REST의 GenerateContentRequest 또는 Google 생성형 AI SDK의 GenerateContentConfig에 있는 최상위 필드)와 함께 다시 전송합니다.
  • 부분 모델 출력을 contents에 추가하거나 모델에 계속하도록 요청하는 후속 프롬프트를 보내지 마세요.
  • 세그먼트가 사고(parts: [{"text": ""}])에 32,768개 또는 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.1 Pro에서 4 Carbon으로 이전

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

  • 4 Carbon은 입력 및 출력 한도가 별도로 적용되지 않고 입력 및 출력(출력에는 사고, 함수 호출, 최종 대답이 포함됨) 전반에 걸쳐 통합된 1,048,576 토큰 한도가 적용됩니다. 단일 포그라운드 세그먼트는 스트리밍 시 65,536개 토큰(비스트리밍 시 32,768개 토큰)으로 제한되며, Interactions API 또는 GenerateContent에서 긴 디코딩을 사용하여 출력을 최대 1,048,576개 토큰까지 확장할 수 있습니다(Google 생성형 AI SDK에서 자동으로 처리, Interactions API에서 background=true 사용 또는 커스텀 루프에서 continuation_token 사용).
  • thinking_budget는 사고 수준에 매핑되는 대신 HTTP 400 오류를 반환합니다. MINIMAL도 오류를 반환합니다.
  • 명시적 컨텍스트 캐싱은 지원되지 않습니다.
  • 그라운딩을 사용할 때 내부 도구 시스템 안내 및 함수 선언을 포함하여 모델이 처리하는 모든 토큰에 요금이 청구됩니다.

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

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

 response = client.models.generate_content(
-    model="gemini-3.1-pro-preview",
+    model="gemini-4-carbon",
     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 Carbon
+            thinking_level="MEDIUM", # Valid: "LOW", "MEDIUM" (default), "HIGH"
         ),
     ),
 )

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

  1. 모델 ID를 gemini-4-carbon로 업데이트합니다(또는 Fairwind 프로그램을 통해 승인된 사이버 보안 워크로드의 경우 gemini-4-carbon-cyber-permissive).
  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_budget 및 MINIMAL를 thinking_level로 대체하고 LOW, MEDIUM(gemini-4-carbon의 기본값) 또는 HIGH(gemini-4-carbon-cyber-permissive의 기본값)로 설정합니다(Interactions API에서 소문자 "low", "medium" 또는 "high" 사용).
  4. 명시적 캐싱을 삭제하고 자동 암시적 캐싱을 위해 정적 프롬프트 콘텐츠(4,096개 이상의 토큰)를 미리 로드합니다.
  5. 효과가 없거나 지원되지 않는 매개변수 삭제: 다음과 같이 무시되고 거부된 생성 필드를 삭제합니다.
    • temperature, top_p, top_k를 삭제합니다. 이들은 무시됩니다.
    • frequency_penalty, presence_penalty, 1보다 큰 candidate_count 값을 삭제합니다.
    • 대화 기록에서 사전 입력된 모델 턴을 삭제합니다.

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

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

알려진 문제

다음과 같은 알려진 문제는 4 Carbon 긴 디코딩에 적용됩니다.

  • 긴 디코딩에는 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 및 기본 제공 도구를 변경하지 않고 유지합니다.

추가 리소스

4 Carbon에 관한 자세한 내용은 다음 리소스를 참고하세요.