使用 Python 客户端库

本教程介绍如何使用 Python 版 Google API 客户端库，在您的 Python 应用中调用 AI Platform Prediction REST API。本文档其余部分中的代码段和示例使用此 Python 客户端库。

在本教程中，您将在 Google Cloud 项目中创建一个模型。此任务很简单，只需藉由一个小示例即可轻松完成。

目标

这是一个基础教程，旨在让您熟悉此 Python 客户端库。完成本教程后，您应该能够达到以下目标：

  • 获取 AI Platform Prediction 服务的 Python 表示法。
  • 使用该表示法在项目中创建模型，这将有助于您了解如何调用其他模型和作业管理 API。

费用

系统不会针对本教程中的操作向您收费。如需了解详情，请参阅价格页面。

准备工作

设置 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

设置身份验证

要设置身份验证，您需要创建服务账号密钥并为服务账号密钥的文件路径设置环境变量。

  1. 创建服务账号：

    1. 在 Google Cloud 控制台中，转到创建服务账号页面。

      转到“创建服务账号”

    2. 在服务账号名称字段中，输入一个名称。
    3. 可选：在服务账号说明字段中，输入说明。
    4. 点击创建。
    5. 点击选择角色字段。在所有角色下，选择 AI Platform > AI Platform Admin。
    6. 点击添加其他角色。

    7. 点击选择角色字段。在所有角色下，选择存储 > Storage Object Admin。

    8. 点击完成以创建服务账号。

      不要关闭浏览器窗口。您将在下一步骤中用到它。

  2. 创建用于身份验证的服务账号密钥：

    1. 在 Google Cloud 控制台中，点击您创建的服务账号的电子邮件地址。
    2. 点击密钥。
    3. 依次点击添加密钥和创建新密钥。
    4. 点击创建。JSON 密钥文件将下载到您的计算机上。
    5. 点击关闭。

  3. 将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为包含服务账号密钥的 JSON 文件的文件路径。此变量仅适用于当前的 shell 会话，因此，如果您打开新的会话，请重新设置该变量。

设置 Python 开发环境

请在以下选项中选择是在 macOS 本地设置环境，还是在 Cloud Shell 的远程环境中设置环境。

如果您是 macOS 用户，我们建议您按照下面的 MACOS 标签页中的说明设置环境。Cloud Shell 适用于 macOS、Linux 和 Windows 系统，在 CLOUD SHELL 标签页中提供。Cloud Shell 可帮助您快速体验 AI Platform Prediction，但不适用于持续性的开发工作。

macOS

  1. 检查 Python 的安装情况
    确认您是否已安装 Python；如有必要，请安装。

    python -V

  2. 检查 pip 的安装情况
    pip 是 Python 的软件包管理器，包含在当前版本的 Python 中。请运行 pip --version 来检查您是否已安装 pip。如果未安装，请了解如何安装 pip。

    您可以使用以下命令升级 pip：

    pip install -U pip

    如需了解详情，请参阅 pip 文档。

  3. 安装 virtualenv
    virtualenv 是用于创建独立 Python 环境的工具。请运行 virtualenv --version 来检查您是否已安装 virtualenv。如果未安装，请安装 virtualenv：

    pip install --user --upgrade virtualenv

    如需为本指南创建一个独立的开发环境，请在 virtualenv 中新建一个虚拟环境。例如，以下命令会激活名为 aip-env 的环境：

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

  4. 在本教程中，请在虚拟环境中运行其余命令。

    详细了解如何使用 virtualenv。如需退出 virtualenv，请运行 deactivate。

Cloud Shell

  1. 打开 Google Cloud 控制台。

    Google Cloud 控制台

  2. 点击控制台窗口顶部的激活 Google Cloud Shell 按钮。

    激活 Google Cloud Shell

    一个 Cloud Shell 会话随即会在控制台底部的新框内打开，并显示命令行提示符。该 Shell 会话可能需要几秒钟来完成初始化。

    Cloud Shell 会话

    您的 Cloud Shell 会话已就绪，可以使用了。

  3. 配置 gcloud 命令行工具以使用您所选的项目。

    gcloud config set project [selected-project-id]

    其中，[selected-project-id] 是您的项目 ID。（忽略中括号）。

安装 Python 版 Google API 客户端库

安装 Python 版 Google API 客户端库。

这是一个基础教程，旨在让您熟悉此 Python 客户端库。完成本教程后，您应该能够达到以下目标：

  • 获取 AI Platform Prediction 服务的 Python 表示法。
  • 使用该表示法在项目中创建模型，这将有助于您了解如何调用其他模型和作业管理 API。
系统不会针对本教程中的操作向您收费。如需了解详情，请参阅价格页面。

导入必需的模块

如果您想使用 Python 版 Google API 客户端库在您的代码中调用 AI Platform Prediction REST API，则必须导入其软件包和 OAuth2 软件包。在本教程中（以及在 AI Platform Prediction 的大多数标准用途中），您只需要导入以下特定的模块：

请参阅这些软件包的文档，了解其他可用模块。

使用您喜欢的编辑器创建一个新的 Python 文件，并添加以下行：

from oauth2client.client import GoogleCredentials
from googleapiclient import discovery
from googleapiclient import errors

构建 API 的 Python 表示法

获取 REST API 的 Python 代表法。调用 build 方法，以便 API 客户端库使用服务发现功能，对在您发出调用时就已存在的服务动态设置连接。调用用于封装 ml 服务的对象：

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

配置参数和请求正文

如需调用服务，您必须创建要传递给 REST API 的参数和请求正文。请将这些参数作为常规 Python 参数传递给代表此调用的方法。正文是一个 JSON 资源，就像您直接使用 HTTP 请求来调用 API 一样。

在新的浏览器标签页中查看用于创建模型的 REST API (projects.models.create)：

  • 请注意路径参数 parent，该参数包含在用于标识项目的请求 URI 中。如果您直接发出 HTTP POST 请求，请使用以下 URI：

    https://ml.googleapis.com/v1/projects/YOUR_PROJECT_ID/models

    使用 API 客户端库时，URI 的变量部分表示为 API 调用的字符串类型参数。请将其设置为 'projects/<var>YOUR_PROJECT_ID</var>'。将项目存储在变量中，以使 API 调用更清晰：

    project_id = 'projects/{}'.format('YOUR_PROJECT_ID')

  • 请求的正文是表示模型信息的 JSON 资源。在模型资源定义中，您可以看到请求正文包含两个输入值：name 和（可选）description。您可以传递 Python 字典以代替 JSON，这样 API 客户端库就会执行必要的转换。

    创建 Python 字典：

    request_dict = {'name': 'your-model-name',
               'description': 'This is a machine learning model entry.'}

创建请求

使用 Python 客户端库调用 API 包含两个步骤：首先创建一个请求，然后使用该请求进行调用。

创建请求

使用之前创建的客户端对象（如果您完全遵循本文的代码段，该对象为 ml）作为 API 层次结构的根，并指定您要使用的 API。API 路径中每个集合的行为类似于一个会返回该路径中的集合和方法列表的函数。例如，所有 AI Platform Prediction API 的根都是 projects，因此您的调用都会以 ml.projects() 开头。

使用此代码来构建您的请求：

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

发送请求

您在上一步中构建的请求展示了 execute 方法，您可以调用该方法来向服务发送请求：

response = request.execute()

通常，开发者会将此步骤与最后一步合并：

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

处理简单的错误

通过互联网进行 API 调用时，很容易出错。因此，最好是处理常见错误。处理错误的最简单方法是将您的请求放入 try 块中，然后捕获可能的错误。服务可能发生的大部分错误都是 HTTP 错误，这类错误封装在 HttpError 类别中。要捕获这些错误，您应使用 googleapiclient 软件包中的 errors 模块。

请将 request.execute() 调用封装到 try 块中。此外，还请在该块中放置一条 print 语句，这样系统就只会在调用成功时才尝试输出响应：

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

添加一个 catch 块以处理 HTTP 错误。您可以使用 HttpError._get_reason() 从响应中获取原因文本字段：

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())

当然，简单的打印语句可能不适合您的应用。

综合应用

以下是完整的示例：

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())

化用到其他方法

您可以使用在这里学到的方法，进行任何其他 REST API 调用。较之创建模型，有些 API 需要更复杂的 JSON 资源，但原理是相同的：

  1. 导入 googleapiclient.discovery 和 googleapiclient.errors。

  2. 使用发现模块来构建 API 的 Python 表示法。

  3. 将 API 表示法用作一系列嵌套对象，以获取所需的 API 并创建请求。例如：

    request = ml.projects().models().versions().delete(
    name='projects/myproject/models/mymodel/versions/myversion')

  4. 调用 request.execute() 来发送请求，以适合应用的方式处理异常。

  5. 如果有响应正文，您可以将其视为一个 Python 字典，以获取 API 参考中所指定的 JSON 对象。请注意，响应中许多对象具有仅在某些情况下才显示的字段。请务必检查以避免键错误：

    response = request.execute()

some_value = response.get('some_key') or 'default_value'

后续步骤