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

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

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

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

במדריך הזה מוסבר איך ליצור מודל שמשתמש בקונטיינר בהתאמה אישית. הוא לא מספק הוראות מפורטות לגבי תכנון ויצירה של קובץ אימג' של קונטיינר Docker.

הכנת קובץ אימג' של קונטיינר

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

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

יצירת קובץ אימג' של קונטיינר

מעצבים ויוצרים קובץ אימג' של קונטיינר Docker שעומד בדרישות של קובץ האימג' של הקונטיינר.

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

העברת קובץ האימג' של הקונטיינר ל-Artifact Registry

מעבירים את קובץ האימג' של הקונטיינר למאגר ב-Artifact Registry.

איך מעבירים קובץ אימג' של קונטיינר ל-Artifact Registry

יצירת Model

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

• ייבוא מודל עם אימון בהתאמה אישית

• יוצרים TrainingPipeline שמריץ CustomJob ומייבאים את פריטי המידע שנוצרו כ-Model.

בקטעים הבאים מוסבר איך להגדיר את שדות ה-API שקשורים לקונטיינרים בהתאמה אישית כשיוצרים Model באחת מהדרכים האלה.

שדות API שקשורים למאגר התגים

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

צריך לציין הודעת ModelContainerSpec בשדה Model.containerSpec. בהודעה הזו אפשר לציין את שדות המשנה הבאים:

‫imageUri (שדה חובה)

מזהה ה-URI של קובץ האימג' של הקונטיינר ב-Artifact Registry. ציינו תקציר (IMAGE@sha256:DIGEST), תג (IMAGE:TAG) או אף אחד מהם (ברירת המחדל היא :latest). אל תציינו גם תג וגם תקציר באותו URI. לפרטים נוספים, ראו פורמט URI של תמונה.

אם אתם משתמשים בפקודה gcloud ai models upload, אתם יכולים להשתמש בדגל --container-image-uri כדי לציין את השדה הזה.

‫command (אופציונלי)

מערך של קובץ הפעלה וארגומנטים לשינוי ההוראה ENTRYPOINT של הקונטיינר. כדי ללמוד איך להגדיר את הפורמט של השדה הזה ואיך הוא פועל עם השדה args, קראו את מאמרי העזרה של ה-API בנושא ModelContainerSpec.

אם אתם משתמשים בפקודה gcloud ai models upload, אתם יכולים להשתמש בדגל --container-command כדי לציין את השדה הזה.

‫args (אופציונלי)

מערך של קובץ הפעלה וארגומנטים שיחליפו את CMD של הקונטיינר. כדי ללמוד איך להגדיר את הפורמט של השדה הזה ואיך הוא פועל עם השדה command, קראו את מאמרי העזרה של ה-API בנושא ModelContainerSpec.

אם אתם משתמשים בפקודה gcloud ai models upload, אתם יכולים להשתמש בדגל --container-args כדי לציין את השדה הזה.

‫ports (אופציונלי)

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

אם אתם משתמשים בפקודה gcloud ai models upload, אתם יכולים להשתמש בדגל --container-ports כדי לציין את השדה הזה.

‫env (אופציונלי)

מערך של משתני סביבה שההוראה ENTRYPOINT של הקונטיינר, וגם השדות command ו-args, יכולים להפנות אליהם. כדי ללמוד איך שדות אחרים יכולים להפנות למשתני הסביבה האלה, קראו את מאמרי העזרה של ה-API של ModelContainerSpec.

אם אתם משתמשים בפקודה gcloud ai models upload, אתם יכולים להשתמש בדגל --container-env-vars כדי לציין את השדה הזה.

‫healthRoute (אופציונלי)

הנתיב בשרת ה-HTTP של הקונטיינר שאליו אתם רוצים ש-Agent Platform ישלח בדיקות תקינות.

אם לא מציינים את השדה הזה, כשפורסים את Model בתור DeployedModel למשאב Endpoint, ברירת המחדל היא /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL, כאשר ENDPOINT מוחלף בקטע האחרון של השדה name של Endpoint (אחרי endpoints/) ו-DEPLOYED_MODEL מוחלף בשדה id של DeployedModel.

אם אתם משתמשים בפקודה gcloud ai models upload, אתם יכולים להשתמש בדגל --container-health-route כדי לציין את השדה הזה.

‫predictRoute (אופציונלי)

הנתיב בשרת ה-HTTP של הקונטיינר שאליו אתם רוצים שפלטפורמת Agent תעביר בקשות להסקת מסקנות.

אם לא מציינים את השדה הזה, כשפורסים את Model בתור DeployedModel למשאב Endpoint, ברירת המחדל היא /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict, כאשר ENDPOINT מוחלף בקטע האחרון של השדה name של Endpoint (אחרי endpoints/) ו-DEPLOYED_MODEL מוחלף בשדה id של DeployedModel.

אם אתם משתמשים בפקודה gcloud ai models upload, אתם יכולים להשתמש בדגל --container-predict-route כדי לציין את השדה הזה.

‫invokeRoutePrefix (אופציונלי)

הפעלת קידומת הנתיב של הקונטיינר בהתאמה אישית. הגדרת השדה הזה לערך "/*" מפעילה ניתוב שרירותי למודל. אחרי הפריסה, כל נתיב שאינו ברמה הבסיסית (root) בשרת המודל יהיה נגיש באמצעות קריאת HTTP להפעלה. לדוגמה, "‎/invoke/foo/bar" יועבר כ-"‎/foo/bar" לשרת המודל. התכונה הזו נמצאת בשלב Public Preview. כדי ליצור מודל שמאפשר הפעלה, פועלים לפי ההוראות לשימוש בנתיבים שרירותיים בהתאמה אישית.

‫sharedMemorySizeMb (אופציונלי)

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

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

אם אתם משתמשים בפקודה gcloud ai models upload, אתם יכולים להשתמש בדגל --container-shared-memory-size-mb כדי לציין את השדה הזה.

‫startupProbe (אופציונלי)

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

אם אתם משתמשים בפקודה gcloud ai models upload, אתם יכולים להשתמש בדגל --container-startup-probe-exec, --container-startup-probe-period-seconds, --container-startup-probe-timeout-seconds כדי לציין את השדה הזה.

‫healthProbe (אופציונלי)

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

אם אתם משתמשים בפקודה gcloud ai models upload, אתם יכולים להשתמש בדגל --container-health-probe-exec, --container-health-probe-period-seconds, --container-health-probe-timeout-seconds כדי לציין את השדה הזה.

בנוסף למשתנים שאתם מגדירים בשדה Model.containerSpec.env, פלטפורמת Agent מגדירה עוד כמה משתנים על סמך ההגדרות שלכם. איך משתמשים במשתני הסביבה בשדות האלה ובהוראה ENTRYPOINT של הקונטיינר

דוגמאות לייבוא מודלים

בדוגמאות הבאות מוסבר איך לציין שדות API שקשורים לקונטיינר כשמייבאים מודל.

הערה: אם אתם משתמשים ב-TrainingPipeline כדי ליצור Model, אתם צריכים לציין את השדות האלה בהקשר אחר. אי אפשר להשתמש ב-Google Cloud CLI כדי ליצור TrainingPipeline. מידע נוסף על יצירת משאבים בהתאמה אישית ב-TrainingPipeline

gcloud

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

gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --container-command=COMMAND \
  --container-args=ARGS \
  --container-ports=PORTS \
  --container-env-vars=ENV \
  --container-health-route=HEALTH_ROUTE \
  --container-predict-route=PREDICT_ROUTE \
  --container-shared-memory-size-mb=SHARED_MEMORY_SIZE \
  --container-startup-probe-exec=STARTUP_PROBE_EXEC \
  --container-startup-probe-period-seconds=STARTUP_PROBE_PERIOD \
  --container-startup-probe-timeout-seconds=STARTUP_PROBE_TIMEOUT \
  --container-health-probe-exec=HEALTH_PROBE_EXEC \
  --container-health-probe-period-seconds=HEALTH_PROBE_PERIOD \
  --container-health-probe-timeout-seconds=HEALTH_PROBE_TIMEOUT \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY

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

Java

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

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

כדי לבצע אימות ב-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. מידע נוסף מופיע במאמרי העזרה של ה-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

למידע נוסף, קראו את המדריך לייבוא מודלים.

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

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

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

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

• במאמר דרישות לגבי קונטיינרים בהתאמה אישית מוסבר מה צריך להביא בחשבון כשמתכננים קונטיינר בהתאמה אישית ל שימוש עם Agent Platform.