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

1. 概览

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

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

学习内容

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

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

2. 前提条件

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

3. 项目设置

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

4. 打开 Cloud Shell Editor

1. 前往 Cloud Shell 编辑器
2. 如果终端未显示在屏幕底部，请打开它：
   • 点击汉堡式菜单
   • 点击终端
   • 点击 New Terminal
3. 在终端中，使用以下命令设置项目：
   • 格式：

     gcloud config set project [PROJECT_ID]
     

   • 示例：

     gcloud config set project lab-project-id-example
     

   • 如果您不记得项目 ID，请执行以下操作：
     • 您可以使用以下命令列出所有项目 ID：

       gcloud projects list | awk '/PROJECT_ID/{print $2}'
       

     
4. 如果系统提示您进行授权，请点击授权以继续。
5. 您应会看到以下消息：

   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

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

   git config --global user.email "[e-mail]"
   

2. 设置全局 git 用户名：

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

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

   git config --global init.defaultBranch main
   

7. 编写代码

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

1. 导航到主目录：

   cd ~
   

2. 创建 codelab-genai 目录：

   mkdir codelab-genai
   

3. 导航到 codelab-genai 目录：

   cd codelab-genai
   

4. 初始化 go.mod 文件以声明我们的模块：

   go mod init codelab-genai
   

5. 创建 main.go 文件：

   touch main.go
   

6. 在 Cloud Shell 编辑器中打开 main.go 文件：

   cloudshell edit main.go
   

   屏幕顶部现在应会显示一个空文件。您可以在此处修改此 main.go 文件。
7. 修改 main.go 并将以下代码粘贴到其中：

   package main
   
   import (
       "fmt"
       "log"
       "net/http"
       "os"
   )
   
   func main() {
       http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
           fmt.Fprintln(w, "Hello, world!")
       })
   
       port := os.Getenv("PORT")
   
       if port == "" {
           port = "8080"
       }
       if err := http.ListenAndServe(":"+port, nil); err != nil {
           log.Fatal(err)
       }
   }
   

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

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

8. 创建代码库

1. 返回到屏幕底部的 Cloud Shell 终端。
2. 确保您仍位于正确的目录中：

   cd ~/codelab-genai
   

3. 初始化 Git 代码库

   git init -b main
   

4. 登录 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. 完成登录
5. 确认您已登录：

   gh api user -q ".login"
   

   如果您已成功登录，此命令应会输出您的 GitHub 用户名。
6. 创建 GITHUB_USERNAME 变量

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

7. 确认您已创建环境变量：

   echo ${GITHUB_USERNAME}
   

   如果您已成功创建该变量，此命令应会输出您的 GitHub 用户名。
8. 创建一个名为 codelab-genai 的空 GitHub 代码库：

   gh repo create codelab-genai --private
   

   如果您收到以下错误：

   GraphQL: Name already exists on this account (createRepository)
   

   那么您已经有一个名为 codelab-genai 的代码库。您可以通过以下两种方式继续学习本教程：
   • 删除现有的 GitHub 代码库
   • 创建具有其他名称的代码库，并记得在以下命令中更改该名称。
9. 将 codelab-genai 代码库添加为远程代码库 origin：

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

9. 分享您的代码

1. 确认您位于正确的目录中：

   cd ~/codelab-genai
   

2. 将当前目录中的所有文件添加到相应提交中：

   git add .
   

3. 创建第一个提交：

   git commit -m "add http server"
   

4. 将提交推送到 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.go \n\n"

10. 设置自动部署

1. 将 Cloud Shell 编辑器标签页保持打开状态。我们稍后会返回此标签页。
2. 在新标签页中，访问 Cloud Run 页面
3. 在控制台中选择正确的 Google Cloud 项目
4. 点击 CONNECT REPO
5. 点击使用 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. 点击保存
6. 向下滚动到身份验证
7. 点击允许未经身份验证的调用
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. 更改代码

1. 返回到屏幕底部的 Cloud Shell 终端。
2. 确保您仍位于正确的目录中：

   cd ~/codelab-genai
   

3. 在 Cloud Shell 编辑器中重新打开 main.go

   cloudshell edit main.go
   

4. 安装 Vertex AI SDK for Go：

   go get cloud.google.com/go/vertexai/genai
   

5. 安装 Go 的元数据库以获取当前项目 ID：

   go get cloud.google.com/go/compute/metadata
   

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

   package main
   
   import (
       "context"
       "fmt"
       "log"
       "net/http"
       "os"
   
       "cloud.google.com/go/compute/metadata"
       "cloud.google.com/go/vertexai/genai"
   )
   
   func main() {
       ctx := context.Background()
       var projectId string
       var err error
       projectId = os.Getenv("GOOGLE_CLOUD_PROJECT")
       if projectId == "" {
           projectId, err = metadata.ProjectIDWithContext(ctx)
           if err != nil {
               return
           }
       }
       var client *genai.Client
       client, err = genai.NewClient(ctx, projectId, "us-central1")
       if err != nil {
           return
       }
       defer client.Close()
   
       model := client.GenerativeModel("gemini-1.5-flash-001")
   
       http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
           animal := r.URL.Query().Get("animal")
           if animal == "" {
               animal = "dog"
           }
   
           resp, err := model.GenerateContent(
               ctx,
               genai.Text(
                   fmt.Sprintf("Give me 10 fun facts about %s. Return the results as HTML without markdown backticks.", animal)),
           )
   
           if err != nil {
               w.WriteHeader(http.StatusServiceUnavailable)
               return
           }
   
           if len(resp.Candidates) > 0 && len(resp.Candidates[0].Content.Parts) > 0 {
               htmlContent := resp.Candidates[0].Content.Parts[0]
               w.Header().Set("Content-Type", "text/html; charset=utf-8")
               fmt.Fprint(w, htmlContent)
           }
       })
   
       port := os.Getenv("PORT")
   
       if port == "" {
           port = "8080"
       }
       if err := http.ListenAndServe(":"+port, nil); err != nil {
           log.Fatal(err)
       }
   }
   

12. 重新部署

1. 确保您仍在 Cloud Shell 中位于正确的目录中：

   cd ~/codelab-genai
   

2. 运行以下命令，将应用的新版本提交到本地 Git 代码库：

   git add .
   git commit -m "add latest changes"
   

3. 将更改推送到 GitHub：

   git push
   

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

   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"
   

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

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

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

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

数据审核日志可能会产生额外费用。

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

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

1. 返回已部署的应用，然后刷新页面以触发日志。
2. 在 Google Cloud 控制台中，前往日志浏览器页面：
   前往日志浏览器
   
3. 在查询窗口中，输入：

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

4. 点击运行查询。

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

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

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

1. 在 Cloud Shell 编辑器中重新打开 main.go

   cloudshell edit ~/codelab-genai/main.go
   

2. 更改您的导入块，以包含 Go 的结构化日志记录和 JSON 库：

   import (
       "context"
       "encoding/json"
       "fmt"
       "log"
       "log/slog"
       "net/http"
       "os"
   
       "cloud.google.com/go/compute/metadata"
       "cloud.google.com/go/vertexai/genai"
   )
   

3. 在初始化 Vertex 客户端（第 33 行）后，添加以下行以初始化使用 Google Cloud Logging 的正确字段的结构化日志记录器：

   opts := &slog.HandlerOptions{
   	Level: slog.LevelDebug,
   	ReplaceAttr: func(group []string, a slog.Attr) slog.Attr {
           if a.Key == slog.LevelKey {
               return slog.Attr{Key: "severity", Value: a.Value}
           }
           if a.Key == slog.MessageKey {
               return slog.Attr{Key: "message", Value: a.Value}
           }
           return slog.Attr{Key: a.Key, Value: a.Value}
   	},
   }
   
   jsonHandler := slog.NewJSONHandler(os.Stdout, opts)
   slog.SetDefault(slog.New(jsonHandler))
   

4. 在检查对 GenerateContent 的响应（第 69 行）后，在 if 块内添加以下几行代码：

   jsonBytes, err := json.Marshal(resp)
   if err != nil {
       slog.Error("Failed to marshal response to JSON", "error", err)
   } else {
       jsonString := string(jsonBytes)
       slog.Debug("Complete response content", "json_response", jsonString)
   }
   

   此代码使用结构化日志记录格式将有关生成内容的 stdout 信息写入日志。Cloud Run 中的日志记录代理会捕获打印到 stdout 的输出，并以这种格式写入 Cloud Logging。
5. 重新打开 Cloud Shell，然后输入以下命令，确保您位于正确的目录中：

   cd ~/codelab-genai
   

6. 提交更改：

   git commit -am "Observe generated content"
   

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

   git push
   

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

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

1. 在 Google Cloud 控制台中，前往日志浏览器页面：
   前往日志浏览器
   
2. 在查询窗口中，输入：

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

3. 点击运行查询。

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

记录提示时请务必小心，因为提示可能包含不应被观察到的敏感信息。您可能需要遮盖或以其他方式模糊处理这些信息。如需了解详情，请参阅 DLP 文档。

15. （可选）清理

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

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

gcloud projects delete $GOOGLE_CLOUD_PROJECT

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

1. 删除 Codelab 项目目录：

   rm -rf ~/codelab-genai
   

2. 清理您可能不再需要的任何 Go 软件包：

   cd ~
   go clean -modcache
   

3. 警告！此操作无法撤消！如果您想删除 Cloud Shell 中的所有内容以释放空间，可以删除整个主目录。请务必将要保留的所有内容保存到其他位置。

   sudo rm -rf $HOME
   

16. 恭喜

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

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

• Python
• Node.js
• Go
• Java
• Angular
• Next.js

如果您有兴趣参与用户体验 (UX) 调研，以帮助我们改进您今天使用的产品，请在此处注册。

以下是一些可供您继续学习的选项：

• 文档：使用 Genkit 作为灵活的模型抽象，以便轻松集成任何模型 API 并使用社区维护的模型。
• Codelab：如何在 Cloud Run 上部署由 Gemini 提供支持的聊天应用
• 如何将 Gemini 函数调用与 Cloud Run 搭配使用
• 点播讲座：Google Kubernetes Engine 入门
• 如何使用 Cloud Run Jobs Video Intelligence API 逐个场景地处理视频