Guia de início rápido: criar e implantar um app da Web em Python (LangChain) no Cloud Run

Com o Cloud Run, você cria e implanta aplicativos LangChain que usam o Gemini para responder a consultas. Neste guia de início rápido, você vai implantar um app da Web em Python que responde a perguntas sobre capitais. O Cloud Run cria automaticamente o contêiner quando você implanta do código-fonte.

Antes de começar

  1. Instale a CLI do Google Cloud.

  2. Configure a CLI gcloud para usar sua identidade federada.

    Para mais informações, consulte Fazer login na CLI gcloud com sua identidade federada.

  3. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  4. Crie ou selecione um projeto do Cloud de Confiance .

    Papéis necessários para selecionar ou criar um projeto

    • Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

    • Crie um projeto do Cloud de Confiance :

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o projeto do Cloud de Confiance que você está criando.

    • Selecione o projeto Cloud de Confiance que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Cloud de Confiance .

  5. Se este guia estiver usando um projeto atual, verifique se você tem as permissões necessárias para concluir o guia. Se você criou um projeto, já tem as permissões necessárias.

  6. Verifique se o faturamento está ativado para o projeto do Cloud de Confiance .

  7. Se você precisa seguir uma política da organização de restrição de domínio que restringe invocações não autenticadas para seu projeto, será necessário acessar o serviço implantado, conforme descrito em Como testar serviços particulares.

  8. Ative as APIs Cloud Run Admin e Cloud Build, se ainda não estiverem ativadas:

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis. 

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

    Depois que a API Cloud Run Admin for ativada, a conta de serviço padrão do Compute Engine será criadas automaticamente.

  9. Consulte os preços do Cloud Run ou faça uma estimativa de custos com a calculadora de preços.
  10. Você precisa de uma chave de API do Google AI Studio para implantar o app LangChain com um modelo do Gemini. Para gerar uma chave de API usando o Google AI Studio, consulte Como usar chaves da API Gemini na documentação da API Gemini. Você vai referenciar essa chave ao implantar o serviço.

Funções exigidas

Para conseguir as permissões necessárias para concluir o guia de início rápido, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Conceder acesso à conta de serviço do Cloud Build ao seu projeto

O Cloud Build usa automaticamente a conta de serviço padrão do Compute Engine como a conta de serviço padrão do Cloud Build para criar seu código-fonte e o recurso do Cloud Run, a menos que você substitua esse comportamento.

Para que o Cloud Build crie suas origens, conceda à conta de serviço do Cloud Build o papel Builder do Cloud Run (roles/run.builder) no seu projeto:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
    --role=roles/run.builder

Substitua PROJECT_ID pelo ID do projeto do Cloud de Confiance e SERVICE_ACCOUNT_EMAIL_ADDRESS pelo endereço de e-mail da conta de serviço do Cloud Build. Se você estiver usando a conta de serviço padrão do Compute Engine como a conta de serviço do Cloud Build, use o seguinte formato para o endereço de e-mail da conta de serviço:

PROJECT_NUMBER-compute@developer.s3ns-system.iam.gserviceaccount.com

Substitua PROJECT_NUMBER pelo número do projeto do Cloud de Confiance.

Para instruções detalhadas sobre como encontrar o ID do projeto e o número do projeto, consulte Criar e gerenciar projetos.

A concessão da função de builder do Cloud Run leva alguns minutos para se propagar.

Crie o aplicativo de exemplo

Para escrever um aplicativo em Python:

  1. Crie um novo diretório com o nome langchain-gemini-fastapi-app e altere o diretório nele:

    mkdir langchain-gemini-fastapi-app
cd langchain-gemini-fastapi-app

  2. Crie um arquivo chamado main.py e cole o seguinte código nele:

    import os
import uvicorn
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from langchain_google_genai import ChatGoogleGenerativeAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

# Initialize FastAPI
app = FastAPI(title="LangChain Gemini Cloud Run App")

# 1. Setup Gemini Model
# We expect GOOGLE_API_KEY to be set in the environment variables
llm = ChatGoogleGenerativeAI(
  model="gemini-2.5-flash",
  temperature=0.7
)

# 2. Define the Chain
prompt = ChatPromptTemplate.from_template("You are a helpful assistant. Answer the following question concisely: {topic}")
output_parser = StrOutputParser()

# Chain: Prompt -> Model -> String Parser
chain = prompt | llm | output_parser

# 3. Define Request Model
class QueryRequest(BaseModel):
  topic: str

# 4. Define Endpoint
@app.post("/chat")
async def chat(request: QueryRequest):
  try:
      response = await chain.ainvoke({"topic": request.topic})
      return {"response": response}
  except Exception as e:
      raise HTTPException(status_code=500, detail=str(e))

@app.get("/")
def health_check():
  return {"status": "ok", "service": "Gemini-FastAPI"}

  3. Crie um arquivo chamado requirements.txt e cole o seguinte código nele:

    fastapi
uvicorn
langchain
langchain-google-genai
python-dotenv

Implantar no Cloud Run da origem

A implantação a partir da origem cria automaticamente uma imagem de contêiner com base no código-fonte e a implanta.

Para implantar a partir da origem, use o seguinte comando:

  gcloud run deploy gemini-fastapi-service \
    --source . \
    --region us-central1 \
    --no-allow-unauthenticated \
    --set-env-vars GEMINI_API_KEY=API_KEY

Substitua API_KEY pela sua chave de API do Google AI Studio. Para produção, recomendamos usar o Secret Manager para processar a chave de API, em vez de variáveis de ambiente simples.

O Cloud Run mostra o URL do serviço, como https://gemini-fastapi-service-xyz-uc.a.run.app, depois que você implanta o app.

Testar o serviço do Cloud Run

Teste o serviço enviando uma consulta ao agente usando o seguinte comando curl:

  curl -X POST YOUR-SERVICE-URL/chat \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
    -d '{"topic": "What is the capital of France?"}'

Substitua YOUR-SERVICE-URL pelo URL do serviço.

O agente envia a seguinte resposta:

  {
  "response": "Paris"
  }

Para verificar se o serviço está funcionando corretamente, confira a guia Registros do serviço do Cloud Run.

Limpar

Para evitar cobranças na conta do Cloud de Confiance pelos recursos usados nesta página, exclua o projeto do Cloud de Confiance e os recursos.

Para evitar cobranças extras na sua conta do Cloud de Confiance by S3NS , exclua todos os recursos implantados com este guia de início rápido.

Excluir o repositório

O Cloud Run não gera cobranças quando o serviço implantado não está em uso. No entanto, é possível que você ainda receba cobranças pelo armazenamento da imagem do contêiner no Artifact Registry. Para excluir repositórios do Artifact Registry, siga as etapas em Excluir repositórios na documentação do Artifact Registry.

Excluir o serviço

Os serviços do Cloud Run não geram custos até receberem solicitações. Para excluir o serviço do Cloud Run, siga uma destas etapas:

Console

Para excluir um serviço, realize as etapas a seguir:

  1. No console do Cloud de Confiance by S3NS , acesse a página Serviços do Cloud Run:

    Acessar o Cloud Run

  2. Localize o serviço que você quer excluir na lista de serviços e clique na caixa de seleção para marcá-lo.

  3. Clique em Excluir. Isso excluirá todas as revisões do serviço.

gcloud

Para excluir um serviço, execute o seguinte comando:

gcloud run services delete SERVICE --region REGION

Substitua:

  • SERVICE: nome do serviço.
  • REGION: Cloud de Confiance região do serviço.

Excluir o projeto de teste

A exclusão do projeto do Cloud de Confiance interrompe o faturamento de todos os recursos dele. Para liberar todos os recursos do Cloud de Confiance by S3NS no seu projeto, siga estas etapas:

    Excluir um projeto do Cloud de Confiance :

    gcloud projects delete PROJECT_ID

A seguir

Para mais informações sobre como criar um contêiner a partir do código-fonte e enviá-lo para um repositório, consulte: