ייבוא מודלים ל-Gemini Enterprise Agent Platform

במדריך הזה מוסבר איך לייבא מודלים ל-Model Registry ב-Gemini Enterprise Agent Platform. אחרי שמייבאים את המודל, הוא מופיע במאגר המודלים. מתוך מרשם המודלים, אפשר לפרוס את המודל המיובא לנקודת קצה ולהריץ מסקנות.

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

כדי לקבל את ההרשאות שנדרשות לייבוא מודלים, צריך לבקש מהאדמין להקצות לכם ב-IAM את התפקיד משתמש בפלטפורמת הסוכנים (roles/aiplatform.user) בפרויקט. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

מאגרי תגים מוכנים מראש או מותאמים אישית

כשמייבאים מודל, מקשרים אותו למאגר כדי ש-Agent Platform יוכל להריץ בקשות הסקה. אתם יכולים להשתמש במאגרי תגים מוכנים מראש שסופקו על ידי Agent Platform, או להשתמש במאגרי תגים בהתאמה אישית שאתם יוצרים ומעלים ל-Artifact Registry.

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

אם אתם מייבאים מודל טבלאי של AutoML שייצאתם בעבר, אתם צריכים להשתמש במאגר מותאם אישית ספציפי שסופק על ידי Agent Platform.

אפשרות אחרת היא ליצור מאגר מותאם אישית חדש או להשתמש במאגר מותאם אישית קיים שנמצא ב-Artifact Registry.

העלאת ארטיפקטים של מודלים ל-Cloud Storage

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

אם הקטגוריה של Cloud Storage נמצאת בפרויקט אחר ב- Google Cloud, צריך לתת גישה ל-Agent Platform כדי לקרוא את הארטיפקטים של המודל.

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

  • ‫TensorFlow SavedModel: saved_model.pb
  • ‫PyTorch: model.mar
  • ‫scikit-learn: model.joblib
  • ‫XGBoost: ‏ model.bst או model.joblib

מידע נוסף על ייצוא של פריטי מידע של מודל לצורך הסקה

ייבוא מודל באמצעות Google Cloud מסוף

כדי לייבא מודל באמצעות מסוף Google Cloud :

  1. נכנסים לדף Models של Agent Platform במסוף Google Cloud .

    כניסה לדף Models

  2. לוחצים על Import.

  3. כדי לייבא מודל חדש, בוחרים באפשרות ייבוא כמודל חדש.

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

  5. שם ואזור: מזינים שם למודל. בוחרים את האזור שתואם לאזור של דלי האחסון ולנקודת הקצה של מיקום פלטפורמת הסוכן שבה אתם משתמשים. לוחצים על Continue.

  6. אם מרחיבים את אפשרויות מתקדמות, אפשר להוסיף מפתח הצפנה בניהול הלקוח.

בהתאם לסוג מאגר התגים שבו אתם משתמשים, בוחרים את הכרטיסייה המתאימה למטה.

מאגר מוכן מראש

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

  2. בוחרים את הפורמט של המודל ואת הגרסה של הפורמט של המודל שבהם השתמשתם כדי לאמן את המודל.

  3. אם רוצים להשתמש ב-GPU להצגת מסקנות, מגדירים את סוג המאיץ ל-GPU.

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

  4. מציינים את הנתיב ב-Cloud Storage לספרייה שמכילה את ארטיפקטים של המודל.

    לדוגמה, gs://BUCKET_NAME/models/.

  5. משאירים את השדה Predict schemata (חיזוי סכימות) ריק.

  6. כדי לייבא את המודל בלי הגדרות של Vertex Explainable AI, לוחצים על ייבוא.

    אחרי שהייבוא יסתיים, המודל יופיע בדף מודלים.

    אחרת, ממשיכים להגדיר את המודל על ידי הזנת הגדרות ההסבר בכרטיסייה Explainability (הסבר). מידע נוסף על הגדרות ההסבר

מאגר תגים בהתאמה אישית

  1. בוחרים באפשרות ייבוא מאגר תגים קיים בהתאמה אישית.

  2. הגדרה של ה-URI של קובץ האימג' של הקונטיינר.

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

    לדוגמה, gs://BUCKET_NAME/models/.

  4. מציינים ערכים בשדות אחרים.

    מידע נוסף על השדות האופציונליים האלה

  5. כדי לייבא את המודל בלי הגדרות של Vertex Explainable AI, לוחצים על ייבוא.

    אחרי שהייבוא יסתיים, המודל יופיע בדף מודלים.

    אחרת, ממשיכים להגדיר את המודל על ידי הזנת הגדרות ההסבר בכרטיסייה Explainability (הסבר). מידע נוסף על הגדרות ההסבר

מאגר AutoML לנתונים טבלאיים

  1. בוחרים באפשרות ייבוא מאגר תגים קיים בהתאמה אישית.

  2. בשדה Container image (תמונת קונטיינר), מזינים MULTI_REGION-docker.pkg.dev/vertex-ai/automl-tabular/prediction-server-v1:latest.

    מחליפים את MULTI_REGION ב-us, ב-europe או ב-asia כדי לבחור מאיזה מאגר Docker רוצים לשלוף את תמונת Docker. כל מאגר מספק את אותו קובץ אימג' של Docker, אבל בחירה במאגר מרובה אזורים של Artifact Registry שקרוב למחשב שבו מריצים את Docker עשויה להפחית את זמן האחזור.

  3. בשדה Package location (מיקום החבילה), מציינים את הנתיב ב-Cloud Storage לספרייה שמכילה את ארטיפקטים של המודל.

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

    gs://BUCKET_NAME/models-MODEL_ID/tf-saved-model/TIMESTAMP/

  4. משאירים את כל שאר השדות ריקים.

  5. לוחצים על Import.

    אחרי שהייבוא יסתיים, המודל יופיע בדף מודלים. אפשר להשתמש במודל הזה בדיוק כמו במודלים אחרים של טבלאות של AutoML, אבל מודלים של טבלאות של AutoML שיובאו לא תומכים ב-Vertex Explainable AI.

ייבוא מודל באופן פרוגרמטי

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

gcloud

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

gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY

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

  • ‫LOCATION_ID: האזור שבו משתמשים בפלטפורמת הסוכנים.
  • ‫MODEL_NAME: שם מוצג ל-Model.
  • ‫IMAGE_URI: ה-URI של קובץ האימג' בקונטיינר שמשמש להצגת מסקנות. לדוגמה, us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. משתמשים במאגר מוכן מראש או במאגר בהתאמה אישית.
  • ‫PATH_TO_MODEL_ARTIFACT_DIRECTORY: ה-URI של Cloud Storage (מתחיל ב-gs://) של ספרייה ב-Cloud Storage שמכילה את הארטיפקטים של המודל.

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

REST

בדוגמת הקוד הבאה מוסבר איך להעלות מודל באמצעות השיטה upload של משאב model.

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

  • ‫LOCATION_ID: האזור שבו משתמשים בפלטפורמת הסוכנים.
  • ‫PROJECT_ID: [מזהה הפרויקט](/resource-manager/docs/creating-managing-projects#identifiers). .
  • ‫MODEL_NAME: שם מוצג ל-Model.
  • ‫MODEL_DESCRIPTION: אופציונלי. תיאור של המודל.
  • ‫IMAGE_URI: ה-URI של קובץ האימג' בקונטיינר שמשמש להצגת מסקנות. לדוגמה, us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. משתמשים במאגר מוכן מראש או במאגר בהתאמה אישית.
  • ‫PATH_TO_MODEL_ARTIFACT_DIRECTORY: ה-URI של Cloud Storage (מתחיל ב-gs://) של ספרייה ב-Cloud Storage שמכילה את הארטיפקטים של המודל. המשתנה הזה והשדה artifactUri הם אופציונליים אם אתם משתמשים במאגר תגים מותאם אישית.
  • ‫labels: אופציונלי. כל קבוצה של צמדי מפתח/ערך לארגון המודלים. לדוגמה:
    • ‪"env": "prod"
    • ‪"tier": "backend"
  • מציינים את LABEL_NAME ואת LABEL_VALUE לכל התוויות שרוצים להחיל על צינור האימון הזה.

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

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/models:upload

גוף בקשת JSON: 

{
  "model": {
    "displayName": "MODEL_NAME",
    "predictSchemata": {},
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "labels": {
      "LABEL_NAME_1": "LABEL_VALUE_1",
      "LABEL_NAME_2": "LABEL_VALUE_2"
    }
  }
}

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

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/models:upload"

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/models:upload" | Select-Object -Expand Content

Java

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

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


import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.aiplatform.v1.LocationName;
import com.google.cloud.aiplatform.v1.Model;
import com.google.cloud.aiplatform.v1.ModelContainerSpec;
import com.google.cloud.aiplatform.v1.ModelServiceClient;
import com.google.cloud.aiplatform.v1.ModelServiceSettings;
import com.google.cloud.aiplatform.v1.UploadModelOperationMetadata;
import com.google.cloud.aiplatform.v1.UploadModelResponse;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class UploadModelSample {
  public static void main(String[] args)
      throws InterruptedException, ExecutionException, TimeoutException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String modelDisplayName = "YOUR_MODEL_DISPLAY_NAME";
    String metadataSchemaUri =
        "gs://google-cloud-aiplatform/schema/trainingjob/definition/custom_task_1.0.0.yaml";
    String imageUri = "YOUR_IMAGE_URI";
    String artifactUri = "gs://your-gcs-bucket/artifact_path";
    uploadModel(project, modelDisplayName, metadataSchemaUri, imageUri, artifactUri);
  }

  static void uploadModel(
      String project,
      String modelDisplayName,
      String metadataSchemaUri,
      String imageUri,
      String artifactUri)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    ModelServiceSettings modelServiceSettings =
        ModelServiceSettings.newBuilder()
            .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 (ModelServiceClient modelServiceClient = ModelServiceClient.create(modelServiceSettings)) {
      String location = "us-central1";
      LocationName locationName = LocationName.of(project, location);

      ModelContainerSpec modelContainerSpec =
          ModelContainerSpec.newBuilder().setImageUri(imageUri).build();

      Model model =
          Model.newBuilder()
              .setDisplayName(modelDisplayName)
              .setMetadataSchemaUri(metadataSchemaUri)
              .setArtifactUri(artifactUri)
              .setContainerSpec(modelContainerSpec)
              .build();

      OperationFuture<UploadModelResponse, UploadModelOperationMetadata> uploadModelResponseFuture =
          modelServiceClient.uploadModelAsync(locationName, model);
      System.out.format(
          "Operation name: %s\n", uploadModelResponseFuture.getInitialFuture().get().getName());
      System.out.println("Waiting for operation to finish...");
      UploadModelResponse uploadModelResponse = uploadModelResponseFuture.get(5, TimeUnit.MINUTES);

      System.out.println("Upload Model Response");
      System.out.format("Model: %s\n", uploadModelResponse.getModel());
    }
  }
}

Node.js

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

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

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 */

// const modelDisplayName = 'YOUR_MODEL_DISPLAY_NAME';
// const metadataSchemaUri = 'YOUR_METADATA_SCHEMA_URI';
// const imageUri = 'YOUR_IMAGE_URI';
// const artifactUri = 'YOUR_ARTIFACT_URI';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';

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

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

// Instantiates a client
const modelServiceClient = new ModelServiceClient(clientOptions);

async function uploadModel() {
  // Configure the parent resources
  const parent = `projects/${project}/locations/${location}`;
  // Configure the model resources
  const model = {
    displayName: modelDisplayName,
    metadataSchemaUri: '',
    artifactUri: artifactUri,
    containerSpec: {
      imageUri: imageUri,
      command: [],
      args: [],
      env: [],
      ports: [],
      predictRoute: '',
      healthRoute: '',
    },
  };
  const request = {
    parent,
    model,
  };

  console.log('PARENT AND MODEL');
  console.log(parent, model);
  // Upload Model request
  const [response] = await modelServiceClient.uploadModel(request);
  console.log(`Long running operation : ${response.name}`);

  // Wait for operation to complete
  await response.promise();
  const result = response.result;

  console.log('Upload model response ');
  console.log(`\tModel : ${result.model}`);
}
uploadModel();

Python

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

from typing import Dict, Optional, Sequence

from google.cloud import aiplatform
from google.cloud.aiplatform import explain


def upload_model_sample(
    project: str,
    location: str,
    display_name: str,
    serving_container_image_uri: str,
    artifact_uri: Optional[str] = None,
    serving_container_predict_route: Optional[str] = None,
    serving_container_health_route: Optional[str] = None,
    description: Optional[str] = None,
    serving_container_command: Optional[Sequence[str]] = None,
    serving_container_args: Optional[Sequence[str]] = None,
    serving_container_environment_variables: Optional[Dict[str, str]] = None,
    serving_container_ports: Optional[Sequence[int]] = None,
    instance_schema_uri: Optional[str] = None,
    parameters_schema_uri: Optional[str] = None,
    prediction_schema_uri: Optional[str] = None,
    explanation_metadata: Optional[explain.ExplanationMetadata] = None,
    explanation_parameters: Optional[explain.ExplanationParameters] = None,
    sync: bool = True,
):

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

    model = aiplatform.Model.upload(
        display_name=display_name,
        artifact_uri=artifact_uri,
        serving_container_image_uri=serving_container_image_uri,
        serving_container_predict_route=serving_container_predict_route,
        serving_container_health_route=serving_container_health_route,
        instance_schema_uri=instance_schema_uri,
        parameters_schema_uri=parameters_schema_uri,
        prediction_schema_uri=prediction_schema_uri,
        description=description,
        serving_container_command=serving_container_command,
        serving_container_args=serving_container_args,
        serving_container_environment_variables=serving_container_environment_variables,
        serving_container_ports=serving_container_ports,
        explanation_metadata=explanation_metadata,
        explanation_parameters=explanation_parameters,
        sync=sync,
    )

    model.wait()

    print(model.display_name)
    print(model.resource_name)
    return model

כדי לייבא מודל עם הגדרות של Vertex Explainable AI מופעלות, אפשר לעיין בדוגמאות לייבוא מודלים של Vertex Explainable AI.

קבלת סטטוס פעולה

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

מגבלות

  • הגודל המקסימלי של מודל שנתמך ב-Model Registry הוא 1TB.

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