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 addestramento di AI Platform nelle tue applicazioni Python. Gli snippet di codice e gli esempi nel resto di questa 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 inclusa in un piccolo esempio.

Obiettivi

Questo è un tutorial di base progettato per acquisire familiarità con la libreria client Python. Al termine, dovresti essere in grado di:

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

Costi

Non ti verrà addebitato alcun costo per le operazioni di questo tutorial. Per ulteriori informazioni, consulta la pagina relativa ai prezzi.

Prima di iniziare

Configura il tuo progetto Google Cloud

  1. Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

  2. Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

    Vai al selettore progetti

  3. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

  4. Abilita le API AI Platform Training & Prediction and Compute Engine.

    Abilita le API

  5. Installa Google Cloud CLI.

  6. Per initialize gcloud CLI, esegui questo comando: 

    gcloud init
    7.

  7. Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

    Vai al selettore progetti

  8. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

  9. Abilita le API AI Platform Training & Prediction and Compute Engine.

    Abilita le API

  10. Installa Google Cloud CLI.

  11. Per initialize gcloud CLI, esegui questo comando: 

    gcloud init
    12.

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 alla 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 Archiviazione > Amministratore oggetti Storage.

    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. Sul computer viene scaricato un file della chiave JSON.
    5. Fai clic su Chiudi.

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

Configura un ambiente di sviluppo Python

Scegli una delle opzioni seguenti per configurare il tuo ambiente localmente su macOS o in un ambiente remoto su Cloud Shell.

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

macOS

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

    python -V

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

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

    pip install -U pip

    Consulta la documentazione pip per ulteriori dettagli.

  3. Installa virtualenv
    virtualenv è uno strumento per creare ambienti Python isolati. Verifica se hai già installato virtualenv eseguendo 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.

    Leggi 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. L'inizializzazione della sessione della shell può richiedere alcuni secondi.

    Sessione di Cloud Shell

    La sessione Cloud Shell è pronta per l'uso.

  3. Configura lo strumento a riga di comando gcloud per utilizzare il progetto selezionato. 

    gcloud config set project [selected-project-id]

    dove [selected-project-id] è l'ID progetto. Ometti le parentesi che racchiudono il testo.

Installa la libreria client delle API di Google per Python

Installa la libreria client delle API di Google per Python.

Questo è un tutorial di base progettato per acquisire familiarità con la libreria client Python. Al termine, dovresti essere in grado di:

  • Ottieni una rappresentazione Python dei servizi di AI Platform Training.
  • Utilizza questa rappresentazione per creare un modello nel progetto, che dovrebbe aiutarti a capire come chiamare le altre API di gestione dei modelli e dei job.
Non ti verrà addebitato alcun costo per le operazioni di questo tutorial. Per ulteriori informazioni, consulta la pagina relativa ai prezzi.

Importazione dei moduli richiesti

Se vuoi utilizzare la libreria client delle API di Google per Python per chiamare le API REST di AI Platform Training 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 Training) devi solo importare moduli specifici:

Fai riferimento alla documentazione dei pacchetti per informazioni sugli altri moduli disponibili.

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 API utilizza Service Discovery per configurare dinamicamente le connessioni ai servizi così come esistono quando effettui la chiamata. Richiama l'oggetto che incapsula i servizi ml:

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

Configurazione dei parametri e 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. Puoi passare i parametri come normali parametri Python al metodo che rappresenta la chiamata. Il corpo è una risorsa JSON, come la useresti se chiami direttamente l'API con una richiesta HTTP.

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

  • Nota il parametro del percorso parent, che è la parte dell'URI della richiesta che identifica il progetto. Se invii direttamente la richiesta HTTP POST, utilizza il seguente URI:

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

    Quando si utilizza la libreria client API, la parte variabile dell'URI è rappresentata come parametro di tipo stringa per la chiamata API. Lo imposterai su 'projects/<var>YOUR_PROJECT_ID</var>'. Archivia il progetto in una variabile per rendere più pulite le chiamate API:

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

  • Il corpo della richiesta è una risorsa JSON che rappresenta le informazioni del modello. Puoi vedere nella definizione della risorsa modello che ha due valori per l'input: name e, facoltativamente, description. Puoi passare un dizionario Python al posto di JSON e la libreria client dell'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 in corso...

L'esecuzione di chiamate alle API con la libreria client Python prevede due passaggi: prima devi creare una richiesta, quindi eseguire la chiamata utilizzando quella richiesta.

Crea la richiesta

Utilizza gli oggetti client compilati che hai creato in precedenza (se hai seguito esattamente lo snippet di codice, è denominato ml) come radice della gerarchia 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 AI Platform Training è projects, quindi la chiamata inizia con ml.projects().

Utilizza questo codice per compilare la richiesta:

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

Invia la richiesta

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

response = request.execute()

È comune per gli sviluppatori combinare 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. È una buona idea 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, incapsulati nella classe HttpError. Per individuare questi errori, utilizza il modulo errors del pacchetto googleapiclient.

Aggrega la chiamata request.execute() in un blocco try. Inoltre, inserisci un'istruzione print nel blocco, in modo da provare a stampare la risposta solo se la chiamata ha esito positivo:

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

Aggiungi un blocco catch per gestire gli errori HTTP. Puoi utilizzare HttpError._get_reason() per ottenere 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())

Naturalmente, una semplice affermazione stampata potrebbe non essere l'approccio giusto per la tua domanda.

Riepilogo

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 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. Usa il modulo di rilevamento per creare una rappresentazione Python dell'API.

  3. Utilizza la rappresentazione API come una serie di oggetti nidificati per raggiungere l'API che vuoi 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 gestirlo come un dizionario Python per trovare gli oggetti JSON specificati nel riferimento API. Tieni presente che molti oggetti nelle risposte hanno campi presenti solo in alcune circostanze. Dovresti sempre controllare per evitare errori importanti:

    response = request.execute()

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

Passaggi successivi