Gemini 4 Argon API: צ׳אט ב-Python עם הזרמה בפורמט המקורי

שיחה דרך ה-API של Gemini 4 Argon משתמשת בתוכן בפורמט המקורי של Gemini: contents, תפקידים ו-parts. הבקשה הראשונה קטנה. החלק המורכב יותר הוא לשמור את התשובה נכון לפני שליחת שאלת המשך. שחזור סבב של המודל מהטקסט הגלוי בלבד עלול לאבד תוכן חתום; הוספת הודעת טעינה ריקה להיסטוריה עלולה להפוך את הבקשה הבאה ללא תקינה.

המדריך משתמש בספרייה הסטנדרטית של Python ובנקודת הקצה המקורית של SeedRouter. הוא עוסק בצ׳אט טקסט ובהזרמה. מדריך ה-API המלא מתאר את מפרט הפרמטרים כולו; המאמר הזה מלווה בקשה אחת עד לשיחה שאפשר להשתמש בה.

לפני הבקשה הראשונה

צריך Python 3, מפתח API של SeedRouter ויתרה מספקת בחשבון. שמור את המפתח במשתנה סביבה בשם SEEDROUTER_API_KEY; אל תכניס אותו לקוד המקור או לחבילת קוד שנשלחת לדפדפן. כל הודעה שתשלח עשויה להיות כרוכה בתשלום. הדוגמה אינה מבצעת ניסיונות חוזרים אוטומטיים או בקשות המשך.

מזהה המודל הוא gemini-4-argon, ויש לציין אותו בנתיב של נקודת הקצה. Google מתעדת את הפורמט במדריך ליצירה בפורמט המקורי. SeedRouter משתמשת באימות Bearer, כפי שמוצג להלן.

שלח בקשה אחת ל-API של Gemini 4 Argon

curl --no-buffer --fail-with-body \
  'https://api.seedrouter.ai/v1beta/models/gemini-4-argon:streamGenerateContent?alt=sse' \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain a mutex in one sentence."}]}],"generationConfig":{"maxOutputTokens":1024,"thinkingConfig":{"thinkingLevel":"low"}}}'

התשובה היא רצף של אירועים שנשלחים מהשרת, ולא מסמך JSON יחיד. כל אירוע data: מכיל JSON בפורמט המקורי של Gemini. הטקסט הגלוי מופיע ב-candidates[].content.parts[].text; חלק מהחלקים מכילים במקום זאת חשיבה או חתימות. usageMetadata עשוי להגיע בנפרד מהטקסט, ולכן יש לקרוא עד האירוע האחרון לפני שמחשיבים את התשובה למלאה.

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

הרץ שיחה בת שני סבבים ב-Python

הורד את דוגמת Python המלאה, שמור אותה מקומית והרץ:

python3 gemini-4-argon-chat.py

שאל ״Explain a mutex in one sentence״ ולאחר מכן ״Give a Python example of that idea״. הסקריפט ממתין לקלט שלך לפני כל בקשה. הזן שורה ריקה כדי לסיים. הכלל המרכזי לניהול ההיסטוריה הוא:

user = {"role": "user", "parts": [{"text": text}]}
body = {"contents": [*history, user]}
history = [*history, user, {"role": "model", "parts": parts}]

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

הקטע הקצר למעלה מסביר את מבנה הנתונים; הרץ את הקובץ המלא כדי לקבל את כל הטיפול בבקשות. לתשובה ללא הזרמה, הפעולה המקבילה היא generateContent, ובדוגמאות העזר מוצגים cURL, Python, Node.js ו-Go.

שמור את חלקי parts המקוריים, לא את מחוון הטעינה

הבקשה השנייה צריכה לכלול שלושה סבבים אמיתיים: הודעת המשתמש הראשונה, תשובת המודל שהושלמה והודעת המשתמש השנייה. הטקסט הזמני ״חושב…״ בממשק אינו סבב נוסף של המודל.

שגיאה כמו contents.3.parts: Too small: expected array to have >=1 items פירושה שלרשומת התוכן הרביעית יש מערך parts ריק. האינדקסים מתחילים באפס. בדוק איך ההיסטוריה נבנית לפני שתשנה את הפרומפט או את המודל. מחוון טעינה שייך למצב התצוגה; הוא לעולם לא אמור להפוך ל-{ "role": "model", "parts": [] } בתוך הבקשה.

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

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

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

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

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

Long decode הוא מקרה נפרד נוסף. סיבת סיום CONTINUATION ממשיכה את היצירה המקורית באמצעות טוקן המשך; זו אינה הודעת משתמש חדשה. Google דורשת את הבקשה המקורית ואת הטוקן העדכני ביותר, בלי להוסיף פלט חלקי ל-contents. ראה את מדריך long decode. סקריפט ההיכרות הזה עוצר במקום לממש המשך אוטומטי.

מה אומת?

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

שאלות על ה-API

אפשר להחליף שם מודל של OpenAI ב-gemini-4-argon?

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

למה התשובה ריקה למרות שנצרכו טוקנים?

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

האם הקשר של מיליון טוקנים אומר מיליון טוקנים של פלט?

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

הוסף יכולות אחרי שהשיחה פועלת

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