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

1. مقدمة

نظرة عامة

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

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

ما ستتعلمه

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

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

تعديل gcloud CLI

يتطلّب هذا الدرس التطبيقي إصدارًا حديثًا من "واجهة سطر الأوامر في gcloud" مثبَّتًا. يمكنك تعديل واجهة سطر الأوامر من خلال تنفيذ

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- إنشاء حزمة Storage وحساب خدمة

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

يمكنك إنشاء حزمة 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

الآن، امنح حساب الخدمة دور مستخدم AI Platform ليتمكّن من إجراء طلبات إلى 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 لمنع استدعاء الدالة بشكل علني

قد يُطلب منك "يتطلّب النشر من المصدر مستودع Artifact Registry Docker لتخزين الحاويات التي تم إنشاؤها. سيتم إنشاء مستودع باسم [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. تهانينا!

تهانينا على إكمال هذا الدرس العملي.

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

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

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

8. تَنظيم

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

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

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