איך משתמשים בפונקציות של 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

כדי להשתמש ב-codelab הזה, צריך להתקין גרסה עדכנית של ה-CLI של gcloud. אפשר לעדכן את ה-CLI על ידי הרצת הפקודה

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

הגדרה של משתני סביבה

אתם יכולים להגדיר משתני סביבה שישמשו אתכם לאורך כל ה-codelab הזה.

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 User כדי שהוא יוכל לבצע קריאות ל-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

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

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>‎]'." מאשרים את ברירת המחדל yes כדי ליצור את המאגר.

כדי לראות את השירות החדש 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 או באמצעות כלי 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. מעולה!

כל הכבוד, סיימתם את ה-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 וללחוץ על 'מחיקה'. אם תמחקו את הפרויקט, תצטרכו לשנות את הפרויקטים ב-Cloud SDK. כדי לראות את רשימת כל הפרויקטים הזמינים, מריצים את הפקודה gcloud projects list.