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.

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.

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)
   • Consumidor de utilização do serviço (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 person_add 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 add 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
        

Substituir:

• PROJECT_NUMBER com o número do seu projeto. Google Cloud
• PROJECT_ID com o seu Google Cloud ID do projeto.
• PRINCIPAL com a conta à qual está a adicionar a associação. Normalmente, este é o 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 uma quota Total Nvidia L4 GPU allocation, per project per region 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 \
   --timeout=600 \
   --region REGION

Substituir:

• 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 da 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 para serviço no Cloud Run, consulte o artigo Autenticação de serviço para 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. Envie-lhe um pedido num separador do terminal separado, deixando o proxy em execução. Tenha em atenção que o proxy é executado em localhost:9090:

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

   Este comando deve fornecer uma saída de streaming semelhante a esta:

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

Interaja de forma segura com o SDK de IA gen da Google

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 pedidos 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 a uma 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 uma fila 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