Executar o Gemma 3 no Cloud Run

Este guia descreve como implantar os modelos abertos do Gemma 3 no Cloud Run usando um contêiner pré-criado e fornece orientações sobre como usar o serviço implantado do Cloud Run com o SDK da IA generativa do Google.

Antes de começar

Se você usou o Google AI Studio para fazer a implantação no Cloud Run, pule para a seção Interagir com segurança com o SDK da IA generativa do Google.

Se você não usou o Google AI Studio, siga estas etapas antes de usar o Cloud Run para criar um novo serviço.

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

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

    Go to project selector

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

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

    Go to project selector

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

  6. Configure o ambiente de desenvolvimento do Cloud Run no seu projeto do Google Cloud .
  7. Instale e inicialize a gcloud CLI.
  8. Verifique se sua conta tem os seguintes papéis do IAM:

    9. Saiba como conceder os papéis

    Console

    1. No console Google Cloud , acesse a página IAM.

      Acessar o IAM
    2. Selecione o projeto.
    3. Clique em CONCEDER ACESSO.

    4. No campo Novos principais, insira seu identificador de usuário. Normalmente, esse é o endereço de e-mail da Conta do Google usado para implantar o serviço do Cloud Run.

    5. Na lista Selecionar um papel, escolha um.
    6. Para conceder outros papéis, clique em Adicionar outro papel e adicione cada papel adicional.
    7. Clique em Salvar.

    gcloud

    Para conceder os papéis do IAM necessários à sua conta no projeto:

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

    Substitua:

    • PROJECT_NUMBER pelo número do projeto Google Cloud .
    • PROJECT_ID com seu Google Cloud ID do projeto.
    • PRINCIPAL com a conta a que você está adicionando a vinculação. Normalmente, é o endereço de e-mail da Conta do Google usado para implantar o serviço do Cloud Run.
    • ROLE com o papel que você está adicionando à conta do implantador.
  9. Solicite a cota Total Nvidia L4 GPU allocation, per project per region na API Cloud Run Admin na página Cotas e limites do sistema.
  10. Consulte a página de preços do Cloud Run. Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.

    11. Implantar um modelo Gemma com um contêiner pré-criado

    O Cloud Run oferece um contêiner pré-criado para disponibilizar modelos abertos do Gemma no Cloud Run.

    Para implantar modelos da Gemma no Cloud Run, use o seguinte comando da CLI gcloud com as configuraçõ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

    Substitua:

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

    • GEMMA_PARAMETER com o modelo do Gemma que você 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

      Se quiser, substitua todo o URL da imagem por uma imagem do Docker criada no repositório do GitHub Gemma-on-Cloudrun.

    • REGION pela região Google Cloud em que o Cloud Run será implantado, como europe-west1. Se você precisar modificar a região, consulte Configuração de GPU para saber mais sobre as regiões compatíveis com implantações habilitadas para GPU.

    As outras configurações são:

    Opção Descrição
    --concurrency

    O número máximo de solicitações que podem ser processadas simultaneamente por uma determinada instância, como 4. Consulte Definir a simultaneidade para performance ideal e veja recomendações sobre a latência ideal de solicitação.
    --cpu

    A quantidade de CPU alocada para seu serviço, como 8.
    --set-env-vars

    As variáveis de ambiente definidas para seu serviço. Por exemplo, OLLAMA_NUM_PARALLEL=4. Consulte Definir a simultaneidade para performance ideal e veja recomendações sobre a latência ideal de solicitação.
    --gpu

    O valor da GPU do seu serviço, como 1.
    --gpu-type

    O tipo de GPU a ser usado no seu serviço, como nvidia-l4.
    --max-instances

    O número máximo de instâncias de contêiner para seu serviço, como 1.
    --memory

    A quantidade de memória alocada para seu serviço, como 32Gi.
    --no-invoker-iam-check

    Desative as verificações do IAM do invocador. Consulte Interagir com segurança com o SDK do Google Gen AI para conferir recomendações sobre como proteger melhor seu app.
    --no-cpu-throttling

    Essa configuração desativa a limitação de CPU quando o contêiner não está atendendo solicitações ativamente.
    --timeout

    O tempo em que uma resposta precisa ser retornada, como 600 segundos.

    Se você precisar modificar as configurações padrão ou adicionar configurações mais personalizadas ao serviço do Cloud Run, consulte Configurar serviços.

    Após a conclusão do serviço implantado, uma mensagem de sucesso será exibida com o URL do endpoint do Cloud Run que termina com run.app.

    Testar o serviço Gemma implantado com curl

    Agora que você implantou o serviço Gemma, é possível enviar solicitações para ele. No entanto, se você enviar uma solicitação diretamente, o Cloud Run responderá com HTTP 401 Unauthorized. Isso é intencional, porque uma API de inferência de LLM é destinada a outros serviços para chamada, como um aplicativo de front-end. Para mais informações sobre serviços no Cloud Run, consulte Como autenticar serviço a serviço.

    Para enviar solicitações ao serviço do Gemma, adicione um cabeçalho com um token OIDC válido às solicitações, por exemplo, usando o proxy de desenvolvedor do Cloud Run:

    1. Inicie o proxy e, quando solicitado a instalar o componente cloud-run-proxy, escolha Y:

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

    2. Envie uma solicitação para ele em uma guia de terminal separada, deixando o proxy em execução. Observe que o proxy é executado em localhost:9090:

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

      O comando vai 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}
...

    Interagir com segurança com o SDK da IA generativa do Google

    Depois de implantar o serviço do Cloud Run, use o endpoint dele com o SDK da IA generativa do Google.

    Antes de usar o SDK da IA generativa do Google, verifique se as solicitações recebidas transmitem o token de identidade adequado. Para saber mais sobre o uso da autenticação do IAM e do Cloud Run, consulte Como autenticar serviço a serviço.

    Os exemplos a seguir mostram como usar o SDK da IA generativa do Google com autenticação do IAM.

    JavaScript ou TypeScript

    Se você estiver usando o SDK da IA generativa do Google para JavaScript e TypeScript, o código poderá ter esta aparência:

    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 você estiver usando curl, execute os seguintes comandos para acessar os endpoints do SDK de IA generativa do Google:

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

    Definir a simultaneidade para ter uma performance ideal

    Nesta seção, fornecemos contexto sobre as configurações de simultaneidade recomendadas. Para uma latência de solicitação ideal, verifique se a configuração --concurrency é igual à variável de ambiente OLLAMA_NUM_PARALLEL do Ollama.

    • OLLAMA_NUM_PARALLEL determina quantos slots de solicitação estão disponíveis para cada modelo para processar solicitações de inferência simultaneamente.
    • O --concurrency determina quantas solicitações o Cloud Run envia para uma instância do Ollama ao mesmo tempo.

    Se --concurrency exceder OLLAMA_NUM_PARALLEL, o Cloud Run poderá enviar mais solicitações a um modelo em Ollama do que os slots disponíveis para ele. Isso leva à formação de filas de solicitações no Ollama, aumentando a latência das solicitações na fila. Isso também leva a um escalonamento automático menos responsivo, já que as solicitações em fila não acionam o Cloud Run para escalonar horizontalmente e iniciar novas instâncias.

    O Ollama também oferece suporte à exibição de vários modelos de uma GPU. Para evitar completamente a fila de solicitações na instância do Ollama, defina --concurrency para corresponder a OLLAMA_NUM_PARALLEL.

    É importante observar que aumentar OLLAMA_NUM_PARALLEL também faz com que as solicitações paralelas demorem mais.

    Utilização otimizada

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

    Limpar

    Exclua os seguintes recursos do Google Cloud criados:

    A seguir