Esta página foi traduzida pela API Cloud Translation.

Como hospedar um LLM em um sidecar para uma função do Cloud Run

1. Introdução

Visão geral

Neste codelab, você vai aprender a hospedar um modelo gemma3:4b em um sidecar para uma função do Cloud Run. Quando um arquivo é enviado para um bucket do Cloud Storage, a função do Cloud Run é acionada. A função vai enviar o conteúdo do arquivo para Gemma 3 no sidecar para resumo.

O que você vai aprender

Como fazer inferência usando uma função do Cloud Run e um LLM hospedado em um sidecar usando GPUs
Como usar a configuração de saída VPC direta para uma GPU do Cloud Run para fazer o upload e a veiculação do modelo mais rapidamente
Como usar o Genkit para interagir com seu modelo de ollama hospedado

2. Antes de começar

Para usar o recurso de GPUs, você precisa solicitar um aumento de cota para uma região com suporte. A cota necessária é nvidia_l4_gpu_allocation_no_zonal_redundancy, que está na API Cloud Run Admin. Este é o link direto para solicitar a cota.

3. Configuração e requisitos

Defina as variáveis de ambiente que serão usadas neste codelab.

PROJECT_ID=<YOUR_PROJECT_ID>
REGION=<YOUR_REGION>

AR_REPO=codelab-crf-sidecar-gpu
FUNCTION_NAME=crf-sidecar-gpu
BUCKET_GEMMA_NAME=$PROJECT_ID-codelab-crf-sidecar-gpu-gemma3
BUCKET_DOCS_NAME=$PROJECT_ID-codelab-crf-sidecar-gpu-docs
SERVICE_ACCOUNT="crf-sidecar-gpu"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com
IMAGE_SIDECAR=$REGION-docker.pkg.dev/$PROJECT_ID/$AR_REPO/ollama-gemma3

Crie a conta de serviço executando este comando:

gcloud iam service-accounts create $SERVICE_ACCOUNT \
  --display-name="SA for codelab crf sidecar with gpu"

Vamos usar essa mesma conta de serviço como a identidade da função do Cloud Run como a conta de serviço do acionador do eventarc para invocar a função do Cloud Run. Se preferir, crie um SA diferente para o Eventarc.

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

Conceda à conta de serviço acesso para receber eventos do Eventarc.

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

Crie um bucket que hospedará seu modelo ajustado. Este codelab usa um bucket regional. Você também pode usar um bucket multirregional.

gsutil mb -l $REGION gs://$BUCKET_GEMMA_NAME

Em seguida, conceda ao SA acesso ao bucket.

gcloud storage buckets add-iam-policy-binding gs://$BUCKET_GEMMA_NAME \
--member=serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
--role=roles/storage.objectAdmin

Agora, crie um bucket regional que vai armazenar os documentos que você quer resumir. Você também pode usar um bucket multirregional, desde que atualize o acionador do Eventarc de acordo (mostrado no final deste codelab).

gsutil mb -l $REGION gs://$BUCKET_DOCS_NAME

Em seguida, conceda ao SA acesso ao bucket Gemma 3.

gcloud storage buckets add-iam-policy-binding gs://$BUCKET_GEMMA_NAME \
--member=serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
--role=roles/storage.objectAdmin

e o bucket de documentos.

gcloud storage buckets add-iam-policy-binding gs://$BUCKET_DOCS_NAME \
--member=serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
--role=roles/storage.objectAdmin

Crie um repositório do Artifact Registry para a imagem do Ollama que será usada no sidecar

gcloud artifacts repositories create $AR_REPO \
    --repository-format=docker \
    --location=$REGION \
    --description="codelab for CR function and gpu sidecar" \
    --project=$PROJECT_ID

4. Fazer o download do modelo Gemma 3

Primeiro, faça o download do modelo Gemma 3 4b no ollama. Para fazer isso, instale o ollama e execute o modelo gemma3:4b localmente.

curl -fsSL https://ollama.com/install.sh | sh
ollama serve

Agora, em uma janela de terminal separada, execute o comando a seguir para baixar o modelo. Se você estiver usando o Cloud Shell, poderá abrir outra janela de terminal clicando no ícone de adição na barra de menus no canto superior direito.

ollama run gemma3:4b

Quando o ollama estiver em execução, faça algumas perguntas ao modelo, por exemplo:

"why is the sky blue?"

Quando terminar de conversar com o ollama, saia do chat executando

/bye

Em seguida, na primeira janela do terminal, execute o comando a seguir para interromper a veiculação da ollama localmente.

# on Linux / Cloud Shell press Ctrl^C or equivalent for your shell

Confira aqui onde o Ollama faz o download dos modelos, dependendo do seu sistema operacional.

https://github.com/ollama/ollama/blob/main/docs/faq.md#where-are-models-stored

Se você estiver usando as estações de trabalho do Cloud, confira os modelos do Ollamarain que foram transferidos por download aqui /home/$USER/.ollama/models

Confirme se os modelos estão hospedados aqui:

ls /home/$USER/.ollama/models

Agora, mova o modelo gemma3:4b para o bucket do GCS

gsutil cp -r /home/$USER/.ollama/models gs://$BUCKET_GEMMA_NAME

5. Criar a função do Cloud Run

Crie uma pasta raiz para o código-fonte.

mkdir codelab-crf-sidecar-gpu &&
cd codelab-crf-sidecar-gpu &&
mkdir cr-function &&
mkdir ollama-gemma3 &&
cd cr-function

Crie uma subpasta chamada src. Dentro da pasta, crie um arquivo chamado index.ts.

mkdir src &&
touch src/index.ts

Atualize index.ts com o seguinte código:

//import util from 'util';
import { cloudEvent, CloudEvent } from "@google-cloud/functions-framework";
import { StorageObjectData } from "@google/events/cloud/storage/v1/StorageObjectData";
import { Storage } from "@google-cloud/storage";

// Initialize the Cloud Storage client
const storage = new Storage();

import { genkit } from 'genkit';
import { ollama } from 'genkitx-ollama';

const ai = genkit({
    plugins: [
        ollama({
            models: [
                {
                    name: 'gemma3:4b',
                    type: 'generate', // type: 'chat' | 'generate' | undefined
                },
            ],
            serverAddress: 'http://127.0.0.1:11434', // default local address
        }),
    ],
});


// Register a CloudEvent callback with the Functions Framework that will
// be triggered by Cloud Storage.

//functions.cloudEvent('helloGCS', await cloudEvent => {
cloudEvent("gcs-cloudevent", async (cloudevent: CloudEvent<StorageObjectData>) => {
    console.log("---------------\nProcessing for ", cloudevent.subject, "\n---------------");

    if (cloudevent.data) {

        const data = cloudevent.data;

        if (data && data.bucket && data.name) {
            const bucketName = cloudevent.data.bucket;
            const fileName = cloudevent.data.name;
            const filePath = `${cloudevent.data.bucket}/${cloudevent.data.name}`;

            console.log(`Attempting to download: ${filePath}`);

            try {
                // Get a reference to the bucket
                const bucket = storage.bucket(bucketName!);

                // Get a reference to the file
                const file = bucket.file(fileName!);

                // Download the file's contents
                const [content] = await file.download();

                // 'content' is a Buffer. Convert it to a string.
                const fileContent = content.toString('utf8');

                console.log(`Sending file to Gemma 3 for summarization`);
                const { text } = await ai.generate({
                    model: 'ollama/gemma3:4b',
                    prompt: `Summarize the following document in just a few sentences ${fileContent}`,
                });

                console.log(text);

            } catch (error: any) {

                console.error('An error occurred:', error.message);
            }
        } else {
            console.warn("CloudEvent bucket name is missing!", cloudevent);
        }
    } else {
        console.warn("CloudEvent data is missing!", cloudevent);
    }
});

Agora, no diretório raiz crf-sidecar-gpu, crie um arquivo chamado package.json com o seguinte conteúdo:

{
    "main": "lib/index.js",
    "name": "ingress-crf-genkit",
    "version": "1.0.0",
    "scripts": {
        "build": "tsc"
    },
    "keywords": [],
    "author": "",
    "license": "ISC",
    "description": "",
    "dependencies": {
        "@google-cloud/functions-framework": "^3.4.0",
        "@google-cloud/storage": "^7.0.0",
        "genkit": "^1.1.0",
        "genkitx-ollama": "^1.1.0",
        "@google/events": "^5.4.0"
    },
    "devDependencies": {
        "typescript": "^5.5.2"
    }
}

Crie um tsconfig.json também no nível do diretório raiz com o seguinte conteúdo:

{
  "compileOnSave": true,
  "include": [
    "src"
  ],
  "compilerOptions": {
    "module": "commonjs",
    "noImplicitReturns": true,
    "outDir": "lib",
    "sourceMap": true,
    "strict": true,
    "target": "es2017",
    "skipLibCheck": true,
    "esModuleInterop": true
  }
}

6. Implante a função

Nesta etapa, você vai implantar a função do Cloud Run executando o comando a seguir.

Observação: o número máximo de instâncias precisa ser definido como um número menor ou igual à cota de GPU.

gcloud beta run deploy $FUNCTION_NAME \
  --region $REGION \
  --function gcs-cloudevent \
  --base-image nodejs22 \
  --source . \
  --no-allow-unauthenticated \
  --max-instances 2 # this should be less than or equal to your GPU quota

7. Criar o sidecar

Saiba mais sobre como hospedar o Ollama em um serviço do Cloud Run em https://cloud.google.com/run/docs/tutorials/gpu-gemma-with-ollama

Acesse o diretório do sidecar:

cd ../ollama-gemma3

Crie um arquivo Dockerfile com o seguinte conteúdo:

FROM ollama/ollama:latest

# Listen on all interfaces, port 11434
ENV OLLAMA_HOST 0.0.0.0:11434

# Store model weight files in /models
ENV OLLAMA_MODELS /models

# Reduce logging verbosity
ENV OLLAMA_DEBUG false

# Never unload model weights from the GPU
ENV OLLAMA_KEEP_ALIVE -1

# Store the model weights in the container image
ENV MODEL gemma3:4b
RUN ollama serve & sleep 5 && ollama pull $MODEL

# Start Ollama
ENTRYPOINT ["ollama", "serve"]

Criar a imagem

gcloud builds submit \
   --tag $REGION-docker.pkg.dev/$PROJECT_ID/$AR_REPO/ollama-gemma3 \
   --machine-type e2-highcpu-32

8. Atualizar a função com o sidecar

Para adicionar um sidecar a um serviço, job ou função, atualize o arquivo YAML para incluir o sidecar.

Extraia o YAML da função do Cloud Run que você acabou de implantar executando:

gcloud run services describe $FUNCTION_NAME --format=export > add-sidecar-service.yaml

Agora adicione o sidecar ao CRf atualizando o YAML da seguinte maneira:

Insira o seguinte fragmento YAML diretamente acima da linha runtimeClassName: run.googleapis.com/linux-base-image-update. O -image precisa estar alinhado com o item do contêiner de entrada -image.

    - image: YOUR_IMAGE_SIDECAR:latest
        name: gemma-sidecar
        env:
        - name: OLLAMA_FLASH_ATTENTION
          value: '1'
        resources:
          limits:
            cpu: 6000m
            nvidia.com/gpu: '1'
            memory: 16Gi
        volumeMounts:
        - name: gcs-1
          mountPath: /root/.ollama
        startupProbe:
          failureThreshold: 2
          httpGet:
            path: /
            port: 11434
          initialDelaySeconds: 60
          periodSeconds: 60
          timeoutSeconds: 60
      nodeSelector:
        run.googleapis.com/accelerator: nvidia-l4
      volumes:
        - csi:
            driver: gcsfuse.run.googleapis.com
            volumeAttributes:
              bucketName: YOUR_BUCKET_GEMMA_NAME
          name: gcs-1

Execute o comando abaixo para atualizar o fragmento YAML com suas variáveis de ambiente:

sed -i "s|YOUR_IMAGE_SIDECAR|$IMAGE_SIDECAR|; s|YOUR_BUCKET_GEMMA_NAME|$BUCKET_GEMMA_NAME|" add-sidecar-service.yaml

O arquivo YAML concluído vai ficar assim:

##############################################
# DO NOT COPY - For illustration purposes only
##############################################

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:    
    run.googleapis.com/build-base-image: us-central1-docker.pkg.dev/serverless-runtimes/google-22/runtimes/nodejs22
    run.googleapis.com/build-enable-automatic-updates: 'true'
    run.googleapis.com/build-function-target: gcs-cloudevent
    run.googleapis.com/build-id: f0122905-a556-4000-ace4-5c004a9f9ec6
    run.googleapis.com/build-image-uri:<YOUR_IMAGE_CRF>
    run.googleapis.com/build-name: <YOUR_BUILD_NAME>
    run.googleapis.com/build-source-location: <YOUR_SOURCE_LOCATION>
    run.googleapis.com/ingress: all
    run.googleapis.com/ingress-status: all
    run.googleapis.com/urls: '["<YOUR_CLOUD_RUN_FUNCTION_URLS"]'
  labels:
    cloud.googleapis.com/location: <YOUR_REGION>
  name: <YOUR_FUNCTION_NAME>
  namespace: '392295011265'
spec:
  template:
    metadata:
      annotations:
        autoscaling.knative.dev/maxScale: '4'
        run.googleapis.com/base-images: '{"":"us-central1-docker.pkg.dev/serverless-runtimes/google-22/runtimes/nodejs22"}'
        run.googleapis.com/client-name: gcloud
        run.googleapis.com/client-version: 514.0.0
        run.googleapis.com/startup-cpu-boost: 'true'
      labels:
        client.knative.dev/nonce: hzhhrhheyd
        run.googleapis.com/startupProbeType: Default
    spec:
      containerConcurrency: 80
      containers:
      - image: <YOUR_FUNCTION_IMAGE>
        ports:
        - containerPort: 8080
          name: http1
        resources:
          limits:
            cpu: 1000m
            memory: 512Mi
        startupProbe:
          failureThreshold: 1
          periodSeconds: 240
          tcpSocket:
            port: 8080
          timeoutSeconds: 240
      - image: <YOUR_SIDECAR_IMAGE>:latest
        name: gemma-sidecar
        env:
        - name: OLLAMA_FLASH_ATTENTION
          value: '1'
        resources:
          limits:
            cpu: 6000m
            nvidia.com/gpu: '1'
            memory: 16Gi
        volumeMounts:
        - name: gcs-1
          mountPath: /root/.ollama
        startupProbe:
          failureThreshold: 2
          httpGet:
            path: /
            port: 11434
          initialDelaySeconds: 60
          periodSeconds: 60
          timeoutSeconds: 60
      nodeSelector:
        run.googleapis.com/accelerator: nvidia-l4
      volumes:
        - csi:
            driver: gcsfuse.run.googleapis.com
            volumeAttributes:
              bucketName: <YOUR_BUCKET_NAME>
          name: gcs-1
      runtimeClassName: run.googleapis.com/linux-base-image-update
      serviceAccountName: <YOUR_SA_ADDRESS>
      timeoutSeconds: 300
  traffic:
  - latestRevision: true
    percent: 100

##############################################
# DO NOT COPY - For illustration purposes only
##############################################

Agora atualize a função com o sidecar executando o comando a seguir.

gcloud run services replace add-sidecar-service.yaml

Por fim, crie o gatilho do Eventarc para a função. Esse comando também adiciona a função.

Observação: se você criou um bucket multirregional, mude o parâmetro --location.

gcloud eventarc triggers create my-crf-summary-trigger  \
    --location=$REGION \
    --destination-run-service=$FUNCTION_NAME  \
    --destination-run-region=$REGION \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=$BUCKET_DOCS_NAME" \
    --service-account=$SERVICE_ACCOUNT_ADDRESS

9. Testar a função

Faça upload de um arquivo de texto simples para a geração de resumo. Não sabe o que resumir? Peça ao Gemini uma descrição rápida de uma a duas páginas sobre a história dos cães. Em seguida, faça upload desse arquivo de texto simples para o bucket $BUCKET_DOCS_NAME do modelo Gemma3:4b para gravar um resumo nos registros de função.

Nos registros, você vai encontrar algo semelhante ao seguinte:

---------------
Processing for objects/dogs.txt
---------------
Attempting to download: <YOUR_PROJECT_ID>-codelab-crf-sidecar-gpu-docs/dogs.txt
Sending file to Gemma 3 for summarization
...
Here's a concise summary of the document "Humanity's Best Friend":
The dog's domestication, beginning roughly 20,000-40,000 years ago, represents a unique, deeply intertwined evolutionary partnership with humans, predating the domestication of any other animal
<...>
solidifying their long-standing role as humanity's best friend.

10. Solução de problemas

Confira alguns erros de digitação que você pode encontrar:

Se você receber um erro PORT 8080 is in use, verifique se o Dockerfile do sidecar do Ollama está usando a porta 11434. Além disso, verifique se você está usando a imagem de sidecar correta caso tenha várias imagens do Ollama no repositório de RA. A função do Cloud Run é veiculada na porta 8080. Se você usou uma imagem diferente do Ollama como o sidecar que também é veiculado na 8080, vai encontrar esse erro.
Se você receber o erro failed to build: (error ID: 7485c5b6): function.js does not exist, verifique se os arquivos package.json e tsconfig.json estão no mesmo nível do diretório src.
Se você receber o erro ERROR: (gcloud.run.services.replace) spec.template.spec.node_selector: Max instances must be set to 4 or fewer in order to set GPU requirements., no arquivo YAML, mude autoscaling.knative.dev/maxScale: '100' para 1 ou para algo menor ou igual à cota de GPU.