نحوه استفاده از توابع Cloud Run و Gemini برای خلاصه کردن یک فایل متنی آپلود شده در یک سطل فضای ذخیره سازی ابری

۱. مقدمه

نمای کلی

توابع Cloud Run روشی جدید برای استقرار بارهای کاری با استفاده از الگوهای رویدادگذاری GCF و امضای تابع است. به جای استفاده از فرآیند ساخت و پیکربندی‌های استقرار دلخواه ما، توابع Cloud Run به شما امکان کنترل مستقیم بر سرویس زیربنایی ایجاد شده در Cloud Run را می‌دهد.

در این بخش، یاد خواهید گرفت که چگونه یک تابع رویدادمحور را در پایتون مستقر کنید که از Gemini برای خلاصه کردن یک فایل متنی ساده آپلود شده در یک مخزن ذخیره‌سازی ابری استفاده می‌کند.

آنچه یاد خواهید گرفت

  • نحوه‌ی پیاده‌سازی یک تابع Cloud Run مبتنی بر رویداد که هر زمان یک شیء در یک سطل GCS آپلود می‌شود، فعال می‌شود
  • نحوه ایجاد یک حساب کاربری سرویس با نقش‌های مناسب برای دریافت رویداد از Cloud Storage و فراخوانی تابع Cloud Run
  • نحوه استفاده از Gemini برای خلاصه کردن یک سند متنی ساده آپلود شده در فضای ابری

۲. متغیرهای محیطی را تنظیم کنید و APIها را فعال کنید

به‌روزرسانی رابط خط فرمان gcloud

این آزمایشگاه کد به نصب آخرین نسخه رابط خط فرمان gcloud نیاز دارد. می‌توانید با اجرای دستور زیر، رابط خط فرمان را به‌روزرسانی کنید:

gcloud components update

فعال کردن APIها

قبل از اینکه بتوانید از این codelab استفاده کنید، باید چندین API را فعال کنید. این codelab به استفاده از APIهای زیر نیاز دارد. می‌توانید با اجرای دستور زیر این APIها را فعال کنید:

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

۳. یک Storage Bucket و یک Service Account ایجاد کنید

یک سطل ذخیره‌سازی ایجاد کنید

با اجرای دستور زیر می‌توانید یک فضای ذخیره‌سازی ابری ایجاد کنید:

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 Event Receiver (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 User) را اعطا کنید تا بتواند با Gemini تماس برقرار کند.

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

و به حساب سرویس، نقش Storage Object Viewer را اعطا کنید تا بتواند به فایل دسترسی داشته باشد.

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 اعطا شده به حساب سرویس فضای ابری گوگل نیاز دارد. 

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

۴. تابع را ایجاد و مستقر کنید

ابتدا، یک دایرکتوری برای کد منبع ایجاد کنید و با دستور cd به آن دایرکتوری بروید. 

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 (new) برای تنظیم نقطه ورودی سرویس جدید به عنوان امضای تابعی که می‌خواهید فراخوانی شود، استفاده می‌شود.
  • (اختیاری) گزینه‌ی --no-allow-unauthenticated برای جلوگیری از فراخوانی عمومی تابع شما.

ممکن است از شما پرسیده شود که «استقرار از منبع نیاز به یک مخزن Docker در رجیستری Artifact برای ذخیره کانتینرهای ساخته شده دارد. یک مخزن با نام [cloud-run-source-deploy] در منطقه [<YOUR_REGION>] ایجاد خواهد شد.» برای ایجاد مخزن، مقدار پیش‌فرض بله را بپذیرید.

شما می‌توانید سرویس جدید crf-vertexai-codelab خود را با اجرای دستور زیر مشاهده کنید: 

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

۵. رویداد را ایجاد کنید

می‌توانیم یک تریگر 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 از فضای ذخیره‌سازی ابری با استفاده از Eventarc را می‌توانید در مستندات Cloud Run اینجا بیابید: https://cloud.google.com/run/docs/tutorials/eventarc

۶. تابع را آزمایش کنید

با استقرار تابع و ایجاد یک تریگر، اکنون آماده‌ایم تا تابع را فراخوانی کنیم.

یک فایل ایجاد کنید و آن را در فضای ذخیره‌سازی ابری خود آپلود کنید. می‌توانید این کار را از طریق رابط وب کنسول ابری یا با استفاده از ابزار gsutil CLI انجام دهید، مثلاً 

gsutil cp <YOUR_PLAIN_TEXT_FILE> gs://$BUCKET_NAME

وقتی فایل با موفقیت آپلود شود، یک رویداد ایجاد می‌شود و تابع شما Gemini را برای خلاصه کردن فایل متنی ساده فراخوانی می‌کند. این خلاصه در لاگ‌ها چاپ می‌شود.

می‌توانید گزارش‌های مربوط به سرویس Cloud Run را در Cloud Console مشاهده کنید، یا می‌توانید دستور زیر را اجرا کنید: 

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.

۷. تبریک می‌گویم!

تبریک می‌گویم که آزمایشگاه کد را تمام کردید!

توصیه می‌کنیم مستندات مربوط به عملکردهای Cloud Run را بررسی کنید.

آنچه ما پوشش داده‌ایم

  • نحوه‌ی پیاده‌سازی یک تابع Cloud Run مبتنی بر رویداد که هر زمان یک شیء در یک سطل GCS آپلود می‌شود، فعال می‌شود
  • نحوه ایجاد یک حساب کاربری سرویس با نقش‌های مناسب برای دریافت رویداد از Cloud Storage و فراخوانی تابع Cloud Run
  • نحوه استفاده از Gemini برای خلاصه کردن یک سند متنی ساده آپلود شده در فضای ابری

۸. تمیز کردن

برای جلوگیری از هزینه‌های ناخواسته، (برای مثال، اگر این سرویس Cloud Run سهواً بیشتر از تخصیص فراخوانی ماهانه Cloud Run شما در سطح رایگان فراخوانی شود)، می‌توانید سرویس Cloud Run یا پروژه‌ای را که در مرحله 2 ایجاد کرده‌اید، حذف کنید.

برای حذف سرویس‌های Cloud Run، به کنسول ابری Cloud Run در آدرس https://console.cloud.google.com/run/ بروید و سرویس crf-vertexai-codelab که در این codelab ایجاد کرده‌اید را حذف کنید.

اگر تصمیم به حذف کل پروژه دارید، می‌توانید به آدرس https://console.cloud.google.com/cloud-resource-manager بروید، پروژه‌ای را که در مرحله ۲ ایجاد کرده‌اید انتخاب کنید و گزینه Delete را انتخاب کنید. اگر پروژه را حذف کنید، باید پروژه‌ها را در Cloud SDK خود تغییر دهید. می‌توانید با اجرای gcloud projects list لیست تمام پروژه‌های موجود را مشاهده کنید.