קריאה לממשקי MaaS API עבור מודלים פתוחים

מודלים פתוחים רבים ב-Gemini Enterprise Agent Platform מציעים מודלים מנוהלים לחלוטין וללא שרתים כממשקי API באמצעות Chat Completions API של Gemini Enterprise Agent Platform. במודלים האלה אין צורך להקצות או לנהל תשתית.

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

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

לפני שמתחילים

כדי להשתמש במודלים פתוחים עם Gemini Enterprise Agent Platform, צריך לבצע את השלבים הבאים. כדי להשתמש ב-Gemini Enterprise Agent Platform, צריך להפעיל את Agent Platform API ‏(aiplatform.googleapis.com). אם כבר יש לכם פרויקט שבו מופעל Agent Platform API, אתם יכולים להשתמש בו במקום ליצור פרויקט חדש.

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. עוברים לכרטיס המודל ב-Model Garden של המודל שרוצים להשתמש בו, ואז לוחצים על הפעלה כדי להפעיל את המודל לשימוש בפרויקט.

    כניסה ל-Model Garden

התחלת שיחה עם מודל פתוח

בדוגמה הבאה מבוצעת קריאה להזרמת נתונים למודל פתוח:

Python

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

כדי לבצע אימות ב-Agent Platform, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.

לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.

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

from openai import OpenAI
client = OpenAI()

stream = client.chat.completions.create(
    model="MODEL",
    messages=[{"role": "ROLE", "content": "CONTENT"}],
    max_tokens=MAX_OUTPUT_TOKENS,
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
  • ‫MODEL: שם המודל שרוצים להשתמש בו, לדוגמה deepseek-ai/deepseek-v3.1-maas.
  • ROLE: התפקיד שמשויך להודעה. אפשר לציין user או assistant. ההודעה הראשונה חייבת להשתמש בתפקיד user. המודלים פועלים בתורות מתחלפות user וassistant. אם ההודעה האחרונה משתמשת בתפקיד assistant, תוכן התגובה ממשיך מיד מהתוכן שבהודעה הזו. אפשר להשתמש בזה כדי להגביל חלק מהתשובה של המודל.
  • ‫CONTENT: התוכן, למשל הטקסט, של ההודעה user או assistant.
  • ‫MAX_OUTPUT_TOKENS: מספר האסימונים המקסימלי שאפשר ליצור בתגובה. אסימון הוא בערך ארבעה תווים. 100 אסימונים מקבילים בערך ל-60-80 מילים.

    כדי לקבל תשובות קצרות יותר, מציינים ערך נמוך יותר, וכדי לקבל תשובות ארוכות יותר, מציינים ערך גבוה יותר.

REST

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

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫LOCATION: אזור שתומך במודלים פתוחים.
  • ‫MODEL: שם המודל שרוצים להשתמש בו, לדוגמה deepseek-ai/deepseek-v2.
  • ROLE: התפקיד שמשויך להודעה. אפשר לציין user או assistant. ההודעה הראשונה חייבת להשתמש בתפקיד user. המודלים פועלים בתורות מתחלפות user וassistant. אם ההודעה האחרונה משתמשת בתפקיד assistant, תוכן התגובה ממשיך מיד מהתוכן שבהודעה הזו. אפשר להשתמש בזה כדי להגביל חלק מהתשובה של המודל.
  • ‫CONTENT: התוכן, למשל הטקסט, של ההודעה user או assistant.
  • ‫MAX_OUTPUT_TOKENS: מספר האסימונים המקסימלי שאפשר ליצור בתגובה. אסימון הוא בערך ארבעה תווים. 100 אסימונים מקבילים בערך ל-60-80 מילים.

    כדי לקבל תשובות קצרות יותר, מציינים ערך נמוך יותר, וכדי לקבל תשובות ארוכות יותר, מציינים ערך גבוה יותר.

  • ‫STREAM: ערך בוליאני שמציין אם התשובה מוצגת באופן שוטף או לא. הצגת התשובה באופן שוטף מקטינה את השהייה שנתפסת אצל משתמש הקצה. מגדירים את הערך ל-true כדי שהתשובה תוצג באופן שוטף, ול-false כדי שהתשובה תוצג בבת אחת.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions

גוף בקשת JSON: 

{
  "model": "MODEL",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_OUTPUT_TOKENS,
  "stream": true
}

כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

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

הדוגמה הבאה מציגה קריאה לא הזרמתית למודל פתוח:

Python

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

כדי לבצע אימות ב-Agent Platform, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.

לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.

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

from openai import OpenAI
client = OpenAI()

completion = client.chat.completions.create(
    model="MODEL",
    messages=[{"role": "ROLE", "content": "CONTENT"}],
    max_tokens=MAX_OUTPUT_TOKENS,
    stream=False,
)
print(completion.choices[0].message)
  • ‫MODEL: שם המודל שרוצים להשתמש בו, לדוגמה deepseek-ai/deepseek-v3.1-maas.
  • ROLE: התפקיד שמשויך להודעה. אפשר לציין user או assistant. ההודעה הראשונה חייבת להשתמש בתפקיד user. המודלים פועלים בתורות מתחלפות user וassistant. אם ההודעה האחרונה משתמשת בתפקיד assistant, תוכן התגובה ממשיך מיד מהתוכן שבהודעה הזו. אפשר להשתמש בזה כדי להגביל חלק מהתשובה של המודל.
  • ‫CONTENT: התוכן, למשל הטקסט, של ההודעה user או assistant.
  • ‫MAX_OUTPUT_TOKENS: מספר האסימונים המקסימלי שאפשר ליצור בתגובה. אסימון הוא בערך ארבעה תווים. 100 אסימונים מקבילים בערך ל-60-80 מילים.

    כדי לקבל תשובות קצרות יותר, מציינים ערך נמוך יותר, וכדי לקבל תשובות ארוכות יותר, מציינים ערך גבוה יותר.

REST

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

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫LOCATION: אזור שתומך במודלים פתוחים.
  • ‫MODEL: שם המודל שרוצים להשתמש בו, לדוגמה deepseek-ai/deepseek-v2.
  • ROLE: התפקיד שמשויך להודעה. אפשר לציין user או assistant. ההודעה הראשונה חייבת להשתמש בתפקיד user. המודלים פועלים בתורות מתחלפות user וassistant. אם ההודעה האחרונה משתמשת בתפקיד assistant, תוכן התגובה ממשיך מיד מהתוכן שבהודעה הזו. אפשר להשתמש בזה כדי להגביל חלק מהתשובה של המודל.
  • ‫CONTENT: התוכן, למשל הטקסט, של ההודעה user או assistant.
  • ‫MAX_OUTPUT_TOKENS: מספר האסימונים המקסימלי שאפשר ליצור בתגובה. אסימון הוא בערך ארבעה תווים. 100 אסימונים מקבילים בערך ל-60-80 מילים.

    כדי לקבל תשובות קצרות יותר, מציינים ערך נמוך יותר, וכדי לקבל תשובות ארוכות יותר, מציינים ערך גבוה יותר.

  • ‫STREAM: ערך בוליאני שמציין אם התשובה מוצגת באופן שוטף או לא. הצגת התשובה באופן שוטף מקטינה את השהייה שנתפסת אצל משתמש הקצה. מגדירים את הערך ל-true כדי שהתשובה תוצג באופן שוטף, ול-false כדי שהתשובה תוצג בבת אחת.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions

גוף בקשת JSON: 

{
  "model": "MODEL",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_OUTPUT_TOKENS,
  "stream": false
}

כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

נקודות קצה אזוריות וגלובליות

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

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

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

ציון נקודת הקצה הגלובלית

כדי להשתמש בנקודת הקצה הגלובלית, מגדירים את האזור ל-global.

לדוגמה, כתובת ה-URL של הבקשה לפקודת curl מבוססת על הפורמט הבא: https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi

ב-Agent Platform SDK, נקודת קצה אזורית היא ברירת המחדל. כדי להשתמש בנקודת הקצה הגלובלית, צריך להגדיר את האזור ל-GLOBAL.

הגבלת השימוש בנקודת קצה ל-API גלובלית

כדי לאכוף את השימוש בנקודות קצה אזוריות, אפשר להשתמש במגבלת מדיניות הארגון constraints/gcp.restrictEndpointUsage כדי לחסום בקשות לנקודת קצה ל-API גלובלית. למידע נוסף, ראו הגבלת השימוש בנקודות קצה.

המאמרים הבאים