Cómo alojar un LLM en un contenedor secundario para una función de Cloud Run

1. Introducción

Descripción general

En este codelab, aprenderás a alojar un modelo gemma3:4b en un proceso secundario para una Cloud Run Function. Cuando se sube un archivo a un bucket de Cloud Storage, se activa la función de Cloud Run. La función enviará el contenido del archivo a Gemma 3 en el sidecar para que lo resuma.

Qué aprenderás

  • Cómo realizar la inferencia con una función de Cloud Run y un LLM alojado en un proceso secundario con GPUs
  • Cómo usar la configuración de salida de VPC directa para una GPU de Cloud Run y acelerar la carga y la entrega del modelo
  • Cómo usar Genkit para interactuar con tu modelo de Ollama alojado

2. Antes de comenzar

Para usar la función de GPUs, debes solicitar un aumento de cuota para una región admitida. La cuota necesaria es nvidia_l4_gpu_allocation_no_zonal_redundancy, que se encuentra en la API de Cloud Run Admin. Este es el vínculo directo para solicitar cuota.

3. Configuración y requisitos

Configura las variables de entorno que se usarán en este 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

Para crear la cuenta de servicio, ejecuta este comando:

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

Usaremos la misma cuenta de servicio que se usa como la identidad de la función de Cloud Run como la cuenta de servicio del activador de Eventarc para invocar la función de Cloud Run. Si lo prefieres, puedes crear una SA diferente para Eventarc.

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

También otorga a la cuenta de servicio acceso para recibir eventos de Eventarc.

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

Crea un bucket que alojará tu modelo ajustado. En este codelab, se usa un bucket regional. También puedes usar un bucket multirregional.

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

Luego, otorga acceso a la SA al bucket.

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

Ahora, crea un bucket regional que almacenará los documentos que deseas resumir. También puedes usar un bucket multirregional, siempre y cuando actualices el activador de Eventarc según corresponda (se muestra al final de este codelab).

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

Luego, otorga acceso a la SA al bucket de Gemma 3.

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

y el bucket de Docs.

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

Crea un repositorio de Artifact Registry para la imagen de Ollama que se usará en el sidecar.

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

4. Descarga el modelo Gemma 3

Primero, deberás descargar el modelo Gemma 3 4b de Ollama. Para ello, instala Ollama y, luego, ejecuta el modelo gemma3:4b de forma local.

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

Ahora, en una ventana de terminal separada, ejecuta el siguiente comando para extraer el modelo. Si usas Cloud Shell, puedes abrir una ventana de terminal adicional haciendo clic en el ícono de signo más en la barra de menú superior derecha.

ollama run gemma3:4b

Una vez que se ejecute Ollama, puedes hacerle algunas preguntas al modelo, p.ej.,

"why is the sky blue?"

Cuando termines de chatear con Ollama, puedes salir del chat ejecutando

/bye

Luego, en la primera ventana de la terminal, ejecuta el siguiente comando para dejar de publicar ollama de forma local:

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

Aquí puedes encontrar dónde Ollama descarga los modelos según tu sistema operativo.

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

Si usas Cloud Workstations, puedes encontrar los modelos de Ollama descargados aquí /home/$USER/.ollama/models

Confirma que tus modelos estén alojados aquí:

ls /home/$USER/.ollama/models

Ahora, mueve el modelo gemma3:4b a tu bucket de GCS.

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

5. Crea la función de Cloud Run

Crea una carpeta raíz para tu código fuente.

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

Crea una subcarpeta llamada src. Dentro de la carpeta, crea un archivo llamado index.ts.

mkdir src &&
touch src/index.ts

Actualiza index.ts con el siguiente 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);
    }
});

Ahora, en el directorio raíz crf-sidecar-gpu, crea un archivo llamado package.json con el siguiente contenido:

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

Crea un archivo tsconfig.json también en el nivel del directorio raíz con el siguiente contenido:

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

6. Implementa la función

En este paso, implementarás la función de Cloud Run ejecutando el siguiente comando.

Nota: La cantidad máxima de instancias debe establecerse en un número menor o igual que tu cuota 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. Crea el sidecar

Puedes obtener más información para alojar Ollama en un servicio de Cloud Run en https://cloud.google.com/run/docs/tutorials/gpu-gemma-with-ollama

Ingresa al directorio de tu sidecar:

cd ../ollama-gemma3

Crea un archivo Dockerfile con el siguiente contenido:

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"]

Compila la imagen

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

8. Actualiza la función con el sidecar

Para agregar un sidecar a un servicio, un trabajo o una función existentes, puedes actualizar el archivo YAML para que contenga el sidecar.

Ejecuta el siguiente comando para recuperar el archivo YAML de la función de Cloud Run que acabas de implementar:

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

Ahora, agrega el archivo adicional al CR actualizando el archivo YAML de la siguiente manera:

  1. Inserta el siguiente fragmento de YAML directamente sobre la línea runtimeClassName: run.googleapis.com/linux-base-image-update. El -image debe alinearse con el elemento del contenedor 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
  1. Ejecuta el siguiente comando para actualizar el fragmento de YAML con tus variables de entorno:
sed -i "s|YOUR_IMAGE_SIDECAR|$IMAGE_SIDECAR|; s|YOUR_BUCKET_GEMMA_NAME|$BUCKET_GEMMA_NAME|" add-sidecar-service.yaml

Tu archivo YAML completo debería verse de la siguiente manera:

##############################################
# 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
##############################################

Ahora, actualiza la función con el sidecar ejecutando el siguiente comando.

gcloud run services replace add-sidecar-service.yaml

Por último, crea el activador de Eventarc para la función. Este comando también lo agrega a la función.

Nota: Si creaste un bucket multirregional, te recomendamos que cambies el 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. Prueba la función

Sube un archivo de texto sin formato para generar un resumen. ¿No sabes qué resumir? Pídele a Gemini una descripción rápida de 1 o 2 páginas sobre la historia de los perros. Luego, sube ese archivo de texto sin formato a tu bucket de $BUCKET_DOCS_NAME para que el modelo Gemma3:4b escriba un resumen en los registros de la función.

En los registros, verás algo similar a lo siguiente:

---------------
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. Solución de problemas

A continuación, se muestran algunos errores de escritura que puedes encontrar:

  1. Si recibes un error que indica PORT 8080 is in use, asegúrate de que tu Dockerfile para el sidecar de Ollama use el puerto 11434. También asegúrate de usar la imagen de sidecar correcta en caso de que tengas varias imágenes de Ollama en tu repo de AR. La función de Cloud Run se ejecuta en el puerto 8080, y si usaste una imagen de Ollama diferente como el proceso secundario que también se ejecuta en el puerto 8080, se producirá este error.
  2. Si obtienes el error failed to build: (error ID: 7485c5b6): function.js does not exist, asegúrate de que los archivos package.json y tsconfig.json estén en el mismo nivel que el directorio src.
  3. Si recibes el error 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., en tu archivo YAML, cambia autoscaling.knative.dev/maxScale: '100' a 1 o a un valor menor o igual que tu cuota de GPU.