Usa la biblioteca cliente de Python

En este instructivo, se describe cómo usar la biblioteca cliente de las API de Google para Python con el fin de llamar a las API de REST de AI Platform Training en las aplicaciones de Python. En los fragmentos y ejemplos de código incluidos en el resto de esta documentación, se usa 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 cobrará por las operaciones de este instructivo. Consulta la página de precios para obtener más información.

Antes de comenzar

Configura tu proyecto de GCP

  1. Accede a tu Cuenta de Google.

    Si todavía no tienes una cuenta, regístrate para obtener una nueva.

  2. En la página de selección de proyectos de Cloud Console, selecciona o crea un proyecto de Cloud.

    Ir a la página Selector de proyectos

  3. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud. Obtén información sobre cómo confirmar que tienes habilitada la facturación para tu proyecto.

  4. Habilita las API de AI Platform Training & Prediction and Compute Engine.

    Habilita las API

  5. Instala e inicializa el SDK de Cloud.

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

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

      Nota: En el campo Función, se autoriza el acceso de tu cuenta de servicio a los recursos. Puedes ver y cambiar este campo más adelante con Cloud Console. Si desarrollas una app de producción, es posible que tengas que especificar permisos más detallados que Machine Learning Engine > Administrador de ML Engine y Almacenamiento > Administrador de objeto de almacenamiento. Si deseas obtener más información, consulta el control de acceso para AI Platform Training.
    5. Haz clic en Crear. Se descargará en tu computadora un archivo JSON que contiene tu clave.
  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 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 cmle-env:

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

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

Cloud Shell

  1. Abre Google Cloud Console.

    Google Cloud Console

  2. Haz clic en el botón Activar Google Cloud Shell que se encuentra 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 las API de Google 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 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.

Importa los módulos necesarios

Si deseas usar la biblioteca cliente de las 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'
    

Próximos pasos