In dieser Anleitung wird beschrieben, wie Sie mit der Google APIs-Clientbibliothek für Python die REST APIs für AI Platform Prediction 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.
Ziele
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 Prediction-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.Vorbereitung
GCP-Projekt einrichten
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the AI Platform Training & Prediction and Compute Engine APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the AI Platform Training & Prediction and Compute Engine APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
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.
-
Erstellen Sie ein Dienstkonto:
-
Wechseln Sie in der Google Cloud Console zur Seite Dienstkonto erstellen.
- Geben Sie im Feld Dienstkontoname einen Namen ein.
- Optional: Geben Sie im Feld Dienstkontobeschreibung eine Beschreibung ein.
- Klicken Sie auf Erstellen.
- Klicken Sie auf das Feld Rolle auswählen. Wählen Sie unter Alle Rollen die Option AI Platform > AI Platform-Administrator aus.
- Klicken Sie auf Weitere Rolle hinzufügen.
-
Klicken Sie auf das Feld Rolle auswählen. Wählen Sie unter Alle Rollen die Option Storage > Storage-Objekt-Administrator.
-
Klicken Sie auf Fertig, um das Dienstkonto zu erstellen.
Schließen Sie das Browserfenster nicht. Sie verwenden es in der nächsten Aufgabe.
-
-
Erstellen Sie einen Dienstkontoschlüssel für die Authentifizierung:
- Klicken Sie in der Google Cloud Console auf die E-Mail-Adresse des von Ihnen erstellten Dienstkontos.
- Klicken Sie auf Schlüssel.
- Klicken Sie auf Schlüssel hinzufügen > Neuen Schlüssel erstellen.
- Klicken Sie auf Erstellen. Daraufhin wird eine JSON-Schlüsseldatei auf Ihren Computer heruntergeladen.
- Klicken Sie auf Schließen.
-
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 Prediction, eignet sich jedoch nicht für fortlaufende Entwicklungsarbeiten.
macOS
-
Python-Installation prüfen.
Prüfen Sie, ob Python installiert ist, und installieren Sie es gegebenenfalls.python -V
-
pip
-Installation prüfen.
pip
ist der Paketmanager von Python, der in aktuellen Versionen von Python enthalten ist. Prüfen Sie, ob Siepip
bereits installiert haben. Dazu führen Siepip --version
aus. Ist das nicht der Fall, lesen Sie die Anleitung zum Installieren vonpip
.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.
-
virtualenv
installieren
virtualenv
ist ein Tool, mit dem sich isolierte Python-Umgebungen erstellen lassen. Prüfen Sie, ob Sievirtualenv
bereits installiert haben. Dazu führen Sievirtualenv --version
aus. Ist dies nicht der Fall, installieren Sievirtualenv
: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 Namenaip-env
aktiviert:virtualenv aip-env source aip-env/bin/activate
-
Führen Sie für diese Anleitung die übrigen Befehle in Ihrer virtuellen Umgebung aus.
Hier finden Sie weitere Informationen zur Verwendung vonvirtualenv
. Zum Beenden vonvirtualenv
führen Siedeactivate
aus.
Cloud Shell
-
Öffnen Sie die Google Cloud Console.
-
Klicken Sie oben auf 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.
Die Cloud Shell-Sitzung kann jetzt verwendet werden.
-
Für die Verwendung Ihres ausgewählten Projekts konfigurieren Sie das
gcloud
-Befehlszeilentool.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.
- Abrufen einer Python-Repräsentation der AI Platform Prediction-Dienste
- Erstellen eines Modells mit dieser Repräsentation im Projekt, sodass Sie in der Lage sind, die anderen Modell- und Jobverwaltungs-APIs aufzurufen
Erforderliche Module importieren
Wenn Sie die REST APIs für AI Platform Prediction anhand der Clientbibliothek der Google API 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 Prediction) müssen Sie nur bestimmte Module importieren:
GoogleCredentials
aus OAuth2discovery
aus Google API-Clientbibliothek für Pythonerrors
aus Google API-Clientbibliothek für Python
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 Prediction 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:
Importieren Sie
googleapiclient.discovery
undgoogleapiclient.errors
.Verwenden Sie das Erkennungsmodul, um eine Python-Repräsentation Ihrer API zu erstellen.
Verwenden Sie die API-Darstellung als eine Reihe verschachtelter Objekte, um die gewünschte API zu ermitteln und eine Anfrage zu erstellen. Beispiel:
request = ml.projects().models().versions().delete( name='projects/myproject/models/mymodel/versions/myversion')
Rufen Sie
request.execute()
auf, um die Anfrage zu senden und Ausnahmen in einer für Ihre Anwendung geeigneten Weise zu verarbeiten.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
- Referenzarchitekturen, Diagramme und Best Practices zu Google Cloud kennenlernen. Weitere Informationen zu Cloud Architecture Center
- Machen Sie sich mit der AI Platform Prediction API vertraut
- Weitere Informationen zum Verwalten von Modellen finden Sie im Überblick über die Modell- und Jobverwaltung.