Usa la biblioteca cliente de Python

En este instructivo, se describe cómo usar la biblioteca cliente de las API de Google para Python a fin de llamar a las API de REST de Cloud Machine Learning Engine en tus aplicaciones. 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 tu proyecto de Google Cloud Platform. Se trata de una tarea simple que se incluye fácilmente en un pequeño ejemplo.

Objetivos

Este es un instructivo básico diseñado para que te familiarices con esta biblioteca cliente de Python. Cuando lo finalices, deberías poder hacer lo siguiente:

  • Obtén una representación de Python de los servicios de Cloud ML Engine.
  • Usa esa representación para crear un modelo en tu 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 Account.

    If you don't already have one, sign up for a new account.

  2. Select or create a Google Cloud Platform project.

    Go to the Manage resources page

  3. Asegúrate de tener habilitada la facturación para tu proyecto.

    Aprende a habilitar la facturación

  4. Habilita las Cloud Machine Learning Engine y Compute Engine API necesarias.

    Habilita las API

  5. Install and initialize the Cloud SDK.

Configura la autenticación

A fin de 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. Crea una clave de cuenta de servicio para la autenticación:
    1. En GCP Console, ve a la página Crear clave de la cuenta de servicio.

      Ir a la página Crear clave de la cuenta de servicio
    2. En la lista desplegable de Cuenta de servicio, selecciona Cuenta de servicio nueva.
    3. En el campo Nombre de la cuenta de servicio, ingresa un nombre.
    4. En la lista desplegable de Función, selecciona Machine Learning Engine > Administrador y Almacenamiento de ML Engine > Administrador de objeto de almacenamiento.

      Nota: Con el campo Función, se autoriza el acceso de tu cuenta de servicio a los recursos. Puedes ver y cambiar este campo más tarde con GCP Console. Si desarrollas una app de producción, es posible que debas especificar permisos más detallados que en Machine Learning Engine > Administrador y Almacenamiento de ML Engine > Administrador del objeto de almacenamiento. A fin de obtener más información, consulta Control de acceso para Cloud ML Engine.
    5. Haz clic en Crear. Se descargará un archivo JSON a tu computadora que contiene tus descargas de claves.
  2. 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 Python

Elige una de las siguientes opciones para configurar tu entorno de forma local en macOS o en un entorno remoto en Cloud Shell.

Para los usuarios de macOS, se recomienda configurar su entorno con 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 Cloud Machine Learning Engine, pero no es adecuada para el trabajo de desarrollo continuo.

macOS

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

    python -V
  2. Comprueba la instalación de pip.
    pip es el administrador de paquetes de Python, incluido con las versiones actuales de Python. Comprueba si ya está instalado pip cuando ejecutes 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 para crear entornos aislados de Python. Comprueba si ya está instalado virtualenv cuando ejecutes virtualenv --version. De lo contrario, instala virtualenv:

    pip install --user --upgrade virtualenv

    Para crear un entorno de desarrollo aislado en esta guía, crea un entorno virtual nuevo en virtualenv. Por ejemplo, el siguiente comando activa un entorno llamado cmle-env:

    virtualenv cmle-env
    source cmle-env/bin/activate
  4. A los fines de este instructivo, ejecuta el resto de los comandos dentro de tu entorno virtual.

    Consulta más información sobre el uso de virtualenv. Para salir de virtualenv, ejecuta deactivate.

Cloud Shell

  1. Abre Google Cloud Platform Console.

    Google Cloud Platform Console

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

    Activa Google Cloud Shell

    Se abrirá una sesión de Cloud Shell dentro de un marco nuevo en la parte inferior de la consola y se mostrará un mensaje de línea de comandos. Es posible que esta sesión tarde unos segundos en inicializarse.

    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 para usar tu proyecto seleccionado.

    gcloud config set project [selected-project-id]

    en el que [selected-project-id] es tu ID del proyecto. (Omite los corchetes de cierre).

Instala la biblioteca cliente de Google Cloud para Python

Instala la biblioteca cliente de las API de Google para Python.

Este es un instructivo básico diseñado para que te familiarices con esta biblioteca cliente de Python. Cuando lo finalices, deberías poder hacer lo siguiente:

  • Obtén una representación de Python de los servicios de Cloud ML Engine.
  • Usa esa representación para crear un modelo en tu proyecto, lo que debería ayudarte a comprender cómo llamar a las otras API de administración de trabajos y modelos.
No se te aplicarán cargos por las operaciones en este instructivo. Consulta la página de precios para obtener más información.

Importa los módulos requeridos.

Cuando desees usar la biblioteca cliente de las API de Google para Python a fin de llamar a las API de REST de Cloud ML Engine en tu código, debes importar tu paquete y el paquete OAuth2. Para este instructivo (y en la mayoría de los usos estándar de Cloud ML Engine) solo necesitas importar módulos específicos:

Consulta la documentación de esos paquetes para obtener información sobre los otros módulos disponibles.

Crea un nuevo archivo 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 Python de la API

Obtén tu representación en 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 dinámicamente las conexiones a los servicios tal y como existen cuando realizas la llamada. Llama a tu objeto que encapsula los servicios ml:

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

Configura tus parámetros y cuerpo de solicitud

Para realizar una llamada a un servicio, debes crear los parámetros y el cuerpo de la solicitud que se pasará a la API de REST. Pasa los parámetros como parámetros regulares de Python al método que representa la llamada. 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 nueva del navegador, projects.models.create:

  • Observa la ruta de acceso al parámetro parent, que es la parte del URI de la solicitud que identifica el proyecto. Si estuvieras haciendo 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. Lo establecerás en 'projects/<var>your_project_ID</var>'. Almacena tu proyecto en una variable para hacer que las llamadas a la API sean más limpias:

    project_id = 'projects/{}'.format('your_project_ID')
    
  • El cuerpo de la solicitud es un recurso JSON que representa la información del modelo. Puedes ver en la definición de recurso del modelo que tiene dos valores para la entrada: nombre y descripción (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.'}
    

Crea tu solicitud

Hacer llamadas a las API con la biblioteca cliente de Python tiene dos pasos: Primero crea una solicitud, luego realiza la llamada con esa solicitud.

Crea la solicitud

Usa los objetos de cliente compilados que creaste anteriormente (si seguiste exactamente el fragmento de código, se llama 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 Cloud ML Engine es projects, por lo que tu llamada comienza con ml.projects().

Usa este código para formar tu solicitud:

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

Envía la solicitud

La solicitud que construiste en el último paso expone un método de execute que llamas para enviar 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. Es una buena idea controlar los errores comunes. La forma más sencilla de lidiar con ellos es poner tu solicitud en un bloque de try y detectar posibles errores. La mayoría de estos, que probablemente recibas del servicio, son errores HTTP que se encapsulan en la clase HttpError. Para detectarlos, usa el módulo de errors del paquete googleapiclient.

Une tu llamada request.execute() en un bloque try. También pon una declaración print en el bloque, de modo que intentes imprimir la respuesta solo si la llamada se realiza correctamente:

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

Agrega un bloque de detección para controlar los errores HTTP. Puedes usar HttpError._get_reason() para obtener los campos de texto de la razón 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 simple declaración impresa podría no ser el enfoque correcto para tu aplicación.

Revisión general

A continuación, se muestra 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())

Generaliza 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 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 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() para enviar la solicitud, controla las excepciones de manera adecuada en tu aplicación.

  5. Cuando hay un cuerpo de respuesta, puedes tratarlo como un diccionario de Python para obtener 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?

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

Cloud ML Engine para TensorFlow