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

1. مقدمه

نمای کلی

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

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

چیزی که یاد خواهید گرفت

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

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

gcloud CLI را به روز کنید

این کد لبه نیاز به یک نسخه جدید از gcloud CLI نصب شده دارد. شما می توانید CLI را با اجرا به روز کنید

gcloud components update

API ها را فعال کنید

قبل از اینکه بتوانید از این کد لبه استفاده کنید، چندین API وجود دارد که باید آنها را فعال کنید. این آزمایشگاه کد نیاز به استفاده از 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

3. یک 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 (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"

و به حساب سرویس نقش 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 نیاز دارد که به حساب سرویس 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. رویداد را ایجاد کنید

می‌توانیم هر بار که یک شی در Google Cloud Storage نهایی می‌شود، یک راه‌انداز Eventarc ایجاد کنیم تا پیام‌هایی را به عملکرد خود ارسال کنیم: 

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 یا با استفاده از ابزار gsutil CLI انجام دهید، به عنوان مثال 

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 Run
  • نحوه استفاده از Gemini برای خلاصه کردن یک سند متنی ساده که در Cloud Storage بارگذاری شده است

8. پاکسازی کنید

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

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

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