איך משתמשים בפונקציות של Cloud Run וב-Gemini לסיכום קובץ טקסט שהועלה לקטגוריה של Cloud Storage

1. מבוא

סקירה כללית

פונקציות של Cloud Run הן דרך חדשה לפרוס עומסי עבודה באמצעות חתימה ופרדיגמות של אירועים מוכרים של GCF. במקום להשתמש בתהליך ה-build ובהגדרות הפריסה שלנו, הפונקציות של Cloud Run נותנות לכם שליטה ישירה על השירות הבסיסי שנוצר ב-Cloud Run.

בקטע הזה תלמדו איך לפרוס ב-python פונקציה מבוססת-אירועים שמשתמשת ב-Gemini כדי לסכם קובץ טקסט פשוט שהועלה לקטגוריה של Cloud Storage.

מה תלמדו

  • איך לפרוס פונקציה מבוססת-אירועים ב-Cloud Run שמופעלת בכל פעם שמועלה אובייקט לקטגוריה ב-GCS
  • איך יוצרים חשבון שירות עם תפקידים מתאימים לקבלת אירוע מ-Cloud Storage ולהפעיל את הפונקציה של Cloud Run
  • איך משתמשים ב-Gemini כדי לסכם מסמך בפורמט טקסט פשוט שהועלה ל-Cloud Storage

2. הגדרת משתני סביבה והפעלת ממשקי API

עדכון ה-CLI של gcloud

כדי להשתמש בקוד הפתוח הזה, צריך להתקין גרסה עדכנית של ה-CLI של gcloud. כדי לעדכן את ה-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. יצירה של קטגוריית אחסון וחשבון שירות

יצירה של קטגוריית אחסון

כדי ליצור קטגוריה של 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 את התפקיד 'מקבל אירועים' ב-Eventarc (roles/eventarc.eventReceiver) בפרויקט, כדי שהטריגר יוכל לקבל אירועים מספקי אירועים.

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

לאחר מכן מקצים לחשבון השירות את התפקיד Cloud Run Invoker כדי שיוכל להפעיל את הפונקציה.

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"

כדי שתהיה לו גישה לקובץ, צריך לתת לחשבון השירות את התפקיד 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

כדי לקבל אירועים דרך Cloud Storage, הטריגר צריך את התפקיד roles/pubsub.publisher שהוקצה לחשבון השירות של Google 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. יצירת הפונקציה ופריסה שלה

קודם יוצרים ספרייה לקוד המקור ומעבירים את עצמנו לספרייה הזו באמצעות 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 (חדש) משמש להגדרת נקודת הכניסה של השירות החדש כחתימת הפונקציה שרוצים להפעיל
  • (אופציונלי) את --no-allow-unauthenticated כדי למנוע הפעלה ציבורית של הפונקציה

יכול להיות שתופיע השאלה "Deploying from source requires an Artifact Registry Docker repository to store built containers. המערכת תיצור מאגר בשם [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., צריך להמתין כמה דקות לפני שמנסים שוב.

מדריך מפורט להגדרת שירות טריגר מ-Cloud Storage באמצעות Eventarc זמין במסמכי העזרה של Cloud Run בכתובת: https://cloud.google.com/run/docs/tutorials/eventarc

6. בדיקת הפונקציה

עכשיו שהפונקציה שלנו פרוסה ונוצר טריגר, ועכשיו אנחנו מוכנים להפעיל את הפונקציה.

יוצרים קובץ ומעלים אותו לקטגוריה ב-Cloud Storage. אפשר לעשות זאת דרך ממשק האינטרנט של מסוף Cloud או באמצעות הכלי CLI של gsutil, למשל:

gsutil cp <YOUR_PLAIN_TEXT_FILE> gs://$BUCKET_NAME

אחרי שהקובץ יועלה בהצלחה, יופק אירוע והפונקציה תפעיל את Gemini כדי לסכם את קובץ הטקסט הפשוט. הסיכום יודפס ביומנים.

אפשר להציג את היומנים של שירות Cloud Run במסוף Cloud, או להריץ את הפקודה הבאה:

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 כדי לסכם מסמך טקסט פשוט שהועלאה ל-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 שיצרתם ב-Codelab הזה.

אם בוחרים למחוק את הפרויקט כולו, אפשר לעבור אל https://console.cloud.google.com/cloud-resource-manager, לבחור את הפרויקט שיצרתם בשלב 2 ולבחור באפשרות Delete (מחיקה). אם תמחקו את הפרויקט, תצטרכו לשנות את הפרויקטים ב-Cloud SDK. כדי להציג את הרשימה של כל הפרויקטים הזמינים, אפשר להריץ את הפקודה gcloud projects list.