Esegui Gemma 3 su Cloud Run

Questa guida descrive come eseguire il deployment dei modelli open source Gemma 3 su Cloud Run utilizzando un container predefinito e fornisce indicazioni sull'utilizzo del servizio Cloud Run di cui è stato eseguito il deployment con l'SDK Google Gen AI.

Prima di iniziare

Se hai utilizzato Google AI Studio per il deployment su Cloud Run, vai alla sezione Interagire in modo sicuro con Google Gen AI SDK.

Se non hai utilizzato Google AI Studio, segui questi passaggi prima di utilizzare Cloud Run per creare un nuovo servizio.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

1. Configura l'ambiente di sviluppo Cloud Run nel tuo progetto Google Cloud .
2. Installa e inizializza gcloud CLI.
3. Assicurati di aver concesso al tuo account i seguenti ruoli IAM:
   • Cloud Run Admin (roles/run.admin)
   • Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin)
   • Consumer di utilizzo del servizio (roles/serviceusage.serviceUsageConsumer)

Scopri come concedere i ruoli

Console

1. Nella console Google Cloud vai alla pagina IAM.

   Vai a IAM
2. Seleziona il progetto.
3. Fai clic su person_add Concedi l'accesso.

4. Nel campo Nuove entità, inserisci il tuo identificatore utente. In genere, si tratta dell'indirizzo email dell'Account Google utilizzato per il deployment del servizio Cloud Run.

5. Nell'elenco Seleziona un ruolo, seleziona un ruolo.
6. Per concedere altri ruoli, fai clic su add Aggiungi un altro ruolo e aggiungi ogni ruolo aggiuntivo.
7. Fai clic su Salva.

gcloud

Per concedere i ruoli IAM richiesti al tuo account nel tuo progetto:

        gcloud projects add-iam-policy-binding PROJECT_ID \
            --member=PRINCIPAL \
            --role=ROLE
        

Sostituisci:

• PROJECT_NUMBER con il numero del tuo progetto Google Cloud .
• PROJECT_ID con l'ID progetto Google Cloud .
• PRINCIPAL con l'account per cui stai aggiungendo il collegamento. In genere, si tratta dell'indirizzo email dell'Account Google utilizzato per il deployment del servizio Cloud Run.
• ROLE con il ruolo che stai aggiungendo all'account deployer.
4. Richiedi la quota Total Nvidia L4 GPU allocation, per project per region nell'API Cloud Run Admin nella pagina Quote e limiti di sistema.
5. Consulta la pagina Prezzi di Cloud Run. Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi.

Esegui il deployment di un modello Gemma con un container predefinito

Cloud Run fornisce un container predefinito per l'hosting dei modelli aperti Gemma su Cloud Run.

Per eseguire il deployment dei modelli Gemma su Cloud Run, utilizza il seguente comando gcloud CLI con le impostazioni consigliate:

gcloud run deploy SERVICE_NAME \
   --image us-docker.pkg.dev/cloudrun/container/gemma/GEMMA_PARAMETER \
   --concurrency 4 \
   --cpu 8 \
   --set-env-vars OLLAMA_NUM_PARALLEL=4 \
   --gpu 1 \
   --gpu-type nvidia-l4 \
   --max-instances 1 \
   --memory 32Gi \
   --no-allow-unauthenticated \
   --no-cpu-throttling \
   --timeout=600 \
   --region REGION

Sostituisci:

• SERVICE_NAME con un nome univoco per il servizio Cloud Run.

• GEMMA_PARAMETER con il modello Gemma che hai utilizzato:

  • Gemma 3 1B (gemma-3-1b-it): gemma3-1b
  • Gemma 3 4B (gemma-3-4b-it): gemma3-4b
  • Gemma 3 12B (gemma-3-12b-it): gemma3-12b
  • Gemma 3 27B (gemma-3-27b-it): gemma3-27b

  (Facoltativo) Sostituisci l'intero URL dell'immagine con un'immagine Docker che hai creato dal repository GitHub Gemma-on-Cloudrun.

• REGION con la regione Google Cloud in cui verrà eseguito il deployment di Cloud Run, ad esempio europe-west1. Se devi modificare la regione, consulta Configurazione GPU per scoprire le regioni supportate per i deployment abilitati per la GPU.

Le altre impostazioni sono le seguenti:

Opzione	Descrizione
--concurrency	Il numero massimo di richieste che possono essere elaborate contemporaneamente da una determinata istanza, ad esempio 4. Consulta la sezione Impostare la concorrenza per un rendimento ottimale per suggerimenti sulla latenza ottimale delle richieste.
--cpu	La quantità di CPU allocata per il tuo servizio, ad esempio 8.
--set-env-vars	Le variabili di ambiente impostate per il servizio. Ad esempio, OLLAMA_NUM_PARALLEL=4. Consulta la sezione Impostare la concorrenza per un rendimento ottimale per suggerimenti sulla latenza ottimale delle richieste.
--gpu	Il valore della GPU per il tuo servizio, ad esempio 1.
--gpu-type	Il tipo di GPU da utilizzare per il servizio, ad esempio nvidia-l4.
--max-instances	Il numero massimo di istanze di container per il servizio, ad esempio 1.
--memory	La quantità di memoria allocata per il tuo servizio, ad esempio 32Gi.
--no-invoker-iam-check	Disattiva i controlli IAM dell'invoker. Consulta la sezione Interagire in modo sicuro con Google Gen AI SDK per suggerimenti su come proteggere meglio la tua app.
--no-cpu-throttling	Questa impostazione disattiva la limitazione della CPU quando il container non gestisce attivamente le richieste.
--timeout	Il tempo entro il quale deve essere restituita una risposta, ad esempio 600 secondi.

Se devi modificare le impostazioni predefinite o aggiungere impostazioni più personalizzate al tuo servizio Cloud Run, consulta Configurare i servizi.

Al termine del servizio di cui è stato eseguito il deployment, viene visualizzato un messaggio di operazione riuscita insieme all'URL dell'endpoint Cloud Run che termina con run.app.

Testa il servizio Gemma di cui è stato eseguito il deployment con curl

Ora che hai eseguito il deployment del servizio Gemma, puoi inviargli richieste. Tuttavia, se invii una richiesta direttamente, Cloud Run risponde con HTTP 401 Unauthorized. Ciò è intenzionale, perché un'API di inferenza LLM è destinata ad essere chiamata da altri servizi, ad esempio un'applicazione frontend. Per ulteriori informazioni sull'autenticazione da servizio a servizio su Cloud Run, consulta Autenticazione da servizio a servizio.

Per inviare richieste al servizio Gemma, aggiungi un'intestazione con un token OIDC valido alle richieste, ad esempio utilizzando il proxy per sviluppatori di Cloud Run:

1. Avvia il proxy e, quando ti viene chiesto di installare il componente cloud-run-proxy, scegli Y:

   gcloud run services proxy ollama-gemma --port=9090

2. Invia una richiesta in una scheda del terminale separata, lasciando in esecuzione il proxy. Tieni presente che il proxy viene eseguito su localhost:9090:

   curl http://localhost:9090/api/generate -d '{
     "model": "gemma3:4b",
     "prompt": "Why is the sky blue?"
   }'

   Questo comando dovrebbe fornire un output di streaming simile a questo:

   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.641492408Z","response":"That","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.687529153Z","response":"'","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.753284927Z","response":"s","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.812957381Z","response":" a","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.889102649Z","response":" fantastic","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.925748116Z","response":",","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.958391572Z","response":" decept","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.971035028Z","response":"ively","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.989678484Z","response":" tricky","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.999321940Z","response":" question","done":false}
   ...
   

Interagire in modo sicuro con Google Gen AI SDK

Dopo aver eseguito il deployment del servizio Cloud Run, puoi utilizzare l'endpoint Cloud Run con l'SDK Google Gen AI.

Prima di utilizzare Google Gen AI SDK, assicurati che le richieste in entrata superino il token di identità appropriato. Per scoprire di più sull'utilizzo dell'autenticazione IAM e di Cloud Run, consulta Autenticazione da servizio a servizio.

Gli esempi seguenti mostrano come utilizzare l'SDK Google Gen AI con l'autenticazione IAM.

JavaScript o TypeScript

Se utilizzi l'SDK Google Gen AI per JavaScript e TypeScript, il codice potrebbe avere il seguente aspetto:

import { GoogleGenAI, setDefaultBaseUrls } from "@google/genai";
import { GoogleAuth} from 'google-auth-library'

const cloudrunurl = 'https://CLOUD_RUN_SERVICE_URL';
const targetAudience = url;

const auth = new GoogleAuth();

async function main() {

  const client = await auth.getIdTokenClient(targetAudience);
  const headers = await client.getRequestHeaders(targetAudience);
  const idToken = headers['Authorization']

const ai = new GoogleGenAI({
  apiKey:"placeholder",
  httpOptions: { baseUrl: url, headers: {'Authorization': idToken}  },
});

  const response = await ai.models.generateContent({
    model: "gemma-3-1b-it",
    contents: "I want a pony",
  });
  console.log(response.text);
}

main();

curl

Se utilizzi curl, esegui i seguenti comandi per raggiungere gli endpoint dell'SDK Google Gen AI:

• Per Genera contenuti, utilizza /v1beta/{model=models/*}:generateContent: genera una risposta del modello dato un input GenerateContentRequest.

  curl "<cloud_run_url>/v1beta/models/<model>:generateContent" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -X POST \
  -d '{
    "contents": [{
      "parts":[{"text": "Write a story about a magic backpack. You are the narrator of an interactive text adventure game."}]
      }]
      }'
  

• Per Stream Generate Content, utilizza /v1beta/{model=models/*}:streamGenerateContent: genera una risposta in streaming dal modello dato un input GenerateContentRequest.

  curl "<cloud_run_url>/v1beta/models/<model>:streamGenerateContent" \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
    -X POST \
    -d '{
      "contents": [{
        "parts":[{"text": "Write a story about a magic backpack. You are the narrator of an interactive text adventure game."}]
        }]
        }'
  

Impostare la concorrenza per un rendimento ottimale

Questa sezione fornisce il contesto delle impostazioni di concorrenza consigliate. Per una latenza delle richieste ottimale, assicurati che l'impostazione --concurrency sia uguale alla variabile di ambiente OLLAMA_NUM_PARALLEL di Ollama.

• OLLAMA_NUM_PARALLEL determina quanti slot di richiesta sono disponibili per ogni modello per gestire le richieste di inferenza contemporaneamente.
• --concurrency determina il numero di richieste che Cloud Run invia a un'istanza Ollama contemporaneamente.

Se --concurrency supera OLLAMA_NUM_PARALLEL, Cloud Run può inviare più richieste a un modello in Ollama rispetto agli slot di richiesta disponibili. Ciò comporta la creazione di code di richieste all'interno di Ollama, aumentando la latenza delle richieste in coda. Inoltre, la scalabilità automatica è meno reattiva, poiché le richieste in coda non attivano lo scale out di Cloud Run e l'avvio di nuove istanze.

Ollama supporta anche la pubblicazione di più modelli da una GPU. Per evitare completamente la coda delle richieste nell'istanza Ollama, devi comunque impostare --concurrency in modo che corrisponda a OLLAMA_NUM_PARALLEL.

È importante notare che l'aumento di OLLAMA_NUM_PARALLEL allunga anche i tempi di esecuzione delle richieste parallele.

Ottimizza l'utilizzo

Per un utilizzo ottimale della GPU, aumenta --concurrency, mantenendolo entro il doppio del valore di OLLAMA_NUM_PARALLEL. Sebbene ciò comporti la creazione di code di richieste in Ollama, può contribuire a migliorare l'utilizzo: le istanze Ollama possono elaborare immediatamente le richieste dalla coda e le code aiutano ad assorbire i picchi di traffico.

Esegui la pulizia

Elimina le seguenti risorse Google Cloud create:

• Servizio Cloud Run
• Immagine container

Passaggi successivi

• Configurare la GPU
• Best practice: inferenza dell'AI su Cloud Run con le GPU
• Eseguire i modelli Gemma 3 con vari framework di runtime AI