Panduan developer untuk Gemini 4 Hydrogen

Gemini 4 Hydrogen menghadirkan kecerdasan mutakhir dengan kecepatan dan efisiensi untuk coding sehari-hari dan alur kerja perusahaan agentic.

Dokumen ini membahas kemampuan utama Hydrogen, konvensi API yang diterapkan, cara bermigrasi dari Gemini 3.8 Flash dan model Gemini 3 Flash sebelumnya, serta panduan memulai. Untuk ringkasan rangkaian Gemini 4, lihat Mulai menggunakan Gemini 4.

Kemampuan utama di Gemini 4 Hydrogen

Gemini 4 Hydrogen mencakup kemampuan berikut:

  • Batas token input dan output terpadu: Hydrogen memiliki batas 1.048.576 token terpadu yang mencakup token input dan output (dengan output mencakup penalaran, panggilan fungsi, dan respons akhir).
  • Dekode panjang hingga 1.048.576 token: Hydrogen memperluas pembuatan di luar satu segmen latar depan 65.536 token (streaming atau non-streaming) hingga 1.048.576 token (dikurangi token input Anda) di Interactions API dan GenerateContent (v1beta1). Google Gen AI SDK menangani continuation_token secara otomatis di seluruh segmen, atau Anda dapat menjalankan dekode latar belakang asinkron yang dikelola server (background=true) atau mengelola continuation_token dalam loop kelanjutan kustom.
  • Thinking level: Hydrogen mendukung LOW, MEDIUM, HIGH (default), dan XHIGH.
  • Penyimpanan ke dalam cache implisit dengan penyimpanan ke dalam cache yang tahan lama: Penyimpanan ke dalam cache implisit berlaku secara otomatis untuk awalan perintah bersama yang berisi 4.096 token atau lebih, dengan penyimpanan ke dalam cache yang tahan lama diaktifkan secara default. Cache konteks eksplisit tidak didukung.
  • Input file Office dan OpenDocument: Selain PDF dan teks biasa, Hydrogen menerima file Microsoft Office (.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) dan OpenDocument (.odt, .odp, .ods) secara inline atau dari Cloud Storage di GenerateContent dan Interactions API, termasuk di dalam bagian FunctionResponse multimodal.
  • Pemahaman video agentic: Pemahaman video agentic tersedia secara umum dan nonaktif secara default.
  • Siklus proses rilis jangka pendek: Hydrogen adalah rilis ketersediaan umum (GA) jangka pendek yang tunduk pada kebijakan pemberitahuan penghentian minimum 45 hari. Untuk mengetahui detail siklus proses, lihat Versi dan siklus proses model.

Panduan Memulai

Sebelum memulai, Anda harus melakukan autentikasi ke Gemini Enterprise Agent Platform menggunakan Kredensial Default Aplikasi (ADC) atau kunci API. Lihat Memulai Agent Platform untuk mengetahui informasi selengkapnya.

Dalam blok kode berikut, ganti PROJECT_ID dengan project ID Anda.

Coba di Agent Studio

Untuk menguji perintah dan mengonfigurasi gemini-4-hydrogen di UI Agent Studio, lakukan hal berikut:

  1. Buka Agent Studio di project Google Cloud Anda, lalu pilih gemini-4-hydrogen di bagian grup Gemini.
  2. Di Model settings, konfigurasikan opsi berikut:
    • Thinking level: Pilih Low, Medium, High (default), atau Extra high.
    • Region: Pilih Global, us, atau eu.
    • Output token limit: Tetapkan antara 32,768 dan 1,048,576 (default 1,048,576). Agent Studio menangani token kelanjutan secara otomatis untuk respons yang melebihi batas permintaan tunggal.

Penginstalan

Mengupgrade ke Google Gen AI SDK terbaru. Kelanjutan otomatis di Interactions API memerlukan google-genai >= 2.34.0 untuk Python, @google/genai >= 2.32.0 untuk JavaScript/TypeScript, >= 1.77.0 untuk Go, atau >= 1.80.0 untuk Java (di GenerateContent, kelanjutan otomatis memerlukan >= 2.30.1 untuk Python, >= 2.29.1 untuk JavaScript/TypeScript, >= 1.74.0 untuk Go, >= 1.77.0 untuk Java, >= 1.26.0 untuk .NET, atau >= 1.6.0 untuk Kotlin):

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

Permintaan dasar

Kirim permintaan ke gemini-4-hydrogen menggunakan Google Gen AI SDK atau REST:

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"
    }
  }
}'

Output terstruktur

Untuk menghasilkan output JSON yang sesuai dengan skema, konfigurasikan response_mime_type dan 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)

Contoh dekode panjang

Secara default, satu segmen API latar depan menghasilkan hingga 65.536 token output (streaming atau non-streaming), dengan output yang mencakup penalaran, panggilan fungsi, dan respons akhir. Untuk menghasilkan penyelesaian hingga 1.048.576 token (dikurangi token input Anda), gunakan dekode panjang di Interactions API atau GenerateContent. Untuk opsi kelanjutan, transisi status, dan aturan validasi, lihat Dekode panjang.

Menggunakan dekode panjang dengan Interactions API

Di google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0, dan Java >= 1.80.0, interactions.create() otomatis mengikuti continuation_token di seluruh segmen setiap kali segmen menampilkan status="requires_continuation". Anda juga dapat memilih tidak ikut (automatic_continuation=False) untuk menjalankan loop tersimpan kustom (store=True) atau stateless (store=False):

Python (SDK otomatis)

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 (Loop kustom)

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 (Disimpan)

# 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"
    }
  }'

Untuk eksekusi asinkron yang dikelola server (background=True dengan store=True) atau pemulihan dari checkpoint streaming (peristiwa interaction.status_update yang dikeluarkan mulai dari 65.536 token output dan setiap 5.000 token setelahnya), gunakan pola berikut:

Python (Background)

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 (Latar Belakang)

# 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 (Checkpoints streaming)

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 (Streaming checkpoint)

# 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"
    }
  }'

Menggunakan dekode panjang dengan GenerateContent

Di GenerateContent (v1beta1), tetapkan max_output_tokens lebih besar dari 65.536 (hingga 1.048.576) untuk permintaan streaming atau non-streaming. Google Gen AI SDK otomatis mengikuti continuation_token di seluruh segmen saat finish_reason adalah CONTINUATION (tetapkan automatic_continuation=False di GenerateContentConfig untuk memilih tidak ikut), atau Anda dapat meneruskan continuation_token dalam loop kustom:

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 (Loop lanjutan kustom)

# 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"}
    }
  }'

Aturan API dan konvensi perilaku wajib

Hydrogen menerapkan konvensi di bagian berikut untuk tingkat pemikiran, batas token, caching, parameter pembuatan, dan eksekusi alat multi-turn.

Tingkat penalaran

Hidrogen mendukung empat nilai thinking_level (thinking_budget dan MINIMAL menampilkan error validasi HTTP 400). Tabel berikut mencantumkan setiap tingkat penalaran dan workload yang direkomendasikan:

Tingkat penalaran Workload yang direkomendasikan
XHIGH Penalaran mendalam, pembuktian matematis, analisis ilmiah, dan tugas rekayasa software multi-file yang paling kompleks.
HIGH (default di gemini-4-hydrogen) Loop alat agentic multi-langkah, pembuatan kode, refaktorisasi arsitektur, dan analisis multimodal yang kompleks.
MEDIUM Coding umum, penggunaan alat, Q&A dokumen, dan pemahaman video dengan latensi yang seimbang.
LOW Klasifikasi, pemilihan rute, peringkasan, dan ekstraksi metadata terstruktur dengan throughput tinggi.

Batas token, caching, dan penagihan

Hydrogen menerapkan aturan token, caching, media, dan penagihan berikut:

  • Batas token input dan output terpadu serta batas output permintaan tunggal: Anggaran token dan batas per permintaan berfungsi sebagai berikut:
    • Batas token keseluruhan model adalah 1,048,576 token dan mencakup token input dan output (dengan output mencakup penalaran, panggilan fungsi, dan respons akhir). max_output_tokens mengontrol batas token output untuk pembuatan (hingga 1,048,576 dikurangi token input Anda); menetapkan max_output_tokens lebih besar dari 1,048,576 akan menampilkan error HTTP 400.
    • Untuk menghindari penyelesaian yang panjang dan tidak diinginkan, anggaran output default dan batas latar depan segmen tunggal (penalaran, panggilan fungsi, dan respons model) adalah 65.536 token untuk permintaan streaming dan non-streaming.
    • Token penalaran yang dihasilkan di HIGH (default) dan XHIGH dihitung dalam max_output_tokens dan diakumulasikan dalam konteks multi-turn saat Anda mempertahankan tanda tangan pemikiran di seluruh giliran. Tetapkan max_output_tokens yang cukup tinggi untuk pemikiran dan output akhir, hindari nilai minimum pemadatan konteks yang terlalu rendah dalam harness coding multi-turn, atau tetapkan thinking_level="MEDIUM" pada giliran alat yang sensitif terhadap latensi.
  • Dekode panjang: Respons latar depan segmen tunggal menghasilkan hingga 65.536 token output (streaming atau non-streaming). Untuk memperluas output single-turn hingga 1.048.576 token (dikurangi token input) di Interactions API atau GenerateContent (v1beta1), lihat Dekode panjang.
  • Context caching: Cache konteks eksplisit tidak didukung. Caching implisit (dengan caching tahan lama yang diaktifkan secara default) diterapkan secara otomatis ke awalan perintah bersama yang berisi 4.096 token atau lebih, jadi tempatkan konten statis di awal perintah Anda.
  • Input Office dan OpenDocument: Teruskan file 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), dan spreadsheet Excel atau OpenDocument (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/vnd.oasis.opendocument.spreadsheet) secara inline atau melalui Cloud Storage URI (gs://) menggunakan inlineData atau fileData pada input GenerateContent (termasuk di dalam bagian FunctionResponse) dan document (termasuk hasil alat) di Interactions API.
  • Video agentic: Video yang diupload ditetapkan secara default ke media_processing="static". Tetapkan media_processing="agentic" untuk mengaktifkan pemrosesan video agentic.
  • Penghitungan dan penagihan token: Setiap token yang diproses model akan dihitung dan ditagih, termasuk token penalaran dan petunjuk sistem alat internal serta deklarasi fungsi saat menggunakan grounding. Grounding dengan Google Penelusuran juga tetap ditagih per kueri.

Parameter, panggilan fungsi, dan validasi chat

Hydrogen menerapkan aturan berikut untuk parameter pembuatan, panggilan alat, tanda tangan pemikiran, dan histori percakapan:

  • Parameter sampling yang diabaikan (temperature, top_k, top_p): Backend mengabaikan nilai kustom. Kontrol kedalaman penalaran dengan thinking_level, dan format output dengan response_schema.
  • Parameter yang tidak didukung (frequency_penalty, presence_penalty, dan candidate_count lebih besar dari 1): Meneruskan frequency_penalty, presence_penalty, atau candidate_count lebih besar dari 1 (candidateCount ditetapkan pada 1) akan menampilkan error HTTP 400. Hapus parameter ini dari permintaan Anda.
  • Panggilan fungsi dan tanda tangan pemikiran: Deklarasi alat, panggilan alat paralel, dan replay thought_signature multi-turn mengikuti aturan berikut:

    • Simetri belokan: Setiap FunctionResponse harus cocok dengan id, name, dan urutan FunctionCall sebelumnya.
    • Bagian FunctionResponse multimodal: Sertakan dokumen Office, spreadsheet, presentasi, PDF, gambar, audio, dan video di dalam bagian FunctionResponse multimodal (atau hasil alat di Interactions API), bukan menambahkannya sebagai bagian giliran pengguna yang terpisah.
    • Penempatan thought_signature panggilan fungsi paralel: Saat model memancarkan beberapa bagian functionCall paralel dalam satu giliran model, hanya bagian functionCall pertama yang berisi thought_signature. Menghilangkan thought_signature dari bagian functionCall pertama dalam giliran pengguna aktif, menduplikasinya ke bagian functionCall paralel berikutnya, atau menyisipkan giliran functionCall dan functionResponse akan menampilkan error HTTP 400; simpan semua bagian functionCall paralel dalam satu giliran model yang diikuti oleh semua bagian functionResponse yang cocok dalam satu giliran user. Untuk mengetahui detailnya, lihat Tanda tangan pemikiran.
    • Pelestarian thought_signature lintas giliran: Teruskan kembali setiap thought_signature di dalam Part aslinya di semua giliran sebelumnya dalam histori percakapan multi-turn (baik bagian functionCall maupun text akhir), bukan hanya dalam giliran pengguna aktif. Meskipun validasi tanda tangan 400 HTTP hanya berlaku untuk langkah-lang6kah functionCall dalam giliran pengguna aktif, menghapus nilai thought_signature dari giliran sebelumnya atau mengganti nilai bypass seperti skip_thought_signature_validator akan menghapus konteks penalaran, menurunkan kualitas output, dan dapat menyebabkan alasan penyelesaian MALFORMED_FUNCTION_CALL.
    • Pemformatan pra-alat: Pisahkan petunjuk inline dengan \n\n dan hindari teks tidak terstruktur sebelum panggilan alat. Untuk mencatat status perantara sebelum panggilan alat, gunakan deklarasi fungsi khusus:

      {
        "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"]
        }
      }
      
  • Validasi urutan chat: Payload multi-turn chat menerapkan batasan berikut:

    • Payload histori tidak boleh diakhiri dengan giliran peran model.
    • Respons model yang telah disiapkan tidak didukung.

Dekode panjang

Dekode panjang membagi pembuatan hingga 1.048.576 token (dikurangi token input Anda) di beberapa segmen pada Interactions API atau GenerateContent (v1beta1). Di Interactions API, setiap segmen latar depan (stream=true atau stream=false) menghasilkan hingga 65.536 token output dan menampilkan status="requires_continuation" dengan continuation_token terenkripsi, atau Anda dapat menetapkan background=true (store=true) sehingga server menjalankan loop lanjutan secara asinkron dan menyimpan output gabungan dalam satu Interaction. Di GenerateContent, setiap segmen streaming atau non-streaming menghasilkan hingga 65.536 token output sebelum memunculkan finish_reason=CONTINUATION dengan continuation_token, dan berlanjut hingga finish_reason=STOP. Di Agent Studio, menetapkan batas token output lebih besar dari 65.536 hingga 1.048.576 akan menangani token kelanjutan secara otomatis. Untuk contoh kode yang dapat dijalankan, lihat Contoh panduan memulai dekode panjang.

Kapan harus menggunakan dekode panjang

Sebagian besar permintaan selesai dalam batas output 65.536 token per segmen. Gunakan dekode panjang hanya jika satu respons memerlukan lebih banyak output dari itu. Dekode panjang memberi model lebih banyak ruang untuk penalaran; hal ini tidak membuat jawaban lebih panjang (gunakan thinking_level untuk mengontrol kedalaman penalaran).

Workload Gunakan dekode panjang? Mengapa
Matematika, sains, riset, dan bukti formal yang sulit Ya Model ini dapat menggunakan lebih dari 65.536 token untuk mengeksplorasi dan memeriksa penalarannya.
Tugas coding dan agentic tersulit Ya Beberapa tugas memerlukan lebih dari 65.536 token penalaran dan kode dalam satu respons. Sebagian besar tugas coding dan agentic selesai dalam waktu kurang dari 65.536 token.
Harness evaluasi yang berhenti pada batas output Ya Dekode panjang mencegah jawaban terpotong saat model menghabiskan seluruh segmen 65.536 token untuk penalaran.
Chat, Tanya Jawab, peringkasan, klasifikasi, dan ekstraksi Tidak Tugas-tugas ini selesai jauh di bawah 65.536 token.
Permintaan untuk panjang tetap, seperti "tulis buku berisi 700.000 kata" Tidak Model tidak mengikuti target panjang.
Agen yang memanggil alat dalam banyak giliran singkat Tidak Setiap giliran berlangsung singkat. Output yang besar pada setiap giliran akan dengan cepat mengisi batas input dan output terpadu sebesar 1.048.576 token.
Perintah yang mendekati batas input 1.048.576 token Tidak Output hanya dapat menggunakan 1.048.576 token dikurangi input Anda.
Permintaan yang sensitif terhadap latensi Tidak Dekode panjang dapat berjalan selama beberapa menit.

Memilih opsi kelanjutan

Pilih pola kelanjutan berdasarkan platform API, postur penyimpanan, dan lingkungan runtime Anda. Semua opsi dalam tabel berikut mencapai batas 1.048.576 token yang sama (dikurangi token input) di gemini-4-hydrogen.

Opsi lanjutan Platform API Siapa yang memulai setiap segmen Token per segmen Batas waktu per permintaan Penyimpanan server Paling cocok untuk
Lanjutan otomatis Google Gen AI SDK (direkomendasikan) Interactions API (v1beta1) Google Gen AI SDK: Python (google-genai >= 2.34.0), JavaScript/TypeScript (@google/genai >= 2.32.0), Go (>= 1.77.0), dan Java (>= 1.80.0) Hingga 65.536 (stream=true atau stream=false) 20 menit per segmen Penyimpanan server 7 hari secara default (store=true), atau tidak ada (store=false) Sebagian besar aplikasi Interactions API stateful atau stateless
Loop latar belakang yang dikelola server (background=true) Interactions API (v1beta1) Loop server Agent Platform; kode Anda melakukan polling get Dikelola di sisi server hingga max_output_tokens Asinkron (tidak memerlukan streaming klien terbuka) Penyimpanan server 7 hari (diperlukan store=true) Tugas asinkron, pemanggil .NET/Kotlin, dan persistensi data tunggal
Loop tersimpan latar depan kustom (store=true) Interactions API (v1beta1) Kode Anda (previous_interaction_id + continuation_token, tanpa input) Hingga 65.536 (stream=true atau stream=false; checkpoint dimulai dari 65.536 dan setiap 5.000 token setelahnya) 20 menit per segmen Penyimpanan server 7 hari (store=true) Pemanggil REST dan pemulihan checkpoint kustom
Loop stateless latar depan kustom (store=false) Interactions API (v1beta1) Kode Anda (input + continuation_token asli, tanpa previous_interaction_id) Hingga 65.536 (stream=true atau stream=false; checkpoint dimulai dari 65.536 dan setiap 5.000 token setelahnya) 20 menit per segmen Tidak ada penyimpanan server (alur kerja Tanpa Retensi Data) Harness REST kustom yang memerlukan eksekusi stateless
Lanjutan otomatis Google Gen AI SDK (direkomendasikan) GenerateContent (v1beta1) Google Gen AI SDK: Python (>= 2.30.1), JavaScript/TypeScript (>= 2.29.1), Go (>= 1.74.0), Java (>= 1.77.0), .NET (>= 1.26.0), dan Kotlin (>= 1.6.0) Hingga 65.536 (generate_content_stream atau generate_content) 20 menit per segmen Tidak ada penyimpanan server (alur kerja Tanpa Retensi Data) Aplikasi GenerateContent yang sudah ada
Loop kelanjutan kustom GenerateContent (v1beta1) Kode Anda (contents + continuation_token asli) Hingga 65.536 (streamGenerateContent atau generateContent; checkpoint dimulai dari 65.536 dan setiap 5.000 token setelahnya) 20 menit per segmen Tidak ada penyimpanan server (alur kerja Tanpa Retensi Data) Pemanggil GenerateContent REST langsung dan harness evaluasi

Persyaratan versi API dan SDK

Dekode panjang memerlukan versi API dan versi SDK minimum berikut:

  • Persyaratan v1beta1 API (masalah umum): Dekode panjang (continuation_token) di Interactions API dan GenerateContent (generateContent dan streamGenerateContent) hanya didukung di v1beta1 API (bukan v1) di Agent Platform. Google Gen AI SDK menggunakan v1beta1 secara default, kecuali jika api_version='v1' ditentukan di http_options (atau api_version="v1" di interactions.create); untuk panggilan REST langsung, gunakan jalur endpoint /v1beta1/.
  • Versi SDK dan kompatibilitas OpenAI: Untuk melanjutkan otomatis di Interactions API, upgrade ke Python google-genai >= 2.34.0, JavaScript/TypeScript @google/genai >= 2.32.0, Go >= 1.77.0, atau Java >= 1.80.0 (untuk .NET dan Kotlin di Interactions API, gunakan background=true atau loop kelanjutan kustom). Untuk melanjutkan otomatis di GenerateContent, upgrade ke Python >= 2.30.1, JavaScript/TypeScript >= 2.29.1, Go >= 1.74.0, Java >= 1.77.0, .NET >= 1.26.0, atau Kotlin >= 1.6.0. Versi SDK yang lebih lama dan lapisan kompatibilitas OpenAI tidak dapat mengambil penyelesaian panjang menggunakan token lanjutan.

Aturan kelanjutan Interactions API

Transisi status, aturan perantaian, dan perilaku penyimpanan berikut berlaku untuk dekode panjang di Interactions API.

Nilai status dan anggaran token output

Jika generation_config.max_output_tokens dihilangkan pada permintaan Interactions API, total anggaran output ditetapkan secara default ke 65.536 token (sesuai dengan batas latar depan segmen tunggal 65.536 token untuk permintaan streaming dan non-streaming). Tetapkan generation_config.max_output_tokens lebih besar dari 65,536 (hingga 1,048,576 dikurangi token input) untuk dekode panjang multi-segmen dalam mode latar depan dan background=true. Server menampilkan nilai status berikut:

  • requires_continuation: Batas output 65.536 token per segmen tercapai sebelum max_output_tokens; teruskan continuation_token yang ditampilkan pada permintaan berikutnya untuk melanjutkan decoding.
  • incomplete: Total anggaran max_output_tokens telah habis; melanjutkan dengan continuation_token tanpa menaikkan max_output_tokens akan menampilkan error HTTP 400 (max_output_tokens has already been exhausted). Tingkatkan max_output_tokens pada permintaan berikutnya untuk melanjutkan decoding.
  • completed: Pembuatan selesai secara alami dan continuation_token dihapus.

Penautan, pengalihan mode, dan penyimpanan segmen

Permintaan kelanjutan di Interactions API menerapkan aturan berikut:

  • Stored continuation (store=true, default): Teruskan previous_interaction_id yang ditetapkan ke segmen id yang mengeluarkan continuation_token bersama dengan continuation_token, dan hilangkan input (segmen yang disimpan sudah menyimpan input giliran). Selalu pasangkan setiap continuation_token dengan previous_interaction_id segmen yang mengeluarkannya; meneruskan continuation_token pada interaksi yang sudah completed akan menampilkan error HTTP 400.
  • Kelanjutan stateless (store=false): Hilangkan previous_interaction_id dan kirim ulang input asli bersama dengan continuation_token di setiap segmen.
  • Beralih mode store di seluruh segmen: Anda dapat beralih dari mode tersimpan (store=true) ke mode stateless (store=false) di tengah proses dekode dengan menghilangkan previous_interaction_id dan mengirim ulang input asli dengan continuation_token. Beralih dari stateless (store=false) ke tersimpan (store=true) tidak didukung karena tidak ada interaksi induk tersimpan untuk previous_interaction_id.
  • Peralihan dan percabangan mode latar depan dan background=true: Kelanjutan yang disimpan (store=true) dapat beralih antara eksekusi latar depan (background=false) dan latar belakang (background=true) di seluruh segmen, termasuk melanjutkan interaksi background=true yang dibatalkan dari checkpoint-nya continuation_token (dipertahankan mulai dari 65.536 token output dan setiap 5.000 token setelahnya) dalam mode latar belakang atau latar depan. Menggunakan kembali previous_interaction_id dan continuation_token yang sama akan membuat kelanjutan cabang yang independen.
  • Penegakan batas giliran: Memulai giliran pengguna baru (previous_interaction_id dengan input baru dan tanpa continuation_token) dari segmen yang statusnya requires_continuation atau incomplete akan menampilkan error HTTP 400. Selesaikan melanjutkan dekode ke completed, atau buat cabang giliran berikutnya dari interaksi completed terbaru. Setelah segmen terakhir mencapai completed, meneruskan id segmen terakhir tersebut sebagai previous_interaction_id akan merekonstruksi histori percakapan lengkap di semua segmen sebelumnya.
  • Konsistensi parameter di seluruh segmen: Mengubah model, system_instruction, atau deklarasi fungsi (tools) pada segmen lanjutan akan menampilkan error HTTP 400. Jangan ubah thinking_level dan alat bawaan di seluruh segmen (lihat Masalah umum).
  • Perilaku get, list, dan delete segmen tunggal: Dalam mode latar depan (background=false), setiap segmen disimpan sebagai resource Interaction terpisah (interactions.get(id) hanya menampilkan segmen tersebut, interactions.list() mencantumkan setiap segmen secara terpisah, dan interactions.delete(id) hanya menghapus segmen tersebut; saat menghapus rantai segmen, hapus dalam urutan terbalik dari segmen terakhir ke belakang). Di Google Gen AI SDK dengan automatic_continuation=True (stream=False), interactions.create() menggabungkan semua segmen saat ditampilkan dan mengisi interaction.continuation_ids dengan ID segmen yang diurutkan (diakhiri dengan interaction.id). Jika segmen berikutnya gagal, melebihi timeout numerik per panggilan, atau terhenti di tengah streaming setelah melewati checkpoint yang dapat dilanjutkan, SDK akan memunculkan ContinuationInterruptedError yang membawa partial_interaction, continuation_token, interaction_id, dan continuation_ids sehingga Anda dapat melanjutkan dari continuation_token.

Aturan loop kustom GenerateContent

Dalam loop kelanjutan GenerateContent kustom, ikuti aturan berikut:

  • Tetapkan max_output_tokens lebih besar dari 65.536 (hingga 1.048.576), dan kirim ulang contents, system_instruction, dan tools asli pada setiap permintaan lanjutan bersama dengan continuation_token terbaru (kolom tingkat teratas pada GenerateContentRequest di REST, atau di GenerateContentConfig di Google Gen AI SDK).
  • Jangan menambahkan output model parsial ke dalam contents atau mengirim perintah lanjutan yang meminta model untuk melanjutkan.
  • Lanjutkan pengulangan selama finish_reason adalah CONTINUATION dan continuation_token ada, meskipun segmen menghabiskan semua 65.536 token untuk penalaran (parts: [{"text": ""}]). Jika finish_reason adalah MAX_TOKENS saat continuation_token ada, naikkan max_output_tokens dalam permintaan berikutnya.
  • Gabungkan bagian yang terakumulasi menjadi satu giliran model untuk histori multi-giliran hanya setelah STOP.

Penghitungan token, pemadatan, dan penyimpanan dalam cache implisit

Penghitungan dan penyimpanan token dalam cache di seluruh segmen lanjutan berfungsi sebagai berikut:

  • Di Interactions API, panggilan interactions.create() non-streaming dengan automatic_continuation=True dan interaksi background=true yang dikelola server menjumlahkan jumlah token di semua segmen dalam usage (total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens, total_tokens), mempertahankan jumlah prompt segmen pertama di usage.initial_input_tokens. Dalam loop latar depan kustom dan peristiwa interaction.completed yang di-streaming, usage setiap segmen hanya melaporkan delta segmen tersebut, jadi jumlahkan kolom usage di seluruh segmen untuk total token yang ditagih.
  • Di GenerateContent, Python Google Gen AI SDK (generate_content dan generate_content_stream) mengakumulasikan total token yang ditagih di seluruh segmen dalam usage_metadata akhir dan mempertahankan initial_prompt_token_count. Dalam loop REST kustom, jumlahkan prompt_token_count, cached_content_token_count, candidates_token_count, dan thoughts_token_count akhir di seluruh segmen.
  • Karena setiap segmen kelanjutan latar depan mengisi ulang percakapan dan token yang dihasilkan sebelumnya sebagai input, usage.total_input_tokens (di Interactions API) dan prompt_token_count (di GenerateContent) meningkat di seluruh segmen. Jangan gunakan jumlah input kumulatif untuk memicu pemadatan konteks di infrastruktur pengelola agen; sebagai gantinya, periksa usage.initial_input_tokens (atau initial_prompt_token_count di GenerateContent) dan padatkan hanya setelah giliran selesai (status="completed" atau tidak ada continuation_token).
  • Setiap segmen kelanjutan akan mengisi ulang perintah ditambah token yang didekode sebelumnya dan otomatis memenuhi syarat untuk cache konteks implisit (minimum 4.096 token, dengan cache tahan lama diaktifkan secara default) saat segmen berjalan secara berurutan. Segmen yang telah selesai akan ditagih pada akhir setiap segmen, meskipun segmen berikutnya gagal atau dibatalkan.

Bermigrasi ke Hydrogen dari 3.8 Flash

Perilaku berikut berbeda dari gemini-3.8-flash dan model Gemini 3 Flash sebelumnya:

  • Hydrogen memiliki batas 1.048.576 token terpadu di seluruh input dan output (dengan output mencakup penalaran, panggilan fungsi, dan respons akhir), bukan batas input dan output yang terpisah. Output latar depan segmen tunggal dibatasi hingga 65.536 token (streaming atau non-streaming), dan dapat diperluas hingga 1.048.576 token menggunakan dekode panjang di Interactions API atau GenerateContent (ditangani secara otomatis di Google Gen AI SDK, dengan background=true di Interactions API, atau menggunakan continuation_token dalam loop kustom).
  • thinking_level default adalah HIGH (diubah dari MEDIUM pada gemini-3.8-flash), dan XHIGH didukung untuk tugas penalaran mendalam (sisakan headroom pemadatan konteks untuk trace penalaran HIGH dan XHIGH dalam harness coding multi-giliran, atau tetapkan MEDIUM pada giliran yang sensitif terhadap latensi). thinking_budget dan thinking_level="MINIMAL" menampilkan error HTTP 400.
  • Penyimpanan cache konteks eksplisit (cached_content) tidak didukung. Caching implisit diterapkan secara otomatis pada minimum 4.096 token (dikurangi dari 6.144 token di gemini-3.8-flash), dengan caching tahan lama diaktifkan secara default.
  • File Microsoft Office (.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) dan OpenDocument (.odt, .odp, .ods) didukung secara inline atau melalui Cloud Storage URI (gs://), termasuk di dalam bagian FunctionResponse multimodal.
  • Giliran pemanggilan fungsi paralel menerapkan penempatan thought_signature yang ketat (hanya bagian functionCall pertama dalam giliran paralel yang membawa thought_signature; menghilangkannya dalam giliran aktif atau menduplikasikannya ke bagian functionCall yang setara berikutnya akan menampilkan error HTTP 400), dan pengeditan awalan perintah model yang sama akan gagal dengan HTTP 400 secara default, kecuali jika prefix_mismatch_behavior="DROP" ditetapkan di ThinkingConfig. Pertahankan bagian thought_signature di semua giliran sebelumnya juga (baik bagian functionCall maupun text akhir) untuk menjaga kualitas penalaran dan menghindari alasan penyelesaian MALFORMED_FUNCTION_CALL.
  • Setiap token yang diproses model akan ditagih, termasuk petunjuk sistem alat internal dan deklarasi fungsi saat menggunakan grounding.

Untuk perbandingan berdampingan, lihat Bermigrasi dari model 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
         ),
     ),
 )

Untuk bermigrasi dari model Gemini 3 Flash gemini-3.8-flash atau yang lebih lama, lakukan hal berikut:

  1. Perbarui ID model menjadi gemini-4-hydrogen.
  2. Upgrade ke Google Gen AI SDK terbaru dan perhitungkan batas token input dan output terpadu: Upgrade ke google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0, atau Java >= 1.80.0 untuk melanjutkan otomatis Interactions API (atau >= 2.30.1 Python/>= 2.29.1 JavaScript di GenerateContent). Token input dan output (termasuk pemikiran dan panggilan fungsi) menggunakan batas token terpadu sebesar 1.048.576 token. Untuk output yang melebihi 65.536 token (hingga 1.048.576 token) di Interactions API atau GenerateContent, tetapkan max_output_tokens lebih besar dari 65.536 agar Google Gen AI SDK berlanjut secara otomatis di seluruh segmen (atau gunakan background=true atau loop continuation_token kustom).
  3. Perbarui konfigurasi thinking_level: Ganti thinking_budget dan MINIMAL dengan thinking_level yang ditetapkan ke LOW, MEDIUM, HIGH (default di gemini-4-hydrogen), atau XHIGH (gunakan huruf kecil "low", "medium", "high", atau "xhigh" di Interactions API). Jika workload Anda mengandalkan MEDIUM sebagai default di gemini-3.8-flash, tetapkan thinking_level="MEDIUM" secara eksplisit untuk mempertahankan latensi penalaran yang setara.
  4. Hapus caching eksplisit dan muat konten perintah statis di awal (4.096 token atau lebih) untuk caching implisit otomatis.
  5. Verifikasi pemeliharaan thought_signature multi-turn dan paralel serta pemadatan awalan: Pertahankan thought_signature di semua giliran sebelumnya (baik bagian functionCall maupun text akhir) daripada menghapus tanda tangan di antara giliran, pertahankan thought_signature hanya pada bagian functionCall pertama dari giliran panggilan alat paralel, dan tetapkan prefix_mismatch_behavior="DROP" di ThinkingConfig jika aplikasi Anda mengubah atau memadatkan giliran sebelumnya dalam histori chat multi-turn.
  6. Hapus parameter yang tidak berpengaruh atau tidak didukung: Hapus kolom pembuatan yang diabaikan dan ditolak sebagai berikut:
    • Hapus temperature, top_p, dan top_k, yang diabaikan.
    • Hapus frequency_penalty, presence_penalty, dan nilai candidate_count yang lebih besar dari 1.
    • Hapus semua respons model yang telah disiapkan dari histori percakapan.

Checklist ringkasan untuk developer

Gunakan checklist berikut untuk memverifikasi integrasi Hydrogen Anda:

Masalah umum

Masalah umum berikut berlaku untuk dekode panjang Hydrogen:

  • Dekode panjang memerlukan v1beta1: Dekode panjang (continuation_token) di Interactions API dan GenerateContent API (generateContent dan streamGenerateContent) hanya didukung di v1beta1 API (bukan v1) di Agent Platform. Google Gen AI SDK menggunakan v1beta1 secara default, kecuali jika api_version='v1' ditetapkan di http_options (atau api_version="v1" di interactions.create); untuk panggilan REST langsung, gunakan jalur endpoint /v1beta1/.
  • Perubahan parameter di seluruh segmen kelanjutan Interactions API: Mengubah model, system_instruction, atau deklarasi fungsi di seluruh segmen kelanjutan akan menampilkan error HTTP 400, sedangkan perubahan di tengah dekode pada generation_config.thinking_level atau alat bawaan (google_search, code_execution, url_context) tidak ditolak oleh validasi server. Pertahankan thinking_level dan alat bawaan agar tidak berubah di semua segmen loop kelanjutan.

Referensi lainnya

Untuk mengetahui informasi selengkapnya tentang Hydrogen, lihat referensi berikut: