Utilizzo della libreria client Python

Questo tutorial descrive come utilizzare la libreria client delle API di Google per Python per chiamare le API REST di AI Platform Prediction nelle tue applicazioni Python. I frammenti di codice e gli esempi nel resto della documentazione utilizzano questa libreria client Python.

In questo tutorial creerai un modello nel tuo progetto Google Cloud. Si tratta di un'attività semplice che può essere facilmente contenuta in un piccolo esempio.

Obiettivi

Questo è un tutorial di base progettato per farti familiarizzare con questa libreria client Python. Al termine, dovresti essere in grado di:

  • Ottieni una rappresentazione in Python dei servizi AI Platform Prediction.
  • Utilizza questa rappresentazione per creare un modello nel tuo progetto, che dovrebbe aiutarti a capire come chiamare le altre API di gestione dei modelli e dei job.

Costi

Le operazioni in questo tutorial non ti verranno addebitate. Per ulteriori informazioni, consulta la pagina dei prezzi.

Prima di iniziare

Configura il progetto Google Cloud

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the AI Platform Training & Prediction and Compute Engine APIs.

    Enable the APIs

  5. Install the Google Cloud CLI.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  8. Make sure that billing is enabled for your Google Cloud project.

  9. Enable the AI Platform Training & Prediction and Compute Engine APIs.

    Enable the APIs

  10. Install the Google Cloud CLI.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init

Configura l'autenticazione

Per configurare l'autenticazione, devi creare una chiave dell'account di servizio e impostare una variabile di ambiente per il percorso del file della chiave dell'account di servizio.

  1. Crea un account di servizio:

    1. Nella console Google Cloud, vai alla pagina Crea account di servizio.

      Vai a Crea account di servizio

    2. Inserisci un nome nel campo Nome account di servizio.
    3. (Facoltativo) Nel campo Descrizione account di servizio, inserisci una descrizione.
    4. Fai clic su Crea.
    5. Fai clic sul campo Seleziona un ruolo. In Tutti i ruoli, seleziona AI Platform > Amministratore AI Platform.
    6. Fai clic su Aggiungi un altro ruolo.

    7. Fai clic sul campo Seleziona un ruolo. In Tutti i ruoli, seleziona Storage > Storage Object Admin.

    8. Fai clic su Fine per creare l'account di servizio.

      Non chiudere la finestra del browser. Lo utilizzerai nel passaggio successivo.

  2. Crea una chiave dell'account di servizio per l'autenticazione:

    1. Nella console Google Cloud, fai clic sull'indirizzo email dell'account di servizio che hai creato.
    2. Fai clic su Chiavi.
    3. Fai clic su Aggiungi chiave, quindi su Crea nuova chiave.
    4. Fai clic su Crea. Un file della chiave JSON viene scaricato sul computer.
    5. Fai clic su Chiudi.

  3. Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON contenente la chiave dell'account di servizio. Questa variabile si applica solo alla sessione di shell corrente, quindi se apri una nuova sessione, imposta di nuovo la variabile.

Configurare un ambiente di sviluppo Python

Scegli una delle opzioni riportate di seguito per configurare l'ambiente localmente su macOS o in un ambiente remoto su Cloud Shell.

Per gli utenti di macOS, ti consigliamo di configurare l'ambiente utilizzando la scheda MACOS di seguito. Cloud Shell, visualizzato nella scheda CLOUD SHELL, è disponibile su macOS, Linux e Windows. Cloud Shell offre un modo rapido per provare AI Platform Prediction, ma non è adatto per lo sviluppo continuo.

macOS

  1. Verifica l'installazione di Python
    Verifica di avere installato Python e, se necessario, installalo.

    python -V

  2. Verifica l'installazione di pip
    pip è il gestore dei pacchetti di Python, incluso nelle versioni attuali di Python. Per verificare se pip è già installato, esegui pip --version. In caso contrario, scopri come installare pip.

    Puoi eseguire l'upgrade di pip utilizzando il seguente comando:

    pip install -U pip

    Per ulteriori dettagli, consulta la documentazione di pip.

  3. Installa virtualenv
    virtualenv è uno strumento per creare ambienti Python isolati. Per verificare se hai già installato virtualenv, esegui virtualenv --version. In caso contrario, installa virtualenv: 

    pip install --user --upgrade virtualenv

    Per creare un ambiente di sviluppo isolato per questa guida, crea un nuovo ambiente virtuale in virtualenv. Ad esempio, il seguente comando attiva un ambiente denominato aip-env:

    virtualenv aip-env
source aip-env/bin/activate

  4. Ai fini di questo tutorial, esegui il resto dei comandi all'interno del tuo ambiente virtuale.

    Consulta ulteriori informazioni sull'utilizzo di virtualenv. Per uscire da virtualenv, esegui deactivate.

Cloud Shell

  1. Apri la console Google Cloud.

    Console Google Cloud

  2. Fai clic sul pulsante Attiva Google Cloud Shell nella parte superiore della finestra della console.

    Attiva Google Cloud Shell

    All'interno di un nuovo frame nella parte inferiore della console si apre una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Potrebbe essere necessario attendere qualche secondo per l'inizializzazione della sessione della shell.

    Sessione di Cloud Shell

    La sessione Cloud Shell è pronta per l'uso.

  3. Configura lo strumento a riga di comando gcloud in modo da utilizzare il progetto selezionato. 

    gcloud config set project [selected-project-id]

    dove [selected-project-id] è l'ID progetto. (Ometti le parentesi graffe di chiusura.)

Installa la libreria client dell'API di Google per Python

Installa la libreria client delle API di Google per Python.

Questo è un tutorial di base progettato per farti familiarizzare con questa libreria client Python. Al termine, dovresti essere in grado di:

  • Ottieni una rappresentazione in Python dei servizi AI Platform Prediction.
  • Utilizza questa rappresentazione per creare un modello nel tuo progetto, che dovrebbe aiutarti a capire come chiamare le altre API di gestione dei modelli e dei job.
Le operazioni in questo tutorial non ti verranno addebitate. Per ulteriori informazioni, consulta la pagina dei prezzi.

Importazione dei moduli richiesti

Quando vuoi utilizzare la libreria client delle API di Google per Python per chiamare le API REST di AI Platform Prediction nel tuo codice, devi importare il relativo pacchetto e il pacchetto OAuth2. Per questo tutorial (e per la maggior parte degli utilizzi standard di AI Platform Prediction) devi importare solo moduli specifici:

Per informazioni sugli altri moduli disponibili, consulta la documentazione di questi pacchetti.

Crea un nuovo file Python utilizzando il tuo editor preferito e aggiungi queste righe:

from oauth2client.client import GoogleCredentials
from googleapiclient import discovery
from googleapiclient import errors

Creazione di una rappresentazione Python dell'API

Ottieni la rappresentazione Python dell'API REST. Il metodo che chiami è build perché la libreria client dell'API utilizza Service Discovery per configurare dinamicamente le connessioni ai servizi esistenti al momento della chiamata. Chiama l'oggetto che incapsula i servizi ml:

ml = discovery.build('ml','v1')

Configurare i parametri e il corpo della richiesta

Per effettuare una chiamata a un servizio, devi creare i parametri e il corpo della richiesta che verranno passati all'API REST. Devi passare i parametri come parametri Python comuni al metodo che rappresenta la chiamata. Il corpo è una risorsa JSON, come faresti se chiamassi direttamente l'API con una richiesta HTTP.

Dai un'occhiata all'API REST per la creazione di un modello in una nuova scheda del browser, projects.models.create:

  • Tieni presente il parametro path parent, che è la parte dell'URI della richiesta che identifica il progetto. Se inviassi direttamente la richiesta POST HTTP, dovresti utilizzare il seguente URI:

    https://ml.googleapis.com/v1/projects/YOUR_PROJECT_ID/models

    Quando utilizzi la libreria client dell'API, la parte variabile dell'URI viene rappresentata come parametro di tipo stringa per la chiamata API. Impostalo su 'projects/<var>YOUR_PROJECT_ID</var>'. Memorizza il progetto in una variabile per semplificare le chiamate API:

    project_id = 'projects/{}'.format('YOUR_PROJECT_ID')

  • Il corpo della richiesta è una risorsa JSON che rappresenta le informazioni del modello. Nella definizione della risorsa del modello puoi vedere che sono presenti due valori per l'input: name e (facoltativo) description. Puoi passare un dizionario Python al posto di JSON e la libreria client API eseguirà la conversione necessaria.

    Crea il tuo dizionario Python:

    request_dict = {'name': 'your-model-name',
               'description': 'This is a machine learning model entry.'}

Creazione della richiesta

Per effettuare chiamate alle API con la libreria client Python sono necessari due passaggi: innanzitutto crei una richiesta, poi effettui la chiamata utilizzandola.

Crea la richiesta

Utilizza gli oggetti client creati in precedenza (se hai seguito esattamente lo snippet di codice, si chiama ml) come radice della gerarchia dell'API e specifica l'API che vuoi utilizzare. Ogni raccolta nel percorso dell'API si comporta come una funzione che restituisce un elenco delle raccolte e dei metodi al suo interno. Ad esempio, la radice di tutte le API di previsione di AI Platform è projects, quindi la chiamata inizia con projects.ml.projects()

Utilizza questo codice per formulare la richiesta:

request = ml.projects().models().create(parent=project_id, body=request_dict)

Invia la richiesta

La richiesta creata nell'ultimo passaggio espone un metodo execute che chiami per inviare la richiesta al servizio:

response = request.execute()

È comune che gli sviluppatori combinino questo passaggio con l'ultimo:

response = ml.projects().models().create(parent=project_id,
                                         body=request_dict).execute()

Gestire errori semplici

Quando effettui chiamate API su internet, possono verificarsi molti problemi. È buona prassi gestire gli errori comuni. Il modo più semplice per gestire gli errori è inserire la richiesta in un blocco try e rilevare gli errori probabili. La maggior parte degli errori che potresti ricevere dal servizio sono errori HTTP, che sono incapsulati nella classe HttpError. Per rilevare questi errori, utilizzerai il modulo errors del pacchetto googleapiclient.

Inserisci la chiamata request.execute() in un blocco try. Inserisci anche un'istruzione print nel blocco, in modo da provare a stampare la risposta solo se la chiamata va a buon fine:

try:
    response = request.execute()
    print(response)

Aggiungi un blocco try/catch per gestire gli errori HTTP. Puoi utilizzare HttpError._get_reason() per recuperare i campi di testo del motivo dalla risposta:

except errors.HttpError, err:
    # Something went wrong, print out some information.
    print('There was an error creating the model. Check the details:')
    print(err._get_reason())

Ovviamente, un semplice comando di stampa potrebbe non essere l'approccio giusto per la tua applicazione.

In sintesi

Ecco l'esempio completo:

from googleapiclient import discovery
from googleapiclient import errors

# Store your full project ID in a variable in the format the API needs.
project_id = 'projects/{}'.format('YOUR_PROJECT_ID')

# Build a representation of the Cloud ML API.
ml = discovery.build('ml', 'v1')

# Create a dictionary with the fields from the request body.
request_dict = {'name': 'your_model_name',
               'description': 'your_model_description'}

# Create a request to call projects.models.create.
request = ml.projects().models().create(
              parent=project_id, body=request_dict)

# Make the call.
try:
    response = request.execute()
    print(response)
except errors.HttpError, err:
    # Something went wrong, print out some information.
    print('There was an error creating the model. Check the details:')
    print(err._get_reason())

Generalizzazione ad altri metodi

Puoi utilizzare la procedura che hai appreso qui per effettuare qualsiasi altra chiamata dell'API REST. Alcune API richiedono risorse JSON molto più complesse rispetto alla creazione di un modello, ma i principi sono gli stessi:

  1. Importa googleapiclient.discovery e googleapiclient.errors.

  2. Utilizza il modulo di rilevamento per creare una rappresentazione Python dell'API.

  3. Utilizza la rappresentazione dell'API come una serie di oggetti nidificati per accedere all'API che ti interessa e creare una richiesta. Ad esempio,

    request = ml.projects().models().versions().delete(
    name='projects/myproject/models/mymodel/versions/myversion')

  4. Chiama request.execute() per inviare la richiesta, gestendo le eccezioni in modo appropriato per la tua applicazione.

  5. Quando è presente un corpo della risposta, puoi trattarlo come un dizionario Python per accedere agli oggetti JSON specificati nel riferimento all'API. Tieni presente che molti degli oggetti nelle risposte hanno campi presenti solo in alcune circostanze. Per evitare errori principali, devi sempre verificare quanto segue:

    response = request.execute()

some_value = response.get('some_key') or 'default_value'

Passaggi successivi