Ottenere deduzioni online da un modello con addestramento personalizzato

Questa pagina mostra come ottenere inferenze online (in tempo reale) dai modelli personalizzati addestrati utilizzando Google Cloud CLI o l'API Vertex AI.

Formatta l'input per l'inferenza online

Questa sezione mostra come formattare e codificare le istanze di input di inferenza come JSON, operazione necessaria se utilizzi il metodo predict o explain. Questo passaggio non è necessario se utilizzi il metodo rawPredict. Per informazioni sul metodo da scegliere, consulta la sezione Inviare la richiesta all'endpoint.

Se utilizzi l'SDK Vertex AI per Python per inviare richieste di inferenza, specifica l'elenco delle istanze senza il campo instances. Ad esempio, specifica [ ["the","quick","brown"], ... ] anziché { "instances": [ ["the","quick","brown"], ... ] }.

Se il modello utilizza un container personalizzato, l'input deve essere formattato come JSON ed è presente un campo parameters aggiuntivo che può essere utilizzato per il container. Scopri di più sull'input per l'inferenza del formato con i container personalizzati.

Formattare le istanze come stringhe JSON

Il formato di base per l'inferenza online è un elenco di istanze di dati. Questi possono essere elenchi semplici di valori o membri di un oggetto JSON, a seconda di come hai configurato gli input nell'applicazione di addestramento. I modelli TensorFlow possono accettare input più complessi, mentre la maggior parte dei modelli scikit-learn e XGBoost prevede un elenco di numeri come input.

Questo esempio mostra un tensore di input e una chiave di istanza per un modello TensorFlow:

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

La composizione della stringa JSON può essere complessa, purché rispetti queste regole:

• Il livello superiore dei dati dell'istanza deve essere un oggetto JSON: un dizionario di coppie chiave-valore.

• I singoli valori in un oggetto istanza possono essere stringhe, numeri o elenchi. Non puoi incorporare oggetti JSON.

• Gli elenchi devono contenere solo elementi dello stesso tipo (inclusi altri elenchi). Non puoi combinare valori stringa e numerici.

Passa le istanze di input per l'inferenza online come corpo del messaggio per la chiamata projects.locations.endpoints.predict. Scopri di più sui requisiti di formattazione del corpo della richiesta.

Rendi ogni istanza un elemento di una matrice JSON e fornisci la matrice come campo instances di un oggetto JSON. Ad esempio:

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

Codifica i dati binari per l'input di inferenza

I dati binari non possono essere formattati come le stringhe con codifica UTF-8 supportate da JSON. Se gli input contengono dati binari, devi utilizzare la codifica base64 per rappresentarli. È richiesta la seguente formattazione speciale:

• La stringa codificata deve essere formattata come un oggetto JSON con una singola chiave denominata b64. In Python 3, la codifica Base64 restituisce una sequenza di byte. Devi convertirlo in una stringa per renderlo serializzabile in JSON:

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

• Nel codice del modello TensorFlow, devi assegnare un nome agli alias per i tensori di input e output binari in modo che terminino con "_bytes".

Esempi di richieste e risposte

Questa sezione descrive il formato del corpo della richiesta di inferenza e del corpo della risposta, con esempi per TensorFlow, scikit-learn e XGBoost.

Dettagli del corpo della richiesta

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

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

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

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

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

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

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

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

{"b64": "..."} 

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

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

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

{
  "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],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

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

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

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

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

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

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

Dettagli del corpo della risposta

Se la chiamata ha esito positivo, il corpo della risposta contiene una voce di inferenza per istanza nel corpo della richiesta, nello stesso ordine:

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

Se l'inferenza non va a buon fine per qualsiasi istanza, il corpo della risposta non contiene inferenze. Contiene invece una sola voce di errore:

{
  "error": string
}

L'oggetto predictions[] contiene l'elenco delle inferenze, una per ogni istanza nella richiesta.

In caso di errore, la stringa error contiene un messaggio che descrive il problema. L'errore viene restituito al posto di un elenco di inferenze se si è verificato un errore durante l'elaborazione di un'istanza.

Anche se esiste un'inferenza per istanza, il formato di un'inferenza non è direttamente correlato al formato di un'istanza. Le inferenze assumono il formato specificato nella raccolta di output definita nel modello. La raccolta di inferenze viene restituita in un elenco JSON. Ogni membro dell'elenco può essere un valore semplice, un elenco o un oggetto JSON di qualsiasi complessità. Se il modello ha più di un tensore di output, ogni inferenza sarà un oggetto JSON contenente una coppia nome-valore per ogni output. I nomi identificano gli alias di output nel grafico.

Esempi di corpo della risposta

Invia una richiesta a un endpoint

Esistono tre modi per inviare una richiesta:

• Richiesta di inferenza: invia una richiesta a predict per ottenere un'inferenza online.

• Richiesta di inferenza non elaborata: invia una richiesta a rawPredict, che ti consente di utilizzare un payload HTTP arbitrario anziché seguire le linee guida descritte nelle sezioni Formatta l'input di questa pagina. Potresti voler ottenere inferenze non elaborate se:

  • Utilizzi un container personalizzato che riceve richieste e invia risposte diverse dalle linee guida.
  • Hai bisogno di una latenza inferiore. rawPredict salta i passaggi di serializzazione e inoltra direttamente la richiesta al container di inferenza.
  • Stai pubblicando inferenze con NVIDIA Triton.

• Richiesta di spiegazione: invia una richiesta a explain. Se hai configurato il tuo Model per Vertex Explainable AI, puoi ottenere spiegazioni online. Le richieste di spiegazione online hanno lo stesso formato delle richieste di inferenza online e restituiscono risposte simili; l'unica differenza è che le risposte di spiegazione online includono attribuzioni delle funzionalità e inferenze.

Invia una richiesta di inferenza online a un endpoint pubblico dedicato

Gli endpoint dedicati facilitano la comunicazione utilizzando i protocolli HTTP e gRPC. Per le richieste gRPC, l'inclusione dell'intestazione x-vertex-ai-endpoint-id è obbligatoria per garantire l'identificazione accurata dell'endpoint. Le seguenti API sono supportate tramite questi endpoint dedicati:

• Previsione
• RawPredict
• StreamRawPredict
• Completamento della chat (solo Model Garden)

Gli endpoint dedicati utilizzano un nuovo percorso URL. Puoi recuperare questo percorso dal campo dedicatedEndpointDns nell'API REST o da Endpoint.dedicated_endpoint_dns nell'SDK Vertex AI per Python. Puoi anche costruire manualmente il percorso dell'endpoint utilizzando il seguente codice:

f"https://ENDPOINT_ID.LOCATION_ID-PROJECT_NUMBER.prediction.vertexai.goog/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"

Sostituisci quanto segue:

• ENDPOINT_ID: l'ID dell'endpoint.
• LOCATION_ID: la regione in cui utilizzi Vertex AI.
• PROJECT_NUMBER: il numero di progetto. Questo valore è diverso dall'ID progetto. Puoi trovare il numero di progetto nella pagina Impostazioni progetto della console Google Cloud .

Per inviare un'inferenza a un endpoint dedicato utilizzando l'SDK Vertex AI per Python, imposta il parametro use_dedicated_endpoint su True:

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

Invia una richiesta di inferenza online a un endpoint pubblico condiviso

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

{
  "instances": INSTANCES
}

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"

$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

{
  "predictions": PREDICTIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

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);
      }
    }
  }
}

/**
 * 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();

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

Inviare una richiesta di inferenza non elaborata online

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)

La risposta include le seguenti intestazioni HTTP:

• X-Vertex-AI-Endpoint-Id: ID di Endpoint che ha pubblicato questa inferenza.

• X-Vertex-AI-Deployed-Model-Id: ID di DeployedModel dell'endpoint che ha fornito questa inferenza.

Inviare una richiesta di spiegazione online

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

{
  "instances": INSTANCES
}

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"

$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

{
  "predictions": PREDICTIONS,
  "explanations": EXPLANATIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

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)

Passaggi successivi

• Scopri di più sulla registrazione dell'inferenza online.