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 針對圖片的回答。
插圖
從開發人員的角度來看，您將在本程式碼研究室中完成下列步驟：
- 在 Cloud Run 函式中建立 HTTP 端點
- 建立「CLOUD_RESOURCE」類型的連線
- 為 Cloud Storage bucket 建立 BigQuery 物件資料表
- 建立遠端函式
- 如同任何其他使用者定義函式，在查詢中使用遠端函式
課程內容
- 如何使用 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
- 在 Cloud 控制台中，按一下「啟用 Cloud Shell」 圖示
。
如果這是您首次啟動 Cloud Shell，系統會顯示中介畫面，說明 Cloud Shell 的功能。如果您看到中介畫面，請按一下「繼續」。
佈建並連線至 Cloud Shell 的作業只需幾分鐘的時間。
這個虛擬機器已載入所有必要的開發工具。提供永久的 5 GB 主目錄，而且在 Google Cloud 中運作，大幅提高網路效能和驗證能力。您可以在瀏覽器中完成本程式碼研究室的大部分工作，甚至是全部工作。
連線至 Cloud Shell 後，您應會發現自己通過驗證，且專案已設為您的專案 ID。
- 在 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`
- 在 Cloud Shell 中執行下列指令，確認 gcloud 指令知道您的專案：
gcloud config list project
指令輸出
[core] project = <PROJECT_ID>
如未設定，請輸入下列指令設定專案：
gcloud config set project <PROJECT_ID>
指令輸出
Updated property [core/project].
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
接著上傳圖片供廠商品質稽核員使用。本程式碼研究室使用語音對話式對話說明文件中的示例圖片。
您可以使用 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 Cloud 資源連線
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 來查看所有可用專案的清單。