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

הרבה מודלים פתוחים ב-Gemini Enterprise Agent Platform מציעים מודלים מנוהלים לחלוטין ובלי שרת (serverless) כממשקי 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) ואת Cloud Commerce Consumer Procurement API (cloudcommerceconsumerprocurement.googleapis.com). אם כבר יש לכם פרויקט שבו ממשקי ה-API האלה מופעלים, אתם יכולים להשתמש בו במקום ליצור פרויקט חדש.

  1. נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud 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

  3. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  4. Verify that billing is enabled for your Google Cloud project.

  5. Enable the Gemini Enterprise Agent Platform and Cloud Commerce Consumer Procurement APIs, if any are 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 APIs

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud 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

  7. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  8. Verify that billing is enabled for your Google Cloud project.

  9. Enable the Gemini Enterprise Agent Platform and Cloud Commerce Consumer Procurement APIs, if any are 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 APIs

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

    כניסה ל-Model Garden

התפקידים הנדרשים

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

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

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

מידע נוסף על מתן הרשאות והגדרת מדיניות ארגונית למודלים פתוחים זמין במאמר מתן גישה למשתמשים למודלים פתוחים.

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

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

Python

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

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

לפני שמריצים את הדוגמה הזו, צריך להגדיר את משתנה הסביבה 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: שם המודל שבו רוצים להשתמש, לדוגמה openai/gpt-oss-120b-maas.
  • ‫ROLE: התפקיד שמשויך להודעה. אפשר לציין user או assistant. ההודעה הראשונה חייבת להשתמש בתפקיד user. המודלים פועלים בתורות, פעם user ופעם assistant. אם ההודעה האחרונה משתמשת בתפקיד assistant, תוכן התשובה ממשיך מיד מהתוכן של ההודעה הזו. אפשר להשתמש בזה כדי להגביל חלק מהתשובה של המודל.
  • ‫CONTENT: התוכן, כמו טקסט, של ההודעה ב-user או ב-assistant.
  • MAX_OUTPUT_TOKENS: המספר המקסימלי של טוקנים שאפשר ליצור בתשובה. טוקן הוא בערך ארבעה תווים. ‫100 טוקנים שווים בערך ל-60 עד 80 מילים.

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

REST

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

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud.
  • ‫MODEL: שם המודל שבו רוצים להשתמש, לדוגמה openai/gpt-oss-120b-maas.
  • ‫ROLE: התפקיד שמשויך להודעה. אפשר לציין user או assistant. ההודעה הראשונה חייבת להשתמש בתפקיד user. המודלים פועלים בתורות, פעם user ופעם assistant. אם ההודעה האחרונה משתמשת בתפקיד assistant, תוכן התשובה ממשיך מיד מהתוכן של ההודעה הזו. אפשר להשתמש בזה כדי להגביל חלק מהתשובה של המודל.
  • ‫CONTENT: התוכן, כמו טקסט, של ההודעה ב-user או ב-assistant.
  • MAX_OUTPUT_TOKENS: המספר המקסימלי של טוקנים שאפשר ליצור בתשובה. טוקן הוא בערך ארבעה תווים. ‫100 טוקנים שווים בערך ל-60 עד 80 מילים.

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

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

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

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/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://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/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://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions" | Select-Object -Expand Content

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

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

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

Python

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

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

לפני שמריצים את הדוגמה הזו, צריך להגדיר את משתנה הסביבה 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: שם המודל שבו רוצים להשתמש, לדוגמה openai/gpt-oss-120b-maas.
  • ‫ROLE: התפקיד שמשויך להודעה. אפשר לציין user או assistant. ההודעה הראשונה חייבת להשתמש בתפקיד user. המודלים פועלים בתורות, פעם user ופעם assistant. אם ההודעה האחרונה משתמשת בתפקיד assistant, תוכן התשובה ממשיך מיד מהתוכן של ההודעה הזו. אפשר להשתמש בזה כדי להגביל חלק מהתשובה של המודל.
  • ‫CONTENT: התוכן, כמו טקסט, של ההודעה ב-user או ב-assistant.
  • MAX_OUTPUT_TOKENS: המספר המקסימלי של טוקנים שאפשר ליצור בתשובה. טוקן הוא בערך ארבעה תווים. ‫100 טוקנים שווים בערך ל-60 עד 80 מילים.

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

REST

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

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud.
  • ‫MODEL: שם המודל שבו רוצים להשתמש, לדוגמה openai/gpt-oss-120b-maas.
  • ‫ROLE: התפקיד שמשויך להודעה. אפשר לציין user או assistant. ההודעה הראשונה חייבת להשתמש בתפקיד user. המודלים פועלים בתורות, פעם user ופעם assistant. אם ההודעה האחרונה משתמשת בתפקיד assistant, תוכן התשובה ממשיך מיד מהתוכן של ההודעה הזו. אפשר להשתמש בזה כדי להגביל חלק מהתשובה של המודל.
  • ‫CONTENT: התוכן, כמו טקסט, של ההודעה ב-user או ב-assistant.
  • MAX_OUTPUT_TOKENS: המספר המקסימלי של טוקנים שאפשר ליצור בתשובה. טוקן הוא בערך ארבעה תווים. ‫100 טוקנים שווים בערך ל-60 עד 80 מילים.

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

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

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

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/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://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/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://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/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. מידע נוסף זמין במאמר הגבלת השימוש בנקודות קצה (endpoints).

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