使用 Python 用戶端程式庫

本教學課程說明如何使用 Python 適用的 Google API 用戶端程式庫,在您的 Python 應用程式中呼叫 AI Platform REST API。本說明文件其餘部分的程式碼片段和範例均使用 Python 用戶端程式庫。

在本教學課程,您將在 Google Cloud Platform 專案中建立模型。這是一個小範例就可以輕鬆完成的簡單工作。

目標

這個基本的教學課程旨在協助您熟悉 Python 用戶端程式庫。完成本課程時,您應該能夠:

  • 瞭解 AI Platform 服務的 Python 表示法。
  • 使用該表示法在專案中建立模型,這應該有助於您瞭解如何呼叫其他模型和工作管理 API。

費用

系統不會向您收取本教學課程中的作業費用。詳情請參閱定價頁面

事前準備

設定 GCP 專案

  1. 登入您的 Google 帳戶。

    如果您沒有帳戶,請申請新帳戶

  2. 選取或建立 Google Cloud Platform 專案。

    前往「Manage resources」(管理資源) 頁面

  3. 請確認您已啟用 Google Cloud Platform 專案的計費功能。

    瞭解如何啟用計費功能

  4. 啟用AI Platform ("Cloud Machine Learning Engine") and Compute Engine API。

    啟用 API

  5. 安裝並初始化 Cloud SDK

設定驗證方法

如要設定驗證方法,您必須建立服務帳戶金鑰,並為該服務帳戶金鑰的檔案路徑設定環境變數。

  1. 為驗證方法建立服務帳戶金鑰:
    1. 前往 GCP 主控台的「Create service account key」(建立服務帳戶金鑰) 頁面。

      前往「Create service account key」(建立服務帳戶金鑰) 頁面
    2. 自「Service account」(服務帳戶) 下拉式清單選取 [New service account] (新增服務帳戶)
    3. 在「Service account name」(服務帳戶名稱) 欄位中輸入名稱。
    4. 在「Role」(角色) 下拉式清單中,依序選取 [Machine Learning Engine] > [ML Engine Admin] (ML Engine 管理員),然後再依序選取 [Storage] (儲存空間) > [Storage Object Admin] (儲存空間物件管理員)

      注意:「Role」(角色) 欄位會將資源的存取權限授予服務帳戶。您稍後可以使用 GCP 主控台查看及變更這個欄位。如果您要開發正式版應用程式,除了依序點選 [Machine Learning Engine] > [ML Engine Admin] (ML Engine 管理員) 和 [Storage] (儲存空間) > [Storage Object Admin] (儲存空間物件管理員) 之外,您可能須指定更精細的權限。詳情請參閱 AI Platform 的存取權控管
    5. 按一下 [Create] (建立),隨後一個包含您金鑰的 JSON 檔案就會下載到電腦中。
  2. 將環境變數 GOOGLE_APPLICATION_CREDENTIALS 設為包含服務帳戶金鑰的 JSON 檔案路徑。此變數僅適用於您目前的殼層工作階段,因此如果您開啟新的工作階段,就必須再次設定變數。

設定 Python 開發環境

請選擇下列其中一個選項,在 macOS 的本機或 Cloud Shell 的遠端環境中設定環境。

如果您是 macOS 使用者,建議使用下列「MACOS」分頁設定環境;「CLOUD SHELL」分頁中顯示的 Cloud Shell 適用於 macOS、Linux 及 Windows。雖然 Cloud Shell 讓您能快速試用 AI Platform,但這項做法不適用於後續的開發工作。

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 中建立新的虛擬環境。例如,下列指令會啟動名稱為 cmle-env 的環境:

    virtualenv cmle-env
    source cmle-env/bin/activate
  4. 為達到本教學課程的目的,請在虛擬環境中執行其餘指令。

    請參閱 virtualenv 的使用詳細資訊。如要結束 virtualenv,請執行 deactivate

Cloud Shell

  1. 開啟 Google Cloud Platform 主控台。

    Google Cloud Platform 主控台

  2. 按一下主控台視窗頂端的 [Activate Google Cloud Shell] (啟用 Google Cloud Shell) 按鈕。

    啟用 Google Cloud Shell

    系統會在主控台底部的新頁框開啟 Cloud Shell 工作階段,並顯示指令列提示。殼層工作階段可能需要幾秒鐘的時間才能完成初始化。

    Cloud Shell 工作階段

    Cloud Shell 工作階段已準備就緒。

  3. 設定 gcloud 指令列工具,以使用選取的專案。

    gcloud config set project [selected-project-id]

    其中 [selected-project-id] 是您的專案 ID ((請去掉括號)。

安裝 Google API Python 專用用戶端程式庫

安裝 Python 適用的 Google API 用戶端程式庫

這個基本的教學課程旨在協助您熟悉 Python 用戶端程式庫。完成本課程時,您應該能夠:

  • 瞭解 AI Platform 服務的 Python 表示法。
  • 使用該表示法在專案中建立模型,這應該有助於您瞭解如何呼叫其他模型和工作管理 API。
系統不會向您收取本教學課程中的作業費用。詳情請參閱定價頁面

匯入必要模組

如果您想使用 Python 適用的 Google API 用戶端程式庫呼叫程式碼中的 AI Platform REST API,必須匯入其套件以及 OAuth2 套件。在本教學課程中 (以及在大部分的 AI Platform 標準使用情況下),您只需匯入下列特定模組:

如要瞭解其他可用的模組,請參閱這些套件的說明文件。

使用您偏好的編輯器建立新的 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 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 類別。如要截取這些錯誤,您需要使用 errors 套件中的 googleapiclient 模組。

請在 try 區塊中納入 request.execute() 呼叫,並將 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())

當然,簡單的 print 陳述式可能並不適合您的應用程式。

完整的程式碼範例

以下是完整範例:

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

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
TensorFlow 適用的 AI Platform