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

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

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Instale a CLI do Google Cloud.

Observação:se você já instalou a CLI gcloud, execute o comando gcloud components update para verificar se tem a versão mais recente.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias 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.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um projeto do Google Cloud :

  gcloud projects create PROJECT_ID

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

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

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.

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Instale a CLI do Google Cloud.

Observação:se você já instalou a CLI gcloud, execute o comando gcloud components update para verificar se tem a versão mais recente.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias 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.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um projeto do Google Cloud :

  gcloud projects create PROJECT_ID

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

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

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.

Verifique se o faturamento está ativado para o projeto do Google Cloud .

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

2. Ative as APIs Cloud Run Admin e Cloud Build, se alguma delas ainda não estiver ativada:

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

3. Consulte os preços do Cloud Run ou faça uma estimativa de custos com a calculadora de preços.
4. 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 a fim de concluir o guia de início rápido, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Administrador do Cloud Run (roles/run.admin) no projeto
• Desenvolvedor de origem do Cloud Run (roles/run.sourceDeveloper) no projeto
• Usuário da conta de serviço (roles/iam.serviceAccountUser) na identidade do serviço
• Leitor de registros (roles/logging.viewer) no projeto

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 Google Cloud 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:

[e-mail]

Substitua PROJECT_NUMBER pelo número do projeto do Google Cloud.

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.

Sucesso:você implantou um app da Web do LangChain no Cloud Run.

Testar o serviço do Cloud Run

Teste seu 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 Google Cloud pelos recursos usados nesta página, exclua o projeto do Google Cloud e os recursos.

Para evitar cobranças extras na sua conta do Google Cloud , 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, ainda é possível receber 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 Google Cloud , 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: Google Cloud região do serviço.

Excluir o projeto de teste

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

Cuidado: a exclusão de um projeto tem os seguintes efeitos:
• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Excluir um projeto do Google Cloud :

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:

• Como desenvolver serviços do Cloud Run
• Como criar contêineres
• Testar um serviço do Cloud Run localmente
• Como implantar do código-fonte