Generazione di previsioni online

La previsione online di AI Platform Prediction è un servizio ottimizzato per eseguire i dati tramite modelli ospitati con la minore latenza possibile. Invia piccoli batch di dati al servizio e questo restituisce le previsioni nella risposta.

Scopri di più sulla previsione online e batch o leggi una panoramica dei concetti di previsione.

Prima di iniziare

Per richiedere previsioni, devi prima:

Regioni

La previsione online è disponibile in determinate regioni. Inoltre, in ogni area geografica sono disponibili diversi tipi di macchine. Per informazioni sulla disponibilità della previsione online in ogni regione, leggi la guida alle regioni.

Creazione di modelli e versioni

Quando crei le risorse del modello e della versione, devi prendere le seguenti decisioni importanti su come eseguire la previsione online:

Risorsa creata Decisione specificata al momento della creazione della risorsa
Modello Regione in cui eseguire le previsioni
Modello Abilita la registrazione delle previsioni online
Versione Versione del runtime da utilizzare
Versione Versione Python da utilizzare
Versione Tipo di macchina da utilizzare per la previsione online

Non puoi aggiornare le impostazioni elencate sopra dopo la creazione iniziale del modello o della versione. Se devi modificare queste impostazioni, crea un nuovo modello o una nuova risorsa di versione con le nuove impostazioni ed esegui nuovamente il deployment del modello.

Tipi di macchina disponibili per la previsione online

Quando crei una versione, puoi scegliere il tipo di macchina virtuale usato da AI Platform Prediction per i nodi di previsione online. Scopri di più sui tipi di macchine.

Richiesta dei log per le richieste di previsione online

Per impostazione predefinita, il servizio di previsione di AI Platform Prediction non fornisce informazioni registrate sulle richieste, poiché i log comportano dei costi. La previsione online a un'elevata frequenza di query al secondo (QPS) può produrre un numero considerevole di log, che sono soggetti ai prezzi di Cloud Logging o ai prezzi di BigQuery.

Se vuoi abilitare il logging delle previsioni online, devi configurarlo quando crei una risorsa del modello o quando crei una risorsa della versione del modello, a seconda del tipo di logging che vuoi abilitare. Esistono tre tipi di logging, che puoi abilitare in modo indipendente:

  • Logging degli accessi, che registra informazioni come timestamp e latenza per ogni richiesta a Cloud Logging.

    Puoi abilitare il logging degli accessi quando crei una risorsa modello.

  • Il logging della console, che registra i flussi stderr e stdout dai nodi di previsione a Cloud Logging, e può essere utile per il debug. Questo tipo di logging è in anteprima per i tipi di macchine di Compute Engine (N1) ed è in disponibilità generale per i tipi di macchine legacy (MLS1).

    Puoi abilitare il logging della console quando crei una risorsa modello.

  • Logging di richiesta-risposta, che registra un campione di richieste di previsione e risposte online a una tabella BigQuery. Questo tipo di logging è in versione beta.

    Per abilitare il logging della richiesta-risposta, crea una risorsa della versione del modello e aggiorna la versione.

gcloud

Per abilitare il logging degli accessi, includi il flag --enable-logging quando crei il modello con il comando gcloud ai-platform models create. Ad esempio:

gcloud ai-platform models create MODEL_NAME \
  --region=us-central1 \
  --enable-logging

Per attivare il logging della console (anteprima), utilizza il componente gcloud beta e includi il flag --enable-console-logging. Ad esempio:

gcloud components install beta

gcloud beta ai-platform models create MODEL_NAME \
  --region=us-central1 \
  --enable-console-logging

Al momento non puoi abilitare il logging della richiesta di risposta (beta) utilizzando gcloud CLI. Puoi abilitare questo tipo di logging solo quando invii una richiesta projects.models.versions.patch all'API REST.

API REST

Per abilitare il logging degli accessi, imposta onlinePredictionLogging su True nella risorsa Modello quando crei il modello con projects.models.create.

Per abilitare il logging della console (beta), imposta il campo onlinePredictionConsoleLogging su True nella risorsa Modello.

Logging richiesta-risposta

A differenza degli altri tipi di logging, non puoi abilitare il logging richiesta-risposta quando crei un modello. Puoi invece abilitarlo utilizzando il metodo projects.models.versions.patch su una versione esistente del modello. Devi prima creare la versione del modello utilizzando la console Google Cloud, gcloud CLI o l'API REST.

Per abilitare il logging della richiesta-risposta, compila il campo requestLoggingConfig della risorsa Versione con le seguenti voci:

  • samplingPercentage: un numero compreso tra 0 o 1 che definisce la frazione di richieste da registrare. Ad esempio, imposta questo valore su 1 per registrare tutte le richieste o su 0.1 per registrare il 10% delle richieste.
  • bigqueryTableName: il nome completo (PROJECT_ID.DATASET_NAME.TABLE_NAME) della tabella BigQuery in cui vuoi registrare richieste e risposte. La tabella deve già esistere con il seguente schema:

    Nome campoTipoModalità
    modelSTRINGAOBBLIGATORIO
    model_versionSTRINGAOBBLIGATORIO
    tempoTIMESTAMPOBBLIGATORIO
    raw_dataSTRINGAOBBLIGATORIO
    raw_predictionSTRINGAAMMETTE VALORI NULL
    dati empirici realiSTRINGAAMMETTE VALORI NULL

    Scopri come creare una tabella BigQuery.

Ispeziona i modelli con lo strumento What-If

Puoi utilizzare lo strumento What-If(WIT) all'interno degli ambienti di blocchi note per ispezionare i modelli di AI Platform Prediction tramite una dashboard interattiva. Lo strumento What-If si integra con TensorBoard, blocchi note Jupyter, blocchi note Colab e JupyterHub. Inoltre, è preinstallato nelle istanze TensorFlow di blocchi note gestiti dall'utente di Vertex AI Workbench.

Scopri come utilizzare lo strumento What-If con AI Platform.

Formattazione dell'input per la previsione online

Formattazione delle istanze come stringhe JSON

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

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

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

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

  • Il livello superiore dei dati dell'istanza deve essere un oggetto JSON, ovvero 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.

Puoi passare le istanze di input per la previsione online come corpo del messaggio per la chiamata projects.predict. Scopri di più sui requisiti di formattazione del corpo della richiesta.

gcloud

Puoi formattare l'input in due modi diversi, a seconda di come prevedi di inviare la richiesta di previsione. Ti consigliamo di utilizzare il flag --json-request del comando gcloud ai-platform predict. In alternativa, puoi utilizzare il flag --json-instances con i dati JSON delimitati da una nuova riga.

Per --json-request

Imposta ogni istanza come elemento in un array JSON e fornisci l'array come campo instances di un file JSON. Ad esempio:

instances.json

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

Per --json-instances

Assicurati che il file di input sia un file JSON delimitato da nuova riga, con ogni istanza sotto forma di oggetto JSON, un'istanza per riga. Ad esempio:

instances.jsonl

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

API REST

Rendi ogni istanza un elemento in un array JSON e fornisci l'array come campo instances di un oggetto JSON. Ad esempio:

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

Dati binari nell'input di previsione

I dati binari non possono essere formattati come stringhe codificate in UTF-8 supportate da JSON. Se negli input sono presenti dati binari, devi utilizzare la codifica Base64 per rappresentarli. È richiesta la seguente formattazione speciale:

  • La stringa codificata deve essere formattata come oggetto JSON con una singola chiave denominata b64. Il seguente esempio di Python 2.7 codifica un buffer di dati JPEG non elaborati utilizzando la libreria base64 per creare un'istanza:

    {"image_bytes": {"b64": base64.b64encode(jpeg_data)}}
    

    In Python 3, la codifica Base64 restituisce una sequenza di byte. Devi convertirlo in una stringa per renderlo serializzabile JSON:

    {'image_bytes': {'b64': base64.b64encode(jpeg_data).decode()}}
    
  • Nel codice del tuo modello TensorFlow, devi assegnare un nome agli alias dei tensori di input e output binario in modo che terminino con "_bytes".

Richiesta di previsioni

Richiedi una previsione online inviando le istanze dei dati di input come stringa JSON in una richiesta di predict. Per la formattazione del corpo della richiesta e della risposta, consulta i dettagli della richiesta di previsione.

Se non specifichi una versione del modello, la richiesta di previsione utilizza la versione predefinita del modello.

gcloud

  1. Crea variabili di ambiente per contenere i parametri, incluso un valore di versione se decidi di specificare una particolare versione del modello:

    MODEL_NAME="[YOUR-MODEL-NAME]"
    INPUT_DATA_FILE="instances.json"
    VERSION_NAME="[YOUR-VERSION-NAME]"
    
  2. Utilizza gcloud ai-platform forecast per inviare istanze a un modello di cui è stato eseguito il deployment. Tieni presente che --version è facoltativo.

    gcloud ai-platform predict \
      --model=$MODEL_NAME \
      --version=$VERSION_NAME \
      --json-request=$INPUT_DATA_FILE \
      --region=REGION
    

    Sostituisci REGION con la regione dell'endpoint a livello di regione in cui hai creato il modello. Se hai creato il modello sull'endpoint globale, ometti il flag --region.

  3. Lo strumento gcloud analizza la risposta e stampa le previsioni sul terminale in un formato leggibile. Puoi specificare un formato di output diverso, ad esempio JSON o CSV, utilizzando il flag --format con il comando predict. Consulta i formati di output disponibili.

Python

Puoi utilizzare la libreria client delle API di Google per Python per chiamare l'API AI Platform Training and Prediction senza creare manualmente le richieste HTTP. Prima di eseguire il seguente esempio di codice, devi configurare l'autenticazione.

# Create the AI Platform service object.
# To authenticate set the environment variable
# GOOGLE_APPLICATION_CREDENTIALS=<path_to_service_account_file>
service = googleapiclient.discovery.build("ml", "v1")

def predict_json(project, model, instances, version=None):
    """Send json data to a deployed model for prediction.

    Args:
        project (str): project where the AI Platform Model is deployed.
        model (str): model name.
        instances ([Mapping[str: Any]]): Keys should be the names of Tensors
            your deployed model expects as inputs. Values should be datatypes
            convertible to Tensors, or (potentially nested) lists of datatypes
            convertible to tensors.
        version: str, version of the model to target.
    Returns:
        Mapping[str: any]: dictionary of prediction results defined by the
            model.
    """
    name = f"projects/{project}/models/{model}"

    if version is not None:
        name += f"/versions/{version}"

    response = (
        service.projects().predict(name=name, body={"instances": instances}).execute()
    )

    if "error" in response:
        raise RuntimeError(response["error"])

    return response["predictions"]

Java

Puoi utilizzare la libreria client delle API di Google per Java per chiamare l'API AI Platform Training and Prediction senza creare manualmente le richieste HTTP. Prima di eseguire il seguente esempio di codice, devi configurare l'autenticazione.

/*
 * Copyright 2017 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.FileContent;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpContent;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.UriTemplate;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.discovery.Discovery;
import com.google.api.services.discovery.model.JsonSchema;
import com.google.api.services.discovery.model.RestDescription;
import com.google.api.services.discovery.model.RestMethod;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.File;
import java.util.ArrayList;
import java.util.List;

/*
 * Sample code for sending an online prediction request to Cloud Machine Learning Engine.
 */

public class OnlinePredictionSample {
  public static void main(String[] args) throws Exception {
    HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
    JsonFactory jsonFactory = GsonFactory.getDefaultInstance();
    Discovery discovery = new Discovery.Builder(httpTransport, jsonFactory, null).build();

    RestDescription api = discovery.apis().getRest("ml", "v1").execute();
    RestMethod method = api.getResources().get("projects").getMethods().get("predict");

    JsonSchema param = new JsonSchema();
    String projectId = "YOUR_PROJECT_ID";
    // You should have already deployed a model and a version.
    // For reference, see https://cloud.google.com/ml-engine/docs/deploying-models.
    String modelId = "YOUR_MODEL_ID";
    String versionId = "YOUR_VERSION_ID";
    param.set(
        "name", String.format("projects/%s/models/%s/versions/%s", projectId, modelId, versionId));

    GenericUrl url =
        new GenericUrl(UriTemplate.expand(api.getBaseUrl() + method.getPath(), param, true));
    System.out.println(url);

    String contentType = "application/json";
    File requestBodyFile = new File("input.txt");
    HttpContent content = new FileContent(contentType, requestBodyFile);
    System.out.println(content.getLength());

    List<String> scopes = new ArrayList<>();
    scopes.add("https://www.googleapis.com/auth/cloud-platform");

    GoogleCredentials credential = GoogleCredentials.getApplicationDefault().createScoped(scopes);
    HttpRequestFactory requestFactory =
        httpTransport.createRequestFactory(new HttpCredentialsAdapter(credential));
    HttpRequest request = requestFactory.buildRequest(method.getHttpMethod(), url, content);

    String response = request.execute().parseAsString();
    System.out.println(response);
  }
}

Risoluzione dei problemi di previsione online

Gli errori più comuni nella previsione online includono:

  • Errori di memoria insufficiente
  • I dati di input non sono formattati correttamente
  • Una singola richiesta di previsione online non deve contenere più di 1,5 MB di dati. Le richieste create utilizzando gcloud CLI possono gestire non più di 100 istanze per file. Per ottenere previsioni per più istanze contemporaneamente, utilizza la previsione batch.

Prova a ridurre le dimensioni del modello prima di eseguirne il deployment in AI Platform Prediction per la previsione.

Leggi ulteriori informazioni sulla risoluzione dei problemi di previsione online.

Passaggi successivi