Come utilizzare le funzioni di Cloud Run e Gemini per riassumere un file di testo caricato in un bucket Cloud Storage

1. Introduzione

Panoramica

Cloud Run Functions è un nuovo modo per eseguire il deployment dei carichi di lavoro utilizzando i paradigmi di eventi e la firma della funzione GCF familiari. Anziché utilizzare il nostro processo di compilazione e le configurazioni di deployment, Cloud Run Functions ti offre il controllo diretto sul servizio sottostante creato in Cloud Run.

In questa sezione, imparerai a eseguire il deployment di una funzione basata su eventi in Python che utilizza Gemini per riepilogare un file di testo normale caricato in un bucket Cloud Storage.

Cosa imparerai a fare

Come eseguire il deployment di una funzione Cloud Run basata su eventi che viene attivata ogni volta che un oggetto viene caricato in un bucket GCS
Come creare un service account con i ruoli appropriati per ricevere un evento da Cloud Storage e richiamare la funzione Cloud Run
Come utilizzare Gemini per riepilogare un documento di testo normale caricato in Cloud Storage

2. Configurare le variabili di ambiente e abilitare le API

Aggiornare gcloud CLI

Questo codelab richiede l'installazione di una versione recente di gcloud CLI. Puoi aggiornare l'interfaccia a riga di comando eseguendo

gcloud components update

Abilitare le API

Prima di poter iniziare a utilizzare questo codelab, devi abilitare diverse API. Questo codelab richiede l'utilizzo delle seguenti API. Puoi abilitare queste API eseguendo il seguente comando:

gcloud services enable run.googleapis.com \
    cloudbuild.googleapis.com \
    storage.googleapis.com \
    artifactregistry.googleapis.com \
    eventarc.googleapis.com \
    aiplatform.googleapis.com

Configurare le variabili di ambiente

Puoi impostare le variabili di ambiente che verranno utilizzate durante questo 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. Creare un bucket di archiviazione e un service account

Creare un bucket di archiviazione

Puoi creare un bucket Cloud Storage eseguendo il seguente comando:

gsutil mb -l us-central1 gs://$BUCKET_NAME

Creare un service account

Per questo esempio, creerai un service account con le autorizzazioni Eventarc richieste e il ruolo Invoker di Cloud Run per ricevere un evento da Cloud Storage e richiamare la funzione Cloud Run.

Crea innanzitutto il service account.

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"

Poi, concedi al service account associato al trigger Eventarc il ruolo Destinatario di eventi Eventarc (roles/eventarc.eventReceiver) nel progetto, in modo che il trigger possa ricevere eventi dai provider di eventi.

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

Quindi, concedi al service account il ruolo Invoker di Cloud Run in modo che possa richiamare la funzione.

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

Ora, concedi al service account il ruolo Utente AI Platform in modo che possa effettuare chiamate a Gemini.

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

Concedi al service account il ruolo Visualizzatore oggetti Storage in modo che possa accedere al file.

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

Cloud Pub/Sub richiede il ruolo roles/iam.serviceAccountTokenCreator nel tuo progetto per creare token di identità.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:service-$PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator

Il trigger richiede il ruolo roles/pubsub.publisher concesso al service account Google Cloud Storage per ricevere eventi tramite 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. Creare ed eseguire il deployment della funzione

Innanzitutto, crea una directory per il codice sorgente e passa a questa directory.

mkdir $SERVICE_NAME && cd $_

Poi, crea un file requirements.txt con i seguenti contenuti:

functions-framework==3.*
google-cloud-aiplatform==1.63.*
google-cloud-storage==2.16.*

Quindi, crea un file main.py con i seguenti contenuti:

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}")

Ora puoi eseguire il deployment della funzione Cloud Run eseguendo il seguente comando:

gcloud beta run deploy $SERVICE_NAME \
      --source . \
      --function hello_gcs \
      --region $REGION \
      --no-allow-unauthenticated \
      --service-account $SERVICE_ACCOUNT_ADDRESS

Tieni presente quanto segue:

Il flag --source viene utilizzato per indicare a Cloud Run di creare la funzione in un servizio basato su container eseguibile
Il flag --function (nuovo) viene utilizzato per impostare il punto di ingresso del nuovo servizio sulla firma della funzione che vuoi richiamare
(Facoltativo) --no-allow-unauthenticated per impedire che la funzione possa essere richiamata pubblicamente

Potresti visualizzare il messaggio "Il deployment dall'origine richiede un repository Docker di Artifact Registry per archiviare i container creati. Verrà creato un repository denominato [cloud-run-source-deploy] nella regione [<YOUR_REGION>]". Accetta il valore predefinito yes per creare il repository.

Puoi visualizzare il nuovo servizio crf-vertexai-codelab eseguendo il seguente comando:

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

5. Creare l'evento

Possiamo creare un trigger Eventarc per inviare messaggi alla nostra funzione ogni volta che un oggetto viene finalizzato in 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

Tieni presente che per il flag --event-filters non devi utilizzare il prefisso gs:// nel nome del bucket.

Se visualizzi l'errore If you recently started to use Eventarc, it may take a few minutes before all necessary permissions are propagated to the Service Agent. (Se hai iniziato di recente a utilizzare Eventarc, potrebbero essere necessari alcuni minuti prima che tutte le autorizzazioni necessarie vengano propagate al service agent), attendi qualche minuto prima di riprovare.

Un tutorial dettagliato sulla configurazione del servizio Trigger da Cloud Storage utilizzando Eventarc è disponibile nella documentazione di Cloud Run qui: https://cloud.google.com/run/docs/tutorials/eventarc

6. Testare la funzione

Ora che la funzione è stata sottoposta a deployment e il trigger è stato creato, possiamo richiamare la funzione.

Crea un file e caricalo nel bucket Cloud Storage. Puoi farlo tramite l'interfaccia web di Cloud Console o utilizzando lo strumento CLI gsutil, ad es.

gsutil cp <YOUR_PLAIN_TEXT_FILE> gs://$BUCKET_NAME

Quando il file viene caricato correttamente, viene generato un evento e la funzione chiama Gemini per riepilogare il file di testo normale. Il riepilogo verrà stampato nei log.

Puoi visualizzare i log in Cloud Console per il servizio Cloud Run oppure eseguire il seguente comando:

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=$SERVICE_NAME AND textPayload: Response"

Ad esempio, se carichi un file di testo normale della guida utente di Cloud Run Functions per l'anteprima privata, nei log viene stampato quanto segue:

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. Complimenti!

Complimenti per aver completato il codelab.

Ti consigliamo di consultare la documentazione di Cloud Run Functions.

Argomenti trattati

Come eseguire il deployment di una funzione Cloud Run basata su eventi che viene attivata ogni volta che un oggetto viene caricato in un bucket GCS
Come creare un service account con i ruoli appropriati per ricevere un evento da Cloud Storage e richiamare la funzione Cloud Run
Come utilizzare Gemini per riepilogare un documento di testo normale caricato in Cloud Storage

8. Liberare spazio

Per evitare addebiti involontari (ad esempio, se questo servizio Cloud Run viene richiamato inavvertitamente più volte rispetto a all'allocazione mensile di richiami di Cloud Run nel livello senza costi), puoi eliminare il servizio Cloud Run o il progetto creato nel passaggio 2.

Per eliminare i servizi Cloud Run, vai a Cloud Run Cloud Console all'indirizzo https://console.cloud.google.com/run/ ed elimina il servizio crf-vertexai-codelab creato in questo codelab.

Se scegli di eliminare l'intero progetto, puoi andare all'indirizzo https://console.cloud.google.com/cloud-resource-manager, selezionare il progetto creato nel passaggio 2 e scegliere Elimina. Se elimini il progetto, dovrai cambiare progetto in Cloud SDK. Puoi visualizzare l'elenco di tutti i progetti disponibili eseguendo gcloud projects list.