IA sem servidor: EmbeddingGemma com o Cloud Run

1. Introdução

Neste codelab, você vai aprender a implantar o EmbeddingGemma, um modelo de embedding de texto multilíngue avançado, no Cloud Run usando GPUs. Em seguida, você vai usar esse serviço implantado para gerar embeddings para um app de pesquisa semântica.

Ao contrário dos modelos de linguagem grandes (LLMs) tradicionais que geram texto, os modelos de embedding convertem texto em vetores numéricos. Esses vetores são essenciais para criar sistemas de geração aumentada por recuperação (RAG), que permitem encontrar os documentos mais relevantes para a consulta de um usuário.

Atividades deste laboratório

• Coloque o modelo EmbeddingGemma em um contêiner usando o Ollama.
• Implante o contêiner no Cloud Run com aceleração de GPU.
• Teste o modelo implantado gerando embeddings para um texto de amostra.
• Crie um sistema de pesquisa semântica leve usando o serviço implantado.

O que é necessário

• Ter um projeto do Google Cloud com o faturamento ativado.
• Conhecimento básico do Docker e da linha de comando.

2. Antes de começar

Configuração do projeto

1. Se você ainda não tiver uma Conta do Google, crie uma.
   • Use uma conta pessoal em vez de uma conta escolar ou de trabalho. As contas escolares e de trabalho podem ter restrições que impedem a ativação das APIs necessárias para este laboratório.
2. Faça login no Console do Google Cloud.
3. Ative o faturamento no console do Cloud.
   • A conclusão deste laboratório custa menos de US $1 em recursos do Cloud.
   • Siga as etapas no final deste laboratório para excluir recursos e evitar mais cobranças.
   • Novos usuários podem aproveitar o teste sem custos financeiros de US$300.
4. Crie um projeto ou reutilize um projeto existente.
   • Se você receber um erro sobre a cota do projeto, reutilize ou exclua um projeto para criar outro.

Iniciar o Cloud Shell

O Cloud Shell é um ambiente de linha de comando executado no Google Cloud que vem pré-carregado com as ferramentas necessárias.

1. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.
2. Depois de se conectar ao Cloud Shell, verifique sua autenticação:

   gcloud auth list
   

3. Confirme se o projeto está selecionado:

   gcloud config get project
   

4. Defina, se necessário:

   gcloud config set project <YOUR_PROJECT_ID>
   

Ativar APIs

Execute este comando para ativar todas as APIs necessárias:

gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com

3. Conteinerizar o modelo

Para executar o EmbeddingGemma sem servidor, precisamos empacotá-lo em um contêiner. Vamos usar o Ollama, um framework leve para executar LLMs, e o Docker.

Criar o Dockerfile

No Cloud Shell, crie um diretório para seu projeto e navegue até ele:

mkdir embedding-gemma-codelab
cd embedding-gemma-codelab

Crie um arquivo chamado Dockerfile com o conteúdo a seguir:

FROM ollama/ollama:latest

# Listen on all interfaces, port 8080
ENV OLLAMA_HOST=0.0.0.0:8080

# 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=embeddinggemma:latest
RUN ollama serve & sleep 5 && ollama pull $MODEL

# Start Ollama
ENTRYPOINT ["ollama", "serve"]

Esse Dockerfile faz o seguinte:

1. Começa com a imagem base oficial do Ollama.
2. Configura o Ollama para detectar na porta 8080 (padrão do Cloud Run).
3. O comando RUN inicia o servidor ollama e baixa o modelo embeddinggemma durante o processo de build para que ele seja incorporado à imagem.
4. Define OLLAMA_KEEP_ALIVE=-1 para garantir que o modelo permaneça carregado na memória da GPU para solicitações subsequentes mais rápidas.

4. Criar e implantar

Vamos usar a implantação de origem do Cloud Run para criar e implantar nosso contêiner em uma única etapa. Esse comando cria a imagem usando o Cloud Build, armazena no Artifact Registry e implanta no Cloud Run.

Execute o comando a seguir para implantar:

gcloud run deploy embedding-gemma \
  --source . \
  --region europe-west1 \
  --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 \
  --labels dev-tutorial=codelab-embedding-gemma

Observação:essa implantação pode levar alguns minutos, já que extrai os pesos do modelo e cria o contêiner. Se esta for sua primeira vez usando a implantação de origem do Cloud Run, talvez seja necessário criar um repositório do Artifact Registry. Responda y para continuar.

Como entender a configuração

• --source . especifica o diretório atual como a origem do build.
• --region europe-west1 usamos uma região compatível com GPUs no Cloud Run.
• --concurrency 4 está definido para corresponder ao valor da variável de ambiente OLLAMA_NUM_PARALLEL.
• --gpu 1 com --gpu-type nvidia-l4 atribui uma GPU NVIDIA L4 a cada instância do Cloud Run no serviço.
• --max-instances 1 especifica o número máximo de instâncias para escalonar. Ela precisa ser igual ou menor que a cota de GPU NVIDIA L4 do seu projeto.
• --no-allow-unauthenticated restringe o acesso não autenticado ao serviço. Ao manter o serviço privado, você pode confiar na autenticação integrada do Identity and Access Management (IAM) do Cloud Run para comunicação entre serviços.
• --no-cpu-throttling é necessário para ativar a GPU.
• --no-gpu-zonal-redundancy defina as opções de redundância zonal de acordo com os requisitos de failover zonal e a cota disponível.

Considerações sobre regiões

As GPUs no Cloud Run estão disponíveis em regiões específicas. Confira as regiões disponíveis na documentação.

Saída da implantação

Após alguns minutos, a implantação será concluída e você vai receber uma mensagem como esta:

Service [embedding-gemma] revision [embedding-gemma-12345-abc] has been deployed and is serving 100 percent of traffic.
Service URL: https://embedding-gemma-123456789012.europe-west1.run.app

Observação:se você tentar acessar o URL diretamente, vai aparecer "Erro 403: proibido" porque seu serviço exige autenticação.

5. Testar a implantação

Como implantamos o serviço com --no-allow-unauthenticated, não podemos simplesmente curl o URL público. Primeiro, precisamos conceder a nós mesmos permissão para acessar o serviço e usar o token de autenticação na solicitação.

1. Conceda à sua conta de usuário permissão para chamar o serviço:

   gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
       --member=user:$(gcloud config get-value account) \
       --role='roles/run.invoker'
   

2. Salve suas credenciais do Google Cloud e o número do projeto em variáveis de ambiente para usar na solicitação:

   export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)")
   export ID_TOKEN=$(gcloud auth print-identity-token)
   

3. Execute o comando a seguir para gerar uma incorporação do texto "Sample text":

   curl -X POST "https://embedding-gemma-$PROJECT_NUMBER.europe-west1.run.app/api/embed" \
       -H "Authorization: Bearer $ID_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
           "model": "embeddinggemma",
           "input": "Sample text"
       }'
   

Você vai ver uma resposta JSON contendo um vetor (uma longa lista de números) no campo embedding. Isso confirma que seu modelo de incorporação sem servidor com suporte de GPU está funcionando.

A resposta será parecida com esta:

Cliente Python

Também é possível usar o Python para interagir com o serviço. Crie um arquivo chamado test_client.py:

import urllib.request
import urllib.parse
import json
import os

# 1. Setup the URL and Payload
url = f"https://embedding-gemma-{os.environ['PROJECT_NUMBER']}.europe-west1.run.app/api/embed"
payload = {
    "model": "embeddinggemma",
    "input": "Sample text"
}

# 2. Create the Request object
# Note: Providing 'data' automatically makes this a POST request
req = urllib.request.Request(
    url,
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['ID_TOKEN']}",
        "Content-Type": "application/json"
    }
)

# 3. Execute and print the response
response = urllib.request.urlopen(req)
result = json.loads(response.read().decode("utf-8"))
print(result)

Execute:

python test_client.py

6. Criar um aplicativo de pesquisa semântica

Agora que temos um serviço de embedding funcionando, vamos criar um aplicativo simples de pesquisa semântica. Vamos usar os embeddings gerados para encontrar o documento mais relevante para uma determinada consulta.

Dependências

Vamos usar o chromadb como banco de dados vetorial e a biblioteca de cliente ollama.

uv init semantic-search --description "Semantic Search Application"
cd semantic-search
uv add chromadb ollama

Criar o app de pesquisa

Crie um arquivo chamado semantic_search.py com o seguinte código:

import ollama
import chromadb
import os

# 1. Define our knowledge base
documents = [
    "Poland is a country located in Central Europe.",
    "The capital and largest city of Poland is Warsaw.",
    "Poland's official language is Polish, which is a West Slavic language.",
    "Marie Curie, the pioneering scientist who conducted groundbreaking research on radioactivity, was born in Warsaw, Poland.",
    "Poland is famous for its traditional dish called pierogi, which are filled dumplings.",
    "The Białowieża Forest in Poland is one of the last and largest remaining parts of the immense primeval forest that once stretched across the European Plain.",
]

print("Initializing Vector Database...")
client = chromadb.Client()
collection = client.create_collection(name="docs")

# Configure the client to point to our Cloud Run proxy
ollama_client = ollama.Client(
    host=f"https://embedding-gemma-{os.environ['PROJECT_NUMBER']}.europe-west1.run.app",
    headers={'Authorization': 'Bearer ' + os.environ['ID_TOKEN']}
)

print("Generating embeddings and indexing documents...")
# 2. Store each document in the vector database
for i, d in enumerate(documents):
    # This calls our Cloud Run service to get the embedding
    response = ollama_client.embed(model="embeddinggemma", input=d)
    embeddings = response["embeddings"]
    collection.add(ids=[str(i)], embeddings=embeddings, documents=[d])

print("Indexing complete.\n")

# 3. Perform a Semantic Search
question = "What is Poland's official language?"
print(f"Query: {question}")

# Generate an embedding for the question
response = ollama_client.embed(model="embeddinggemma", input=question)

# Query the database for the most similar document
results = collection.query(
    query_embeddings=[response["embeddings"][0]],
    n_results=1
)

best_match = results["documents"][0][0]
print(f"Best Match Document: {best_match}")

Execute o aplicativo

Execute o script a seguir:

uv run semantic_search.py

Observação:se você receber um erro como KeyError: 'ID_TOKEN' ou KeyError: 'PROJECT_NUMBER', isso significa que você esqueceu de definir a variável de ambiente ID_TOKEN ou PROJECT_NUMBER. Execute export ID_TOKEN=$(gcloud auth print-identity-token) e export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)") para definir.

Será exibida uma saída semelhante a esta:

Initializing Vector Database...
Generating embeddings and indexing documents...
Indexing complete.

Query: What is Poland's official language?
Best Match Document: Poland's official language is Polish, which is a West Slavic language.

Este script demonstra o núcleo de um sistema RAG: usar o serviço EmbeddingGemma sem servidor para converter documentos e consultas em vetores, permitindo encontrar as informações exatas necessárias para responder à pergunta de um usuário.

7. Limpar

Para evitar cobranças contínuas na sua conta do Google Cloud, exclua os recursos criados durante este codelab.

Excluir o serviço do Cloud Run

gcloud run services delete embedding-gemma --region europe-west1 --quiet

Excluir a imagem do contêiner

gcloud artifacts docker images delete \
    europe-west1-docker.pkg.dev/${GOOGLE_CLOUD_PROJECT}/cloud-run-source-deploy/embedding-gemma \
    --quiet

Aviso:verifique novamente o caminho do Artifact Registry se o comando acima falhar, já que o nome do repositório pode variar um pouco dependendo das configurações exatas de implantação. Dica: use gcloud artifacts docker images list $REPO_PATH para listar imagens nos repositórios de artefatos.

8. Parabéns

Parabéns! Você implantou o EmbeddingGemma no Cloud Run com GPUs e o usou para alimentar um aplicativo de pesquisa semântica.

Agora você tem uma base escalonável e sem servidor para criar aplicativos de IA que exigem a compreensão do significado do texto.

O que você aprendeu

• Como conteinerizar um modelo do Ollama com o Docker.
• Como implantar um serviço habilitado para GPU no Cloud Run.
• Como usar o modelo implantado para pesquisa semântica (RAG).

Próximas etapas

• Conheça outros modelos da família Gemma.
• Saiba mais sobre GPUs do Cloud Run.
• Confira outros codelabs do Cloud Run.
• Crie um pipeline de RAG completo conectando esta etapa de recuperação a um modelo generativo.

Documentos de referência

• Card de modelo do EmbeddingGemma
• Documentação do Ollama