使用 BigQuery 遠端函式，在 SQL 查詢中向 Vertex AI 視覺化問題回答 (VQA) 提問

1. 簡介

總覽

BigQuery 遠端函式可讓您使用 SQL 和 JavaScript 以外的語言，或使用 BigQuery 使用者定義函式不允許的程式庫和服務，實作函式。BigQuery 遠端函式提供與 Cloud Run 函式和 Cloud Run 的直接整合。您可以在 SQL 查詢中叫用 BigQuery 遠端函式，方法是將一或多個資料欄做為輸入內容，然後傳回單一值做為輸出內容。

Cloud Run 函式是一個輕量的運算解決方案，可讓開發人員建立獨立的單一用途函式，並透過 HTTPS 觸發這些函式，或回應 CloudEvents，而不必管理伺服器或執行階段環境。Cloud Run 函式支援 Node.js、Python、Go、Java、.NET、Ruby 和 PHP。

在這個程式碼研究室中，您將瞭解如何建立 BigQuery 遠端函式，以便透過 Vertex AI 視覺問答 (VQA) 功能，回答有關 Cloud Storage 中圖片的問題。SQL 查詢會從 BigQuery 資料表擷取圖片的 URI。接著，您會使用 BigQuery 遠端函式，將圖片 URI 傳送至 Cloud Run 函式，該函式會回傳 VQA 針對圖片的回答。

插圖

從開發的角度來看，您將在本程式碼研究室中完成下列步驟：

1. 在 Cloud Run 函式中建立 HTTP 端點
2. 建立 CLOUD_RESOURCE 類型的連線
3. 為 Cloud Storage bucket 建立 BigQuery 物件資料表
4. 建立遠端函式
5. 在查詢中使用遠端函式，就像使用其他使用者定義函式一樣

課程內容

• 如何使用 Python 建立 HTTP Cloud Run 函式
• 如何在 SQL 查詢中建立及使用 BigQuery 遠端函式
• 如何建立 BigQuery 物件資料表
• 如何使用 Python 適用的 Vertex AI SDK 使用視覺問答 (VQA)

2. 設定和需求

必要條件

• 您已登入 Cloud 控制台。
• 您先前已部署 HTTP Cloud Run 函式。查看 Python 快速入門指南。
• 您先前已在 Cloud Storage 中建立值區。參閱 Cloud Storage 快速入門指南。
• 您具備適當的角色，可在 BigQuery 中建立資料集、資料表和遠端函式。請參閱在 BigQuery 中載入及查詢資料的快速入門指南。

啟用 Cloud Shell

1. 在 Cloud 控制台中，按一下「啟用 Cloud Shell」 圖示 。

如果這是您第一次啟動 Cloud Shell，系統會顯示中繼畫面，說明設定程序。如果畫面上顯示中間畫面，請按一下「繼續」。

佈建並連線至 Cloud Shell 的作業只需幾分鐘的時間。

這個虛擬機器已載入所有必要的開發工具。提供永久的 5 GB 主目錄，而且在 Google Cloud 中運作，可大幅提升網路效能和驗證功能。在本程式碼研究室中，您的大部分作業都可透過瀏覽器完成。

連線至 Cloud Shell 後，您應會發現自己通過驗證，且專案已設為您的專案 ID。

2. 在 Cloud Shell 中執行下列指令，確認您已通過驗證：

gcloud auth list

指令輸出

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

注意：gcloud 指令列工具是 Google Cloud 功能強大的整合式指令列工具，已預先安裝於 Cloud Shell 中。您會發現它支援分頁完成功能。第一次執行指令時，系統可能會提示您進行驗證。如需詳細資訊，請參閱 gcloud 指令列工具總覽。

3. 在 Cloud Shell 中執行下列指令，確認 gcloud 指令知道您的專案：

gcloud config list project

指令輸出

[core]
project = <PROJECT_ID>

如果尚未設定，請使用下列指令進行設定：

gcloud config set project <PROJECT_ID>

指令輸出

Updated property [core/project].

注意：如果您是在 Cloud Shell 以外的地方完成本教學課程，請按照「設定應用程式預設憑證」中的步驟操作。

3. 設定本機環境變數

在本程式碼中，您將建立一些環境變數，藉此改善本程式碼研究室中所用 gcloud 指令的可讀性。

PROJECT_ID=$(gcloud config get-value project)

# Cloud Function variables
FUNCTION_NAME="imagen-vqa"
FUNCTION_REGION="us-central1"

# Cloud Function variables
BUCKET_NAME=$PROJECT_ID-imagen-vqa

# BigQuery variables
DATASET_ID="remote_function_codelab"
TABLE_NAME="images"
BQ_REGION="US"
CONNECTION_ID="imagen_vqa_connection"

4. 建立 Cloud Run 函式

如要建立 BigQuery 遠端函式，您必須先使用 Cloud Run 函式建立 HTTP 端點。端點必須能夠在單一 HTTP POST 要求中處理一批資料列，並以 HTTP 回應的形式傳回批次結果。

這個 Cloud Run 函式會接收圖片儲存 URI 和問題提示做為 SQL 查詢的輸入內容，並傳回視覺問題回答 (VQA) 的答案。

本程式碼研究室使用 Python 適用的 Vertex AI SDK 的 python311 執行階段範例。

建立函式原始碼

首先，建立目錄並以 cd 放入該目錄。

mkdir imagen-vqa && cd $_

接著，建立 requirements.txt 檔案。

google-cloud-aiplatform[preview]
google-cloud-storage
functions-framework==3.*

接著，請建立 main.py 來源檔案。

from vertexai.preview.vision_models import ImageQnAModel
from vertexai.preview.vision_models import Image
from flask import jsonify
from google.cloud import storage
from urllib.parse import urlparse
import functions_framework

# This is the entry point for the cloud function
@functions_framework.http
def imagen_vqa(request):
    try:
        # See if you can parse the incoming JSON
        return_value = []
        request_json = request.get_json()
        # This grabs the input into the function as called from the SQL function 
        calls = request_json['calls']
        for call in calls:
            # We call the VQA function here in another function defined below
            ai_result = vqa(call)
            # The result to BigQuery is in the order it was prepared in 
            return_value.append(ai_result[0])
        # Prepare the response back to BigQuery
        return_json = jsonify( { "replies": return_value } )
        return return_json
    except Exception as e:
        return jsonify( { "errorMessage": str(e) } ), 400

# Helper function to split apart the GCS URI 
def decode_gcs_url(url):
    # Read the URI and parse it
    p = urlparse(url)
    bucket = p.netloc
    file_path = p.path[0:].split('/', 1)
    # Return the relevant objects (bucket, path to object)
    return bucket, file_path[1]
    
# We can't use the image load from local file since it expects a local path
# We use a GCS URL and get the bytes of the image 
def read_file(object_path):
    # Parse the path
    bucket, file_path = decode_gcs_url(object_path)
    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket)
    blob = bucket.blob(file_path)
    # Return the object as bytes
    return blob.download_as_bytes()

# This is the function that calls the VQA function
def vqa (parameters):
    # This is the model we want to use
    image_qna_model = ImageQnAModel.from_pretrained("imagetext@001")
    # The location is the first parameter 
    image_loc = parameters[0]
    # Get the bytes 
    image_bytes = read_file(image_loc)
    # Load the bytes into the Image handler
    input_image = Image(image_bytes)
    # Ask the VQA the question
    results = image_qna_model.ask_question(
        image=input_image,
        # The prompt was the second parameter
        question=parameters[1],
        number_of_results=1
    )
    return results

部署 Cloud Run 函式

您現在可以為 python311 執行階段部署 Cloud Run 函式。

如要將 Cloud Run 函式直接部署至 Cloud Run，請執行下列指令：

gcloud beta run deploy $FUNCTION_NAME \
      --source . \
      --function imagen_vqa \
      --region $FUNCTION_REGION \
      --no-allow-unauthenticated

如要部署為 Cloud Functions (第 2 代) 部署，請使用下列指令：

gcloud functions deploy $FUNCTION_NAME \
--gen2 \
--region=$FUNCTION_REGION \
--runtime=python311 \
--trigger-http \
--source=. \
--no-allow-unauthenticated

然後將函式網址儲存為環境變數，以便日後使用。

ENDPOINT_URL="$(gcloud beta run services describe $FUNCTION_NAME --region $FUNCTION_REGION --format='value(status.url)')"

5. 建立 Cloud Storage 值區

首先，建立 Cloud Storage 值區來儲存圖片。

gcloud storage buckets create gs://$BUCKET_NAME

接著，請上傳 VQA 要使用的圖片。本程式碼研究室會使用廠商品質確保說明文件中的範例圖片。

您可以使用 Cloud Storage 的 Cloud 控制台，將圖片直接上傳至值區。或者，您也可以執行下列指令，將範例圖片下載至目前的 Cloud Shell 目錄

wget -O image.jpg -o /dev/null https://unsplash.com/photos/QqN25A3iF9w/download?ixid=M3wxMjA3fDB8MXxhbGx8fHx8fHx8fHwxNjk1NzYxMjY2fA&force=true

然後上傳至 Cloud Storage 值區。

gcloud storage cp image.jpg gs://$BUCKET_NAME

6. 建立 BigQuery 雲端資源連線

BigQuery 會使用 CLOUD_RESOURCE 連線與 Cloud Function 互動。執行下列指令來建立這個連線。

bq mk --connection --location=$BQ_REGION --project_id=$PROJECT_ID \
--connection_type=CLOUD_RESOURCE $CONNECTION_ID

接著，顯示新 BigQuery 連線的詳細資料。

bq show --connection $PROJECT_ID.$BQ_REGION.$CONNECTION_ID

如圖所示，將 BigQuery 連線服務帳戶名稱儲存至變數。

CONNECTION_SA="<YOUR-SERVICE-ACCOUNT-ID>@gcp-sa-bigquery-condel.iam.gserviceaccount.com"

授予服務帳戶存取 Cloud Storage 值區的權限。

gsutil iam ch serviceAccount:$CONNECTION_SA:objectAdmin gs://$BUCKET_NAME

7. 建立 BigQuery 物件資料表

BigQuery 物件資料表是位於 Cloud Storage 中的非結構化資料物件上的唯讀資料表。

物件資料表可讓您分析 Cloud Storage 中的非結構化資料。您可以使用遠端函式分析資料，然後將這些作業的結果與 BigQuery 中的其他結構化資料合併。

首先建立資料集。

bq --location=$BQ_REGION mk \
    --dataset \
    $DATASET_ID

下列指令會根據 Cloud Storage 圖片值區建立物件資料表。產生的資料表會包含該值區中所有圖片的 URI。

bq mk --table \
--external_table_definition=gs://$BUCKET_NAME/*@$BQ_REGION.$CONNECTION_ID \
--object_metadata=SIMPLE \
$PROJECT_ID:$DATASET_ID.$TABLE_NAME

8. 建立 BigQuery 遠端函式

最後一步是設定 BigQuery 遠端函式。

首先，請授予 BigQuery 連線服務帳戶權限，以便叫用 Cloud Run 函式。不建議允許 Cloud Run 函式服務的未經驗證叫用。

gcloud run services add-iam-policy-binding $FUNCTION_NAME \
 --member=serviceAccount:$CONNECTION_SA \
 --role="roles/run.invoker" \
 --region $FUNCTION_REGION

接著，將 SQL 查詢儲存至變數。

SQL_CREATE_FUNCTION="CREATE FUNCTION \`$PROJECT_ID.$DATASET_ID\`.vqa(uri STRING, image_prompt STRING) RETURNS STRING
REMOTE WITH CONNECTION \`$PROJECT_ID.$BQ_REGION.$CONNECTION_ID\`
OPTIONS (
  endpoint = '$ENDPOINT_URL'
)"

接著執行查詢。

bq query --nouse_legacy_sql $SQL_CREATE_FUNCTION

執行查詢建立遠端函式後，您會看到 Created <your-project-id>.remote_function_codelab.vqa

9. 在 SQL 查詢中呼叫 BigQuery 遠端函式

您已完成建立遠端函式的開發步驟。您現在可以從 SQL 查詢中呼叫 Cloud Run 函式。

首先，請將問題和 SQL 查詢儲存至變數。本程式碼研究室使用「Visual Question Answering」說明文件中的範例。這項查詢會使用儲存值區中新增的最新圖片。

export SQL_QUERY="DECLARE question STRING DEFAULT 'What objects are in the image?';
SELECT uri, image_prompt ,\`$DATASET_ID\`.vqa(uri, image_prompt) as result
FROM ( 
  SELECT 
  *, 
  dense_rank() over (order by updated) as rnk ,
  question as image_prompt
  FROM \`$PROJECT_ID.$DATASET_ID.images\`) as innertable
  WHERE rnk  = 1;
"

接著執行 SQL 查詢，顯示 Vertex AI Visual Question Answering (VQA) 服務的回應。

bq query --nouse_legacy_sql $SQL_QUERY

結果應如下列示例輸出內容：

+---------------------------------+--------------------------------+----------+
|               uri               |    image_prompt                |  result  |
+---------------------------------+--------------------------------+----------+
| gs://<YOUR_BUCKET>/image.jpg    | What objects are in the image? |  marbles |
+---------------------------------+--------------------------------+----------+

10. 疑難排解

建立 BigQuery 資料表時，如果收到錯誤 BigQuery error in mk operation: Source URI must be a Google Cloud Storage location: gs://$BUCKET_NAME，請確認您已在指令的 $BUCKET_NAME 後方加入 /* 路徑。

執行 SQL 查詢時，如果收到 Access Denied: BigQuery BigQuery: Received response code 403 from endpoint <your-function-endpoint> 錯誤，請等待約 1 到 2 分鐘，讓 Cloud Function 叫用者角色權限授予作業傳播至 BigQuery 連線服務帳戶，然後再重試。

11. 恭喜！

恭喜您完成程式碼研究室！

建議您查看 BigQuery 遠端函式和視覺問題回答 (VQA) 的說明文件。

涵蓋內容

• 如何設定 Cloud Run 函式的驗證機制，並確認驗證機制已正確設定
• 提供 gcloud 身分的憑證，從本機開發環境叫用已驗證的函式
• 如何建立服務帳戶並授予叫用函式的適當角色
• 如何從具有適當函式叫用角色的本機開發環境，模擬服務

12. 清理

為避免產生意外費用 (舉例來說，如果不小心叫用這個 Cloud Run 函式的次數超出免費方案的每月 Cloud Run 函式叫用分配數量)，您可以刪除 Cloud 函式或刪除步驟 2 中建立的專案。

如要刪除 Cloud Run 函式，請前往 Cloud Run 控制台 (https://console.cloud.google.com/functions/) 並刪除 imagen-vqa 函式 (或 $FUNCTION_NAME，如果您使用的是其他名稱)。

如果您選擇刪除整個專案，可以前往 https://console.cloud.google.com/cloud-resource-manager，選取您在步驟 2 中建立的專案，然後選擇「Delete」(刪除)。如果您刪除專案，就必須在 Cloud SDK 中變更專案。您可以執行 gcloud projects list 來查看可用專案的清單。