אתם יכולים להשתמש ברמת Deferred כדי להריץ קריאות אסינכרוניות עם כמה שלבים למודל Gemini בשביל סוכנים בהתאמה אישית בתעריף מוזל ב-Gemini Enterprise Agent Platform. ב-Interactions API, פלטפורמת Agent Platform מוסיפה לתור כל פנייה מושהית להפעלה ברקע בטווח של 24 שעות, ושומרת את המצב למשך 7 ימים.
רמת Deferred מתאימה לעומסי עבודה של סוכנים שיכולים להתמודד עם זמן אחזור, וצריכים שליטה בכל שלב, למשל:
- סוכני אבטחה וקידוד בכמה שלבים: סריקות לבדיקת נקודות חולשה במאגר, העברות קוד אוטומטיות ומיון רגרסיה.
- תהליכי עבודה של מסמכים ומחקר: בדיקות של עיצוב טכני, בדיקות לאחור (backtesting) של נתונים פיננסיים וסינתזה של כמה מסמכים באמצעות קריאות API לכלים.
- הערכות סוכנים אופליין: נקודות השוואה לאיכות בקנה מידה גדול שמקשרות בין
previous_interaction_idתורות בלי אילוצי זמן אחזור בזמן אמת.
כדי להשוות בין כל מודלי המחשוב, קראו את המאמר אפשרויות צריכה. כדי לתזמן סוכנים של הערכה לפיתוח סוכנים (ADK) או הפעלות מנוהלות בסוכן Gemini Deep Research, קראו את המאמר תזמון סוכנים אוטונומיים.
מודלים ומיקומים נתמכים
רמת Deferred נתמכת רק בנקודת הקצה global (locations/global ב-aiplatform.googleapis.com). אם שולחים בקשה עם service_tier="deferred" לנקודת קצה אזורית או לנקודות קצה במספר אזורים (us או eu), מוחזרת השגיאה HTTP 400 ("code": "invalid_request").
מודלי Gemini העיקריים הבאים תומכים ברמת Deferred בנקודת הקצה global:
- Gemini 4 Carbon (
gemini-4-carbon) - Gemini 4 Argon (
gemini-4-argon) - Gemini 3.8 Flash (
gemini-3.8-flash) - Gemini 3.7 Flash (
gemini-3.7-flash) - Gemini 3.6 Flash (
gemini-3.6-flash) - Gemini 3.5 Flash-Lite (
gemini-3.5-flash-lite) - Gemini 3.5 Flash (
gemini-3.5-flash) - Gemini 3.1 Flash-Lite (
gemini-3.1-flash-lite) - Gemini 3.1 Pro (
gemini-3.1-pro-preview)
אם לפרויקט שלכם יש גישה לרשימת ההיתרים דרך צוות ניהול החשבון ב- Google Cloud , אתם יכולים להשתמש גם במודלים הבאים של Cyber:
- Gemini 4 Carbon לסייבר (
gemini-4-carbon-cyber-permissive) - Gemini 4 Argon Cyber Permissive (
gemini-4-argon-cyber-permissive)
לפני שמתחילים
בפרויקט קיים ב- Google Cloud שמופעל בו חיוב, מבצעים את השלבים הבאים:
-
נכנסים לחשבון Google.
אם עדיין אין חשבון, יוצרים חשבון חדש.
-
התקינו את ה-CLI של Google Cloud.
-
אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.
-
כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:
gcloud init מפעילים את Agent Platform API, אם הוא עדיין לא מופעל:
התפקידים שנדרשים כדי להפעיל ממשקי API
כדי להפעיל ממשקי API, צריך את ההרשאה
serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). כך מקצים תפקידים.gcloud services enable aiplatform.googleapis.com
-
אם אתם משתמשים במעטפת מקומית, צרו פרטי כניסה לאימות מקומי בחשבון המשתמש:
gcloud auth application-default login
אם אתם משתמשים ב-Cloud Shell, אתם לא צריכים לעשות את זה.
אם מוחזרת שגיאת אימות ואתם משתמשים בספק זהויות חיצוני (IdP), ודאו שנכנסתם ל-ה-CLI של gcloud באמצעות הזהות המאוחדת.
-
התקינו את ה-CLI של Google Cloud.
-
אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.
-
כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:
gcloud init מפעילים את Agent Platform API, אם הוא עדיין לא מופעל:
התפקידים שנדרשים כדי להפעיל ממשקי API
כדי להפעיל ממשקי API, צריך את ההרשאה
serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). כך מקצים תפקידים.gcloud services enable aiplatform.googleapis.com
-
אם אתם משתמשים במעטפת מקומית, צרו פרטי כניסה לאימות מקומי בחשבון המשתמש:
gcloud auth application-default login
אם אתם משתמשים ב-Cloud Shell, אתם לא צריכים לעשות את זה.
אם מוחזרת שגיאת אימות ואתם משתמשים בספק זהויות חיצוני (IdP), ודאו שנכנסתם ל-ה-CLI של gcloud באמצעות הזהות המאוחדת.
התפקידים הנדרשים
כדי לקבל את ההרשאות שדרושות ליצירה, למעקב ולביטול של קריאות למודלים מושהים, בקשו מהאדמין להקצות לכם את התפקידים הבאים ב-IAM בפרויקט ב- Google Cloud :
-
ליצור, לבדוק, לבטל ולמחוק אינטראקציות מושהות:
משתמש בפלטפורמת הסוכנים (
roles/aiplatform.user) -
מעקב אחרי אינטראקציות מושהות (לקריאה בלבד):
צפייה בפלטפורמת הנציגים (
roles/aiplatform.viewer) -
קריאת קובצי קלט מולטימודליים מ-Cloud Storage (אופציונלי):
צפייה באובייקטים באחסון (
roles/storage.objectViewer)
להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.
התקנת Google Gen AI SDK
אם אתם משתמשים בספריית לקוח, התקינו או שדרגו את Google Gen AI SDK (@google/genai >= 2.32.0 או google-genai >= 2.34.0) בסביבת הפיתוח:
Node.js
npm install @google/genai@latest
Python
pip install --upgrade "google-genai>=2.34.0"
יצירה וניהול של קריאות למודל מושהה
מריצים את התהליכים הבאים בסביבה שהגדרתם בקטע לפני שמתחילים. הדוגמאות ל-REST מאמתות באמצעות פרטי הכניסה של ה-CLI של gcloud, והדוגמאות ל-Google Gen AI SDK משתמשות בפרטי הכניסה של Application Default Credentials (ADC). אם קריאה מחזירה שגיאה, עיינו בקטע פתרון בעיות.
יצירת קריאה למודל מושהה
שולחים תור אסינכרוני באמצעות קריאה ל-interactions.create עם service_tier="deferred", background=true ו-store=true. משמיטים את stream או מגדירים אותו ל-false. לפני שמריצים דוגמה, מחליפים את PROJECT_ID במזהה הפרויקט ב- Google Cloud , למשל my-agent-project.
REST
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
-
PROJECT_ID: מזהה הפרויקט ב- Google Cloud , למשלmy-agent-project.
ה-method של ה-HTTP וכתובת ה-URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions
תוכן בקשת JSON:
{
"model": "gemini-4-argon",
"input": "In two sentences, explain how a circuit breaker differs from exponential backoff in a distributed microservice architecture.",
"service_tier": "deferred",
"background": true,
"store": true
}
כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:
התגובה מחזירה מטען ייעודי (payload) של JSON שדומה לזה:
{
"id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
"model": "gemini-4-argon",
"status": "queued",
"service_tier": "deferred",
"steps": []
}
Node.js
import { GoogleGenAI } from "@google/genai";
async function createDeferredInteraction(projectId) {
const ai = new GoogleGenAI({
enterprise: true,
project: projectId,
location: "global",
});
const interaction = await ai.interactions.create({
model: "gemini-4-argon",
input:
"In two sentences, explain how a circuit breaker differs from exponential backoff in a distributed microservice architecture.",
service_tier: "deferred",
background: true,
store: true,
});
console.log(`Interaction ID: ${interaction.id}`);
console.log(`Status: ${interaction.status}`);
console.log(`Service tier: ${interaction.service_tier}`);
return interaction.id ?? "";
}
await createDeferredInteraction("PROJECT_ID");
הפלט אמור להיראות כך:
Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred
Python
from google import genai
def create_deferred_interaction(project_id: str) -> str:
client = genai.Client(
enterprise=True,
project=project_id,
location="global",
)
interaction = client.interactions.create(
model="gemini-4-argon",
input=(
"In two sentences, explain how a circuit breaker differs from "
"exponential backoff in a distributed microservice architecture."
),
service_tier="deferred",
background=True,
store=True,
)
print(f"Interaction ID: {interaction.id}")
print(f"Status: {interaction.status}")
print(f"Service tier: {interaction.service_tier}")
return interaction.id or ""
create_deferred_interaction("PROJECT_ID")
הפלט אמור להיראות כך:
Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred
בדיקת סטטוס וקבלת נתונים על השימוש בטוקנים
מבצעים דגימה של interactions.get עם השהיה, כל עוד הערך של status הוא queued או in_progress. כשהתור מגיע לסטטוס סופי, קוראים את output_text ואת usage.
ברמת Deferred, היעד הוא להשלים 95% מהתורים תוך 24 שעות, בלי הסכם רמת שירות (SLA) לזמן אחזור שמגובה בקרדיט. בטבלה הבאה מתוארים הערכים של status במשאב Interaction:
| סטטוס | סופי | המשמעות והשלב הבא |
|---|---|---|
queued |
לא | הבקשה אושרה וממתינה לקיבולת. דגימה של interactions.get עם השהיה. עדיין לא צריך לבקש stream=true. |
in_progress |
לא | פועל. ממשיכים לדגום את interactions.get או מצרפים סטרימינג של SSE באמצעות stream=true. |
requires_action |
כן | התור הסתיים בשלב function_call שהמודל פלט. מפעילים את הכלי ואז יוצרים סבב חדש עם previous_interaction_id. |
requires_continuation |
כן | פענוח ארוך הופסק עם פלט חלקי וcontinuation_token. המשך עם previous_interaction_id ו-continuation_token, השמט את input והגבה את max_output_tokens. |
completed |
כן | התור הסתיים. צריך לקרוא את output_text ו-usage, או להעביר את id בתור previous_interaction_id בתור הבא. |
incomplete |
כן | התשובה הופסקה מוקדם מדי, למשל כשהיא הגיעה ל-max_output_tokens. בודקים את ה-steps וה-usage החלקיים. |
failed |
כן | הייתה שגיאת זמן ריצה או שחלון הזמן של 24 שעות להשלמת המשימה הסתיים. ה-API לא משתמש בסטטוס expired. צריך לבדוק את error ואז לשלוח בקשה חדשה. |
cancelled |
כן | שיחה אל interactions.cancel עצרה את התור לפני שהוא הסתיים. |
אם תור פענוח ארוך מסתיים בתור requires_continuation, צריך להמשיך אותו על ידי קריאה ל-interactions.create עם previous_interaction_id, continuation_token, background=true, store=true ו-service_tier="deferred". משמיטים את input ומגדירים את max_output_tokens לערך גבוה יותר ממספר האסימונים שנוצרו עד עכשיו. בקטע תמחור וחיוב מוסבר איך מתבצע החיוב על כל סטטוס סופי.
לפני שמריצים דוגמה, צריך להחליף את הערכים הבאים:
-
PROJECT_ID: מזהה הפרויקט ב- Google Cloud , למשלmy-agent-project.
INTERACTION_ID: מזהה האינטראקציה שמוחזר כשיוצרים את הקריאה למודל המושהה, למשלv1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
REST
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
-
PROJECT_ID: מזהה הפרויקט ב- Google Cloud , למשלmy-agent-project. -
INTERACTION_ID: מזהה האינטראקציה שהוחזר כשיצרתם את הקריאה למודל המושהה, למשלv1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
ה-method של ה-HTTP וכתובת ה-URL:
GET https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID
כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:
התגובה מחזירה מטען ייעודי (payload) של JSON שדומה לזה:
{
"id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
"model": "gemini-4-argon",
"status": "completed",
"service_tier": "deferred",
"steps": [
{
"type": "model_output",
"content": [
{
"type": "text",
"text": "Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again."
}
]
}
],
"usage": {
"total_input_tokens": 27,
"total_output_tokens": 41,
"total_tokens": 68
}
}
Node.js
import { GoogleGenAI } from "@google/genai";
const PENDING_STATES = new Set(["queued", "in_progress"]);
const MAX_DELAY_MS = 30000;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function waitForDeferredInteraction(projectId, interactionId) {
const ai = new GoogleGenAI({
enterprise: true,
project: projectId,
location: "global",
});
let delayMs = 5000;
let current = await ai.interactions.get(interactionId);
while (PENDING_STATES.has(current.status)) {
await sleep(delayMs);
delayMs = Math.min(delayMs * 2, MAX_DELAY_MS);
current = await ai.interactions.get(interactionId);
}
console.log(`Status: ${current.status}`);
if (current.status === "failed") {
throw new Error(`Deferred turn failed: ${JSON.stringify(current.error)}`);
}
if (current.output_text) {
console.log(current.output_text);
}
if (current.usage) {
console.log(`Input tokens: ${current.usage.total_input_tokens}`);
console.log(`Output tokens: ${current.usage.total_output_tokens}`);
console.log(`Total tokens: ${current.usage.total_tokens}`);
}
return current.output_text ?? "";
}
await waitForDeferredInteraction(
"PROJECT_ID",
"INTERACTION_ID",
);
הפלט אמור להיראות כך:
Status: completed
Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again.
Input tokens: 27
Output tokens: 41
Total tokens: 68
Python
import time
from google import genai
PENDING_STATES = frozenset({"queued", "in_progress"})
MAX_DELAY_SECONDS = 30.0
def wait_for_deferred_interaction(
project_id: str,
interaction_id: str,
) -> str:
client = genai.Client(
enterprise=True,
project=project_id,
location="global",
)
delay_seconds = 5.0
current = client.interactions.get(interaction_id)
while current.status in PENDING_STATES:
time.sleep(delay_seconds)
delay_seconds = min(delay_seconds * 2.0, MAX_DELAY_SECONDS)
current = client.interactions.get(interaction_id)
print(f"Status: {current.status}")
if current.status == "failed":
raise RuntimeError(f"Deferred turn failed: {current.error}")
if current.output_text:
print(current.output_text)
if current.usage:
print(f"Input tokens: {current.usage.total_input_tokens}")
print(f"Output tokens: {current.usage.total_output_tokens}")
print(f"Total tokens: {current.usage.total_tokens}")
return current.output_text or ""
wait_for_deferred_interaction(
"PROJECT_ID",
"INTERACTION_ID",
)
הפלט אמור להיראות כך:
Status: completed
Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again.
Input tokens: 27
Output tokens: 41
Total tokens: 68
אופציונלי: פלט סטרימינג בזמן שהקריאה פועלת
אחרי ש-interactions.get מדווח על status="in_progress", אפשר לצרף סטרימינג של אירועים שנשלחים מהשרת (SSE) באמצעות stream=true ולחדש חיבורים שנותקו באמצעות last_event_id:
REST
מוסיפים את ?stream=true לכתובת ה-URL של interactions.get. כשמתחברים מחדש, צריך גם להוסיף את &last_event_id=EVENT_ID, ולהחליף את EVENT_ID במזהה האירוע האחרון שהתקבל.
Node.js
חוזרים על await ai.interactions.get(interactionId, { stream: true,
last_event_id: lastEventId }), מתעדים את event.event_id וקוראים את event.delta?.text באירועים של step.delta.
Python
חזרה על client.interactions.get(interaction_id, stream=True,
last_event_id=last_event_id), תיעוד event.event_id וקריאת event.delta.text באירועים של step.delta.
מידע נוסף על סטרימינג וחיבור מחדש של SSE זמין במדריך למפתחים של Interactions API.
שרשור של תהליכי עבודה מושהים עם כמה שלבים
כדי להמשיך שיחה בכמה שלבים או להחזיר תוצאות של הפעלת כלי, מעבירים את ה-id של אינטראקציה מסוג completed או requires_action ב-previous_interaction_id. שדות ברמת התור, כמו tools, system_instruction ו-generation_config, לא מועברים אוטומטית, אז צריך להעביר אותם בכל תור שבו הם נדרשים. סבבי שיחה משורשרים עדיין מתאימים לשמירת הקשר במטמון באופן משתמע, אבל יכול להיות שתוקף הקידומות שנשמרו במטמון יפוג בזמן המתנה של כמה שעות בתור. סכימות של שלבי תוצאות הכלים מפורטות במדריך למפתחים של Interactions API.
לפני שמריצים דוגמה, צריך להחליף את הערכים הבאים:
-
PROJECT_ID: מזהה הפרויקט ב- Google Cloud , למשלmy-agent-project.
PREVIOUS_INTERACTION_ID: המזהה של התור הקודם שלcompletedאוrequires_action, למשלv1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
REST
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
-
PROJECT_ID: מזהה הפרויקט ב- Google Cloud , למשלmy-agent-project. -
PREVIOUS_INTERACTION_ID: מזהה האינטראקציה שהושלמה או שנדרשת בה פעולה מהשלב הקודם, למשלv1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
ה-method של ה-HTTP וכתובת ה-URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions
תוכן בקשת JSON:
{
"model": "gemini-4-argon",
"previous_interaction_id": "PREVIOUS_INTERACTION_ID",
"input": "Draft a one-paragraph rollout checklist for adding a circuit breaker to a payment gateway client without causing false trips.",
"service_tier": "deferred",
"background": true,
"store": true
}
כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:
התגובה מחזירה מטען ייעודי (payload) של JSON שדומה לזה:
{
"id": "v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0",
"model": "gemini-4-argon",
"previous_interaction_id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
"status": "queued",
"service_tier": "deferred",
"steps": []
}
Node.js
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
enterprise: true,
project: "PROJECT_ID",
location: "global",
});
const followUp = await ai.interactions.create({
model: "gemini-4-argon",
previous_interaction_id: "PREVIOUS_INTERACTION_ID",
input:
"Draft a one-paragraph rollout checklist for adding a circuit breaker to a payment gateway client without causing false trips.",
service_tier: "deferred",
background: true,
store: true,
});
console.log(`Follow-up ID: ${followUp.id} (${followUp.status})`);
הפלט אמור להיראות כך:
Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)
Python
from google import genai
client = genai.Client(
enterprise=True,
project="PROJECT_ID",
location="global",
)
follow_up = client.interactions.create(
model="gemini-4-argon",
previous_interaction_id="PREVIOUS_INTERACTION_ID",
input=(
"Draft a one-paragraph rollout checklist for adding a circuit "
"breaker to a payment gateway client without causing false trips."
),
service_tier="deferred",
background=True,
store=True,
)
print(f"Follow-up ID: {follow_up.id} ({follow_up.status})")
הפלט אמור להיראות כך:
Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)
ביטול קריאה למודל מושהה
כדי לעצור אינטראקציה מושהית שהערך של status שלה הוא queued או in_progress, צריך להפעיל את interactions.cancel. אם קוראים ל-interactions.cancel באינטראקציה בכל סטטוס אחר, מוחזרת השגיאה 409 ("code": "aborted") של HTTP. בקטע תמחור וחיוב מוסבר איך הביטול משפיע על החיוב.
לפני שמריצים דוגמה, צריך להחליף את הערכים הבאים:
-
PROJECT_ID: מזהה הפרויקט ב- Google Cloud , למשלmy-agent-project.
INTERACTION_ID: המזהה של אינטראקציה מסוגqueuedאוin_progress, למשלv1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.
REST
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
-
PROJECT_ID: מזהה הפרויקט ב- Google Cloud , למשלmy-agent-project. -
INTERACTION_ID: המזהה של אינטראקציה בתור או בתהליך שרוצים לבטל, למשלv1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.
ה-method של ה-HTTP וכתובת ה-URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel
כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:
התגובה מחזירה מטען ייעודי (payload) של JSON שדומה לזה:
{
"id": "v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ",
"model": "gemini-4-argon",
"status": "cancelled",
"service_tier": "deferred"
}
Node.js
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
enterprise: true,
project: "PROJECT_ID",
location: "global",
});
const cancelled = await ai.interactions.cancel("INTERACTION_ID");
console.log(`Status: ${cancelled.status}`);
הפלט שיתקבל:
Status: cancelled
Python
from google import genai
client = genai.Client(
enterprise=True,
project="PROJECT_ID",
location="global",
)
cancelled = client.interactions.cancel("INTERACTION_ID")
print(f"Status: {cancelled.status}")
הפלט שיתקבל:
Status: cancelled
תמחור, מכסות ואמצעי בקרה לאבטחה
לפני שמריצים עומסי עבודה בסביבת הייצור ברמת Deferred, חשוב לבדוק את כללי החיוב, המכסות, מגבלות המטען הייעודי (payload) ואמצעי הבקרה לאבטחה.
תמחור וחיוב
החיוב על קריאות למודל עם עיכוב כולל הנחה של 50% בהשוואה לתעריפים של תשלום רגיל לפי שימוש על טוקנים של קלט, פלט וחשיבה. החיוב מתבצע לפי הכללים הבאים:
- הנחות מצטברות: ההנחה על השימוש המאוחר מצטברת עם הנחות חוזיות והנחות על טוקנים של שמירת הקשר במטמון באופן משתמע, והיא חלה בנוסף לתעריף של שמירת ההקשר במטמון.
- אין חזרה לתעריפים רגילים: בקשות מושהות אף פעם לא עוברות או משונמכות ל-Standard PayGo, ולכן הן לא מחויבות בתעריפים רגילים ללא הנחה.
- חיוב לפי קריאה למודל: כל קריאה למודל שמתבצעת בתור מחויבת.
תורות שמסתיימים בסטטוס
completed,incomplete,requires_actionאוrequires_continuationמחויבים בתעריף של תורות שנדחו. - פניות שבוטלו: פנייה שביטלתם כשהיא הייתה במצב
queuedלא תחויב. אם מבטלים תור כשהוא במצבin_progress, הקריאות למודל שכבר התחילו מחויבות, כולל קריאה שהופסקה באמצע תהליך היצירה. - פניות שנכשלו: פניות בשיחה אחת שמסתיימות בסטטוס
failed, כולל פניות שחורגות מחלון הזמן של 24 שעות להשלמה, לא מחויבות. בלולאה מרובת שלבים של כלים בצד השרת, קריאות למודל שהושלמו לפני הכישלון מחויבות, אבל הקריאה שנכשלה לא מחויבת. - פניות משורשרות: כל פנייה בשרשרת של
previous_interaction_idמחויבת בנפרד. ביטול של תור מאוחר יותר, או כישלון של תור מאוחר יותר, לא משנה את החיובים על תורים מוקדמים יותר.
בדף התמחור של Agent Platform מפורטים תעריפי הטוקנים לכל מודל.
מכסות, מגבלות על המטען הייעודי (payload) ושימור
לרמת Deferred אין מכסה משלה לקריאות למודל. קריאות מושהות חולקות את המכסה של Flex בתשלום לפי שימוש (flex_requests_per_minute_per_project_per_base_model, 3,000 RPM), שנבדקת בכל קריאה למודל אחרי ש-interactions.create מחזיר queued. אלה המכסות העיקריות לפרויקטים ומגבלות המערכת:
- מכסות יצירה ובו-זמניות: עד 100 בקשות לדקה או ללא הגבלה ל-
stateful_genai_interaction_creationsבזמן היצירה. עד 500concurrent_interaction_generations, בהתאם לרמת המכסה. - קצב העברת נתונים יומי עם שמירת מצב (קבוע): 240GiB ליום לכתיבה ו-480GiB ליום לקריאה בכל פרויקט.
- מגבלות על המטען הייעודי (payload) ועל השמירה: עד 9.75MiB של גוף HTTP לא דחוס לכל קריאה ל-
interactions.create, ושמירת מצב למשך 7 ימים. אפשר להשתמש בשרשראות עם עד 100 מזהי URI נפרדים של Cloud Storage (gs://).
במאמר מכסות ומגבלות של Deferred Tier מופיעה טבלת המכסות המלאה והוראות לשימוש במסוף.
אמצעי בקרה לאבטחה ותאימות
מכיוון שהרמה Deferred מוסיפה לתור ושומרת את המצב בנקודת הקצה של global, ודאו שאמצעי הבקרה הנתמכים שלה תואמים לדרישות התאימות שלכם:
- אמצעי הבקרה הנתמכים:
VPC Service Controls
(VPC-SC; אסור להשתמש בכלים חיצוניים של
mcp_serverבתוך היקף האבטחה), Access Transparency (AXT), יומני ביקורת של Cloud ו-FedRAMP High. - אמצעי בקרה שלא נתמכים: שמירת נתונים בלי שמירת מצב (
store=falseואכיפתconstraints/vertexai.disableAPIStorageמחזירות את שגיאת HTTP400עם"code": "invalid_request"), מפתחות הצפנה בניהול הלקוח (CMEK), מיקום אחסון הנתונים, DoD IL5 ו-ITAR.
במאמר אמצעי אבטחה ל-AI גנרטיבי מפורטות כל התכונות.
פתרון בעיות
בטבלה הבאה מתוארות שגיאות נפוצות ברמה Deferred ואיך לפתור אותן:
| שגיאה או סטטוס | גורמים נפוצים | רזולוציה |
|---|---|---|
400 (error.code: "invalid_request"; נקודת קצה, דגלים או מודל) |
נקודת קצה (endpoint) שאינה global, מודל לא נתמך או דגלים לא חוקיים של background, store או stream ב-interactions.create. |
מטרגטים את locations/global באמצעות מודל נתמך, מגדירים את background=true ו-store=true, ומשמיטים את stream=true. |
400 (error.code: "invalid_request"; מטען ייעודי (payload), מזהי URI או כלים) |
גוף לא דחוס חורג מ-9.75 MiB, השרשרת חורגת מ-100 מזהי URI של gs://, או כלים חיצוניים של mcp_server בתוך VPC-SC. |
מעבירים קבצים גדולים בתור מזהי URI של gs:// (עד 100 לכל שרשרת), ומשמיטים כלים חיצוניים של mcp_server בתוך VPC-SC. |
400 (error.code: "invalid_request" ב-interactions.create; status: "FAILED_PRECONDITION" ב-interactions.delete) |
|
|
401 (status: "UNAUTHENTICATED" או error.code: "authentication") |
פרטי הכניסה ל-CLI של gcloud (דוגמאות ל-REST) או ל-ADC (דוגמאות ל-Google Gen AI SDK) חסרים או שפג תוקפם. | בדוגמאות של REST, מריצים את gcloud auth login. כדי לראות דוגמאות ל-Google Gen AI SDK, מריצים את הפקודה gcloud auth application-default login. אחר כך אפשר לנסות לשלוח את הבקשה שוב. |
403 (status: "PERMISSION_DENIED" או error.code: "permission_denied") |
|
הענקת הרשאה ל-roles/aiplatform.user. לקלט של Cloud Storage, צריך להקצות גם את התפקיד roles/storage.objectViewer. |
404 (error.code: "not_found"; status: "NOT_FOUND" ב-interactions.delete) |
האינטראקציה או previous_interaction_id לא קיימים או שהם נמחקו. יכול להיות גם שהיא שייכת לנקודת קצה (endpoint) שהיא לא של global, או שהיא ישנה יותר מתקופת השמירה של 7 ימים. |
בודקים את מזהה האינטראקציה בנקודת הקצה (endpoint) של global. אם התור של ההורה פג, צריך להתחיל שרשרת חדשה בלי previous_interaction_id. |
409 (error.code: "aborted") |
האירוע interactions.cancel מטרגט אינטראקציה שכבר נמצאת בסטטוס סופי: requires_action, requires_continuation, completed, incomplete, failed או cancelled. |
קודם צריך לבדוק את status עם interactions.get. אפשר לבטל רק אינטראקציות מסוג queued ו-in_progress. |
429 (error.code: "too_many_requests") |
הפרויקט חרג מהמכסה לכל פרויקט, כמו קצב יצירת האינטראקציות, יצירת אינטראקציות בו-זמנית או קצב העברת הנתונים היומי עם שמירת מצב. |
|
status="failed" |
|
|
המאמרים הבאים
מדריכים קשורים ומאמרי עזרה לעומסי עבודה אסינכרוניים ועם שמירת מצב ב-Gemini:
- השוואה בין מודלים של מחשוב באפשרויות צריכה.
- במדריך למפתחים בנושא Interactions API מוסבר איך ליצור אפליקציות עם שיחות מרובות-שלבים ששומרות את מצב השיחה.
- מתזמנים סוכני ADK ומנהלים הרצות מחקר בתזמון סוכנים אוטונומיים.
- במאמרי העזרה של Interactions API מוסבר על סכימות של שיטות.