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:
- פותחים את Agent Studio בפרויקט Google Cloud ובוחרים באפשרות
gemini-4-hydrogenבקבוצת Gemini. - בקטע 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 בלולאה מותאמת אישית:
Python (SDK – מומלץ)
from google import genai
from google.genai import types
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
# Automatic continuation is enabled by default in google-genai >= 2.30.1.
# Chunks across all continuation requests are yielded as a single stream.
for chunk in client.models.generate_content_stream(
model="gemini-4-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, מוחזרת שגיאת HTTP400. - כדי למנוע השלמות ארוכות לא מכוונות, תקציב הפלט שמוגדר כברירת מחדל ומגבלת החזית של קטע בודד (חשיבה, קריאה להפעלת פונקציות ותגובת המודל) הם 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) מחזירה שגיאת HTTP400. צריך להסיר את הפרמטרים האלה מהבקשות. קריאה לפונקציות וחתימות מחשבה: הצהרות על כלים, קריאות מקבילות לכלים והפעלה מחדש של
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, תוחזר שגיאת HTTP400. צריך לשמור את כל החלקים המקבילים שלfunctionCallבתור אחד שלmodel, ואחריו את כל החלקים התואמים שלfunctionResponseבתור אחד שלuser. פרטים נוספים מופיעים במאמר חתימות של מחשבות. - שמירה על
thought_signatureבין פניות: צריך להחזיר כלthought_signatureבתוך ה-Partהמקורי שלו בכל הפניות הקודמות בהיסטוריית השיחה עם הזיכרון (גם בחלקים שלfunctionCallוגם בחלקים הסופיים שלtext), ולא רק בפניית המשתמש הפעיל. למרות שאימות החתימה של HTTP400חל רק על שלבי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, מוחזרת שגיאת HTTP400(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מחזירה שגיאת HTTP400. - המשך בלי שמירת מצב (
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, מוחזרת שגיאת HTTP400. צריך לסיים את פענוח ה-completed, או להתחיל את התור הבא מהאינטראקציה האחרונה שלcompleted. אחרי שהקטע האחרון מגיע ל-completed, העברת ה-idשל הקטע האחרון בתורprevious_interaction_idמשחזרת את היסטוריית השיחות המלאה בכל הקטעים הקודמים. - עקביות של פרמטרים בין קטעים: שינוי של
model,system_instructionאו הצהרות פונקציה (tools) בקטע המשך מחזיר שגיאת HTTP400. גם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"מחזירים שגיאת HTTP400. - אין תמיכה בשמירת הקשר במטמון באופן מפורש (
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, מוחזרת שגיאת HTTP400). בנוסף, עריכות של תחילית ההנחיה באותו מודל נכשלות עם שגיאת HTTP400כברירת מחדל, אלא אם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, מבצעים את הפעולות הבאות:
- מעדכנים את מזהה המודל ל-
gemini-4-hydrogen. - משדרגים לגרסה העדכנית של 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.1Python />= 2.29.1JavaScript ב-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בהתאמה אישית). - עדכון ההגדרה של
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,096 טוקנים או יותר) לשמירה אוטומטית משתמעת במטמון.
- אימות של שימור
thought_signatureודחיסת קידומות בשיחות עם זיכרון ובקריאות מקבילות: צריך לשמר אתthought_signatureבכל הפניות הקודמות (גם בחלקים שלfunctionCallוגם בחלקים הסופיים שלtext) במקום להסיר חתימות בין הפניות, לשמור אתthought_signatureרק בחלק הראשון שלfunctionCallבפנייה מקבילה של קריאה לכלי, ולהגדיר אתprefix_mismatch_behavior="DROP"ב-ThinkingConfigאם האפליקציה משנה או דוחסת פניות קודמות בהיסטוריית השיחות עם הזיכרון. - הסרת פרמטרים שלא משפיעים או לא נתמכים: מסירים שדות יצירה שנדחו או שמתעלמים מהם, באופן הבא:
- צריך להסיר את
temperature,top_pו-top_k, כי המערכת מתעלמת מהם. - מסירים את
frequency_penalty,presence_penaltyוכל ערך שלcandidate_countשגדול מ-1. - להסיר מהיסטוריית השיחות תשובות מודל מאוכלסות מראש.
- צריך להסיר את
רשימת משימות מסכמת למפתחים
הכנו רשימת משימות שתעזור לכם לוודא שהגדרתם את השילוב עם Hydrogen כמו שצריך:
בעיות מוכרות
הבעיות הבאות רלוונטיות לפענוח ארוך ב-Hydrogen:
- פענוח ארוך דורש את
v1beta1: פענוח ארוך (continuation_token) גם ב-Interactions API וגם ב-GenerateContentAPI (generateContentו-streamGenerateContent) נתמך רק ב-v1beta1API (לא ב-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או הצהרות על פונקציות בקטעי ההמשך מחזיר שגיאת HTTP400, אבל שינויים באמצע הפענוח שלgeneration_config.thinking_levelאו של כלים מובנים (google_search,code_execution,url_context) לא נדחים על ידי אימות השרת. חשוב להשאיר אתthinking_levelואת הכלים המובנים ללא שינוי בכל החלקים של לולאת ההמשך.
מקורות מידע נוספים
למידע נוסף על Hydrogen, אפשר לעיין במקורות המידע הבאים: