Como usar as funções do Cloud Run e o Gemini para resumir um arquivo de texto enviado para um bucket do Cloud Storage

1. Introdução

Visão geral

As funções do Cloud Run são uma nova maneira de implantar cargas de trabalho usando os paradigmas de eventos e a assinatura de função conhecidos do GCF. Em vez de usar nosso processo de build e configurações de implantação, as funções do Cloud Run oferecem controle direto sobre o serviço criado no Cloud Run.

Nesta seção, você vai aprender a implantar uma função orientada a eventos em Python que usa o Gemini para resumir um arquivo de texto simples enviado para um bucket do Cloud Storage.

O que você vai aprender

  • Como implantar uma função do Cloud Run orientada por eventos que é acionada sempre que um objeto é enviado para um bucket do GCS
  • Como criar uma conta de serviço com papéis adequados para receber um evento do Cloud Storage e invocar a função do Cloud Run
  • Como usar o Gemini para resumir um documento de texto simples enviado para o Cloud Storage

2. Configurar variáveis de ambiente e ativar APIs

Atualizar a gcloud CLI

Este codelab requer uma versão recente da CLI gcloud instalada. Para atualizar a CLI, execute

gcloud components update

Ativar APIs

Antes de começar a usar este codelab, você precisa ativar várias APIs. Este codelab exige o uso das seguintes APIs. É possível ativar essas APIs executando o seguinte comando:

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

Configurar as variáveis de ambiente.

Você pode definir variáveis de ambiente que serão usadas neste 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. Criar um bucket do Storage e uma conta de serviço

Criar um bucket de armazenamento

Para criar um bucket do Cloud Storage, execute o seguinte comando:

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

Criar uma conta de serviço

Neste exemplo, você vai criar uma conta de serviço com as permissões necessárias do Eventarc e o papel de invocador do Cloud Run para receber um evento do Cloud Storage e invocar a função do Cloud Run.

Primeiro, crie a conta de serviço.

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"

Em seguida, conceda o papel Receptor de eventos do Eventarc (roles/eventarc.eventReceiver) no projeto à conta de serviço associada ao gatilho do Eventarc para que ele possa receber eventos de provedores de eventos.

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

Em seguida, conceda à conta de serviço o papel de invocação do Cloud Run para que ela possa invocar a função.

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

Agora, conceda à conta de serviço o papel de usuário da plataforma de IA para que ela possa fazer chamadas para o Gemini.

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

E conceder o papel Leitor de objetos do Storage à conta de serviço para que ela possa acessar o arquivo.

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

Para criar tokens de identidade, o Cloud Pub/Sub precisa do papel roles/iam.serviceAccountTokenCreator no seu projeto.

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

Seu gatilho precisa do papel roles/pubsub.publisher concedido à conta de serviço do Google Cloud Storage para receber eventos pelo 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. Criar e implantar a função

Primeiro, crie um diretório para o código-fonte e use cd nele.

mkdir $SERVICE_NAME && cd $_

Em seguida, crie um arquivo requirements.txt com o seguinte conteúdo:

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

Em seguida, crie um arquivo main.py com o seguinte conteúdo:

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

Agora você pode implantar a função do Cloud Run executando o seguinte comando:

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

Observações:

  • a sinalização --source é usada para dizer ao Cloud Run para criar a função em um serviço baseado em contêiner executável;
  • A flag --function (new) é usada para definir o ponto de entrada do novo serviço como a assinatura de função que você quer invocar.
  • (opcional) --no-allow-unauthenticated para impedir que a função seja invocável publicamente

Talvez você receba a mensagem "A implantação da origem requer um repositório do Docker do Artifact Registry para armazenar contêineres criados. Um repositório chamado [cloud-run-source-deploy] na região [<YOUR_REGION>] será criado." Aceite o padrão "sim" para criar o repositório.

Para ver o novo serviço crf-vertexai-codelab, execute o seguinte comando:

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

5. Criar o evento

Podemos criar um acionador do Eventarc para enviar mensagens para nossa função toda vez que um objeto for finalizado no 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

Para a flag --event-filters, não use o prefixo gs:// no nome do bucket.

Se você receber um erro If you recently started to use Eventarc, it may take a few minutes before all necessary permissions are propagated to the Service Agent., aguarde alguns minutos e tente novamente.

Confira um tutorial detalhado sobre como configurar o serviço de gatilho do Cloud Storage usando o Eventarc na documentação do Cloud Run: https://cloud.google.com/run/docs/tutorials/eventarc

6. Testar a função

Com nossa função implantada e um gatilho criado, agora estamos prontos para invocar a função.

Crie um arquivo e faça upload dele para o bucket do Cloud Storage. Para isso, use a interface da Web do Console do Google Cloud ou a ferramenta CLI gsutil.

gsutil cp <YOUR_PLAIN_TEXT_FILE> gs://$BUCKET_NAME

Quando o upload for concluído, um evento será gerado, e sua função vai chamar o Gemini para resumir o arquivo de texto simples. O resumo será impresso nos registros.

É possível conferir os registros no console do Cloud para o serviço do Cloud Run ou executar o seguinte comando:

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

Por exemplo, o upload de um arquivo de texto simples do guia do usuário das funções do Cloud Run para a visualização privada resulta na impressão do seguinte nos registros:

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. Parabéns!

Parabéns por concluir o codelab.

Recomendamos a análise da documentação das Funções do Cloud Run.

O que vimos

  • Como implantar uma função do Cloud Run orientada por eventos que é acionada sempre que um objeto é enviado para um bucket do GCS
  • Como criar uma conta de serviço com papéis adequados para receber um evento do Cloud Storage e invocar a função do Cloud Run
  • Como usar o Gemini para resumir um documento de texto simples enviado para o Cloud Storage

8. Limpar

Para evitar cobranças acidentais (por exemplo, se esse serviço do Cloud Run for invocado mais vezes do que sua alocação mensal de invocação do Cloud Run no nível sem custo financeiro), exclua o serviço do Cloud Run ou o projeto criado na etapa 2.

Para excluir os serviços do Cloud Run, acesse o console do Cloud Run em https://console.cloud.google.com/run/ e exclua o serviço crf-vertexai-codelab que você criou neste codelab.

Se você quiser excluir o projeto inteiro, acesse https://console.cloud.google.com/cloud-resource-manager, selecione o projeto criado na etapa 2 e escolha "Excluir". Se você excluir o projeto, vai precisar mudar os projetos no Cloud SDK. Para conferir a lista de todos os projetos disponíveis, execute gcloud projects list.