快速入门：构建 Python (LangChain) Web 应用并将其部署到 Cloud Run

了解如何使用 Cloud Run 和 Gemini 构建和部署 LangChain 应用，以回答有关城市首都的问题。

按照本快速入门中的步骤操作时，Cloud Run 会在您从源代码进行部署时自动为您构建 Dockerfile。

准备工作

  1. 安装 Google Cloud CLI。

  2. 配置 gcloud CLI 以使用您的联合身份。

    如需了解详情，请参阅使用联合身份登录 gcloud CLI。

  3. 如需初始化 gcloud CLI，请运行以下命令： 

    gcloud init

  4. 创建或选择 Google Cloud 项目。

    选择或创建项目所需的角色

    • 选择项目：选择项目不需要特定的 IAM 角色，您可以选择已获授角色的任何项目。
    • 创建项目：如需创建项目，您需要拥有 Project Creator 角色 (roles/resourcemanager.projectCreator)，该角色包含 resourcemanager.projects.create 权限。了解如何授予角色。

    • 创建 Google Cloud 项目：

      gcloud projects create PROJECT_ID

      将 PROJECT_ID 替换为您要创建的 Google Cloud 项目的名称。

    • 选择您创建的 Google Cloud 项目：

      gcloud config set project PROJECT_ID

      将 PROJECT_ID 替换为您的 Google Cloud 项目名称。

  5. 如果您要使用现有项目来完成本指南，请验证您是否拥有完成本指南所需的权限。如果您创建了新项目，则您已拥有所需的权限。

  6. 验证是否已为您的 Google Cloud 项目启用结算功能。

  7. 如果您通过网域限制组织政策来限制项目的未经身份验证的调用，则您需要按照测试专用服务中的说明访问已部署的服务。

  8. 启用 Cloud Run Admin API 和 Cloud Build API：

    启用 API 所需的角色

    如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。 

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

    启用 Cloud Run Admin API 后，系统会自动创建 Compute Engine 默认服务账号。

  9. 查看 Cloud Run 价格或使用价格计算器估算费用。
  10. 您需要使用 Google AI Studio 中的 API 密钥才能部署使用 Gemini 模型的 LangChain 应用。如需使用 Google AI 工作室生成 API 密钥，请参阅 Gemini API 文档中的使用 Gemini API 密钥。部署服务时，您将引用此密钥。

所需的角色

如需获得完成本教程所需的权限，请让您的管理员为您授予以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

授予 Cloud Build 服务账号对项目的访问权限

除非您替换此行为，否则 Cloud Build 会自动使用 Compute Engine 默认服务账号作为默认 Cloud Build 服务账号来构建源代码和 Cloud Run 资源。

为了让 Cloud Build 能够构建来源，请向 Cloud Build 服务账号授予项目的 Cloud Run Builder (roles/run.builder) 角色：

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

将 PROJECT_ID 替换为您的 Google Cloud项目 ID，并将 SERVICE_ACCOUNT_EMAIL_ADDRESS 替换为 Cloud Build 服务账号的邮箱。如果您使用 Compute Engine 默认服务账号作为 Cloud Build 服务账号，则服务账号邮箱应采用以下格式：

PROJECT_NUMBER-compute@

将 PROJECT_NUMBER 替换为您的 Google Cloud项目编号。

如需详细了解如何查找项目 ID 和项目编号，请参阅创建和管理项目。

授予 Cloud Run Builder 角色之后，需要几分钟时间才能完成传播。

编写示例应用

如需使用 Python 编写应用，请执行以下操作：

  1. 创建名为 langchain-gemini-fastapi-app 的新目录，并转到此目录中：

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

  2. 创建名为 main.py 的文件，并将以下代码粘贴到其中：

    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. 创建名为 requirements.txt 的文件，并将以下代码粘贴到其中：

    fastapi
uvicorn
langchain
langchain-google-genai
python-dotenv

从源代码部署到 Cloud Run

从源代码部署会自动从源代码构建容器映像并进行部署。

如需从源代码进行部署，请使用以下命令：

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

将 API_KEY 替换为您的 Google AI Studio API 密钥。 对于生产环境，建议使用 Secret Manager 处理 API 密钥，而不是使用纯环境变量。

成功部署应用后，Cloud Run 会显示服务网址，例如 https://gemini-fastapi-service-xyz-uc.a.run.app。

测试 Cloud Run 服务

使用以下 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?"}'

将 YOUR-SERVICE-URL 替换为您的服务的网址。

代理发送以下回答：

  {
  "response": "Paris"
  }

如需验证服务是否正常运行，请检查 Cloud Run 服务的日志标签页。

清理

为避免因本页面中使用的资源导致您的 Google Cloud 账号产生费用，请删除包含这些资源的 Google Cloud 项目。

为避免您的 Google Cloud 账号产生额外费用，请删除您在本快速入门中部署的所有资源。

删除仓库