Usa la biblioteca cliente de Python

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

  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 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.

  1. Crear una cuenta de servicio:

    1. En la consola de Google Cloud, ve a la página Crear cuenta de servicio.

      Ve a Crear cuenta de servicio

    2. Ingresa un nombre en el campo Nombre de cuenta de servicio.
    3. Opcional: en el campo Descripción de la cuenta de servicio, ingresa una descripción.
    4. Haz clic en Crear.
    5. Haz clic en el campo Seleccionar una función. En Todos los roles, selecciona AI Platform > Administrador de AI Platform.
    6. Haz clic en Agregar otra función.

    7. Haz clic en el campo Seleccionar una función. En Todas las funciones, selecciona Storage > Administrador de objeto de Storage.

    8. Haz clic en Listo para crear la cuenta de servicio.

      No cierres la ventana del navegador. La usarás en la próxima tarea.

  2. Crea una clave de cuenta de servicio para la autenticación:

    1. En la consola de Google Cloud, haz clic en la dirección de correo electrónico de la cuenta de servicio que creaste.
    2. Haga clic en Claves.
    3. Haz clic en Agregar clave -> Crear nueva clave.
    4. Haz clic en Crear. Se descargará un archivo de claves JSON en tu computadora.
    5. Haz clic en Cerrar.

  3. 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

  1. Verifica la instalación de Python
    Confirma que tienes Python instalado y, si es necesario, instálalo.

    python -V

  2. 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 tienes pip instalado, ejecuta el comando pip --version. De lo contrario, consulta cómo instalar pip.

    Puedes actualizar pip con el siguiente comando:

    pip install -U pip

    Consulta la documentación de pip para obtener más detalles.

  3. Instala virtualenv
    virtualenv es una herramienta que sirve para crear entornos de Python aislados. Para verificar si ya tienes virtualenv instalado, ejecuta el comando virtualenv --version. De lo contrario, instala virtualenv 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 llamado aip-env:

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

  4. 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 de virtualenv. Para salir de virtualenv, ejecuta deactivate.

Cloud Shell

  1. Abre la consola de Google Cloud.

    La consola de Google Cloud

  2. Haz clic en el botón Activar Cloud Shell en la parte superior de la ventana de la consola.

    Activar Google Cloud Shell

    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.

    Sesión de Cloud Shell

    Tu sesión de Cloud Shell está lista para usarse.

  3. 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

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
No se cobrará por las operaciones de este instructivo. Consulta la página de precios para obtener más información.

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:

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:

  1. Importa googleapiclient.discovery y googleapiclient.errors.

  2. Usa el módulo de descubrimiento para compilar una representación de Python de la API.

  3. 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')

  4. Llama a request.execute() a fin de enviar la solicitud y controla las excepciones de forma adecuada para la aplicación.

  5. 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?