استخدِم دوال BigQuery عن بُعد لطرح أسئلة على Vertex AI Visual Question Answering (VQA) في طلب بحث SQL

1. مقدمة

نظرة عامة

تتيح لك الوظائف عن بُعد في BigQuery تنفيذ دالة بلغات أخرى غير SQL وJavaScript، أو باستخدام المكتبات والخدمات غير المسموح بها في الدوال التي يحدّدها المستخدم في BigQuery. توفّر الدوالّ البعيدة في BigQuery عملية دمج مباشرة مع وظائف Cloud Run وCloud Run. يمكنك استدعاء دالة عن بُعد في BigQuery ضمن طلب بحث SQL من خلال أخذ عمود واحد أو أكثر كمدخل ثم عرض قيمة واحدة كمخرج.

وظائف Cloud Run هي حلّ حوسبة خفيف الوزن يتيح للمطوّرين إنشاء وظائف مستقلة ذات غرض واحد يمكن تشغيلها باستخدام بروتوكول HTTPS أو الاستجابة CloudEvents بدون الحاجة إلى إدارة خادم أو بيئة وقت التشغيل. تتوافق وظائف Cloud Run مع Node.js وPython وGo وJava وNET. وRuby وPHP.

في هذا الدليل التعليمي حول رموز البرامج، ستتعرّف على كيفية إنشاء دالة عن بُعد في BigQuery للحصول على إجابات عن سؤال حول الصور المخزّنة في Cloud Storage باستخدام ميزة Visual Question Answering (VQA) في Vertex AI. سيسترجع طلب البحث SQL عنوان URL لصورة من جدول في BigQuery. بعد ذلك، باستخدام دالة عن بُعد في BigQuery، سترسل عنوان URL للصورة إلى دالة Cloud Run التي ستردّ عليك بإجابات من VQA حول الصورة.

رسم توضيحي

من منظور التطوير، إليك الخطوات التي ستكملها في هذا الدليل التعليمي حول الرموز البرمجية:

1. إنشاء نقطة نهاية HTTP في دوال التشغيل في السحابة الإلكترونية
2. إنشاء اتصال من النوع CLOUD_ري
3. إنشاء جدول عناصر في BigQuery لحزمة Cloud Storage
4. إنشاء الوظيفة عن بُعد
5. استخدام الوظيفة البعيدة في أي استعلام، تمامًا مثل أي دوال أخرى يحددها المستخدم

ما ستتعرّف عليه

• كيفية إنشاء دالة HTTP Cloud Run في بايثون
• كيفية إنشاء دالة عن بُعد في BigQuery واستخدامها في طلب بحث SQL
• كيفية إنشاء جدول عناصر في BigQuery
• طريقة استخدام Vertex AI SDK for Python لاستخدام ميزة الأسئلة المرئية عن الأسئلة (VQA)

2. الإعداد والمتطلبات

المتطلبات الأساسية

• أن تكون مسجِّلاً الدخول إلى Cloud Console
• سبق لك نشر دالة HTTP Cloud Run. الاطّلاع على دليل البدء السريع في Python
• سبق أن أنشأت حزمة في Cloud Storage. الاطّلاع على دليل البدء السريع لخدمة Cloud Storage
• أن يكون لديك الأدوار المناسبة لإنشاء مجموعة بيانات وجدول ودالة عن بُعد في BigQuery اطّلِع على البدء السريع في تحميل البيانات وإجراء طلبات بحث في BigQuery.

تفعيل Cloud Shell

1. من Cloud Console، انقر على تفعيل Cloud Shell .

إذا كانت هذه هي المرة الأولى التي تبدأ فيها Cloud Shell، ستظهر لك شاشة وسيطة توضّح ماهيتها. إذا ظهرت لك شاشة وسيطة، انقر على متابعة.

من المفترَض أن تستغرق عملية إدارة الحسابات والاتصال بخدمة Cloud Shell بضع دقائق فقط.

تم تحميل هذه الآلة الافتراضية بجميع أدوات التطوير اللازمة. ويقدّم هذا الدليل دليلاً منزليًا دائمًا بسعة 5 غيغابايت ويتم تشغيله في Google Cloud، ما يُحسِّن بشكل كبير أداء الشبكة والمصادقة. يمكن تنفيذ الكثير من عملك في هذا الدليل التعليمي للترميز، إن لم يكن كلّه، باستخدام متصفّح.

بعد الاتصال بـ Cloud Shell، من المفترض أن تظهر لك رسالة تفيد بأنّه تم مصادقة حسابك وأنّه تم ضبط المشروع على معرّف مشروعك.

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، عليك أولاً إنشاء نقطة نهاية HTTP باستخدام دالة Cloud Run. يجب أن تكون نقطة النهاية قادرة على معالجة دفعة من الصفوف في طلب HTTP POST واحد وإرجاع نتائج الدفعة كاستجابة HTTP.

ستتلقّى دالة Cloud Run هذه عنوان URL لتخزين الصور ونص السؤال كمدخلات من طلب SQL، وستُرجع الإجابة من ميزة "الإجابة عن الأسئلة المرئية" (VQA).

يستخدِم هذا الدرس التطبيقي حول الترميز مثالاً على وقت تشغيل python311 باستخدام حزمة تطوير برامج (SDK) Vertex AI لبرنامج Python.

إنشاء رمز المصدر للدالة

أولاً، أنشئ دليلاً وانتقل إليه باستخدام الأمر 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

يمكنك الآن نشر دالة Cloud Run في بيئة تشغيل python311.

لنشر دالة Cloud Run مباشرةً على Cloud Run، نفِّذ الأمر التالي:

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

إذا كنت تفضِّل النشر كجيل ثانٍ من Cloud Functions، استخدِم الأمر التالي:

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

وبعد ذلك يمكنك حفظ عنوان URL للدالة كمتغير بيئة لاستخدامه لاحقًا.

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 Console في Cloud Storage لتحميل الصورة مباشرةً إلى حزمة التخزين. يمكنك أيضًا تنفيذ الأوامر التالية لتنزيل نموذج الصورة إلى دليل 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- إنشاء اتصال بمورد Cloud في 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. استدعاء الدالة البعيدة في BigQuery في طلب بحث SQL

لقد أكملت الآن خطوات التطوير لإنشاء الوظيفة عن بُعد. يمكنك الآن استدعاء دالة Cloud Run من داخل استعلام SQL.

أولاً، احفظ سؤالك وطلب بحث 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 لعرض الردّ من خدمة Visual Question Answering (VQA) في Vertex AI.

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>، حاوِل الانتظار لمدة تتراوح بين دقيقة ودقيقتين حتى يتم نشر إذن دور "مُشغِّل دالة السحابة" إلى حساب خدمة ربط BigQuery قبل إعادة المحاولة.

11. تهانينا!

تهانينا على إكمال دورة codelab.

ننصحك بمراجعة المستندات حول وظائف BigQuery البعيدة وإجابة الأسئلة المرئية (VQA).

المواضيع التي تناولناها

• كيفية ضبط المصادقة في إحدى وظائف Cloud Run والتأكّد من ضبط المصادقة بشكلٍ صحيح
• استدعاء دالة تمّت مصادقتها من بيئة تطوير محلية من خلال تقديم الرمز المميّز لهوية gcloud
• طريقة إنشاء حساب خدمة ومنحه الدور المناسب لاستدعاء وظيفة
• كيفية انتحال هوية خدمة من بيئة تطوير محلية تتضمّن الأدوار المناسبة لتشغيل دالة

12. تَنظيم

لتجنُّب الرسوم غير المقصودة (على سبيل المثال، إذا تمّ استدعاء دالة Cloud Run هذه بدون قصد لعدد مرات يتجاوز المساحة المخصّصة لك شهريًا لاستدعاء دالة Cloud Run في الفئة المجانية)، يمكنك إما حذف دالة Cloud Function أو حذف المشروع الذي أنشأته في الخطوة 2.

لحذف دالة Cloud Run، انتقِل إلى وحدة تحكّم Cloud Run على الرابط https://console.cloud.google.com/functions/ واحذِف دالة imagen-vqa (أو $FUNCTION_NAME في حال استخدام اسم مختلف).

إذا اخترت حذف المشروع بأكمله، يمكنك الانتقال إلى https://console.cloud.google.com/cloud-resource-manager واختيار المشروع الذي أنشأته في الخطوة 2 ثم اختيار "حذف". إذا حذفت المشروع، ستحتاج إلى تغيير المشاريع في حزمة تطوير البرامج (SDK) للسحابة الإلكترونية. يمكنك عرض قائمة بكل المشاريع المتاحة من خلال تشغيل gcloud projects list.