קבלת מסקנות אונליין ממודל שאומן בהתאמה אישית

בדף הזה מוסבר איך לקבל הסקות אונליין (בזמן אמת) מהמודלים המותאמים אישית שאומנו באמצעות Google Cloud CLI או Agent Platform API.

עיצוב הקלט להסקה אונליין

בקטע הזה מוסבר איך להגדיר את הפורמט והקידוד של המכונות של קלט ההסקה כ-JSON, שנדרש אם משתמשים ב-method‏ predict או explain. לא צריך להגדיר את זה אם משתמשים בשיטה rawPredict. במאמר שליחת בקשה לנקודת קצה (endpoint) מוסבר איך לבחור את השיטה.

אם אתם משתמשים ב-Agent Platform SDK ל-Python כדי לשלוח בקשות להסקת מסקנות, ציינו את רשימת המכונות בלי השדה instances. לדוגמה, צריך לציין [ ["the","quick","brown"], ... ] במקום { "instances": [ ["the","quick","brown"], ... ] }.

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

פורמט של מופעים כמחרוזות JSON

הפורמט הבסיסי להסקת מסקנות אונליין הוא רשימה של מופעי נתונים. אלה יכולות להיות רשימות פשוטות של ערכים או איברים של אובייקט JSON, בהתאם לאופן שבו הגדרתם את הקלט באפליקציית האימון. מודלים של TensorFlow יכולים לקבל קלט מורכב יותר, בעוד שרוב המודלים של scikit-learn ו-XGBoost מצפים לרשימה של מספרים כקלט.

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

 {"values": [1, 2, 3, 4], "key": 1}

המבנה של מחרוזת ה-JSON יכול להיות מורכב, כל עוד הוא עומד בכללים הבאים:

  • הרמה העליונה של נתוני המופע חייבת להיות אובייקט JSON: מילון של צמדי מפתח/ערך.

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

  • רשימות יכולות להכיל רק פריטים מאותו סוג (כולל רשימות אחרות). אי אפשר לשלב ערכי מחרוזת וערכים מספריים.

אתם מעבירים מופעי קלט להסקה אונליין כגוף ההודעה לקריאה ל-projects.locations.endpoints.predict. מידע נוסף על הדרישות בנוגע לפורמט של גוף הבקשה

כל מופע צריך להיות פריט במערך JSON, ואת המערך צריך לספק בתור השדה instances של אובייקט JSON. לדוגמה:

{"instances": [
  {"values": [1, 2, 3, 4], "key": 1},
  {"values": [5, 6, 7, 8], "key": 2}
]}

קידוד נתונים בינאריים לקלט של הסקה

אי אפשר להגדיר את הפורמט של נתונים בינאריים כמחרוזות בקידוד UTF-8 שנתמכות ב-JSON. אם יש לכם נתונים בינאריים בקלט, אתם צריכים להשתמש בקידוד base64 כדי לייצג אותם. צריך להשתמש בפורמט המיוחד הבא:

  • המחרוזת המקודדת צריכה להיות בפורמט של אובייקט JSON עם מפתח אחד בשם b64. ב-Python 3, קידוד base64 מוציא רצף בייטים. צריך להמיר את זה למחרוזת כדי שיהיה אפשר להפוך את זה ל-JSON:

    {'image_bytes': {'b64': base64.b64encode(jpeg_data).decode()}}

  • בקוד של מודל TensorFlow, צריך לתת שמות לכינויים של טנזורי הקלט והפלט הבינאריים כך שהם יסתיימו ב-‎_bytes.

דוגמאות לבקשות ותשובות

בקטע הזה מתואר הפורמט של גוף הבקשה להסקת מסקנות ושל גוף התגובה, עם דוגמאות ל-TensorFlow, ל-scikit-learn ול-XGBoost.

פרטי גוף הבקשה

TensorFlow

גוף הבקשה מכיל נתונים במבנה הבא (ייצוג JSON):

{
  "instances": [
    <value>|<simple/nested list>|<object>,
    ...
  ]
}

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

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

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

בהמשך מופיעות כמה דוגמאות לגופי בקשות.

נתוני CSV שבהם כל שורה מקודדת כערך מחרוזת:

{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}

טקסט פשוט:

{"instances": ["the quick brown fox", "the lazy dog"]}

משפטים שמקודדים כרשימות של מילים (וקטורים של מחרוזות):

{
  "instances": [
    ["the","quick","brown"],
    ["the","lazy","dog"],
    ...
  ]
}

ערכים סקלריים של נקודה צפה (floating-point):

{"instances": [0.0, 1.1, 2.2]}

וקטורים של מספרים שלמים:

{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}

טנזורים (במקרה הזה, טנזורים דו-ממדיים):

{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}

תמונות, שאפשר לייצג בדרכים שונות. בשיטת הקידוד הזו, שני המאפיינים הראשונים מייצגים את השורות והעמודות של התמונה, והמאפיין השלישי מכיל רשימות (וקטורים) של ערכי R, ‏ G ו-B לכל פיקסל:

{
  "instances": [
    [
      [
        [138, 30, 66],
        [130, 20, 56],
        ...
      ],
      [
        [126, 38, 61],
        [122, 24, 57],
        ...
      ],
      ...
    ],
    ...
  ]
}

קידוד נתונים

מחרוזות JSON צריכות להיות מקודדות ב-UTF-8. כדי לשלוח נתונים בינאריים, צריך לקודד אותם ב-base64 ולסמן אותם כבינאריים. כדי לסמן מחרוזת JSON כבינארית, מחליפים אותה באובייקט JSON עם שם מאפיין יחיד בשם b64: 

{"b64": "..."}

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

{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}

בדוגמה הבאה מוצגות שתי מחרוזות בייטים של תמונות JPEG, שדורשות קידוד base64 (נתונים מזויפים, למטרות המחשה בלבד):

{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}

טנזורים מרובים של קלט

בחלק מהמודלים יש תרשים TensorFlow בסיסי שמקבל כמה טנזורים של קלט. במקרה כזה, צריך להשתמש בשמות של צמדי שם/ערך ב-JSON כדי לזהות את טנזורי הקלט.

בתרשים עם כינויי טנסור קלט "tag" (מחרוזת) ו-"image" (מחרוזת בקידוד base64): 

{
  "instances": [
    {
      "tag": "beach",
      "image": {"b64": "ASa8asdf"}
    },
    {
      "tag": "car",
      "image": {"b64": "JLK7ljk3"}
    }
  ]
}

בתרשים עם כינויי טנסור קלט "tag" (מחרוזת) ו-"image" (מערך תלת-ממדי של מספרים שלמים של 8 ביט):

{
  "instances": [
    {
      "tag": "beach",
      "image": [
        [
          [138, 30, 66],
          [130, 20, 56],
          ...
        ],
        [
          [126, 38, 61],
          [122, 24, 57],
          ...
        ],
        ...
      ]
    },
    {
      "tag": "car",
      "image": [
        [
          [255, 0, 102],
          [255, 0, 97],
          ...
        ],
        [
          [254, 1, 101],
          [254, 2, 93],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

scikit-learn

גוף הבקשה מכיל נתונים במבנה הבא (ייצוג JSON):

{
  "instances": [
    <simple list>,
    ...
  ]
}

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

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

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

XGBoost

גוף הבקשה מכיל נתונים במבנה הבא (ייצוג JSON):

{
  "instances": [
    <simple list>,
    ...
  ]
}

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

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

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

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

שירות ההסקה אונליין מפרש את הערכים 0 ו-NaN באופן שונה. אם הערך של מאפיין הוא אפס, צריך להשתמש ב-0.0 בקלט המתאים. אם חסר ערך של מאפיין, צריך להשתמש ב-"NaN" בקלט המתאים.

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

{"instances": [[0.0, 1.1, "NaN"]]}

PyTorch

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

{
  "instances": [
    { "data": , <value> },
    { "data": , <value> }
  ]
}

פרטי גוף התשובה

אם הקריאה מצליחה, גוף התגובה מכיל רשומת הסקה אחת לכל מופע בגוף הבקשה, באותו סדר:

{
  "predictions": [
    {
      object
    }
  ],
  "deployedModelId": string
}

אם ההסקה נכשלת במכונה כלשהי, גוף התגובה לא מכיל הסקות. במקום זאת, הוא מכיל רשומת שגיאה אחת:

{
  "error": string
}

האובייקט predictions[] מכיל את רשימת ההסקות, אחת לכל מופע בבקשה.

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

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

דוגמאות לגוף התגובה

TensorFlow

הדוגמאות הבאות מציגות כמה תשובות אפשריות:

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

    {"predictions":
   [5, 4, 3],
   "deployedModelId": 123456789012345678
}

  • קבוצה מורכבת יותר של חיזויים, שכל אחד מהם מכיל שני ערכים בעלי שם שתואמים לטנזורים של פלט, בשם label ו-scores בהתאמה. הערך של label הוא הקטגוריה החזויה ("מכונית" או "חוף"), והערך של scores מכיל רשימה של הסתברויות לאותו מופע בכל הקטגוריות האפשריות.

    {
  "predictions": [
    {
      "label": "beach",
      "scores": [0.1, 0.9]
    },
    {
      "label": "car",
      "scores": [0.75, 0.25]
    }
  ],
  "deployedModelId": 123456789012345678
}

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

    {"error": "Divide by zero"}

scikit-learn

הנה כמה דוגמאות לתשובות אפשריות:

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

    {"predictions":
   [5, 4, 3],
   "deployedModelId": 123456789012345678
}

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

    {"error": "Divide by zero"}

XGBoost

הדוגמאות הבאות מציגות כמה תשובות אפשריות:

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

    {"predictions":
   [5, 4, 3],
   "deployedModelId": 123456789012345678
}

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

    {"error": "Divide by zero"}

שליחת בקשה לנקודת קצה (endpoint)

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

שליחת בקשת הסקה אונליין לנקודת קצה ציבורית ייעודית

נקודות קצה ייעודיות מאפשרות תקשורת באמצעות הפרוטוקולים HTTP ו-gRPC. בבקשות gRPC, חובה לכלול את הכותרת x-vertex-ai-endpoint-id כדי לוודא שנקודת הקצה מזוהה בצורה מדויקת. ממשקי ה-API הבאים נתמכים דרך נקודות הקצה הייעודיות האלה:

  • חיזוי
  • RawPredict
  • StreamRawPredict
  • השלמת צ'אט (רק ב-Gemini Enterprise Agent Platform Model Garden)
  • הפעלה

נקודות קצה ייעודיות משתמשות בנתיב חדש של כתובת URL. אפשר לאחזר את הנתיב הזה מהשדה dedicatedEndpointDns ב-API בארכיטקטורת REST, או מהשדה Endpoint.dedicated_endpoint_dns ב-Agent Platform SDK ל-Python.

כדי לשלוח הסקה לנקודת קצה ייעודית באמצעות Agent Platform SDK ל-Python, מגדירים את הפרמטר use_dedicated_endpoint לערך True:

endpoint.predict(instances=instances, use_dedicated_endpoint=True)

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

gcloud

בדוגמה הבאה משתמשים בפקודה gcloud ai endpoints predict:

  1. כותבים את אובייקט ה-JSON הבא בקובץ בסביבה המקומית. שם הקובץ לא משנה, אבל בדוגמה הזו נקרא לקובץ request.json.

    {
 "instances": INSTANCES
}

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

    • ‫INSTANCES: מערך JSON של המופעים שרוצים לקבל עבורם הסקות. הפורמט של כל מופע תלוי בנתוני הקלט שמודל ה-ML המאומן מצפה לקבל. מידע נוסף זמין במאמר עיצוב הקלט להסקת מסקנות אונליין.

  2. מריצים את הפקודה הבאה:

    gcloud ai endpoints predict ENDPOINT_ID \
  --region=LOCATION_ID \
  --json-request=request.json

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

    • ‫ENDPOINT_ID: המזהה של נקודת הקצה.
    • ‫LOCATION_ID: האזור שבו אתם משתמשים ב-Agent Platform.

REST

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

  • ‫LOCATION_ID: האזור שבו אתם משתמשים ב-Agent Platform.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫ENDPOINT_ID: המזהה של נקודת הקצה.
  • ‫INSTANCES: מערך JSON של המכונות שרוצים לקבל עבורן הסקות. הפורמט של כל מופע תלוי בנתוני הקלט שהמודל המאומן של למידת המכונה מצפה לקבל. מידע נוסף זמין במאמר עיצוב הקלט להסקת מסקנות אונליין.

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

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict

גוף בקשת JSON: 

{
  "instances": INSTANCES
}

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

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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"

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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content
אם הפעולה בוצעה ללא שגיאות, תתקבל תגובת JSON שדומה לזו: בתשובה, צפויות ההחלפות הבאות:
  • ‫PREDICTIONS: מערך JSON של חיזויים, אחד לכל מכונה שכללתם בגוף הבקשה.
  • ‫DEPLOYED_MODEL_ID: המזהה של DeployedModel שסיפק את החיזויים. 
{
  "predictions": PREDICTIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Java

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

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


import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictRequest;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.protobuf.ListValue;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.io.IOException;
import java.util.List;

public class PredictCustomTrainedModelSample {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String instance = "[{ “feature_column_a”: “value”, “feature_column_b”: “value”}]";
    String project = "YOUR_PROJECT_ID";
    String endpointId = "YOUR_ENDPOINT_ID";
    predictCustomTrainedModel(project, endpointId, instance);
  }

  static void predictCustomTrainedModel(String project, String endpointId, String instance)
      throws IOException {
    PredictionServicPredictionServiceSettingsceSettings =
        PredictionServicPredictionServiceSettings          .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (PredictionServicPredictionServiceClientceClient =
        PredictionServicPredictionServiceClientonServiceSettings)) {
      String location = "us-central1";
      EndpointName endEndpointNameEndpointName.of(EndpointNameation, endpointId);

      ListValue.BuildeListValueue = ListValue.newBuiListValue     JsonFormat.parseJsonFormatinstance, listValue);
      List<Value> instanListValuelistValue.getValuesList();

      PredictRequest pPredictRequest=
          PredictRequest.nPredictRequest            .setEndpoint(endpointName.toSendpointName.toString().addAllInstances(instanceList)
              .build();
      PredictResponse PredictResponse = predictionServiceClient.predict(predictRequest);

      System.out.println("Predict Custom Trained model Response");
      System.out.format("\tDeployed Model Id: %s\n", predictResponse.predictResponse.getDeployedModelId()out.println("Predictions");
      for (Value predictionValueedictResponse.predictResponse.getPredictionsList()em.out.format("\tPrediction: %s\n", prediction);
      }
    }
  }
}

Node.js

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

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

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 * (Not necessary if passing values as arguments)
 */

// const filename = "YOUR_PREDICTION_FILE_NAME";
// const endpointId = "YOUR_ENDPOINT_ID";
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';
const util = require('util');
const {readFile} = require('fs');
const readFileAsync = util.promisify(readFile);

// Imports the Google Cloud Prediction Service Client library
const {PredictionServiceClient} = require('@google-cloud/aiplatform');

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: 'us-central1-aiplatform.googleapis.com',
};

// Instantiates a client
const predictionServiceClient = new PredictionServiceClient(clientOptions);

async function predictCustomTrainedModel() {
  // Configure the parent resource
  const endpoint = `projects/${project}/locations/${location}/endpoints/${endpointId}`;
  const parameters = {
    structValue: {
      fields: {},
    },
  };
  const instanceDict = await readFileAsync(filename, 'utf8');
  const instanceValue = JSON.parse(instanceDict);
  const instance = {
    structValue: {
      fields: {
        Age: {stringValue: instanceValue['Age']},
        Balance: {stringValue: instanceValue['Balance']},
        Campaign: {stringValue: instanceValue['Campaign']},
        Contact: {stringValue: instanceValue['Contact']},
        Day: {stringValue: instanceValue['Day']},
        Default: {stringValue: instanceValue['Default']},
        Deposit: {stringValue: instanceValue['Deposit']},
        Duration: {stringValue: instanceValue['Duration']},
        Housing: {stringValue: instanceValue['Housing']},
        Job: {stringValue: instanceValue['Job']},
        Loan: {stringValue: instanceValue['Loan']},
        MaritalStatus: {stringValue: instanceValue['MaritalStatus']},
        Month: {stringValue: instanceValue['Month']},
        PDays: {stringValue: instanceValue['PDays']},
        POutcome: {stringValue: instanceValue['POutcome']},
        Previous: {stringValue: instanceValue['Previous']},
      },
    },
  };

  const instances = [instance];
  const request = {
    endpoint,
    instances,
    parameters,
  };

  // Predict request
  const [response] = await predictionServiceClient.predict(request);

  console.log('Predict custom trained model response');
  console.log(`\tDeployed model id : ${response.deployedModelId}`);
  const predictions = response.predictions;
  console.log('\tPredictions :');
  for (const prediction of predictions) {
    console.log(`\t\tPrediction : ${JSON.stringify(prediction)}`);
  }
}
predictCustomTrainedModel();

Python

במאמר התקנת Vertex AI SDK ל-Python מוסבר איך להתקין או לעדכן את Vertex AI SDK ל-Python. מידע נוסף מופיע ב מאמרי העזרה של ה-API מבוסס-Python. 

def endpoint_predict_sample(
    project: str, location: str, instances: list, endpoint: str
):
    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint)

    prediction = endpoint.predict(instances=instances)
    print(prediction)
    return prediction

שליחת בקשה אונליין להסקה גולמית

gcloud

בדוגמאות הבאות משתמשים בפקודה gcloud ai endpoints raw-predict:

  • כדי לבקש הסקה באמצעות אובייקט ה-JSON ב-REQUEST שצוין בשורת הפקודה:

     gcloud ai endpoints raw-predict ENDPOINT_ID \
     --region=LOCATION_ID \
     --request=REQUEST

  • כדי לבקש הסקות עם תמונה שמאוחסנת בקובץ image.jpeg והכותרת המתאימה של Content-Type:

     gcloud ai endpoints raw-predict ENDPOINT_ID \
     --region=LOCATION_ID \
     --http-headers=Content-Type=image/jpeg \
     --request=@image.jpeg

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

    • ‫ENDPOINT_ID: המזהה של נקודת הקצה.
    • ‫LOCATION_ID: האזור שבו אתם משתמשים ב-Agent Platform.
    • ‫REQUEST: תוכן הבקשה שרוצים לקבל עבורה הסקות. הפורמט של הבקשה תלוי במה שהקונטיינר המותאם אישית מצפה לקבל, ולא בהכרח באובייקט JSON.

Python

במאמר התקנת Vertex AI SDK ל-Python מוסבר איך להתקין או לעדכן את Vertex AI SDK ל-Python. מידע נוסף מופיע ב מאמרי העזרה של ה-API מבוסס-Python. 

from google.cloud import aiplatform_v1


def sample_raw_predict():
    # Create a client
    client = aiplatform_v1.PredictionServiceClient()

    # Initialize request argument(s)
    request = aiplatform_v1.RawPredictRequest(
        endpoint="endpoint_value",
    )

    # Make the request
    response = client.raw_predict(request=request)

    # Handle the response
    print(response)

התשובה כוללת את כותרות ה-HTTP הבאות:

  • ‫X-Vertex-AI-Endpoint-Id: המזהה של Endpoint שסיפק את ההסקה הזו.

  • ‫X-Vertex-AI-Deployed-Model-Id: המזהה של DeployedModel של נקודת הקצה שסיפק את ההסקה הזו.

שליחת בקשה להסבר אונליין

gcloud

בדוגמה הבאה משתמשים בפקודה gcloud ai endpoints explain:

  1. כותבים את אובייקט ה-JSON הבא בקובץ בסביבה המקומית. שם הקובץ לא משנה, אבל בדוגמה הזו נקרא לקובץ request.json.

    {
 "instances": INSTANCES
}

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

    • ‫INSTANCES: מערך JSON של המופעים שרוצים לקבל עבורם הסקות. הפורמט של כל מופע תלוי בנתוני הקלט שהמודל המאומן של למידת המכונה מצפה לקבל. מידע נוסף זמין במאמר עיצוב הקלט להסקת מסקנות אונליין.

  2. מריצים את הפקודה הבאה:

    gcloud ai endpoints explain ENDPOINT_ID \
  --region=LOCATION_ID \
  --json-request=request.json

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

    • ‫ENDPOINT_ID: המזהה של נקודת הקצה.
    • ‫LOCATION_ID: האזור שבו אתם משתמשים ב-Agent Platform.

    אם רוצים לשלוח בקשה להסבר ל-DeployedModel ספציפי ב-Endpoint, אפשר לציין את הדגל --deployed-model-id:

    gcloud ai endpoints explain ENDPOINT_ID \
  --region=LOCATION \
  --deployed-model-id=DEPLOYED_MODEL_ID \
  --json-request=request.json

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

    • ‫DEPLOYED_MODEL_ID אופציונלי: המזהה של המודל שנפרס ורוצים לקבל הסברים לגביו. המזהה נכלל בתשובה של ה-method ‏predict. אם אתם צריכים לבקש הסברים למודל מסוים, ויש לכם יותר ממודל אחד שנפרס באותה נקודת קצה, אתם יכולים להשתמש במזהה הזה כדי לוודא שההסברים יוחזרו למודל הספציפי הזה.

REST

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

  • ‫LOCATION_ID: האזור שבו אתם משתמשים ב-Agent Platform.
  • PROJECT_ID:
  • ‫ENDPOINT_ID: המזהה של נקודת הקצה.
  • ‫INSTANCES: מערך JSON של המכונות שרוצים לקבל עבורן הסקות. הפורמט של כל מופע תלוי בנתוני הקלט שהמודל המאומן של למידת המכונה מצפה לקבל. מידע נוסף זמין במאמר עיצוב הקלט להסקת מסקנות אונליין.

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

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain

גוף בקשת JSON: 

{
  "instances": INSTANCES
}

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

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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain"

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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain" | Select-Object -Expand Content
אם הפעולה בוצעה ללא שגיאות, תתקבל תגובת JSON שדומה לזו: בתשובה, צפויות ההחלפות הבאות:
  • ‫PREDICTIONS: מערך JSON של חיזויים, אחד לכל מכונה שכללתם בגוף הבקשה.
  • ‫EXPLANATIONS: מערך JSON של הסברים, אחד לכל חיזוי.
  • ‫DEPLOYED_MODEL_ID: המזהה של DeployedModel שסיפק את החיזויים. 
{
  "predictions": PREDICTIONS,
  "explanations": EXPLANATIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

במאמר התקנת Vertex AI SDK ל-Python מוסבר איך להתקין או לעדכן את Vertex AI SDK ל-Python. מידע נוסף מופיע ב מאמרי העזרה של ה-API מבוסס-Python. 

def explain_tabular_sample(
    project: str, location: str, endpoint_id: str, instance_dict: Dict
):

    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint_id)

    response = endpoint.explain(instances=[instance_dict], parameters={})

    for explanation in response.explanations:
        print(" explanation")
        # Feature attributions.
        attributions = explanation.attributions
        for attribution in attributions:
            print("  attribution")
            print("   baseline_output_value:", attribution.baseline_output_value)
            print("   instance_output_value:", attribution.instance_output_value)
            print("   output_display_name:", attribution.output_display_name)
            print("   approximation_error:", attribution.approximation_error)
            print("   output_name:", attribution.output_name)
            output_index = attribution.output_index
            for output_index in output_index:
                print("   output_index:", output_index)

    for prediction in response.predictions:
        print(prediction)

שליחת בקשת הפעלה אונליין

הנתיב Invoke מאפשר גישה לכל נתיבי הבקשות שאינם ברמה הבסיסית (root) בפריסה. לדוגמה, /invoke/foo/bar יועבר כ-/foo/bar לשרת המודל. יש שתי דרכים לגשת למסלול.

בקשה לניתוב בהתאמה אישית לנקודת קצה ייעודית

Python

במאמר התקנת Vertex AI SDK ל-Python מוסבר איך להתקין או לעדכן את Vertex AI SDK ל-Python. מידע נוסף מופיע ב מאמרי העזרה של ה-API מבוסס-Python. 

def invoke_tabular_sample(
    project: str,
    location: str,
    endpoint_id: str,
    request_path: str,
    http_request_body: Dict[str, Any],
    stream: bool = False,
):
    aiplatform.init(project=project, location=location)

    dedicated_endpoint = aiplatform.Endpoint(endpoint_id)
    if stream:
        for chunk in dedicated_endpoint.invoke(
            request_path=request_path,
            body=json.dumps(http_request_body).encode("utf-8"),
            headers={"Content-Type": "application/json"},
            stream=True,
        ):
            print(chunk)
    else:
        response = dedicated_endpoint.invoke(
            request_path=request_path,
            body=json.dumps(http_request_body).encode("utf-8"),
            headers={"Content-Type": "application/json"},
        )
        print(response)

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

Python

במאמר התקנת Vertex AI SDK ל-Python מוסבר איך להתקין או לעדכן את Vertex AI SDK ל-Python. מידע נוסף מופיע ב מאמרי העזרה של ה-API מבוסס-Python. 

def invoke_direct_deployed_model_inference_tabular_sample(
    project: str,
    location: str,
    endpoint_id: str,
    request_path: str,
    http_request_body: Dict[str, Any],
    deployed_model_id: str,
    stream: bool = False,
):
    aiplatform.init(project=project, location=location)

    dedicated_endpoint = aiplatform.Endpoint(endpoint_id)
    if stream:
        for chunk in dedicated_endpoint.invoke(
            request_path=request_path,
            body=json.dumps(http_request_body).encode("utf-8"),
            headers={"Content-Type": "application/json"},
            deployed_model_id=deployed_model_id,
            stream=True,
        ):
            print(chunk)
    else:
        response = dedicated_endpoint.invoke(
            request_path=request_path,
            body=json.dumps(http_request_body).encode("utf-8"),
            headers={"Content-Type": "application/json"},
            deployed_model_id=deployed_model_id,
        )
        print(response)

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