Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 ONNX 格式的 PyTorch 模型進行預測

Open Neural Network Exchange (ONNX) 提供統一格式，可表示任何機器學習架構。BigQuery ML 支援 ONNX，可讓您：

使用您偏好的架構訓練模型。
將模型轉換為 ONNX 模型格式。
將 ONNX 模型匯入 BigQuery，並使用 BigQuery ML 進行預測。

本教學課程說明如何將使用 PyTorch 訓練的 ONNX 模型匯入 BigQuery 資料集，並使用這些模型透過 SQL 查詢進行預測。

目標

使用 PyTorch 匯入預先訓練的模型。
使用 torch.onnx 將模型轉換為 ONNX 格式。
使用 CREATE MODEL 陳述式將 ONNX 模型匯入 BigQuery。
使用 ML.PREDICT 函式，透過匯入的 ONNX 模型進行預測。

費用

在本文件中，您將使用下列 Google Cloud計費元件：

您可以使用 Pricing Calculator，根據預測用量估算費用。

初次使用 Google Cloud 的使用者可能符合免費試用期資格。

完成本文所述工作後，您可以刪除建立的資源，避免繼續計費，詳情請參閱「清除所用資源」。

事前準備

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

確認 Google Cloud 專案已啟用計費功能。

啟用 BigQuery、BigQuery Connection 和 Cloud Storage API (如果尚未啟用)。
啟用 API 所需的角色
您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
啟用 API

請確認您具備必要權限，可執行本文件中的工作。

必要的角色

如果您建立新專案，您就是專案擁有者，並會獲得完成本教學課程所需的所有必要 Identity and Access Management (IAM) 權限。

如果您使用的是現有專案，請按照下列步驟操作。

確認您具備下列專案角色：

BigQuery Studio 管理員 (roles/bigquery.studioAdmin)
BigQuery 連線管理員 (roles/bigquery.connectionAdmin)
儲存空間管理員 (roles/storage.admin)

檢查角色

前往 Google Cloud 控制台的「IAM」頁面。
前往「IAM」頁面
選取專案。
在「Principal」(主體) 欄中，找出所有代表您或您所屬群組的資料列。如要瞭解您所屬的群組，請與管理員聯絡。
針對指定或包含您的所有資料列，請查看「Role」(角色) 欄，確認角色清單是否包含必要角色。

授予角色

前往 Google Cloud 控制台的「IAM」頁面。
前往「IAM」頁面
選取專案。
按一下「Grant access」(授予存取權)。
在「New principals」(新增主體) 欄位中，輸入您的使用者 ID。這通常是指 Google 帳戶的電子郵件地址。
按一下「Select a role」(選取角色)，然後搜尋角色。
如要授予其他角色，請按一下「Add another role」(新增其他角色)，然後新增其他角色。
按一下「Save」(儲存)。

如要進一步瞭解 BigQuery 的 IAM 權限，請參閱「IAM 權限」。

選用：訓練模型並轉換為 ONNX 格式

下列程式碼範例說明如何將預先訓練的分類模型匯入 PyTorch，以及如何將產生的模型轉換為 ONNX 格式。本教學課程使用預先建構的範例模型，儲存在 gs://cloud-samples-data/bigquery/ml/onnx/resnet18.onnx。如果您使用的是範例模型，則不必完成這些步驟。

建立 PyTorch Vision 模型來分類圖片

請使用下列程式碼範例，匯入 PyTorch 預先訓練的 resnet18 模型，該模型可接受 BigQuery ML ML.DECODE_IMAGE 和 ML.RESIZE_IMAGE 函式傳回的解碼圖片資料。

import torch
import torch.nn as nn

# Define model input format to match the output format of
# ML.DECODE_IMAGE function: [height, width, channels]
dummy_input = torch.randn(1, 224, 224, 3, device="cpu")

# Load a pretrained pytorch model for image classification
model = torch.hub.load('pytorch/vision:v0.10.0', 'resnet18', pretrained=True)

# Reshape input format from [batch_size, height, width, channels]
# to [batch_size, channels, height, width]
class ReshapeLayer(nn.Module):
    def __init__(self):
        super().__init__()

    def forward(self, x):
        x = x.permute(0, 3, 1, 2)  # reorder dimensions
        return x

class ArgMaxLayer(nn.Module):
    def __init__(self):
        super().__init__()

    def forward(self, x):
       return torch.argmax(x, dim=1)

final_model = nn.Sequential(
    ReshapeLayer(),
    model,
    nn.Softmax(),
    ArgMaxLayer()
)

將模型轉換為 ONNX 格式

請參考下列範例，使用 torch.onnx 匯出 PyTorch 視覺模型。匯出的 ONNX 檔案名稱為 resnet18.onnx。

torch.onnx.export(final_model,            # model being run
                  dummy_input,            # model input
                  "resnet18.onnx",        # where to save the model
                  opset_version=10,       # the ONNX version to export the model to
                  input_names = ['input'],         # the model's input names
                  output_names = ['class_label'])  # the model's output names

將 ONNX 模型上傳至 Cloud Storage

儲存模型後，請按照下列步驟操作：

建立 Cloud Storage bucket 來儲存模型。
將 ONNX 模型上傳至 Cloud Storage bucket。

建立資料集

如要建立 BigQuery 資料集，請選取下列其中一個選項：

控制台

前往 Google Cloud 控制台的「BigQuery」頁面。

前往「BigQuery」
點選左側窗格中的「Explorer」。

如果沒有看到左側窗格，請按一下「Expand left pane」(展開左側窗格)，開啟窗格。
在「Explorer」中展開專案，然後按一下「資料集」。
在「Datasets」(資料集) 頁面，按一下「Create dataset」(建立資料集)。
在「建立資料集」窗格中，執行下列操作：
- 在「Dataset ID」(資料集 ID) 中輸入 bqml_tutorial。
- 在「資料位置」部分，選取「US」。
其餘預設設定則保持不變。
點選「建立資料集」。

bq

如要建立新的資料集，請使用 bq mk --dataset 指令。

建立名為 bqml_tutorial 的資料集，並將資料位置設為 US：

bq mk --dataset \
  --location=US \
  --description "BigQuery ML tutorial dataset." \
  bqml_tutorial

確認資料集已建立：
```
bq ls
```

API

使用定義的資料集資源呼叫 datasets.insert 方法：

{
  "datasetReference": {
     "datasetId": "bqml_tutorial"
  }
}

將 ONNX 模型匯入 BigQuery

下列步驟說明如何使用 CREATE MODEL 陳述式，將 Cloud Storage 中的範例 ONNX 模型匯入資料集。

控制台

前往 Google Cloud 控制台的「BigQuery Studio」頁面。

前往 BigQuery Studio
在查詢編輯器中，輸入下列 CREATE MODEL 陳述式。
```
CREATE OR REPLACE MODEL `bqml_tutorial.imported_onnx_model`
 OPTIONS (MODEL_TYPE='ONNX',
  MODEL_PATH='BUCKET_PATH')
```
將 BUCKET_PATH 替換為您上傳至 Cloud Storage 的模型路徑。如果您使用範例模型，請將 BUCKET_PATH 替換為下列值：gs://cloud-samples-data/bigquery/ml/onnx/resnet18.onnx。

作業完成後，您會看到類似以下的訊息：Successfully created model named imported_onnx_model。

新模型會顯示在「Resources」(資源) 面板中。模型會以模型圖示表示：。如果您在「Resources」(資源) 面板中選取新模型，模型相關資訊會顯示在「Query editor」(查詢編輯器) 旁邊。

bq

輸入下列 CREATE MODEL 陳述式，從 Cloud Storage 匯入 ONNX 模型。
```
bq query --use_legacy_sql=false \
"CREATE OR REPLACE MODEL
  `bqml_tutorial.imported_onnx_model`
OPTIONS
  (MODEL_TYPE='ONNX',
   MODEL_PATH='BUCKET_PATH')"
```
將 BUCKET_PATH 替換為您上傳至 Cloud Storage 的模型路徑。如果您使用範例模型，請將 BUCKET_PATH 替換為以下值：gs://cloud-samples-data/bigquery/ml/onnx/resnet18.onnx。

匯入模型後，請確認模型顯示在資料集中。

bq ls -m bqml_tutorial

輸出結果會與下列內容相似：

tableId               Type
--------------------- -------
imported_onnx_model  MODEL

如要進一步瞭解如何將 ONNX 模型匯入 BigQuery，包括格式和儲存空間需求，請參閱「用於匯入 ONNX 模型的 CREATE MODEL 陳述式」。

在 BigQuery 建立物件資料表，分析圖片資料

物件資料表是唯讀資料表，用於儲存 Cloud Storage 中的非結構化資料物件。物件資料表可讓您透過 BigQuery 分析非結構化資料。

在本教學課程中，您將使用 ML.PREDICT 函式，輸出儲存在 Cloud Storage bucket 中的輸入圖片預測類別標籤。

建立物件資料表時，您必須執行下列操作：

建立 Cloud Storage bucket，並上傳金魚圖片。
建立 Cloud 資源連結，用於存取物件資料表。
將存取權授予資源連線的服務帳戶。

建立 bucket 並上傳圖片

請按照下列步驟建立 Cloud Storage bucket，並上傳金魚圖片。

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
點選「Create」(建立)。
在「Create a bucket」(建立 bucket) 頁面中，輸入 bucket 資訊。
1. 在「Get started」(開始使用) 部分，執行下列操作：
  1. 在方塊中輸入 bqml_images。
  2. 按一下「繼續」。
2. 在「Choose where to store your data」(選擇資料的儲存位置) 部分，執行下列操作：
  1. 在「位置類型」部分，選取「多區域」。
  2. 在位置類型的選單中，選取「US (multiple regions in United States)」(美國 (多個美國區域))。
  3. 按一下「繼續」。
3. 在「Choose a storage class for your data」(為資料選擇儲存空間級別) 部分：
  1. 選取「設定預設級別」。
  2. 選取「標準」。
  3. 按一下「繼續」。
4. 其餘部分則保留預設值。
點選「建立」。

指令列

輸入下列 gcloud storage buckets create 指令：

gcloud storage buckets create gs://bqml_images --location=us

如果要求成功，指令會傳回下列訊息：

Creating gs://bqml_images/...

將圖片上傳至 Cloud Storage bucket

建立 bucket 後，請下載金魚圖片，並上傳至 Cloud Storage bucket。

請按照下列步驟上傳圖片：

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點按「bqml_images」。
在 bucket 的「Objects」(物件) 分頁中，執行下列任一操作：
- 將檔案從桌面或檔案管理工具拖曳到 Google Cloud 控制台的主窗格。
- 依序點選「上傳」>「上傳檔案」，在顯示的對話方塊中選取要上傳的圖片檔，然後點選「開啟」。

指令列

輸入下列 gcloud storage cp 指令：

gcloud storage cp OBJECT_LOCATION gs://bqml_images/IMAGE_NAME

更改下列內容：

OBJECT_LOCATION：圖片檔的本機路徑。例如：Desktop/goldfish.jpg。
IMAGE_NAME：映文件名稱。例如：goldfish.jpg。

如果成功，回應會與下列內容相似：

Completed files 1/1 | 164.3kiB/164.3kiB

建立 BigQuery Cloud 資源連結

您必須建立 Cloud 資源連結，才能連結至本教學課程稍後建立的物件資料表。

您可以透過 Cloud 資源連結，查詢儲存在 BigQuery 外部的資料，例如 Cloud Storage 或 Spanner 等 Google Cloud 服務，或 AWS 或 Azure 等第三方來源。這些外部連結會使用 BigQuery Connection API。

請按照下列步驟建立 Cloud 資源連結。

控制台

前往「BigQuery Studio」頁面。

前往 BigQuery Studio
在左側窗格中，點選「資料庫」「資料探索工具」：

如果沒有看到左側窗格，請按一下「Expand left pane」(展開左側窗格)，開啟窗格。
在「資料」窗格中，點選「新增資料」圖示。

「新增資料」對話方塊隨即開啟。
在「篩選依據」窗格的「資料來源類型」部分，選取「資料庫」。

或者，您也可以在「Search for data sources」(搜尋資料來源) 欄位中輸入 Vertex AI。
在「精選資料來源」部分，點選「Vertex AI」。
點選「Vertex AI Models: BigQuery Federation」解決方案資訊卡。
在「連線類型」清單中，選取「Vertex AI 遠端模型、遠端函式和 BigLake (Cloud 資源)」。
在「連線 ID」欄位輸入 bqml_tutorial。
確認已選取「多區域 - 美國」。
點選「建立連線」。
按一下視窗底部的「前往連線」。或者，在「Explorer」窗格中，依序點選「Connections」(連線) 和「us.bqml_tutorial」。
在「連線資訊」窗格，複製服務帳戶 ID，設定連線權限時，會需要這個 ID。建立連線資源時，BigQuery 會建立專屬的系統服務帳戶，並與連線建立關聯。

bq

建立連線：
```
bq mk --connection --location=US --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE bqml_tutorial
```
將 PROJECT_ID 替換為Google Cloud 專案 ID。--project_id 參數會覆寫預設專案。

建立連線資源時，BigQuery 會建立專屬的系統服務帳戶，並與連線建立關聯。

疑難排解：如果收到下列連線錯誤訊息，請更新 Google Cloud SDK：
```
Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
```

擷取並複製服務帳戶 ID，以便在後續步驟中使用：

bq show --connection PROJECT_ID.us.bqml_tutorial

輸出結果會與下列內容相似：

name                          properties
1234.REGION.CONNECTION_ID {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

設定連線存取權

將 Storage 物件管理員角色授予 Cloud 資源連結的服務帳戶。您必須在上傳圖片檔的專案中授予這個角色。

如要授予角色，請按照下列步驟操作：

前往「IAM & Admin」(IAM 與管理) 頁面。

前往「IAM & Admin」(IAM 與管理) 頁面
點選「授予存取權」。
在「New principals」(新增主體) 欄位中，輸入先前複製的 Cloud 資源連結服務帳戶 ID。
在「Select a role」(請選擇角色) 欄位中，依序選取「Cloud Storage」和「Storage object admin」(Storage 物件管理員)。
按一下「儲存」。

建立物件資料表

請按照下列步驟，使用上傳至 Cloud Storage 的金魚圖片，建立名為 goldfish_image_table 的物件資料表。

控制台

前往「BigQuery Studio」頁面。

前往 BigQuery Studio

在查詢編輯器中輸入這項查詢，建立物件資料表。

CREATE EXTERNAL TABLE `bqml_tutorial.goldfish_image_table`
WITH CONNECTION `us.bqml_tutorial`
OPTIONS(
object_metadata = 'SIMPLE',
uris = ['gs://bqml_images/IMAGE_NAME'],
max_staleness = INTERVAL 1 DAY,
metadata_cache_mode = 'AUTOMATIC');

將 IMAGE_NAME 替換成圖片檔名稱，例如 goldfish.jpg。

作業完成後，您會看到類似 This statement created a new table named goldfish_image_table 的訊息。

bq

輸入下列 CREATE EXTERNAL TABLE 陳述式，建立物件資料表。

bq query --use_legacy_sql=false \
"CREATE EXTERNAL TABLE `bqml_tutorial.goldfish_image_table`
WITH CONNECTION `us.bqml_tutorial`
OPTIONS(
object_metadata = 'SIMPLE',
uris = ['gs://bqml_images/IMAGE_NAME'],
max_staleness = INTERVAL 1 DAY,
metadata_cache_mode = 'AUTOMATIC')"

將 IMAGE_NAME 替換成圖片檔名稱，例如 goldfish.jpg。

建立物件資料表後，請確認該資料表是否顯示在資料集中。

bq ls bqml_tutorial

輸出結果會與下列內容相似：

tableId               Type
--------------------- --------
goldfish_image_table  EXTERNAL

詳情請參閱「建立物件資料表」。

使用匯入的 ONNX 模型進行預測

重要事項：您必須具備預留項目，才能使用匯入的模型和物件資料表執行預測。詳情請參閱匯入 ONNX 模型的限制。

如果沒有預留項目，使用 ML.PREDICT 執行查詢會產生以下錯誤：

BigQuery ML inference using imported models and
  object tables requires a reservation, but no reservations were assigned for
  job type `QUERY`...`

。

您將使用下列包含 ML.PREDICT 函式的查詢，根據輸入物件資料表 goldfish_image_table 中的圖片資料進行預測。這項查詢會根據 ImageNet 標籤字典，輸出輸入圖片的預測類別標籤。

在查詢中，必須使用 ML.DECODE_IMAGE 函式解碼圖片資料，ML.PREDICT 才能解讀。系統會呼叫 ML.RESIZE_IMAGE 函式，將圖片大小調整為符合模型輸入大小 (224*224)。

如要進一步瞭解如何對圖片物件資料表執行推論，請參閱「對圖片物件資料表執行推論」。

如要根據圖片資料進行預測，請按照下列步驟操作。

控制台

前往「BigQuery Studio」頁面。

前往 BigQuery Studio

在查詢編輯器中，輸入下列 ML.PREDICT 查詢。

 SELECT
   class_label
 FROM
   ML.PREDICT(MODEL bqml_tutorial.imported_onnx_model,
     (
     SELECT
       ML.RESIZE_IMAGE(ML.DECODE_IMAGE(DATA),
         224,
         224,
         FALSE) AS input
     FROM
       bqml_tutorial.goldfish_image_table))

查詢結果大致如下：

ML.PREDICT 查詢結果

bq

輸入下列 bq query 指令：

bq query --use_legacy_sql=false \
'SELECT
  class_label
FROM
  ML.PREDICT(MODEL `bqml_tutorial.imported_onnx_model`,
    (
    SELECT
      ML.RESIZE_IMAGE(ML.DECODE_IMAGE(DATA),
        224,
        224,
        FALSE) AS input
    FROM
      bqml_tutorial.goldfish_image_table))'

清除所用資源

為避免因為本教學課程所用資源，導致系統向 Google Cloud 收取費用，請刪除含有相關資源的專案，或者保留專案但刪除個別資源。

刪除專案

控制台

前往 Google Cloud 控制台的「Manage resources」(管理資源) 頁面。
前往「Manage resources」(管理資源)
在專案清單中選取要刪除的專案，然後點選「Delete」(刪除)。
在對話方塊中輸入專案 ID，然後按一下 [Shut down] (關閉) 以刪除專案。

gcloud

刪除 Google Cloud 專案：

gcloud projects delete PROJECT_ID

刪除個別資源

或者，如要移除本教學課程中使用的個別資源，請按照下列步驟操作：

後續步驟

如要進一步瞭解如何匯入 ONNX 模型，請參閱「ONNX 模型的 CREATE MODEL 陳述式」。
如要進一步瞭解可用的 ONNX 轉換器和教學課程，請參閱「轉換為 ONNX 格式」。
如需 BigQuery ML 的總覽，請參閱 BigQuery ML 簡介。
如要開始使用 BigQuery ML，請參閱「在 BigQuery ML 中建立機器學習模型」。

使用 ONNX 格式的 PyTorch 模型進行預測 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

目標

費用

事前準備

必要的角色

檢查角色

授予角色

選用：訓練模型並轉換為 ONNX 格式

建立 PyTorch Vision 模型來分類圖片

將模型轉換為 ONNX 格式

將 ONNX 模型上傳至 Cloud Storage

建立資料集

控制台

bq

API

將 ONNX 模型匯入 BigQuery

控制台

bq

在 BigQuery 建立物件資料表，分析圖片資料

建立 bucket 並上傳圖片

控制台

指令列

將圖片上傳至 Cloud Storage bucket

控制台

指令列

建立 BigQuery Cloud 資源連結

控制台

bq

設定連線存取權

建立物件資料表

控制台

bq

使用匯入的 ONNX 模型進行預測

控制台

bq

清除所用資源

刪除專案

控制台

gcloud

刪除個別資源

後續步驟

使用 ONNX 格式的 PyTorch 模型進行預測