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

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

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

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

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

קונטיינרים מובנים או בהתאמה אישית

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

אתם יכולים להשתמש בקונטיינר מוגדר מראש אם המודל עומד בדרישות הבאות:

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

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

העלאת פריטי מידע שנוצרו באופן אוטומטי של מודלים ל-Cloud Storage

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

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

אם אתם משתמשים בקונטיינר מובנה, ודאו ששמות הקבצים של פריטי המידע שנוצרו מהמודל תואמים בדיוק לדוגמאות הבאות:

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

מידע נוסף על ייצוא פריטי מידע שנוצרו בתהליך הפיתוח (Artifact) של מודלים להסקת מסקנות

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

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

  1. במסוף Cloud de Confiance , נכנסים לדף Models ב-Agent Platform.

    כניסה לדף Models

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

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

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

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

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

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

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

  1. בוחרים באפשרות Import model artifacts into a new prebuilt container.

  2. בוחרים את Model framework ואת Model framework version שבהם השתמשתם כדי לאמן את המודל.

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

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

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

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

  5. משאירים את השדה Predict schemata ריק.

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

    בסיום הייבוא, המודל יופיע בדף Models.

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

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

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

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

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

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

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

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

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

    בסיום הייבוא, המודל יופיע בדף Models.

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

קונטיינר של טבלאות AutoML

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

  2. בשדה קובץ אימג' של קונטיינר, מזינים את הערך 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.

    בסיום הייבוא, המודל יופיע בדף Models. אתם יכולים להשתמש במודל הזה בדיוק כמו במודלים אחרים של טבלאות AutoML, אבל מודלים מיובאים של טבלאות AutoML לא תומכים ב-Vertex 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: האזור שבו אתם משתמשים ב-Agent Platform.
  • ‫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-, תואמים לשדות של containerSpec ב-Model.

REST

כדי להעלות מודל באמצעות השיטה upload של המשאב model, אפשר להשתמש בדוגמת הקוד הבאה.

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

  • ‫LOCATION_ID: האזור שבו אתם משתמשים ב-Agent Platform.
  • ‫PROJECT_ID: מזהה הפרויקט. .
  • ‫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 באמצעות ספריות לקוח.

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

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


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 באמצעות ספריות לקוח.

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

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

/**
 * 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. מידע נוסף מופיע ב מאמרי העזרה של ה-API מבוסס-Python.

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

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

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

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

מגבלות

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

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