מדריך למפתחים: Gemini 4 Hydrogen

‫Gemini 4 Hydrogen מביא יכולות AI מתקדמות ופורצות דרך במהירות וביעילות לתכנות יומיומי ולתהליכי עבודה אג'נטיים בארגון.

במסמך הזה נסביר על היכולות העיקריות של Hydrogen, על מוסכמות ה-API שהוא אוכף, על איך לעבור אליו מ-Gemini 3.8 Flash וממודלים קודמים של Gemini 3 Flash, ועל התחלה מהירה. איך מתחילים לעבוד עם Gemini 4

היכולות העיקריות של Gemini 4 Hydrogen

‫Gemini 4 Hydrogen כולל את היכולות הבאות:

  • מגבלה אחידה על טוקנים של קלט ופלט: ל-Hydrogen יש מגבלה אחידה של 1,048,576 טוקנים, שכוללת גם טוקנים של קלט וגם טוקנים של פלט (הפלט כולל חשיבה, קריאה להפעלת פונקציות ואת התשובה הסופית).
  • פענוח ארוך של עד 1,048,576 טוקנים: Hydrogen מרחיב את היצירה מעבר לפלח חזיתי יחיד של 65,536 טוקנים (בסטרימינג או לא בסטרימינג) עד ל-1,048,576 טוקנים (פחות טוקני הקלט) גם ב-Interactions API וגם ב-GenerateContent (v1beta1). Google Gen AI SDK מטפל ב-continuation_token באופן אוטומטי בין הפלחים, או שאפשר להריץ פענוחים אסינכרוניים ברקע שמנוהלים על ידי השרת (background=true) או לנהל את continuation_token בלולאת המשך מותאמת אישית.
  • רמות חשיבה: ‏Hydrogen תומך ב-LOW, ב-MEDIUM, ב-HIGH (ברירת המחדל) וב-XHIGH.
  • שמירה במטמון באופן משתמע עם שמירה עמידה במטמון: שמירה במטמון באופן משתמע חלה באופן אוטומטי על תחיליות משותפות של הנחיות עם 4,096 טוקנים או יותר, והשמירה העמידה במטמון מופעלת כברירת מחדל. אין תמיכה בשמירת הקשר במטמון באופן מפורש.
  • קלט של קובצי Office ו-OpenDocument: בנוסף ל-PDF ולטקסט פשוט, Hydrogen מקבל קובצי Microsoft Office (.docx,‏ .dotx,‏ .doc,‏ .pptx,‏ .ppt,‏ .xlsx,‏ .xls) ו-OpenDocument (.odt,‏ .odp,‏ .ods) מוטמעים או מ-Cloud Storage גם ב-GenerateContent וגם ב-Interactions API, כולל בתוך חלקים FunctionResponse מולטי-מודאליים.
  • הבנת וידאו מבוססת-סוכן: התכונה זמינה לכלל המשתמשים (GA) ומושבתת כברירת מחדל.
  • מחזור חיים קצר של גרסאות: גרסת Hydrogen היא גרסה לטווח קצר שזמינה לכלל המשתמשים (GA), וכפופה למדיניות של הודעה על הוצאה משימוש לפחות 45 ימים מראש. לפרטים על מחזור החיים, קראו את המאמר גרסאות ומחזור החיים של המודלים.

מדריך למתחילים

לפני שמתחילים, צריך לאמת את Gemini Enterprise Agent Platform באמצעות פרטי כניסה של ברירת מחדל של אפליקציה (ADC) או מפתח API. מידע נוסף זמין במאמר תחילת העבודה עם Agent Platform.

בבלוקים הבאים של הקוד, מחליפים את PROJECT_ID במזהה הפרויקט.

רוצה לנסות את זה ב-Agent Studio?

כדי לבדוק הנחיות ולהגדיר את gemini-4-hydrogen בממשק המשתמש של Agent Studio:

  1. פותחים את Agent Studio בפרויקט Google Cloud ובוחרים באפשרות gemini-4-hydrogen בקבוצת Gemini.
  2. בקטע Model settings, קובעים את ההגדרות הבאות:
    • רמת ההעמקה: בוחרים באפשרות Low,‏ Medium,‏ High (ברירת המחדל) או Extra high.
    • אזור: בוחרים באפשרות Global,‏ us או eu.
    • ‫Output token limit: הגדירו ערך בין 32,768 ל-1,048,576 (ברירת המחדל היא 1,048,576). ‫Agent Studio מטפל באופן אוטומטי בטוקנים להמשך לתשובות שחורגות מהמגבלה של בקשה אחת.

התקנה

משדרגים לגרסה העדכנית של Google Gen AI SDK. כדי להמשיך באופן אוטומטי ב-Interactions API, צריך להשתמש ב-google-genai >= 2.34.0 ב-Python, ב-@google/genai >= 2.32.0 ב-JavaScript או ב-TypeScript, ב->= 1.77.0 ב-Go או ב->= 1.80.0 ב-Java (ב-GenerateContent, כדי להמשיך באופן אוטומטי צריך להשתמש ב->= 2.30.1 ב-Python, ב->= 2.29.1 ב-JavaScript או ב-TypeScript, ב->= 1.74.0 ב-Go, ב->= 1.77.0 ב-Java, ב->= 1.26.0 ב-‎ .NET או ב->= 1.6.0 ב-Kotlin):

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

בקשה בסיסית

שולחים בקשה אל gemini-4-hydrogen באמצעות Google Gen AI SDK או 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"
    }
  }
}'

פלט מובנה

כדי ליצור פלט 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() עוקבת באופן אוטומטי אחרי continuation_token בין מקטעים בכל פעם שמקטע מחזיר status="requires_continuation". אפשר גם לבטל את ההסכמה (automatic_continuation=False) כדי להריץ לולאה מותאמת אישית עם שמירת מצב (store=True) או ללא שמירת מצב (store=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 (בלי שמירת מצב)

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

כדי להפעיל באופן אסינכרוני בניהול השרת (background=True עם store=True) או לשחזר מנקודות ביקורת בסטרימינג (אירועי interaction.status_update שנוצרים החל מ-65,536 טוקנים של פלט וכל 5,000 טוקנים לאחר מכן), משתמשים בתבניות הבאות:

‫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) לבקשות סטרימינג או לבקשות שאינן סטרימינג. ‫Google Gen AI SDK עוקב באופן אוטומטי אחרי continuation_token בין מקטעים כש-finish_reason מוגדר כ-CONTINUATION (כדי לבטל את ההסכמה, מגדירים את automatic_continuation=False ב-GenerateContentConfig), או שאפשר להעביר את 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 תומך בארבעה ערכי thinking_level (thinking_budget ו-MINIMAL מחזירים שגיאת אימות HTTP 400). בטבלה הבאה מפורטות רמות החשיבה ועומסי העבודה המומלצים לכל אחת מהן:

רמת ההעמקה עומסי עבודה מומלצים
XHIGH חשיבה רציונלית מעמיקה, הוכחות מתמטיות, ניתוח מדעי ומשימות הנדסת תוכנה מורכבות ביותר עם כמה קבצים.
‫HIGH (ברירת המחדל במכשיר gemini-4-hydrogen) לולאות של כלים אג'נטיים עם כמה שלבים, יצירת קוד, ארגון מחדש של ארכיטקטורה וניתוח מולטי-מודאלי מורכב.
MEDIUM תכנות כללי, שימוש בכלים, שאלות ותשובות לגבי מסמכים והבנת סרטונים עם זמן אחזור מאוזן.
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 טוקנים של פלט (בסטרימינג או לא בסטרימינג). כדי להרחיב את הפלט של פנייה אחת עד 1,048,576 טוקנים (פחות טוקנים של קלט) ב-Interactions API או ב-GenerateContent (v1beta1), קראו את המאמר פענוחים ארוכים.
  • שמירת הקשר במטמון: אין תמיכה בשמירת הקשר מפורשת במטמון. שמירה במטמון באופן משתמע (עם שמירה במטמון לטווח ארוך שמופעלת כברירת מחדל) חלה באופן אוטומטי על תחיליות משותפות של הנחיות עם 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) בתוך השורה או באמצעות URI של Cloud Storage‏ (gs://) באמצעות inlineData או fileData ב-GenerateContent (כולל בתוך חלקי FunctionResponse) וקלט של document (כולל תוצאות של כלים) ב-Interactions API.
  • סרטון עם סוכן: סרטונים שהועלו מוגדרים כברירת מחדל ל-media_processing="static". מגדירים את media_processing="agentic" כדי להפעיל עיבוד וידאו מבוסס-סוכנים.
  • ספירת טוקנים וחיוב: כל טוקן שהמודל מעבד נספר ומחויב, כולל טוקנים של חשיבה, הוראות מערכת של כלים פנימיים והצהרות על פונקציות כשמשתמשים ב-grounding. גם החיוב על עיגון באמצעות חיפוש Google נשאר לפי שאילתה.

פרמטרים, קריאה להפעלת פונקציות ואימות צ'אט

‫Hydrogen אוכף את הכללים הבאים לגבי פרמטרים של יצירה, קריאות API לכלים, חתימות מחשבה והיסטוריית צ'אט:

  • ‫Ignored sampling parameters (temperature, top_k, top_p): ה-backend מתעלם מערכים מותאמים אישית. אפשר לשלוט בעומק החשיבה באמצעות 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 חייב להתאים לid, לname ולסדר של הFunctionCall הקודם.
    • חלקים FunctionResponse: כוללים מסמכי Office, גיליונות אלקטרוניים, מצגות, קובצי PDF, תמונות, אודיו ווידאו בתוך חלקים FunctionResponse (או תוצאות של כלים ב-Interactions API) במקום לצרף אותם כחלקים נפרדים של פניית המשתמש.
    • מיקום thought_signature בקריאה להפעלת פונקציות במקביל: כשהמודל פולט כמה חלקים של functionCall במקביל בתור אחד של model, רק החלק הראשון של functionCall מכיל את thought_signature. אם משמיטים את thought_signature מהחלק הראשון של functionCall בתור של המשתמש הפעיל, משכפלים אותו לחלקים מקבילים של functionCall או משלבים בין תורות של functionCall ו-functionResponse, תוחזר שגיאת HTTP‏ 400. צריך לשמור את כל החלקים המקבילים של functionCall בתור אחד של model, ואחריו את כל החלקים התואמים של functionResponse בתור אחד של user. פרטים נוספים מופיעים במאמר חתימות של מחשבות.
    • שמירה על thought_signature בין פניות: צריך להחזיר כל thought_signature בתוך ה-Part המקורי שלו בכל הפניות הקודמות בהיסטוריית השיחה עם הזיכרון (גם בחלקים של functionCall וגם בחלקים הסופיים של text), ולא רק בפניית המשתמש הפעיל. למרות שאימות החתימה של HTTP 400 חל רק על שלבי functionCall בתור של המשתמש הפעיל, הסרת ערכי thought_signature מתורים קודמים או החלפת ערכי מעקף כמו skip_thought_signature_validator מסירה את ההקשר של החשיבה, פוגעת באיכות הפלט ויכולה לגרום לסיבות סיום של MALFORMED_FUNCTION_CALL.
    • עיצוב לפני הכלי: מפרידים בין ההוראות המוטבעות באמצעות \n\n ונמנעים מטקסט לא מובנה לפני קריאות API לכלי. כדי לתעד מצב ביניים לפני קריאת API לכלי, משתמשים בהצהרת פונקציה ייעודית:

      {
        "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"]
        }
      }
      
  • אימות רצף הצ'אט: המטענים הייעודיים (payloads) של שיחה עם זיכרון אוכפים את המגבלות הבאות:

    • היסטוריית המידע לא יכולה להסתיים בתור של תפקיד model.
    • אין תמיכה בתשובות מודל מאוכלסות מראש.

פענוחים ארוכים

פענוח ארוך מפצל את היצירה של עד 1,048,576 טוקנים (פחות טוקני הקלט) לכמה קטעים ב-Interactions API או ב-GenerateContent (v1beta1). ב-Interactions API, כל קטע בחזית (stream=true או stream=false) יוצר עד 65,536 טוקני פלט ומחזיר את status="requires_continuation" עם continuation_token מוצפן, או שאפשר להגדיר את background=true (store=true) כדי שהשרת יריץ את לולאת ההמשך באופן אסינכרוני ויאחסן את הפלט הממוזג ב-Interaction אחד. ב-GenerateContent, כל קטע בסטרימינג או לא בסטרימינג יוצר עד 65,536 אסימוני פלט לפני שהוא פולט את finish_reason=CONTINUATION עם continuation_token, וממשיך עד finish_reason=STOP. ב-Agent Studio, אם מגדירים את מגבלת הטוקנים של הפלט ליותר מ-65,536 ועד 1,048,576, המערכת מטפלת בטוקנים של המשך באופן אוטומטי. במדריך למתחילים בנושא פענוח ארוך יש דוגמאות קוד שאפשר להריץ.

מתי כדאי להשתמש בפענוח ארוך

רוב הבקשות מסתיימות במסגרת מגבלת הפלט של 65,536 טוקנים לכל קטע. השתמשו בפענוח ארוך רק אם תשובה אחת צריכה פלט ארוך יותר. פענוח ארוך נותן למודל יותר מקום להסקת מסקנות, אבל לא מאריך את התשובות (אפשר להשתמש ב-thinking_level כדי לשלוט בעומק הסקת המסקנות).

עומס עבודה להשתמש בפענוח ארוך? למה לבחור ב-
מתמטיקה, מדע, מחקר והוכחות פורמליות ברמה גבוהה כן המודל יכול להשתמש ביותר מ-65,536 טוקנים כדי לבדוק את תהליך החשיבה שלו.
משימות התכנות והמשימות האג'נטיות הכי קשות כן יש משימות שדורשות יותר מ-65,536 טוקנים של חשיבה וקוד בתשובה אחת. רוב משימות התכנות והמשימות של הסוכנים מסתיימות בפחות מ-65,536 טוקנים.
כלי הערכה שעוצרים במגבלת הפלט כן פענוח ארוך מונע תשובות קטועות כשהמודל משתמש בקטע שלם של 65,536 טוקנים לחשיבה.
צ'אט, שאלות ותשובות, סיכום, סיווג וחילוץ לא המשימות האלה מסתיימות הרבה לפני שמגיעים ל-65,536 טוקנים.
בקשות לאורך קבוע, כמו "כתוב ספר באורך 700,000 מילים" לא המודל לא פועל לפי יעדי האורך.
נציגים שמשתמשים בכלים בהרבה פניות קצרות לא כל תור הוא קצר. פלט גדול בכל שלב ממלא במהירות את מגבלת הקלט והפלט המאוחדת של 1,048,576 טוקנים.
הנחיות שקרובות למגבלת הקלט של 1,048,576 טוקנים לא הפלט יכול להשתמש רק ב-1,048,576 טוקנים פחות הקלט שלכם.
בקשות שרגישות לזמן הטעינה לא פענוח ארוך יכול להימשך כמה דקות.

בחירת אפשרות להמשך

בוחרים תבנית המשך בהתאם לממשק ה-API, למצב האחסון ולסביבת זמן הריצה. כל האפשרויות בטבלה הבאה מגיעות לאותה מגבלה של 1,048,576 טוקנים (פחות טוקנים של קלט) ב-gemini-4-hydrogen.

אפשרות המשך פלטפורמת ה-API מי מתחיל כל קטע טוקנים לכל מקטע מגבלת זמן לכל בקשה נפח האחסון בשרת למי זה מתאים
המשך אוטומטי של Google Gen AI SDK (מומלץ) ‫Interactions API‏ (v1beta1) ‫Google Gen 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) רוב האפליקציות של 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 ושחזור נקודות ביקורת בהתאמה אישית
לולאה מותאמת אישית ללא שמירת מצב בחזית (store=false) ‫Interactions API‏ (v1beta1) הקוד שלך (input מקורי + continuation_token, ללא previous_interaction_id) עד 65,536 (stream=true או stream=false; נקודות ביקורת שמתחילות ב-65,536 וכל 5,000 טוקנים לאחר מכן) ‫20 דקות לכל מקטע אין אחסון בשרת (תהליכי עבודה של אפס שמירת נתונים) רתמות REST בהתאמה אישית שדורשות הפעלה ללא שמירת מצב (stateless)
המשך אוטומטי של Google Gen AI SDK (מומלץ) 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) ו-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 דקות לכל מקטע אין אחסון בשרת (תהליכי עבודה של אפס שמירת נתונים) ממשקי הערכה ומתקשרים ישירים ל-GenerateContent ב-REST

דרישות לגבי גרסת ה-API וערכת ה-SDK

כדי להשתמש בפענוח ארוך, צריך את גרסת ה-API הבאה ואת גרסאות ה-SDK המינימליות הבאות:

  • דרישת API של v1beta1 (בעיה ידועה): פענוח ארוך (continuation_token) גם ב-Interactions API וגם ב-GenerateContent (generateContent ו-streamGenerateContent) נתמך רק ב-API של v1beta1 (לא ב-v1) ב-Agent Platform. כברירת מחדל, Google Gen AI SDK משתמש ב-v1beta1, אלא אם צוין api_version='v1' ב-http_options (או ב-api_version="v1" ב-interactions.create). לקריאות REST ישירות, צריך להשתמש בנתיב נקודת הקצה (endpoint) של /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 (ב-NET .וב-Kotlin ב-Interactions API, השתמשו ב-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.

ערכי סטטוס ותקציב טוקנים לפלט

אם משמיטים את generation_config.max_output_tokens בבקשת Interactions API, תקציב הפלט הכולל מוגדר כברירת מחדל ל-65,536 טוקנים (בהתאם למגבלה של 65,536 טוקנים לפלח יחיד בחזית, גם לבקשות בסטרימינג וגם לבקשות שלא בסטרימינג). כדי להגדיר פענוח קוד ארוך עם כמה קטעים גם במצב חזיתי וגם במצב background=true, צריך להגדיר את generation_config.max_output_tokens כך שיהיה גדול מ-65,536 (עד 1,048,576 פחות טוקנים של קלט). השרת מחזיר את ערכי הסטטוס הבאים:

  • requires_continuation: הגענו למגבלת הפלט של 65,536 טוקנים לכל קטע לפני max_output_tokens. כדי להמשיך בפענוח, צריך להעביר את הערך continuation_token שהוחזר בבקשה הבאה.
  • ‫incomplete: התקציב הכולל של max_output_tokens נוצל. אם ממשיכים עם continuation_token בלי להגדיל את max_output_tokens, מוחזרת שגיאת HTTP‏ 400 (max_output_tokens has already been exhausted). כדי להמשיך בפענוח, צריך להגדיל את max_output_tokens בבקשה הבאה.
  • ‫completed: היצירה הסתיימה באופן טבעי והשדה continuation_token נמחק.

שרשור, החלפת מצבים ואחסון פלחים

בקשות המשך ב-Interactions API כפופות לכללים הבאים:

  • המשך מאוחסן (store=true, ברירת המחדל): מעבירים את previous_interaction_id שמוגדר לפלח id שהנפיק את continuation_token יחד עם continuation_token, ומשמיטים את input (הפלח המאוחסן כבר מכיל את הקלט של התור). תמיד צריך להתאים בין כל continuation_token לבין ה-previous_interaction_id של הפלח שהנפיק אותו. העברת continuation_token באינטראקציה שכבר completed מחזירה שגיאת HTTP 400.
  • המשך בלי שמירת מצב (store=false): משמיטים את previous_interaction_id ושולחים מחדש את input המקורי לצד continuation_token בכל מקטע.
  • מעבר בין מצבי store בין מקטעים: אפשר לעבור ממצב שמור (store=true) למצב בלי שמירת מצב (store=false) באמצע הפענוח על ידי השמטת previous_interaction_id ושליחה מחדש של input המקורי עם continuation_token. אי אפשר לעבור מאינטראקציה בלי שמירת מצב (store=false) לאינטראקציה עם שמירת מצב (store=true) כי אין אינטראקציה ראשית (parent) עם שמירת מצב בשביל previous_interaction_id.
  • מעבר בין מצב חזית למצב background=true והסתעפות: המשכים מאוחסנים (store=true) יכולים לעבור בין הפעלה בחזית (background=false) לבין הפעלה ברקע (background=true) בין מקטעים, כולל המשך של אינטראקציה מבוטלת ב-background=true מנקודת הבדיקה שלה continuation_token (נשמרת החל מ-65,536 טוקנים של פלט וכל 5,000 טוקנים לאחר מכן) במצב רקע או במצב חזית. שימוש חוזר באותם previous_interaction_id ו-continuation_token יוצר המשכים מסועפים בלתי תלויים.
  • אכיפת גבולות הפנייה: אם מתחילים פנייה חדשה של משתמש (previous_interaction_id עם input חדש וללא continuation_token) מקטע שהסטטוס שלו הוא requires_continuation או incomplete, מוחזרת שגיאת 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) מוחק רק את הפלח הזה. כשמוחקים שרשרת של פלחים, צריך למחוק בסדר הפוך, מהפלח האחרון אחורה). ב-Google Gen AI SDK עם automatic_continuation=True (stream=False), הפונקציה interactions.create() ממזגת את כל הקטעים בהחזרה ומאכלסת את interaction.continuation_ids במזהי הקטעים לפי הסדר (שמסתיים ב-interaction.id). אם קטע מאוחר יותר נכשל, חורג מ-timeout מספרי לכל קריאה או נמחק באמצע הסטרימינג אחרי שהתקדמתם מעבר לנקודת בדיקה שניתן להמשיך ממנה, ערכת ה-SDK מעלה את ContinuationInterruptedError עם partial_interaction, continuation_token, interaction_id ו-continuation_ids כדי שתוכלו להמשיך מ-continuation_token.

כללי לולאה מותאמים אישית של GenerateContent

בלולאת המשך מותאמת אישית של GenerateContent, צריך לפעול לפי הכללים הבאים:

  • מגדירים את max_output_tokens לערך שגדול מ-65,536 (עד 1,048,576), ושולחים מחדש את contents, system_instruction ו-tools המקוריים בכל בקשת המשך, יחד עם הערך האחרון של continuation_token (שדה ברמה העליונה ב-GenerateContentRequest ב-REST, או ב-GenerateContentConfig ב-Google Gen AI SDK).
  • אל תוסיפו פלט חלקי של המודל ל-contents ואל תשלחו הנחיית המשך כדי לבקש מהמודל להמשיך.
  • ממשיכים בלולאה כל עוד הערך של finish_reason הוא CONTINUATION ו-continuation_token קיים, גם אם קטע מסוים השתמש בכל 65,536 הטוקנים לחשיבה (parts: [{"text": ""}]). אם הערך של finish_reason הוא MAX_TOKENS כש-continuation_token קיים, מגדילים את max_output_tokens בבקשה הבאה.
  • שילוב חלקים שנצברו לסיבוב model יחיד להיסטוריה של כמה סיבובים רק אחרי STOP.

ספירת טוקנים, דחיסה ושמירה במטמון באופן משתמע

האופן שבו מתבצעים החישוב והשמירה במטמון של טוקנים בקטעי המשך:

  • ב-Interactions API, קריאות interactions.create() ללא סטרימינג עם automatic_continuation=True ואינטראקציות 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 Gen 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 (או את initial_prompt_token_count ב-GenerateContent) ובצעו דחיסה רק אחרי שהתור מסתיים (status="completed" או ללא continuation_token).
  • כל קטע המשך ממלא מראש את ההנחיה ואת האסימונים שכבר פוענחו, ועומד באופן אוטומטי בדרישות של שמירת הקשר במטמון באופן משתמע (מינימום 4,096 אסימונים, עם שמירה עמידה במטמון שמופעלת כברירת מחדל) כשמריצים קטעים ברצף. החיוב על קטעים שהושלמו מתבצע בסוף כל קטע, גם אם קטע מאוחר יותר נכשל או בוטל.

מעבר מ-‎3.8 Flash ל-Hydrogen

ההתנהגות הבאה שונה מ-gemini-3.8-flash וממודלים קודמים של Gemini 3 Flash:

  • ל-Hydrogen יש מגבלה מאוחדת של 1,048,576 טוקנים לקלט ולפלט (כשהפלט כולל תהליך חשיבה, בקשות להפעלת פונקציות והתשובה הסופית), במקום מגבלות נפרדות לקלט ולפלט. הפלט בחזית של קטע בודד מוגבל ל-65,536 טוקנים (בסטרימינג או לא בסטרימינג), ואפשר להרחיב אותו עד ל-1,048,576 טוקנים באמצעות פענוחים ארוכים ב-Interactions API או ב-GenerateContent (מטופל באופן אוטומטי ב-Google Gen AI SDK, עם background=true ב-Interactions API או באמצעות continuation_token בלולאות בהתאמה אישית).
  • ערך ברירת המחדל של thinking_level הוא HIGH (השתנה מ-MEDIUM ב-gemini-3.8-flash), ו-XHIGH נתמך במשימות של הסקת מסקנות מעמיקה (צריך להשאיר מקום לדחיסת הקשר בשביל עקבות הסקת המסקנות של HIGH ו-XHIGH ברתמות קידוד עם כמה שלבים, או להגדיר את MEDIUM בשלבים שרגישים לזמן אחזור). ‫thinking_budget ו-thinking_level="MINIMAL" מחזירים שגיאת HTTP 400.
  • אין תמיכה בשמירת הקשר במטמון באופן מפורש (cached_content). שמירה במטמון באופן משתמע מתבצעת באופן אוטומטי במינימום של 4,096 טוקנים (פחות מ-6,144 טוקנים ב-gemini-3.8-flash), כשהשמירה במטמון לטווח ארוך מופעלת כברירת מחדל.
  • אפשר להשתמש בקובצי Microsoft Office‏ (.docx,‏ .dotx,‏ .doc,‏ .pptx,‏ .ppt,‏ .xlsx,‏ .xls) ו-OpenDocument‏ (.odt,‏ .odp,‏ .ods) בתוך השורה או באמצעות URI של Cloud Storage‏ (gs://), כולל בתוך חלקים FunctionResponse מולטי-מודאליים.
  • בסבבים של קריאה לפונקציות במקביל, נאכפת הצבה קפדנית של thought_signature (רק החלק הראשון של functionCall בסבב מקביל כולל את thought_signature. אם משמיטים אותו בסבב הפעיל או משכפלים אותו לחלקים מקבילים של functionCall, מוחזרת שגיאת HTTP‏ 400). בנוסף, עריכות של תחילית ההנחיה באותו מודל נכשלות עם שגיאת HTTP‏ 400 כברירת מחדל, אלא אם prefix_mismatch_behavior="DROP" מוגדר ב-ThinkingConfig. חשוב לשמור על החלקים של thought_signature גם בכל הסבבים הקודמים (גם החלקים של functionCall וגם החלקים הסופיים של text) כדי לשמור על איכות החשיבה ולהימנע מסיבות סיום של MALFORMED_FUNCTION_CALL.
  • כל טוקן שהמודל מעבד מחויב, כולל הוראות מערכת של כלים פנימיים והצהרות על פונקציות כשמשתמשים ב-grounding.

להשוואה בטבלה, ראו מעבר ממודלים של 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. מעדכנים את מזהה המודל ל-gemini-4-hydrogen.
  2. משדרגים לגרסה העדכנית של Google Gen AI SDK ומביאים בחשבון את מגבלת האסימונים המאוחדת לקלט ולפלט: משדרגים לגרסה google-genai >= 2.34.0 (Python),‏ @google/genai >= 2.32.0 (JavaScript/TypeScript),‏ Go >= 1.77.0 או Java >= 1.80.0 להמשך אוטומטי של Interactions API (או >= 2.30.1 Python /‏ >= 2.29.1 JavaScript ב-GenerateContent). אסימוני קלט ופלט (כולל חשיבה וקריאה להפעלת פונקציות) חולקים את המגבלה המאוחדת של 1,048,576 אסימונים. אם הפלט חורג מ-65,536 טוקנים (עד 1,048,576 טוקנים) ב-Interactions API או ב-GenerateContent, מגדירים את max_output_tokens לערך שגדול מ-65,536 כדי ש-Google Gen AI SDK ימשיך באופן אוטומטי בין הקטעים (או משתמשים ב-background=true או בלולאת continuation_token בהתאמה אישית).
  3. עדכון ההגדרה של thinking_level: מחליפים את thinking_budget ו-MINIMAL ב-thinking_level שמוגדר ל-LOW,‏ MEDIUM,‏ HIGH (ברירת המחדל ב-gemini-4-hydrogen) או XHIGH (משתמשים באותיות קטנות "low",‏ "medium",‏ "high" או "xhigh" ב-Interactions API). אם עומס העבודה שלכם הסתמך על MEDIUM כברירת המחדל ב-gemini-3.8-flash, הגדירו במפורש את thinking_level="MEDIUM" כדי לשמור על זמן אחזור שווה ערך להסקת מסקנות.
  4. הסירו את השמירה המפורשת במטמון וטענו מראש תוכן סטטי של הנחיות (4,096 טוקנים או יותר) לשמירה אוטומטית משתמעת במטמון.
  5. אימות של שימור thought_signature ודחיסת קידומות בשיחות עם זיכרון ובקריאות מקבילות: צריך לשמר את thought_signature בכל הפניות הקודמות (גם בחלקים של functionCall וגם בחלקים הסופיים של text) במקום להסיר חתימות בין הפניות, לשמור את thought_signature רק בחלק הראשון של functionCall בפנייה מקבילה של קריאה לכלי, ולהגדיר את prefix_mismatch_behavior="DROP" ב-ThinkingConfig אם האפליקציה משנה או דוחסת פניות קודמות בהיסטוריית השיחות עם הזיכרון.
  6. הסרת פרמטרים שלא משפיעים או לא נתמכים: מסירים שדות יצירה שנדחו או שמתעלמים מהם, באופן הבא:
    • צריך להסיר את temperature, top_p ו-top_k, כי המערכת מתעלמת מהם.
    • מסירים את frequency_penalty,‏ presence_penalty וכל ערך של candidate_count שגדול מ-1.
    • להסיר מהיסטוריית השיחות תשובות מודל מאוכלסות מראש.

רשימת משימות מסכמת למפתחים

הכנו רשימת משימות שתעזור לכם לוודא שהגדרתם את השילוב עם Hydrogen כמו שצריך:

בעיות מוכרות

הבעיות הבאות רלוונטיות לפענוח ארוך ב-Hydrogen:

  • פענוח ארוך דורש את v1beta1: פענוח ארוך (continuation_token) גם ב-Interactions API וגם ב-GenerateContent API (generateContent ו-streamGenerateContent) נתמך רק ב-v1beta1 API (לא ב-v1) ב-Agent Platform. כברירת מחדל, Google Gen AI SDK משתמש ב-v1beta1, אלא אם api_version='v1' מוגדר ב-http_options (או ב-api_version="v1" ב-interactions.create). בקריאות REST ישירות, צריך להשתמש בנתיב של נקודת הקצה /v1beta1/.
  • שינויים בפרמטרים בקטעי ההמשך של Interactions API: שינוי של model,‏ system_instruction או הצהרות על פונקציות בקטעי ההמשך מחזיר שגיאת HTTP‏ 400, אבל שינויים באמצע הפענוח של generation_config.thinking_level או של כלים מובנים (google_search,‏ code_execution,‏ url_context) לא נדחים על ידי אימות השרת. חשוב להשאיר את thinking_level ואת הכלים המובנים ללא שינוי בכל החלקים של לולאת ההמשך.

מקורות מידע נוספים

למידע נוסף על Hydrogen, אפשר לעיין במקורות המידע הבאים: