自动将生成式 AI Python Web 应用从版本控制系统部署到 Cloud Run

1. 概览

首次部署 Web 应用可能令人望而生畏。即使在首次部署后，如果该流程过于繁琐，您也可能会避免部署新版本的应用。借助持续部署，您可以轻松自动部署应用更改。

在本实验中，您将编写一个 Web 应用，并配置 Cloud Run，以便在应用的源代码发生更改时自动部署应用。然后，您修改应用并再次部署。

学习内容

使用 Cloud Shell 编辑器编写 Web 应用
在 GitHub 中存储应用代码
自动将应用部署到 Cloud Run

使用 Vertex AI 将生成式 AI 添加到您的应用

2. 前提条件

如果您还没有 Google 账号，则必须先创建一个 Google 账号。
- 请改用个人账号，而非工作账号或学校账号。工作账号和学校账号可能存在限制，导致您无法启用本实验所需的 API。
如果您还没有 GitHub 账号，则必须创建 GitHub 账号
- 使用已有的 GitHub 账号（如果有）。GitHub 更容易将新账号视为垃圾账号加以屏蔽。
- 在 GitHub 账号中配置双重身份验证，以降低账号被标记为垃圾账号的几率。

3. 项目设置

登录 Google Cloud 控制台。
在 Cloud 控制台中启用结算功能。
- 完成本实验的 Cloud 资源费用应低于 1 美元。
- 您可以按照本实验末尾的步骤删除资源，以避免产生更多费用。
- 新用户符合参与 $300 USD 免费试用计划的条件。
- 要参加 Gen AI for Devs 活动？您或许可以获得 1 美元抵用金。
创建新项目或选择重复使用现有项目。
在 Cloud Billing 的我的项目中确认结算功能已启用
- 如果新项目的 Billing account 列中显示 Billing is disabled，请执行以下操作：
  1. 点击 Actions 列中的三点状图标
  2. 点击更改结算信息
  3. 选择您要使用的结算账号
- 如果您参加的是 Gen AI for Devs 活动，则该账号的名称很可能是 Google Cloud Platform 试用结算账号

4. 打开 Cloud Shell Editor

前往 Cloud Shell 编辑器
如果终端未显示在屏幕底部，请打开它：
- 点击汉堡式菜单
- 点击终端
- 点击 New Terminal
在终端中，使用以下命令设置项目：
- 格式：
```
gcloud config set project [PROJECT_ID]
```
- 示例：
```
gcloud config set project lab-project-id-example
```
- 如果您不记得项目 ID，请执行以下操作：
  - 您可以使用以下命令列出所有项目 ID：
```
gcloud projects list | awk '/PROJECT_ID/{print $2}'
```
如果系统提示您进行授权，请点击授权以继续。
您应会看到以下消息：
```
Updated property [core/project].
```
如果您看到 WARNING 并被问到 Do you want to continue (Y/N)?，则很可能是您输入的项目 ID 有误。按 N，按 Enter，然后尝试再次运行 gcloud config set project 命令。

5. 启用 API

在终端中，启用以下 API：

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

此命令可能需要几分钟时间才能完成，但最终应会生成类似如下所示的成功消息：

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

6. 配置 Git

设置全局 git 用户电子邮件地址：

git config --global user.email "you@example.com"

设置全局 Git 用户名：

git config --global user.name "Your Name"

将全局 Git 默认分支设置为 main：

git config --global init.defaultBranch main

7. 编写代码

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

前往主目录：
```
cd ~
```
创建 codelab-genai 目录：
```
mkdir codelab-genai
```
导航到 codelab-genai 目录：
```
cd codelab-genai
```
创建 main.py 文件：
```
touch main.py
```

使用依赖项列表创建 requirements.txt：

cat > requirements.txt << EOF
Flask==3.0.0
gunicorn==20.1.0
EOF

在 Cloud Shell 编辑器中打开 main.py 文件：
```
cloudshell edit main.py
```
屏幕顶部现在应会显示一个空文件。您可以在此处修改此 main.py 文件。

复制以下代码并将其粘贴到打开的 main.py 文件中：

import os

from flask import Flask

app = Flask(__name__)

@app.route("/")
def hello_world():
    return f"Hello world!"


if __name__ == "__main__":
    app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

几秒钟后，Cloud Shell 编辑器会自动保存您的代码。此代码使用我们的“Hello world!”问候语响应 HTTP 请求。

应用的初始代码已完成，可以存储在版本控制系统中。

8. 创建代码库

返回到屏幕底部的 Cloud Shell 终端。
确保您仍位于正确的目录中：
```
cd ~/codelab-genai
```
初始化 Git 代码库
```
git init -b main
```
登录 GitHub CLI
```
gh auth login
```
按 Enter 接受默认选项，然后按照 GitHub CLI 工具中的说明操作，包括：
1. 您要登录哪个账号？ GitHub.com
2. 您希望在此主机上使用哪种协议进行 Git 操作？ HTTPS
3. 是否使用您的 GitHub 凭据对 Git 进行身份验证？Y（如果未显示此界面，请跳过。）
4. 您想如何对 GitHub CLI 进行身份验证？ Login with a web browser
5. 复制一次性验证码
6. 打开 https://github.com/login/device
7. 粘贴一次性验证码
8. 点击 Authorize github
9. 完成登录
确认您已登录：
```
gh api user -q ".login"
```
如果您已成功登录，此命令应会输出您的 GitHub 用户名。

创建 GITHUB_USERNAME 变量

GITHUB_USERNAME=$(gh api user -q ".login")

确认您已创建该环境变量：
```
echo ${GITHUB_USERNAME}
```
如果您已成功创建该变量，此命令应会输出您的 GitHub 用户名。
创建一个名为 codelab-genai 的空 GitHub 代码库：
```
gh repo create codelab-genai --private
```
如果您收到以下错误：
```
GraphQL: Name already exists on this account (createRepository)
```
那么您已经有一个名为 codelab-genai 的代码库。您可以通过以下两种方式继续学习本教程：
- 删除现有的 GitHub 代码库
- 创建具有其他名称的仓库，并记得在以下命令中更改该名称。

将 codelab-genai 代码库添加为远程代码库 origin：

git remote add origin https://github.com/${GITHUB_USERNAME}/codelab-genai

9. 分享您的代码

确认您位于正确的目录中：
```
cd ~/codelab-genai
```
将当前目录中的所有文件添加到相应提交中：
```
git add .
```
创建第一个提交：
```
git commit -m "add http server"
```
将提交推送到 origin 代码库的 main 分支：
```
git push -u origin main
```

您可以运行此命令并访问生成的网址，以在 GitHub 上查看您的应用代码：

echo -e "\n\nTo see your code, visit this URL:\n \
    https://github.com/${GITHUB_USERNAME}/codelab-genai/blob/main/main.py \n\n"

10. 设置自动部署

将 Cloud Shell 编辑器标签页保持打开状态。我们稍后会返回此标签页。
在新标签页中，访问 Cloud Run 页面
在控制台中选择正确的 Google Cloud 项目
点击 CONNECT REPO
点击使用 Cloud Build 进行设置
1. 选择 GitHub 作为代码库提供程序
  - 如果您尚未在浏览器中登录 GitHub 账号，请使用您的凭据登录。
2. 点击验证，然后点击继续。
3. 登录后，您会在 Cloud Run 页面上看到一条消息，指出未针对您的任何代码库安装 GitHub 应用。
4. 点击安装 Google Cloud Build 按钮。
  - 在“安装设置”页面上，选择仅选择代码库，然后选择您通过 CLI 创建的 codelab-genai 代码库。
  - 点击安装
  - 注意：如果您有很多 GitHub 代码库，则可能需要几分钟的时间才能加载完成。
5. 选择 your-user-name/codelab-genai 作为代码库
  - 如果未显示相应代码库，请点击管理关联的代码库链接。
6. 将分支保留为 ^main$
7. 点击 Go、Node.js、Python、Java、.NET Core、Ruby 或 PHP（通过 Google Cloud 的 Buildpack）
  - 其他字段（Build context directory、Entrypoint 和 Function target）保持不变。
8. 点击保存
向下滚动到身份验证
点击允许未通过身份验证的调用
点击创建 (CREATE)

构建完成后（需要几分钟时间），运行此命令并访问生成的网址，以查看正在运行的应用：

echo -e "\n\nOnce the build finishes, visit your live application:\n \
    "$( \
        gcloud run services list | \
        grep codelab-genai | \
        awk '/URL/{print $2}' | \
        head -1 \
    )" \n\n"

11. 更改救援码

返回 Cloud Shell 编辑器

如果您仍打开着 Cloud Shell 编辑器，则可以跳过这些步骤。

前往 Cloud Shell 编辑器
如果终端未显示在屏幕底部，请打开它：
- 点击汉堡式菜单
- 点击终端
- 点击 New Terminal
在终端中，使用以下命令设置项目：
- 格式：
```
gcloud config set project [PROJECT_ID]
```
- 示例：
```
gcloud config set project lab-project-id-example
```
- 如果您不记得项目 ID，请执行以下操作：
  - 您可以使用以下命令列出所有项目 ID：
```
gcloud projects list | awk '/PROJECT_ID/{print $2}'
```
如果系统提示您进行授权，请点击授权以继续。
您应会看到以下消息：
```
Updated property [core/project].
```
如果您看到 WARNING 并被问到 Do you want to continue (Y/N)?，则很可能是您输入的项目 ID 有误。按 N，按 Enter，然后尝试再次运行 gcloud config set project 命令。

将 Vertex AI 添加到您的应用

返回到屏幕底部的 Cloud Shell 终端。
确保您仍位于正确的目录中：
```
cd ~/codelab-genai
```

将 Vertex AI SDK 依赖项添加到现有依赖项中：

sed -i -e '$agoogle-cloud-aiplatform==1.59.0' requirements.txt

将 Google Auth 库添加到现有依赖项中：

sed -i -e '$agoogle-auth==2.32.0' requirements.txt

在 Cloud Shell 编辑器中重新打开 main.py
```
cloudshell edit main.py
```

将 main.py 文件中的代码替换为：

import os

from flask import Flask, request

import google.auth
import vertexai
from vertexai.generative_models import GenerativeModel

_, project = google.auth.default()

app = Flask(__name__)

@app.route("/")
def hello_world():
    vertexai.init(project=project, location="us-central1")
    model = GenerativeModel("gemini-1.5-flash")
    animal = request.args.get("animal", "dog") 
    prompt = f"Give me 10 fun facts about {animal}. Return this as html without backticks."
    response = model.generate_content(prompt)
    return response.text

if __name__ == "__main__":
    app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

12. 重新部署

确保您仍在 Cloud Shell 中位于正确的目录中：
```
cd ~/codelab-genai
```
运行以下命令，将应用的新版本提交到本地 Git 代码库：
```
git add .
git commit -m "add latest changes"
```
将更改推送到 GitHub：
```
git push
```

构建完成后，运行以下命令并访问已部署的应用：

echo -e "\n\nOnce the build finishes, visit your live application:\n \
    "$( \
        gcloud run services list | \
        grep codelab-genai | \
        awk '/URL/{print $2}' | \
        head -1 \
    )" \n\n"

可能需要过几分钟，构建才能完成，然后您才能看到所做的更改。

您可以在以下网址查看所有修订版本的历史记录：https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions

13. （可选）审核您的 Vertex AI 使用情况

与其他 Google Cloud 服务一样，您可以审核 Vertex AI 操作。审核日志可帮助您回答“哪些用户何时在何处执行过哪些操作？”这一问题。Vertex AI 的管理审核日志默认处于启用状态。如需审核生成内容的请求，您必须启用数据访问审核日志：

在 Google Cloud 控制台中，前往审核日志页面：

如果您使用搜索栏查找此页面，请选择子标题为 IAM 和管理的结果。
确保现有 Google Cloud 项目是您创建 Cloud Run 应用的项目。
在数据访问审核日志配置表中，从“服务”列中找到并选择 Vertex AI API。
在日志类型标签页中，选择数据访问审核日志类型 Admin read 和 Data read。
点击保存。

启用后，您将能够看到应用每次调用的审核日志。如需查看包含调用详情的审核日志，请执行以下操作：

返回已部署的应用并刷新页面以触发日志。
在 Google Cloud 控制台中，前往日志浏览器页面：

在查询窗口中，输入：

LOG_ID("cloudaudit.googleapis.com%2Fdata_access")
protoPayload.serviceName="aiplatform.googleapis.com"

点击运行查询。

审核日志会捕获 Vertex AI API 的使用情况，但不会让您观察工作负载相关数据，例如提示或回答详细信息。

14. （可选）提高 AI 工作负载的可观测性

审核日志不会捕获与工作负载相关的信息。为了提高工作负载的可观测性，您必须明确记录此信息。您可以使用自己喜欢的日志记录框架来完成此操作。以下步骤演示了如何使用原生 Node.js 日志记录机制来实现此目的。

在 Cloud Shell 编辑器中重新打开 main.py
```
cloudshell edit ~/codelab-genai/main.py
```

在 import os（第 1 行）这一行之后，添加以下几行：

import sys, json, logging

class JsonFormatter(logging.Formatter):
    def format(self, record):
        json_log_object = {
            "severity": record.levelname,
            "message": record.getMessage(),
        }
        json_log_object.update(getattr(record, "json_fields", {}))
        return json.dumps(json_log_object)
logger = logging.getLogger(__name__)
sh = logging.StreamHandler(sys.stdout)
sh.setFormatter(JsonFormatter())
logger.addHandler(sh)
logger.setLevel(logging.DEBUG)

这些行会更改 Python 日志的默认格式，使其遵循可被 Google Cloud 提取的 JSON 结构化格式。

在调用 model.generate_content(prompt) 的行（第 34 行）之后，添加以下几行代码：
```
    json_fields = {"prompt": prompt, "response": response.to_dict()}
    logger.debug("Content is generated", extra={"json_fields": json_fields})
```
此代码会将有关内容生成的结构化信息输出到 stdout，供 Logging 代理读取并注入到 Cloud Logging 中。
重新打开 Cloud Shell，然后输入以下命令，确保您位于正确的目录中：
```
cd ~/codelab-genai
```

提交更改：

git commit -am "observe generated content"

将更改推送到 GitHub 以触发重新部署修改后的版本：
```
git push
```

新版本部署完毕后，您可以观察有关对 Vertex AI 的调用的调试信息。

如需查看应用日志，请执行以下操作：

在 Google Cloud 控制台中，前往日志浏览器页面：

在查询窗口中，输入：

LOG_ID("run.googleapis.com%2Fstdout")
severity=DEBUG

点击运行查询。

查询结果会显示包含提示和 Vertex AI 回答的日志，其中包括可用于监控安全实践的“安全评级”

15. （可选）清理

虽然 Cloud Run 不会对未在使用中的服务计费，但您可能仍然需要支付将容器映像存储在 Artifact Registry 中而产生的相关费用。您可以删除 Cloud 项目，以避免产生费用。删除 Cloud 项目后，系统即会停止对该项目中使用的所有资源计费。

如果您愿意，可以删除项目：

gcloud projects delete $GOOGLE_CLOUD_PROJECT

您可能还希望从 Cloud Shell 磁盘中删除不必要的资源。您可以：

删除 Codelab 项目目录：
```
rm -rf ~/codelab-genai
```
警告！此操作无法撤消！如果您想删除 Cloud Shell 中的所有内容以释放空间，可以删除整个主目录。请务必将要保留的所有内容保存到其他位置。
```
sudo rm -rf $HOME
```

16. 恭喜

在本实验中，您编写了一个 Web 应用，并配置了 Cloud Run，以便在应用源代码发生更改时自动部署应用。然后，您修改了应用并再次部署。

如果您喜欢本实验，可以尝试使用其他编程语言或框架再次完成本实验：