Execute o Gemma 3 no Cloud Run

Este guia descreve como implementar os modelos abertos Gemma 3 no Cloud Run através de um contentor pré-criado e fornece orientações sobre a utilização do serviço do Cloud Run implementado com o SDK de IA gen da Google.

Antes de começar

Se usou o Google AI Studio para implementar no Cloud Run, avance para a secção Interaja em segurança com o SDK de IA gen da Google.

Se não usou o Google AI Studio, siga estes passos antes de usar o Cloud Run para criar um novo serviço.

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.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify 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.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Configure o ambiente de programação do Cloud Run no seu Google Cloud projeto.
2. Instale e inicialize a CLI gcloud.
3. Certifique-se de que tem as seguintes funções do IAM concedidas à sua conta:
   • Administrador do Cloud Run (roles/run.admin)
   • Project IAM Admin (roles/resourcemanager.projectIamAdmin)
   • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

Saiba como conceder as funções

Consola

1. Na Google Cloud consola, aceda à página IAM.

   Aceda ao IAM
2. Selecione o projeto.
3. Clique em Conceder acesso.

4. No campo Novos responsáveis, introduza o identificador do utilizador. Normalmente, este é o endereço de email da Conta Google usado para implementar o serviço do Cloud Run.

5. Na lista Selecionar uma função, selecione uma função.
6. Para conceder funções adicionais, clique em Adicionar outra função e adicione cada função adicional.
7. Clique em Guardar.

gcloud

Para conceder as funções de IAM necessárias à sua conta no seu projeto:

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

Substituição:

• PROJECT_NUMBER com o número do seu projeto. Google Cloud
• PROJECT_ID com o ID do seu Google Cloud projeto.
• PRINCIPAL com a conta à qual está a adicionar a associação. Normalmente, trata-se do endereço de email da Conta Google que é usado para implementar o serviço do Cloud Run.
• ROLE com a função que está a adicionar à conta do implementador.
4. Peça Total Nvidia L4 GPU allocation, per project per region quota na API Cloud Run Admin na página Quotas e limites do sistema.
5. Reveja a página de preços do Cloud Run. Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Implemente um modelo Gemma com um contentor pré-criado

O Cloud Run fornece um contentor pré-criado para publicar modelos abertos Gemma no Cloud Run.

Para implementar modelos Gemma no Cloud Run, use o seguinte comando da CLI gcloud com as definições recomendadas:

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 \
   --no-gpu-zonal-redundancy \
   --timeout=600 \
   --region REGION

Substituição:

• SERVICE_NAME com um nome exclusivo para o serviço do Cloud Run.

• GEMMA_PARAMETER com o modelo Gemma que usou:

  • 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

  Opcionalmente, substitua o URL da imagem completo por uma imagem do Docker que criou a partir do repositório do GitHub do Gemma no Cloud Run.

• REGION com a Google Cloud região onde o Cloud Run vai ser implementado, como europe-west1. Se precisar de modificar a região, consulte a secção Configuração da GPU para saber mais sobre as regiões suportadas para implementações com GPU.

As outras definições são as seguintes:

Opção	Descrição
--concurrency	O número máximo de pedidos que podem ser processados em simultâneo por uma determinada instância, como 4. Consulte o artigo Defina a simultaneidade para um desempenho ideal para ver recomendações sobre a latência de pedidos ideal.
--cpu	A quantidade de CPU alocada para o seu serviço, como 8.
--set-env-vars	As variáveis de ambiente definidas para o seu serviço. Por exemplo, OLLAMA_NUM_PARALLEL=4. Consulte o artigo Defina a simultaneidade para um desempenho ideal para ver recomendações sobre a latência de pedidos ideal.
--gpu	O valor da GPU para o seu serviço, como 1.
--gpu-type	O tipo de GPU a usar para o seu serviço, como nvidia-l4.
--max-instances	O número máximo de instâncias de contentores para o seu serviço, como 1.
--memory	A quantidade de memória alocada para o seu serviço, como 32Gi.
--no-invoker-iam-check	Desative as verificações de IAM do invocador. Consulte o artigo Interaja de forma segura com o SDK de IA gen da Google para ver recomendações sobre como proteger melhor a sua app.
--no-cpu-throttling	Esta definição desativa a limitação do CPU quando o contentor não está a processar ativamente pedidos.
--timeout	O tempo dentro do qual uma resposta tem de ser devolvida, como 600 segundos.

Se precisar de modificar as predefinições ou adicionar definições mais personalizadas ao seu serviço do Cloud Run, consulte o artigo Configurar serviços.

Após a conclusão do serviço implementado, é apresentada uma mensagem de êxito juntamente com o URL do ponto final do Cloud Run que termina com run.app.

Teste o serviço Gemma implementado com o curl

Agora que implementou o serviço Gemma, pode enviar-lhe pedidos. No entanto, se enviar um pedido diretamente, o Cloud Run responde com HTTP 401 Unauthorized. Isto é intencional, porque uma API de inferência de MDG destina-se a ser chamada por outros serviços, como uma aplicação de front-end. Para mais informações sobre a autenticação de serviço a serviço no Cloud Run, consulte o artigo Autenticação de serviço a serviço.

Para enviar pedidos ao serviço Gemma, adicione um cabeçalho com um token OIDC válido aos pedidos, por exemplo, através do proxy do programador do Cloud Run:

1. Inicie o proxy e, quando lhe for pedido para instalar o componente cloud-run-proxy Y, escolha:

   gcloud run services proxy SERVICE_NAME --port=9090

2. Execute o seguinte comando para enviar um pedido num separador do terminal separado, deixando o proxy em execução. O proxy é executado em localhost:9090. Especifique o modelo Gemma que usou anteriormente:

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

   Este comando deve fornecer um resultado de streaming semelhante ao seguinte:

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

   Êxito: implementou um serviço do Cloud Run com GPUs ativadas e o Gemma 3, e enviou-lhe um pedido de inferência.

Interaja de forma segura com o SDK Google Gen AI

Depois de implementar o seu serviço do Cloud Run, pode usar o ponto final do Cloud Run com o SDK de IA gen da Google.

Antes de usar o SDK de IA gen da Google, certifique-se de que os pedidos recebidos transmitem o token de identidade adequado. Para saber mais sobre a utilização da autenticação IAM e do Cloud Run, consulte o artigo Autenticação de serviço a serviço.

Os exemplos seguintes mostram como usar o SDK de IA gen da Google com a autenticação IAM.

JavaScript ou TypeScript

Se estiver a usar o SDK de IA gen da Google para Javascript e TypeScript, o código pode ter o seguinte aspeto:

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 estiver a usar o curl, execute os seguintes comandos para aceder aos endpoints do SDK de IA gen da Google:

• Para gerar conteúdo, use /v1beta/{model=models/*}:generateContent: gera uma resposta do modelo com base numa entrada 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."}]
      }]
      }'
  

• Para conteúdo gerado por stream, use /v1beta/{model=models/*}:streamGenerateContent: gera uma resposta transmitida a partir do modelo, dado um GenerateContentRequest de entrada.

  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."}]
        }]
        }'
  

Defina a simultaneidade para um desempenho ideal

Esta secção fornece contexto sobre as definições de concorrência recomendadas. Para uma latência de pedido ideal, certifique-se de que a definição --concurrency é igual à variável de ambiente OLLAMA_NUM_PARALLEL do Ollama.

• OLLAMA_NUM_PARALLEL determina quantos espaços de pedidos estão disponíveis por cada modelo para processar pedidos de inferência em simultâneo.
• --concurrency determina quantos pedidos o Cloud Run envia a uma instância do Ollama em simultâneo.

Se --concurrency exceder OLLAMA_NUM_PARALLEL, o Cloud Run pode enviar mais pedidos a um modelo no Ollama do que tem espaços de pedidos disponíveis. Isto leva à colocação em fila de pedidos no Ollama, o que aumenta a latência dos pedidos em fila. Também leva a um dimensionamento automático menos reativo, uma vez que os pedidos em fila não acionam o Cloud Run para aumentar a escala e iniciar novas instâncias.

O Ollama também suporta a publicação de vários modelos a partir de uma GPU. Para evitar completamente a colocação em fila de pedidos na instância do Ollama, deve continuar a definir --concurrency de modo a corresponder a OLLAMA_NUM_PARALLEL.

É importante ter em atenção que o aumento de OLLAMA_NUM_PARALLEL também faz com que os pedidos paralelos demorem mais tempo.

Otimize a utilização

Para uma utilização da GPU ideal, aumente o valor de --concurrency, mantendo-o dentro do dobro do valor de OLLAMA_NUM_PARALLEL. Embora isto leve a filas de pedidos no Ollama, pode ajudar a melhorar a utilização: as instâncias do Ollama podem processar imediatamente pedidos da respetiva fila, e as filas ajudam a absorver picos de tráfego.

Limpar

Elimine os seguintes Google Cloud recursos criados:

• Serviço do Cloud Run
• Imagem do contentor

O que se segue?

• Configurar GPU
• Práticas recomendadas: inferência de IA no Cloud Run com GPUs
• Execute modelos Gemma 3 com várias frameworks de tempo de execução de IA
• Implemente o seu agente ADK no Cloud Run com GPU