En este instructivo se describe cómo usar la biblioteca cliente de la API de Google para Python con el fin de llamar a las API de REST de AI Platform Training en tus aplicaciones de Python. Los fragmentos de código y los ejemplos en el resto de esta documentación usan esta biblioteca cliente de Python.
En este instructivo, crearás un modelo en el proyecto de Google Cloud. Se trata de una tarea simple que se incluye con facilidad en un ejemplo breve.
Objetivos
Este es un instructivo básico diseñado para que te familiarices con esta biblioteca cliente de Python. Cuando hayas terminado, deberías poder hacer lo siguiente:- Obtener una representación de Python de los servicios de AI Platform Training
- Usar esa representación para crear un modelo en el proyecto, lo que debería ayudarte a comprender cómo llamar a las otras API de administración de trabajos y modelos
Costos
No se te aplicarán cargos por las operaciones en este instructivo. Consulta la página de precios para obtener más información.Antes de comenzar
Configura tu proyecto de GCP
- Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
-
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.
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
-
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
Configura la autenticación
Para configurar la autenticación, debes crear una clave de cuenta de servicio y establecer una variable de entorno para la ruta de acceso del archivo a la clave de la cuenta de servicio.
-
Crear una cuenta de servicio:
-
En la consola de Google Cloud, ve a la página Crear cuenta de servicio.
- Ingresa un nombre en el campo Nombre de cuenta de servicio.
- Opcional: en el campo Descripción de la cuenta de servicio, ingresa una descripción.
- Haz clic en Crear.
- Haz clic en el campo Seleccionar una función. En Todos los roles, selecciona AI Platform > Administrador de AI Platform.
- Haz clic en Agregar otra función.
-
Haz clic en el campo Seleccionar una función. En Todas las funciones, selecciona Storage > Administrador de objeto de Storage.
-
Haz clic en Listo para crear la cuenta de servicio.
No cierres la ventana del navegador. La usarás en la próxima tarea.
-
-
Crea una clave de cuenta de servicio para la autenticación:
- En la consola de Google Cloud, haz clic en la dirección de correo electrónico de la cuenta de servicio que creaste.
- Haga clic en Claves.
- Haz clic en Agregar clave -> Crear nueva clave.
- Haz clic en Crear. Se descargará un archivo de claves JSON en tu computadora.
- Haz clic en Cerrar.
-
Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta de acceso del archivo JSON que contiene la clave de tu cuenta de servicio. Esta variable solo se aplica a tu sesión actual de shell. Por lo tanto, si abres una sesión nueva, deberás volver a configurar la variable.
Configura un entorno de desarrollo de Python
Elige una de las siguientes opciones para configurar tu entorno de manera local en macOS o en un entorno remoto en Cloud Shell.
Si eres usuario de macOS, te recomendamos que configures tu entorno mediante el uso de la pestaña MACOS a continuación. Cloud Shell, que se muestra en la pestaña CLOUD SHELL, está disponible en macOS, Linux y Windows. Cloud Shell proporciona una forma rápida de probar AI Platform Training, pero no es conveniente para el trabajo de desarrollo continuo.
macOS
-
Verifica la instalación de Python
Confirma que tienes Python instalado y, si es necesario, instálalo.python -V
-
Verifica la instalación de
pip
pip
es el administrador de paquetes de Python y se incluye en sus versiones actuales. Para verificar si ya tienespip
instalado, ejecuta el comandopip --version
. De lo contrario, consulta cómo instalarpip
.Puedes actualizar
pip
con el siguiente comando:pip install -U pip
Consulta la documentación de pip para obtener más detalles.
-
Instala
virtualenv
virtualenv
es una herramienta que sirve para crear entornos de Python aislados. Para verificar si ya tienesvirtualenv
instalado, ejecuta el comandovirtualenv --version
. De lo contrario, instalavirtualenv
con el comando siguiente:pip install --user --upgrade virtualenv
Si deseas crear un entorno de desarrollo aislado para esta guía, crea un entorno virtual nuevo en
virtualenv
. Por ejemplo, el siguiente comando activa un entorno llamadoaip-env
:virtualenv aip-env source aip-env/bin/activate
-
A los fines de este instructivo, ejecuta el resto de los comandos dentro de tu entorno virtual.
Obtén más información sobre el uso devirtualenv
. Para salir devirtualenv
, ejecutadeactivate
.
Cloud Shell
-
Abre la consola de Google Cloud.
-
Haz clic en el botón Activar Cloud Shell en la parte superior de la ventana de la consola.
Se abrirá una sesión de Cloud Shell dentro de un marco nuevo en la parte inferior de la consola y, en ella, se mostrará una ventana de la línea de comandos. La sesión de Shell puede tardar unos segundos en inicializar.
Tu sesión de Cloud Shell está lista para usarse.
-
Configura la herramienta de línea de comandos de
gcloud
a fin de usar el proyecto seleccionado.gcloud config set project [selected-project-id]
donde
[selected-project-id]
es el ID del proyecto. (omite los corchetes).
Instala la biblioteca cliente de la API de Google para Python
Instala la biblioteca cliente de la API de Google para Python
- Obtener una representación de Python de los servicios de AI Platform Training
- Usar esa representación para crear un modelo en el proyecto, lo que debería ayudarte a comprender cómo llamar a las otras API de administración de trabajos y modelos
Cómo importar los módulos obligatorios
Si deseas usar la biblioteca cliente de la API de Google para Python con el fin de llamar a las API de REST de AI Platform Training en el código, debes importar su paquete y el de OAuth2. En este instructivo (y en la mayoría de los usos estándares de AI Platform Training), solo tienes que importar módulos específicos:
GoogleCredentials
de OAuth2discovery
de la Biblioteca cliente de la API de Google para Pythonerrors
de la Biblioteca cliente de la API de Google para Python
Consulta la documentación de esos paquetes para obtener información sobre los otros módulos disponibles.
Crea un archivo nuevo de Python con tu editor favorito y agrega estas líneas:
from oauth2client.client import GoogleCredentials from googleapiclient import discovery from googleapiclient import errors
Compila una representación de Python de la API
Obtén la representación de Python de la API de REST. El método al que llamas es build
porque la biblioteca cliente de la API usa el descubrimiento de servicios para configurar conexiones a los servicios de forma dinámica, tal como existen cuando realizas la llamada. Llama al objeto que encapsula los servicios de ml
:
ml = discovery.build('ml','v1')
Configura los parámetros y el cuerpo de la solicitud
Para realizar una llamada a un servicio, debes crear los parámetros y el cuerpo de la solicitud que se enviarán a la API de REST. Los parámetros se pasan al método que representa la llamada como parámetros normales de Python. El cuerpo es un recurso JSON tal y como lo usarías si llamaras directamente a la API con una solicitud HTTP.
Consulta la API de REST para crear un modelo en una pestaña del navegador nueva, projects.models.create:
Presta atención al parámetro de ruta
parent
, que es la parte del URI de la solicitud que identifica el proyecto. Si realizaras la solicitud HTTP POST directamente, usarías el siguiente URI:https://ml.googleapis.com/v1/projects/YOUR_PROJECT_ID/models
Cuando se usa la biblioteca cliente de la API, la parte variable del URI se representa como un parámetro de tipo string para la llamada a la API. Debes configurarlo como
'projects/<var>YOUR_PROJECT_ID</var>'
. Almacena el proyecto en una variable para que las llamadas a la API sean más claras:project_id = 'projects/{}'.format('YOUR_PROJECT_ID')
El cuerpo de la solicitud es un recurso JSON que representa la información del modelo. En la definición del recurso del modelo, puedes ver que tiene dos valores para la entrada: name y description (opcional). Puedes pasar un diccionario de Python en lugar de JSON y la biblioteca cliente de la API realizará la conversión necesaria.
Crea tu diccionario de Python:
request_dict = {'name': 'your-model-name', 'description': 'This is a machine learning model entry.'}
Cómo crear tu solicitud
Hacer llamadas a las API con la biblioteca cliente de Python es un proceso de dos pasos: primero debes crear una solicitud y luego realizar la llamada mediante esa solicitud.
Crea la solicitud
Usa los objetos de cliente integrados que creaste antes (si seguiste el fragmento de código con exactitud, el nombre es ml
) como la raíz de la jerarquía de la API y especifica la API que deseas usar. Cada colección en la ruta de acceso a la API se comporta como una función que muestra una lista de las colecciones y los métodos que contiene. Por ejemplo, la raíz de todas las API de AI Platform Training es projects
, por lo que la llamada comienza con ml.projects()
.
Usa este código para formar la solicitud:
request = ml.projects().models().create(parent=project_id, body=request_dict)
Envía la solicitud
La solicitud que creaste en el último paso expone un método execute
al que debes llamar para enviarle la solicitud al servicio:
response = request.execute()
Es común que los desarrolladores combinen este paso con el último:
response = ml.projects().models().create(parent=project_id, body=request_dict).execute()
Controla errores simples
Muchos aspectos pueden salir mal cuando haces llamadas a la API a través de Internet. Se recomienda controlar los errores simples. La forma más sencilla de abordar los errores consiste en colocar la solicitud en un bloque try
y detectar posibles errores. Es probable que la mayoría de los errores que muestra el servicio sean errores de HTTP, que se encapsulan en la clase HttpError
. Para detectar estos errores, usa el módulo errors
del paquete googleapiclient
.
Une la llamada request.execute()
en un bloque try
. Además, incluye una declaración print
en el bloque, de modo que solo intentes imprimir la respuesta si la llamada se realiza de forma correcta:
try: response = request.execute() print(response)
Agrega un bloque catch para controlar los errores de HTTP. Puedes usar HttpError._get_reason()
para obtener los campos de texto del motivo de la respuesta:
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())
Por supuesto, una declaración de impresión simple podría no ser el enfoque correcto para la aplicación.
Revisión general
Aquí está el ejemplo 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())
Cómo generalizar a otros métodos
Puedes usar el procedimiento que aprendiste aquí para realizar cualquiera de las otras llamadas a la API de REST. Algunas de las API requieren recursos JSON mucho más complicados que los que se requieren para la creación de un modelo, pero los principios son los mismos:
Importa
googleapiclient.discovery
ygoogleapiclient.errors
.Usa el módulo de descubrimiento para compilar una representación de Python de la API.
Usa la representación de la API como una serie de objetos anidados para obtener la API que deseas y crear una solicitud. Por ejemplo:
request = ml.projects().models().versions().delete( name='projects/myproject/models/mymodel/versions/myversion')
Llama a
request.execute()
a fin de enviar la solicitud y controla las excepciones de forma adecuada para la aplicación.Cuando hay un cuerpo de respuesta, puedes tratarlo como un diccionario de Python para acceder a los objetos JSON especificados en la referencia de la API. Ten en cuenta que muchos de los objetos en las respuestas tienen campos que están presentes solo en algunas circunstancias. Siempre debes comprobar para evitar errores clave:
response = request.execute() some_value = response.get('some_key') or 'default_value'
¿Qué sigue?
- Explora arquitecturas de referencia, diagramas y prácticas recomendadas sobre Google Cloud. Consulta nuestro Cloud Architecture Center.
- Familiarízate con la API de AI Platform Training.
- Obtén más información sobre la administración de modelos en la descripción general de administración de modelos y trabajos.