Python-Clientbibliothek verwenden

In dieser Anleitung wird beschrieben, wie Sie mit der Google API-Clientbibliothek für Python die REST APIs für AI Platform Training in Ihren Python-Anwendungen aufrufen. Die Code-Snippets und -beispiele in dieser Dokumentation verwenden jene Python-Clientbibliothek.

Sie erstellen in dieser Anleitung ein Modell in Ihrem Google Cloud-Projekt. Es handelt sich dabei um eine einfache Aufgabe, die problemlos anhand eines kleinen Beispiels ausgeführt werden kann.

Lernziele

In dieser grundlegenden Anleitung werden Sie mit jener Python-Clientbibliothek vertraut gemacht. Wenn Sie diese Anleitung abgeschlossen haben, sollten Sie Folgendes können:

  • Abrufen einer Python-Repräsentation der AI Platform Training-Dienste
  • Erstellen eines Modells mit dieser Repräsentation im Projekt, sodass Sie in der Lage sind, die anderen Modell- und Jobverwaltungs-APIs aufzurufen

Kosten

Für die Vorgänge in dieser Anleitung werden keine Gebühren berechnet. Weitere Informationen finden Sie auf der Preisseite.

Hinweise

GCP-Projekt einrichten

  1. Melden Sie sich bei Ihrem Google Cloud-Konto an. Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

  2. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

  3. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

  4. AI Platform Training & Prediction and Compute Engine APIs aktivieren.

    Aktivieren Sie die APIs

  5. Installieren Sie die Google Cloud CLI.

  6. Führen Sie folgenden Befehl aus, um die gcloud CLI zu initialisieren: 

    gcloud init
    7.

  7. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

  8. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

  9. AI Platform Training & Prediction and Compute Engine APIs aktivieren.

    Aktivieren Sie die APIs

  10. Installieren Sie die Google Cloud CLI.

  11. Führen Sie folgenden Befehl aus, um die gcloud CLI zu initialisieren: 

    gcloud init
    12.

Authentifizierung einrichten

Für die Einrichtung der Authentifizierung müssen Sie einen Dienstkontoschlüssel erstellen und eine Umgebungsvariable für den Dateipfad zum Dienstkontoschlüssel festlegen.

  1. Erstellen Sie ein Dienstkonto:

    1. Wechseln Sie in der Google Cloud Console zur Seite Dienstkonto erstellen.

      Zur Seite „Dienstkonto erstellen“

    2. Geben Sie im Feld Dienstkontoname einen Namen ein.
    3. Optional: Geben Sie im Feld Dienstkontobeschreibung eine Beschreibung ein.
    4. Klicken Sie auf Erstellen.
    5. Klicken Sie auf das Feld Rolle auswählen. Wählen Sie unter Alle Rollen die Option AI Platform > AI Platform-Administrator aus.
    6. Klicken Sie auf Weitere Rolle hinzufügen.

    7. Klicken Sie auf das Feld Rolle auswählen. Wählen Sie unter Alle Rollen die Option Storage > Storage-Objekt-Administrator.

    8. Klicken Sie auf Fertig, um das Dienstkonto zu erstellen.

      Schließen Sie das Browserfenster nicht. Sie verwenden es in der nächsten Aufgabe.

  2. Erstellen Sie einen Dienstkontoschlüssel für die Authentifizierung:

    1. Klicken Sie in der Google Cloud Console auf die E-Mail-Adresse des von Ihnen erstellten Dienstkontos.
    2. Klicken Sie auf Schlüssel.
    3. Klicken Sie auf Schlüssel hinzufügen > Neuen Schlüssel erstellen.
    4. Klicken Sie auf Erstellen. Daraufhin wird eine JSON-Schlüsseldatei auf Ihren Computer heruntergeladen.
    5. Klicken Sie auf Schließen.

  3. Legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad der JSON-Datei fest, die Ihren Dienstkontoschlüssel enthält. Diese Variable gilt nur für Ihre aktuelle Shell-Sitzung. Wenn Sie eine neue Sitzung öffnen, müssen Sie die Variable noch einmal festlegen.

Python-Entwicklungsumgebung einrichten

Wählen Sie eine der folgenden Optionen aus, um Ihre Umgebung lokal auf macOS oder in einer Remoteumgebung in Cloud Shell einzurichten.

Nutzern von macOS wird empfohlen, ihre Umgebung mit dem folgenden MACOS-Tab einzurichten. Cloud Shell ist unter macOS, Linux und Windows verfügbar. Die entsprechende Anleitung finden Sie auf dem Tab CLOUD SHELL. Cloud Shell bietet eine schnelle Möglichkeit für den Test von AI Platform Training, eignet sich jedoch nicht für fortlaufende Entwicklungsarbeiten.

macOS

  1. Python-Installation prüfen.
    Prüfen Sie, ob Python installiert ist, und installieren Sie es gegebenenfalls.

    python -V

  2. pip-Installation prüfen.
    pip ist der Paketmanager von Python, der in aktuellen Versionen von Python enthalten ist. Prüfen Sie, ob Sie pip bereits installiert haben. Dazu führen Sie pip --version aus. Ist das nicht der Fall, lesen Sie die Anleitung zum Installieren von pip.

    Mit diesem Befehl können Sie ein Upgrade von pip ausführen:

    pip install -U pip

    Weitere Informationen finden Sie in der Dokumentation zu pip.

  3. virtualenv installieren
    virtualenv ist ein Tool, mit dem sich isolierte Python-Umgebungen erstellen lassen. Prüfen Sie, ob Sie virtualenv bereits installiert haben. Dazu führen Sie virtualenv --version aus. Ist dies nicht der Fall, installieren Sie virtualenv: 

    pip install --user --upgrade virtualenv

    Zur Einrichtung einer isolierten Entwicklungsumgebung für diese Anleitung erstellen Sie in virtualenv eine neue virtuelle Umgebung. Mit dem folgenden Befehl wird beispielsweise eine Umgebung mit dem Namen aip-env aktiviert:

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

  4. Führen Sie für diese Anleitung die übrigen Befehle in Ihrer virtuellen Umgebung aus.

    Hier finden Sie weitere Informationen zur Verwendung von virtualenv. Zum Beenden von virtualenv führen Sie deactivate aus.

Cloud Shell

  1. Öffnen Sie die Google Cloud Console.

    Google Cloud Console

  2. Klicken Sie oben auf Cloud Shell aktivieren.

    Google Cloud Shell aktivieren

    In einem neuen Frame im unteren Teil der Console wird eine Cloud Shell-Sitzung geöffnet und darin eine Eingabeaufforderung angezeigt. Die Initialisierung der Shell-Sitzung kann einige Sekunden dauern.

    Cloud Shell-Sitzung

    Die Cloud Shell-Sitzung kann jetzt verwendet werden.

  3. Konfigurieren Sie das gcloud-Befehlszeilentool für die Verwendung des ausgewählten Projekts. 

    gcloud config set project [selected-project-id]

    Dabei ist [selected-project-id] Ihre Projekt-ID. Diese geben Sie ohne die Klammern ein.

Google API-Clientbibliothek für Python installieren

Installieren Sie die Google-API-Clientbibliothek für Python.

In dieser grundlegenden Anleitung werden Sie mit jener Python-Clientbibliothek vertraut gemacht. Wenn Sie diese Anleitung abgeschlossen haben, sollten Sie Folgendes können:

  • Abrufen einer Python-Repräsentation der AI Platform Training-Dienste
  • Erstellen eines Modells mit dieser Repräsentation im Projekt, sodass Sie in der Lage sind, die anderen Modell- und Jobverwaltungs-APIs aufzurufen
Für die Vorgänge in dieser Anleitung werden keine Gebühren berechnet. Weitere Informationen finden Sie in der Preisübersicht.

Erforderliche Module importieren

Wenn Sie die REST API für AI Platform Training anhand der Clientbibliothek der Google APIs für Python in Ihrem Code aufrufen möchten, müssen Sie deren Paket und das OAuth2-Paket importieren. Für diese Anleitung (und für die meisten Standardanwendungsfälle von AI Platform Training) müssen Sie nur bestimmte Module importieren:

Informationen zu den anderen verfügbaren Modulen finden Sie in der Dokumentation zum jeweiligen Paket.

Erstellen Sie mit Ihrem bevorzugten Editor eine neue Python-Datei und fügen Sie diese Zeilen hinzu:

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

Python-Darstellung der API erstellen

Rufen Sie Ihre Python-Darstellung der REST API ab. Dazu rufen Sie die Methode build auf, da die API-Clientbibliothek mithilfe der Service Discovery dynamisch Verbindungen mit den Diensten einrichtet, wenn diese beim Aufruf vorhanden sind. Rufen Sie das Objekt auf, das die ml-Dienste einschließt:

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

Parameter und Anfragetext konfigurieren

Die Parameter und der Anfragetext, die bzw. der an die REST API übergeben werden, müssen erstellt werden, um einen Aufruf eines Dienstes durchzuführen. Die Parameter werden als reguläre Python-Parameter an die Methode übergeben, mit der der Aufruf durchgeführt wird. Der Text stellt eine JSON-Ressource wie beim direkten Aufruf der API mit einer HTTP-Anfrage dar.

Werfen Sie einen Blick auf die REST API für die Erstellung eines Modells im neuen Browsertab, projects.models.create:

  • Achten Sie auf den Pfadparameter parent. Dieser ist der Teil des Anfrage-URI, der das Projekt identifiziert. Wenn Sie die HTTP-POST-Anfrage direkt ausführen, verwenden Sie den folgenden URI:

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

    Bei Verwendung der API-Clientbibliothek ist der variable Teil des URI ein Stringparameter für den API-Aufruf. Legen Sie den Wert auf 'projects/<var>YOUR_PROJECT_ID</var>' fest. Speichern Sie Ihr Projekt in einer Variable, um API-Aufrufe übersichtlicher zu machen:

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

  • Der Anfragetext ist eine JSON-Ressource, die die Modellinformationen enthält. In der Ressourcendefinition des Modells enthält der Text zwei Eingabewerte: name und description (optional). Sie können anstelle von JSON ein Python-Wörterbuch übergeben. Die API-Clientbibliothek führt dann die notwendige Konvertierung durch.

    Erstellen Sie Ihr Python-Wörterbuch:

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

Anfrage erstellen

Der Aufruf von APIs mit der Python-Clientbibliothek erfolgt in zwei Schritten: Zuerst erstellen Sie eine Anfrage, dann führen Sie mit dieser Anfrage den Aufruf durch.

Anfrage erstellen

Verwenden Sie die zuvor erstellten Clientobjekte (wenn Sie das Code-Snippet wie angegeben verwendet haben, lautet es ml) als Basis der API-Hierarchie und geben Sie die gewünschte API an. Jede Sammlung im API-Pfad verhält sich wie eine Funktion, die eine Liste der darin enthaltenen Sammlungen und Methoden zurückgibt. Beispielsweise ist projects das Stammverzeichnis aller AI Platform Training APIs. Ihr Aufruf beginnt also mit ml.projects().

Verwenden Sie für Ihre Anfrage folgenden Code:

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

Anfrage senden

Die im letzten Schritt erstellte Anfrage gibt eine execute-Methode an, die Sie zum Senden der Anfrage an den Dienst aufrufen:

response = request.execute()

Entwickler kombinieren diesen Schritt in der Regel mit dem letzten Schritt:

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

Einfache Fehler abfangen

Bei der Durchführung von API-Aufrufen über das Internet gibt es viele potenzielle Fehlerquellen. Es ist deshalb empfehlenswert, gängige Fehler systematisch abzufangen. Der einfachste Weg zur Fehlerbehandlung ist die Platzierung Ihrer Anfrage in einem try-Block, um so mögliche Fehler abzufangen. Bei den meisten denkbaren Fehlern des Dienstes handelt es sich um HTTP-Fehler, die in der Klasse HttpError gekapselt sind. Verwenden Sie zum Erkennen dieser Fehler das Modul errors aus dem Paket googleapiclient.

Fassen Sie Ihren request.execute()-Aufruf in einem try-Block zusammen. Fügen Sie außerdem eine print-Anweisung in den Block ein, damit erst dann versucht wird, die Antwort auszugeben, wenn der Aufruf erfolgreich war:

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

Fügen Sie einen entsprechenden Block hinzu, um HTTP-Fehler abzufangen. Sie können die Textfelder zur Fehlerursache mit HttpError._get_reason() aus der Antwort abrufen:

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())

Möglicherweise reicht aber eine einfache Ausgabeanweisung für Ihre Anwendung nicht aus.

Alle Anweisungen zusammengefasst

So sieht das Beispiel komplett aus:

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())

Auf andere Methoden übertragen

Sie können mit der hier dargestellten Prozedur auch alle anderen REST API-Aufrufe durchführen. Für einige APIs sind komplexere JSON-Ressourcen als für das Erstellen eines Modells erforderlich. Die grundsätzliche Vorgehensweise unterscheidet sich aber nicht:

  1. Importieren Sie googleapiclient.discovery und googleapiclient.errors.

  2. Verwenden Sie das Erkennungsmodul, um eine Python-Repräsentation Ihrer API zu erstellen.

  3. Verwenden Sie die API-Darstellung als eine Reihe verschachtelter Objekte, um zur gewünschten API zu gelangen und eine Anfrage zu erstellen. Beispiel:

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

  4. Rufen Sie request.execute() auf, um die Anfrage zu senden und Ausnahmen in einer für Ihre Anwendung geeigneten Weise zu verarbeiten.

  5. Wenn ein Antworttext vorhanden ist, können Sie diesen wie ein Python-Wörterbuch behandeln und damit die in der API-Referenz angegebenen JSON-Objekte ermitteln. Beachten Sie, dass viele der Objekte in Antworten Felder haben, die nur in bestimmten Fällen vorhanden sind. Es wird empfohlen, immer eine Prüfung vorzunehmen, um zentrale Fehler zu vermeiden:

    response = request.execute()

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

Nächste Schritte