מדריך למפתחים בנושא Gemini 3.5 Flash

‫Gemini 3.5 Flash הוא מודל מהיר, חסכוני ומתקדם ממשפחת Gemini 3. המודל הזה נועד לספק יכולות אג'נטיות שקרובות לאלה של Pro, בלי להתפשר על הביצועים או על הערך. עכשיו הוא זמין לכלל המשתמשים (GA) – למפתחים שמשתמשים ב-Gemini API ולארגונים שמשתמשים ב-Gemini Enterprise Agent Platform.

במסמך הזה מוסבר מה חדש ב-‎3.5 Flash, מתי כדאי להשתמש בו, איך לעבור ל-‎3.5 Flash ואיך להתחיל להשתמש בו במהירות.

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

בטבלה הבאה מוצגת השוואה בין חלק מהמפרטים של ‎3.5 Flash,‏ ‎3.1 Pro ו-‎3.1 Flash-Lite:

	Gemini 3.5 Flash	Gemini 3.1 Pro	Gemini 3.1 Flash-Lite
מזהה המודל	gemini-3.5-flash	gemini-3.1-pro-preview	gemini-3.1-flash-lite
שלב ההשקה	GA	תצוגה מקדימה	GA
סוגי קלט	טקסט, תמונה, אודיו, וידאו	טקסט, תמונה, אודיו, וידאו	טקסט, תמונה, אודיו, וידאו
סוגי הפלט	טקסט	טקסט	טקסט
חלון ההקשר	1,048,576	1,048,576	1,048,576
אורך מקסימלי של טוקנים בפלט	65,536	65,536	65,536
אזורים נתמכים	גלובלי, מספר אזורים, אמריקה, אירופה, אסיה והאוקיינוס השקט	עולמי	גלובלי, במספר אזורים
רמות ההעמקה הנתמכות	‫MINIMAL, LOW, MEDIUM, HIGH (ברירת המחדל: MEDIUM)	LOW, MEDIUM, HIGH (ברירת המחדל: HIGH)	‫MINIMAL, LOW, MEDIUM, HIGH (ברירת המחדל: MINIMAL)
המיקוד העיקרי	משימות מאוזנות, קריאות API לכלים ורמת חשיבה בינונית	חשיבה מעמיקה, משימות מורכבות מאוד	משימות בנפח גבוה, רגישות לעלויות ורגישות לזמן אחזור

בדף של מודל ‎3.5 Flash מפורטת הרשימה המלאה של היכולות, הכלים ואפשרויות הצריכה הנתמכים.

פירוט תרחישי השימוש

האסטרטגיה המומלצת עבור Agentic Workflows משתמשת בגישה מדורגת כדי לשפר את האיכות, המהירות והעלות:

• ‫Gemini Pro: מיועד למשימות קוגניטיביות מורכבות מאוד שדורשות חשיבה רציונלית מעמיקה, כמו תכנון ראשוני, פתרון בעיות מורכבות, כתיבת קוד קשה וקבלת החלטות קריטיות.
• ‫Gemini Flash: משמש כמודל העיקרי לביצוע משימות, קריאות API לכלים ושלבי ביניים של חשיבה רציונלית, ומציע את האיזון הטוב ביותר בין ביצועים ליעילות.
• ‫Gemini Flash-Lite: מודל שמתאים למשימות מבניות ולעיבוד מקדים בנפח גבוה ובזמן אחזור קצר, שבהן המהירות והעלות הן הגורמים הכי חשובים, כמו ניתוב לפי כוונה, חילוץ נתונים, תיוג וסיווג.

מה חדש ב-Gemini 3.5 Flash?

‫Gemini 3.5 Flash מביא איתו את השינויים והשיפורים הבאים למגוון מודלי Gemini:

• ביצועים מתקדמים לאורך זמן: מודל Flash הכי חכם שלנו, שמותאם למשימות של סוכנים ולמשימות תכנות בקנה מידה נרחב.
• ביצוע משימות באמצעות סוכנים: פריסת סוכני משנה, פתרון בעיות ולולאות סוכנים מהירות בקנה מידה נרחב.
• תכנות משופר: מחזורי תכנות איטרטיביים, בדיקה מהירה ויצירת אב טיפוס כדי לבדוק דרכים חלופיות ולבחון פתרונות באופן דינמי.
• טווח ארוך: תהליכי עבודה עם כמה שלבים ושימוש בכלים בקנה מידה נרחב.
• שימור תהליכי חשיבה: המודל שומר באופן אוטומטי את שלבי הביניים של תהליך החשיבה בשיחות עם כמה סבבים. אין צורך לבצע שינויים ב-API.
• רמת העמקה חדשה שמוגדרת כברירת מחדל: רמת ההעמקה שמוגדרת כברירת מחדל השתנתה מ-HIGH ל-MEDIUM.
• שיפור ביכולת החשיבה של LOW: רמת החשיבה הנמוכה שופרה באופן משמעותי בקוד ובמשימות של סוכנים שדורשות פחות שלבים, ומציעה איכות גבוהה עם זמן אחזור נמוך ועלות נמוכה יותר.

פרטים נוספים זמינים בקטע השינויים העיקריים.

הערה: יכול להיות שתבחינו בעלייה במספר הטוקנים המדווחים. התשתית המשודרגת סופרת במדויק את כל רכיבי הבקשה, כולל מטא-נתונים מורכבים כמו סכמות תשובה וקריאות להפעלת פונקציות, שלא נספרו במלואן בגרסאות קודמות.

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

לפני שמתחילים, צריך לבצע אימות ב-Agent Platform באמצעות Application Default Credentials ‏ (ADC) או מפתח API. מידע נוסף מופיע במאמר תחילת העבודה עם Gemini Enterprise Agent Platform.

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

התקנה

חשוב לוודא שאתם משתמשים בגרסה העדכנית ביותר של ה-SDK של google-genai:

pip install --upgrade google-genai

בקשה בסיסית

Python

from google import genai

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

response = client.models.generate_content(
  model="gemini-3.5-flash",
  contents="How does AI work?",
)
print(response.text)

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

השינויים העיקריים

בקטע הזה מפורטים השינויים הבאים שנוספו ב-Gemini 3.5 Flash:

• רמת חשיבה חדשה שמוגדרת כברירת מחדל (MEDIUM)
• שימור תהליכי חשיבה
• הוצא משימוש: פרמטרים לדגימה
• הוצא משימוש: thinking_budget

רמת ההעמקה החדשה שמוגדרת כברירת מחדל

רמת ההעמקה שמוגדרת כברירת מחדל במודלים של Gemini 3 היא עכשיו MEDIUM, במקום HIGH בגרסת טרום-ההשקה (Preview) של Gemini 3 Flash. רמת החשיבה MEDIUM מניבה תוצאות טובות במגוון רחב של משימות, והיא מהירה וחסכונית יותר.

רמות ההעמקה הנתמכות הן:

• MINIMAL: תואם להגדרה "ללא חשיבה" ברוב השאילתות. המודל עשוי להשקיע מעט מאוד זמן חשיבה במשימות מורכבות כמו תכנות. מצמצם את זמן האחזור באפליקציות של צ'אט או של תפוקה גבוהה.
• ‫LOW: יכולת חשיבה בסיסית לרוב המשימות, במהירות גבוהה ובעלות נמוכה יותר.
• ‫MEDIUM: (ברירת מחדל) הגדרה מאוזנת לרוב המשימות שדורשות חשיבה רציונלית.
• ‫HIGH: מקסימום חשיבה כדי לשפר את הביצועים של המשימה. יכול להיות שהמודל ייקח יותר זמן מאשר בהגדרה MEDIUM כדי ליצור את הטוקן הראשון, אבל הפלט יהיה יסודי יותר.

לדוגמה, השתמשו ב-HIGH לחידות היגיון, בעיות מילוליות במתמטיקה או תרחישים מסובכים שבהם המודל צריך להסיק מסקנות בכמה שלבים:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.5-flash",
   contents="A farmer has chickens and rabbits. There are 35 heads and 94 legs. How many chickens and how many rabbits does he have? Show your step-by-step logic.",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.HIGH
       )
   ),
)
print(response.text)

הפרמטר thinking_level הוא אופציונלי. אם לא מציינים ערך, מודל ‎3.5 Flash ישתמש בהגדרת ברירת המחדל שלו (MEDIUM).

הערה: הפרמטר thinking_level והפרמטר הקודם thinking_budget לא יכולים לפעול יחד. אם תשתמשו בשניהם בבקשה, תוחזר שגיאה מסוג 400.

שימור תהליכי חשיבה

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

ההרהורים מאינטראקציות קודמות נשמרים עכשיו כברירת מחדל. השירות לא מוחק יותר את היסטוריית תהליך החשיבה מההקשר של השיחה לפני שהוא מעביר אותה למודל.

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

הערה: שימור תהליכי חשיבה עלול להגדיל את השימוש בטוקנים ואת זמן התגובה. בשאילתות פשוטות ועצמאיות, ניקוי המחשבות בין התורות יכול לעזור.

הוצא משימוש: פרמטרים לדגימה

הפרמטרים הבאים לדגימה כבר לא מומלצים למודלים של Gemini 3:

• temperature
• top_p
• top_k

המודל מנהל את הדגימה שלו כדי להגיע לתוצאות אופטימליות. הסירו את הפרמטרים האלה מכל הבקשות. כדי להבטיח דטרמיניזם, הגדירו הוראות מערכת עם כללים מפורשים לתרחיש הספציפי שלכם.

הוצא משימוש: thinking_budget

הפרמטר המספרי הגולמי thinking_budget לא נתמך יותר בכל המודלים של Gemini 3. במקום זאת, צריך להשתמש במאפיין thinking_level מסוג string enum.

# ⚠️ Before (not recommended)
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_budget=7500)
)

# ✅ After
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_level="MEDIUM")
)

שיטות מומלצות

בקטע הזה מפורטות השיטות המומלצות הבאות לשימוש ב-‎3.5 Flash:

• שימוש בהתאמה מחמירה של תשובות לבקשות להפעלת פונקציות
• הכללת תוכן מולטימודלי בתגובת הפונקציה parts
• שימוש בהוראות מוטבעות בתגובת הפונקציה
• צמצום קריאות מיותרות לכלים

שימוש בהתאמה מחמירה של תשובות לקריאות להפעלת פונקציות

תגובות לא תואמות גורמות למודל להחזיר תגובות ריקות עם finish_reason: STOP ברוב המקרים. תמיד צריך לפעול לפי המוסכמות הבאות:

• כולל id: כל FunctionResponse חייב לכלול את id מה-FunctionCall התואם.
• התאמה של name: הערך של name בתגובה חייב להיות זהה לערך של name בקריאה.
• מספר ההתאמות: החזרת FunctionResponse אחד בדיוק לכל FunctionCall שהתקבל.

הקוד הבא הוא דוגמה לקריאה נכונה לפונקציה:

# ✅ Include matching id and name in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result},
                id=tool_call.id,
            )
        ]),
    ],
)

הכללת תוכן מולטימודלי בתגובת הפונקציה parts

אם תספקו תמונות מחוץ לתגובת הפונקציה, זה עלול להוביל להתנהגות לא צפויה של המודל, כמו דליפת מחשבות, ולפגוע באיכות. פועלים לפי ההמלצה שמופיעה בקטע מבוא לקריאה להפעלת פונקציות וכוללים תוכן מולטימודלי בחלקי התגובה של הפונקציה ששולחים למודל. המודל יכול לעבד את התוכן המולטי-מודאלי הזה בשלב הבא כדי ליצור תשובה מושכלת יותר.

לדוגמה:

# ✅ Include multimodal content in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={
                    "result": "instrument.jpg",
                    "image": base64_image_data,
                },
                id=tool_call.id,
            )
        ]),
    ],
)

שימוש בהוראות מוטבעות בתגובה לפונקציה

אם מספקים הוראות לפלטפורמה יחד עם תגובות של פונקציות בתור parts הבא, זה יכול להוביל להתנהגות לא צפויה של המודל, כמו דליפת מחשבות, ולפגוע באיכות. במקום זאת, צריך להוסיף אותו בסוף טקסט התגובה של הפונקציה, אחרי שתי שורות חדשות.

לדוגמה:

# ✅ Append inline instructions to the end of the function response separated by two newlines
result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result_text},
                id=tool_call.id,
            )
        ]),
    ],
)

צמצום קריאות API מיותרות לכלים

אם אתם נתקלים בשימוש יתר בקריאות API לכלים, יש שתי שיטות שיכולות לעזור לצמצם אותן:

1. להוריד את רמת החשיבה: רמות חשיבה גבוהות יותר מעודדות את המודל להשתמש ביותר כלים כדי לחקור ולאמת, אז הורדת הרמה יכולה להפחית את קריאות ה-API לכלים.

2. הוספת הוראות מערכת: אם המודל ממשיך להשתמש בכלים יותר מדי גם אחרי שמשנים את רמת החשיבה, כדאי להשתמש בהנחיה שמגבילה את השימוש בכלים. לדוגמה:

   You have a limited action budget of <n> tool calls. Use them efficiently.
   

מעבר מ-‎3.5 Flash או מ-‎3.1 Pro ל-‎3.6 Flash

כדי לעבור ל-‎3.6 Flash מ-‎3.5 Flash או מ-‎3.1 Pro, פועלים לפי השלבים הבאים:

1. עדכון מזהה המודל: משנים את מחרוזת המודל בקריאות ל-API ל-gemini-3.6-flash.
2. התאמת הקוד לכללי ה-API החדשים של משפחת Gemini 3: ‫Gemini 3.6 Flash אוכף בקפדנות את כללי הפרמטרים ואת מוסכמות ה-API שנקבעו בכל משפחת Gemini 3:
   • הסרת הטמפרטורה, Top-K ו-Top-P: מסירים את הפרמטרים המותאמים אישית האלה מהמטען הייעודי (payload). המודל לא יציג שגיאה, אבל הוא יתעלם מהם לחלוטין. במקום זאת, השתמשו בפרמטר thinking_level או בפלטים מובְנים של json_schema כדי לשלוט בדטרמיניזם של הפלט.
   • הסרת קנסות על תדירות ונוכחות: הסירו את כל ההגדרות האישיות של קנסות על תדירות ונוכחות כדי למנוע מהקריאות ל-API להחזיר שגיאות זמן ריצה.
   • מוודאים שהשילוב של הצ'אט לא מנסה למלא מראש את המודל: בודקים את המערכים של היסטוריית ההודעות כדי לוודא שהמטען הייעודי (payload) של ה-API לא מסתיים בתור ריק של המשתמש או של המודל. אם האובייקט האחרון במערך ההיסטוריה הוא תפקיד "model" (‏GenerateContent API) או סוג "model_output" (‏Interactions API), צריך לשנות את מבנה הרצף כדי למנוע שגיאת אימות מחמירה.
   • שימוש ב-thinking_level: צריך להסיר מופעים של הפרמטר thinking_budget שהוצא משימוש ולהשתמש במקום זאת ב-thinking_level.
   • אכיפה קפדנית של מוסכמות קריאה להפעלת פונקציות: ה-FunctionResponse חייב להתאים באופן מדויק ל-id, ל-name ולמספר ההרצות של ה-FunctionCall הקודם. אם אתם צריכים להוסיף הוראות בתוך השורה, הציבו אותן ישירות בתוך טקסט התגובה של הפונקציה, כשהן מופרדות על ידי שתי שורות חדשות (\n\n).
3. התחשבות בשינויים בתהליך העבודה:
   • אם האפליקציה שלכם מסתמכת על לולאות שיחה עם כמה שלבים, בדקו את תהליכי העבודה כדי לוודא שהתמציתיות החדשה של המודל לא גורמת ליציאות מוקדמות מדי.
   • אם אתם מפתחים סוכני סקריפטים בסיסיים או סוכני ממשק משתמש, כדאי לעקוב אחרי קריאות מיותרות ל-execute_code לצורך בדיקה, בגלל הנטייה החדשה של המודל לבדיקה פרוגרמטית מראש.

פתרונות עקיפים לדרישות הטקסט שלפני הכלי

אם ההנחיה דורשת מהמודל להפיק טקסט מובנה (XLM,‏ YAML,‏ Json וכו') (לדוגמה, <UPDATE>...</UPDATE>) מיד לפני ביצוע קריאת API לכלי, יכול להיות שלפעמים קריאת ה-API לכלי תיכשל ותופיע השגיאה Malformed_Function_Call. כדי לפתור את הבעיה, אפשר להשתמש באחד מהפתרונות החלופיים הבאים:

• (מומלץ) להורות למודל להכניס את ההערות שלפני השימוש בכלי לקריאה ייעודית לפונקציה update() במקום לטקסט גולמי. הוראות מפורטות להטמעה מופיעות בקטע הבא.
• מנחים את המודל לכתוב הערות ככותרות Markdown (לדוגמה, # UPDATE,‏ ## PLAN) במקום טקסט מובנה.
• אל תדרשו מהמודל להפיק טקסט לפני קריאות API לכלי.

הפתרון המומלץ: להוסיף את הערות העבודה לקריאה ייעודית להפעלת פונקציה

במקום ההוראה המקורית:

Before calling a tool, in every response you MUST first output a single
`<UPDATE>` part as specified, don't skip this part or any of required sub-tags
within `<UPDATE>`.

השתמשו בהוראה המעודכנת הזו:

Before calling any other tool, in every response you MUST first call `update`
with all required parameters (previous_step, plan, next_step, external).

מעדכנים את כל ההפניות לפורמט ה-XML הישן של <UPDATE> בבקשת הלקוח. לאחר מכן, מוסיפים את הצהרת הפונקציה המתאימה לפונקציית העדכון:

{
  "name": "update",
  "description": "Update working notes (previous step analysis, plan, next step, external note).",
  "parameters": {
    "type": "OBJECT",
    "properties": {
      "previous_step": {
        "type": "STRING",
        "description": "Key findings and outcomes since the previous step."
      },
      "plan": {
        "type": "STRING",
        "description": "The current status of the plan."
      },
      "next_step": {
        "type": "STRING",
        "description": "Brief explanation of the immediate next action according to the plan."
      },
      "external": {
        "type": "STRING",
        "description": "A short, plain-language note shown to the User about what you are ABOUT TO DO next."
      }
    },
    "required": [
      "previous_step",
      "plan",
      "next_step",
      "external"
    ]
  }
}

המודל יבצע שתי קריאות באותו שלב: הקריאה ל-update() שמחליפה את ה-XML המובנה, והקריאה בפועל לפונקציה שהוא רוצה לבצע.

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

• דף המודל של Gemini 3.5 Flash
• תיקיית Notebook למתחילים