كيفية استخدام وظائف Cloud Run وGemini لتلخيص ملف نصي تم تحميله إلى حزمة على Cloud Storage

1. مقدمة

نظرة عامة

دوالّ Cloud Run هي طريقة جديدة لنشر أعباء العمل باستخدام نماذج أحداث GCF وتوقيع الدالة المألوفين. بدلاً من استخدام عملية الإنشاء وإعدادات النشر التي ننصحك بها، تمنحك دوالّ Cloud Run إمكانية التحكّم مباشرةً في الخدمة الأساسية التي تم إنشاؤها على Cloud Run.

في هذا القسم، ستتعرّف على كيفية تفعيل دالة تعتمد على الأحداث في لغة بايثون تستخدم Gemini لتلخيص ملف نص عادي تم تحميله إلى حزمة على Cloud Storage.

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

  • كيفية نشر دالة Cloud Run مستندة إلى الحدث يتم تشغيلها عند تحميل عنصر إلى حزمة GCS
  • كيفية إنشاء حساب خدمة مع الأدوار المناسبة لاستلام حدث من Cloud Storage واستدعاء دالة Cloud Run
  • كيفية استخدام Gemini لتلخيص مستند نص عادي تم تحميله إلى Cloud Storage

2. إعداد متغيّرات البيئة وتفعيل واجهات برمجة التطبيقات

تعديل واجهة برمجة التطبيقات gcloud CLI

يتطلب هذا الدليل التعليمي للترميز تثبيت إصدار حديث من gcloud CLI. يمكنك تعديل وحدة التحكّم في الخطوط من خلال تشغيل

gcloud components update

تفعيل واجهات برمجة التطبيقات

قبل أن تتمكّن من بدء استخدام هذا الدليل التعليمي للترميز، هناك عدة واجهات برمجة تطبيقات يجب تفعيلها. يتطلّب هذا الدرس التطبيقي استخدام واجهات برمجة التطبيقات التالية. يمكنك تفعيل واجهات برمجة التطبيقات هذه من خلال تنفيذ الأمر التالي:

gcloud services enable run.googleapis.com \
    cloudbuild.googleapis.com \
    storage.googleapis.com \
    artifactregistry.googleapis.com \
    eventarc.googleapis.com \
    aiplatform.googleapis.com

إعداد المتغيّرات البيئية

يمكنك ضبط متغيّرات البيئة التي سيتم استخدامها في هذا المختبر البرمجي.

PROJECT_ID=<YOUR_PROJECT_ID>
REGION=<YOUR_REGION, e.g. us-central1>

gcloud config set project $PROJECT_ID
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
SERVICE_NAME=crf-vertexai-codelab
BUCKET_NAME=$PROJECT_ID-$SERVICE_NAME
TRIGGER_NAME=$SERVICE_NAME-trigger

3- إنشاء حزمة تخزين وحساب خدمة

إنشاء حزمة تخزين

يمكنك إنشاء حزمة في Cloud Storage من خلال تنفيذ الأمر التالي:

gsutil mb -l us-central1 gs://$BUCKET_NAME

إنشاء حساب خدمة

في هذا المثال، ستنشئ حساب خدمة يتضمّن أذونات EventArc المطلوبة ودور "مُشغِّل Cloud Run" لتلقّي حدث من Cloud Storage وتشغيل وظيفة Cloud Run.

أولاً، أنشئ حساب الخدمة.

SERVICE_ACCOUNT="crf-vertexai-codelab"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com

gcloud iam service-accounts create $SERVICE_ACCOUNT \
  --display-name="Cloud Run functions Eventarc service account"

بعد ذلك، امنح دور مستلم الأحداث في Eventarc (roles/eventarc.eventReceiver) في المشروع إلى حساب الخدمة المرتبط بمشغِّل Eventarc حتى يتمكّن المشغّل من تلقّي الأحداث من موفّري الأحداث.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role=roles/eventarc.eventReceiver

بعد ذلك، امنح حساب الخدمة دور "مُشغِّل Cloud Run" حتى يتمكّن من تشغيل الدالة.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role=roles/run.invoker

الآن، عليك منح حساب الخدمة دور "مستخدم منصة الذكاء الاصطناعي" حتى يتمكّن من إجراء مكالمات إلى Gemini.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
    --role="roles/aiplatform.user"

وامنح حساب الخدمة دور "مُشاهد عناصر التخزين" حتى يتمكّن من الوصول إلى الملف.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
    --role="roles/storage.objectViewer"

تحتاج خدمة Cloud Pub/Sub إلى الدور roles/iam.serviceAccountTokenCreator في مشروعك لإنشاء رموز تعريف.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:service-$PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator

يحتاج المشغِّل إلى دور roles/pubsub.publisher الذي تم منحه لحساب خدمة Google Cloud Storage لتلقّي الأحداث عبر Cloud Storage.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:service-$PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com \
  --role=roles/pubsub.publisher

4. إنشاء الدالة ونشرها

أولاً، أنشئ دليلاً لرمز المصدر ثم انتقِل إلى هذا الدليل.

mkdir $SERVICE_NAME && cd $_

بعد ذلك، أنشِئ ملف requirements.txt يتضمّن المحتوى التالي:

functions-framework==3.*
google-cloud-aiplatform==1.63.*
google-cloud-storage==2.16.*

بعد ذلك، أنشِئ ملف main.py يتضمّن المحتوى التالي:

import functions_framework
import vertexai
from vertexai.generative_models import GenerativeModel
from google.cloud import storage

vertexai.init(project="<YOUR_PROJECT_ID>", location="us-central1")

model = GenerativeModel(
    model_name="gemini-1.5-pro-001",
    system_instruction=[
        "Summarize the following document in a single sentence. Do not respond with more than one sentence.",
    ],
)

# Triggered by a change in a storage bucket
@functions_framework.cloud_event
def hello_gcs(cloud_event):
    data = cloud_event.data

    # download the file
    storage_client = storage.Client()
    blob = storage_client.bucket(data["bucket"]).get_blob(data["name"])
    #print(blob)

    doc = blob.download_as_text()
    contents = [doc]

    response = model.generate_content(contents)
    print(response.text)

    print(f"Response from Model: {response.text}")

يمكنك الآن نشر دالة Cloud Run من خلال تنفيذ الأمر التالي:

gcloud beta run deploy $SERVICE_NAME \
      --source . \
      --function hello_gcs \
      --region $REGION \
      --no-allow-unauthenticated \
      --service-account $SERVICE_ACCOUNT_ADDRESS

ملاحظات:

  • تُستخدَم العلامة --source لإخبار Cloud Run بإنشاء الدالة في خدمة مستندة إلى حاوية قابلة للتشغيل.
  • يتم استخدام العلامة --function (جديدة) لضبط نقطة دخول الخدمة الجديدة لتكون توقيع الدالة الذي تريد استدعاؤه.
  • (اختياري) الرمز --no-allow-unauthenticated لمنع إمكانية استدعاء الدالة بشكل علني

قد يُطلب منك "يتطلب النشر من المصدر مستودع Docker في Artifact Registry لتخزين الحاويات التي تم إنشاؤها. سيتم إنشاء مستودع باسم [cloud-run-source-deploy] في المنطقة [<YOUR_REGION>]." اقبل الإعداد التلقائي "نعم" لإنشاء المستودع.

يمكنك الاطّلاع على خدمتك الجديدة "crf-vertexai-codelab" من خلال تنفيذ الأمر التالي:

gcloud beta run services describe $SERVICE_NAME --region $REGION

5- إنشاء الحدث

يمكننا إنشاء عامل تشغيل Eventarc لإرسال رسائل إلى وظيفتنا في كل مرة يتم فيها الانتهاء من معالجة عنصر في Google Cloud Storage:

BUCKET_REGION=$REGION

gcloud eventarc triggers create $TRIGGER_NAME \
     --location=$REGION \
     --destination-run-service=$SERVICE_NAME \
  --destination-run-region=$BUCKET_REGION \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=$BUCKET_NAME" \
     --service-account=$SERVICE_ACCOUNT_ADDRESS

يُرجى ملاحظة أنّه بالنسبة إلى العلامة --event-filters، يجب عدم استخدام البادئة gs:// في اسم الحزمة.

إذا ظهرت لك رسالة خطأ If you recently started to use Eventarc, it may take a few minutes before all necessary permissions are propagated to the Service Agent.، يُرجى الانتظار بضع دقائق قبل إعادة المحاولة.

يمكن العثور على دليل تعليمي مفصّل حول إعداد خدمة Trigger من Cloud Storage باستخدام Eventarc في مستندات Cloud Run على الرابط التالي: https://cloud.google.com/run/docs/tutorials/eventarc.

6- اختبار الدالة

بعد نشر الدالة وإنشاء عامل تشغيل، أصبحنا جاهزين الآن لاستدعاء الدالة.

أنشئ ملفًا وحمِّله إلى حزمة Cloud Storage. يمكنك إجراء ذلك من خلال واجهة الويب في Cloud Console أو باستخدام أداة سطر الأوامر gsutil، على سبيل المثال:

gsutil cp <YOUR_PLAIN_TEXT_FILE> gs://$BUCKET_NAME

عند تحميل الملف بنجاح، سيتم إنشاء حدث وستستدعي وظيفتك Gemini لتلخيص ملف النص العادي. وستتم طباعة الملخص في السجلات.

يمكنك عرض السجلات في Cloud Console لخدمة Cloud Run، أو يمكنك تشغيل الأمر التالي:

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=$SERVICE_NAME AND textPayload: Response"

على سبيل المثال، يؤدي تحميل ملف نص عادي من دليل مستخدم وظائف Cloud Run لمعاينة خاصة إلى ظهور ما يلي مطبوعًا في السجلات:

Response from Model: Cloud Run functions offer a new way to deploy serverless workloads with familiar Google Cloud Functions paradigms while providing control over the underlying Cloud Run service.

7- تهانينا!

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

ننصحك بمراجعة مستندات وظائف Cloud Run.

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

  • كيفية نشر دالة Cloud Run مستندة إلى الأحداث يتم تفعيلها عند تحميل عنصر إلى حزمة GCS
  • كيفية إنشاء حساب خدمة مع الأدوار المناسبة لاستلام حدث من Cloud Storage واستدعاء دالة Cloud Run
  • كيفية استخدام Gemini لتلخيص مستند نصي عادي تم تحميله إلى "مساحة التخزين في السحابة الإلكترونية"

8. تَنظيم

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

لحذف خدمات تشغيل السحابة الإلكترونية، انتقِل إلى Cloud Run Console على الرابط https://console.cloud.google.com/run/ واحذف خدمة crf-vertexai-codelab التي أنشأتها في هذا الدرس التطبيقي حول الترميز.

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