使用 Genkit Web Application 自動將生成式 AI Go 部署至 Cloud Run

1. 總覽

首次部署網頁應用程式可能會讓您感到困惑，即使在首次部署後，如果程序的工作量太大，您可能會避免部署應用程式的新版本。透過持續部署功能，您可以輕鬆自動部署應用程式變更。

在本研究室中，您將編寫網頁應用程式，並設定 Cloud Run，以便在應用程式原始碼變更時自動部署應用程式。然後修改應用程式並重新部署。

學習目標

• 使用 Cloud Shell 編輯器編寫網頁應用程式
• 將應用程式程式碼儲存在 GitHub 中
• 自動將應用程式部署至 Cloud Run

• 使用 Genkit 在應用程式中加入生成式 AI
• 使用 dotprompt 程式庫管理 LLM 提示

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 的「我的專案」
   中確認已啟用計費功能。
   • 如果新專案的 Billing account 欄顯示 Billing is disabled，請按照下列步驟操作：
     1. 按一下 Actions 欄中的三點圖示
     2. 按一下「變更帳單」
     3. 選取要使用的帳單帳戶
   • 如果您參加「Gen AI for Devs」活動，帳戶名稱可能會是「Google Cloud Platform Trial Billing Account」

4. 開啟 Cloud Shell 編輯器

1. 前往 Cloud Shell 編輯器
2. 如果終端機未顯示在畫面底部，請按照下列步驟開啟：
   • 按一下漢堡選單
   • 按一下「Terminal」
   • 按一下「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. 按一下「授權 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. 按一下「連結存放區」
5. 按一下「Set up with Cloud Build」(設定 Cloud Build)
   1. 選取「GitHub」做為「存放區供應商」
      • 如果您尚未在瀏覽器中登入 GitHub 帳戶，請使用憑證登入。
   2. 依序點選「驗證」和「繼續」。
   3. 登入後，Cloud Run 頁面會顯示「您的所有存放區均未安裝 GitHub 應用程式」的訊息。
   4. 按一下「INSTALL GOOGLE CLOUD BUILD」按鈕。
      • 在「安裝設定」頁面中，選取「Only select repositories」，然後選擇您透過 CLI 建立的 codelab-genai 存放區。
      • 按一下「安裝」
      • 注意：如果您有許多 GitHub 存放區，載入作業可能需要幾分鐘的時間。
   5. 選取 your-user-name/codelab-genai 做為「存放區」
      • 如果沒有存放區，請按一下「管理已連結的存放區」連結。
      • 將「Branch」保留為 ^main$
      • 按一下「透過 Google Cloud 的 Buildpacks 使用」Go、Node.js、Python、Java、.NET Core、Ruby 或 PHP
        • 其他欄位 (Build context directory、Entrypoint 和 Function target) 則保留預設值。
      • 點選「儲存」。
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. 安裝 Go 適用的 Genkit SDK：

   go get github.com/firebase/genkit/go/ai
   

4. 安裝 Genkit 適用的 Vertex AI 外掛程式：

   go get github.com/firebase/genkit/go/plugins/vertexai
   

5. 安裝 dotprompt 外掛程式，以便管理 LLM 提示：

   go get github.com/firebase/genkit/go/plugins/dotprompt
   

6. 安裝 Go 的中繼資料程式庫，取得目前的專案 ID：

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

7. 在 Cloud Shell 編輯器中重新開啟 main.go

   cloudshell edit main.go
   

8. 將 main.go 檔案中的程式碼替換為：

   package main
   
   import (
       "context"
       "fmt"
       "log"
       "net/http"
       "os"
   
       "cloud.google.com/go/compute/metadata"
       "github.com/firebase/genkit/go/plugins/dotprompt"
       "github.com/firebase/genkit/go/plugins/vertexai"
   )
   
   func main() {
       ctx := context.Background()
       var projectId string
       var err error
       projectId = os.Getenv("GOOGLE_CLOUD_PROJECT")
       if projectId == "" {
           projectId, err = metadata.ProjectIDWithContext(ctx)
           os.Setenv("GOOGLE_CLOUD_PROJECT", projectId)
           if err != nil {
               return
           }
       }
   
       if err := vertexai.Init(ctx, nil); err != nil {
           log.Fatal(err)
           return
       }
   
       dotprompt.SetDirectory("./")
       prompt, err := dotprompt.Open("animal-facts")
       if err != nil {
           log.Fatal(err)
           return
       }
       type AnimalPromptInput struct {
           Animal string `json:"animal"`
       }
   
       http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
   
           animal := r.URL.Query().Get("animal")
           if animal == "" {
               animal = "dog"
           }
   
           response, err := prompt.Generate(
               ctx,
               &dotprompt.PromptRequest{
                   Variables: AnimalPromptInput{
                       Animal: animal,
                   },
               },
               nil,
           )
   
           if err != nil {
               w.WriteHeader(http.StatusServiceUnavailable)
               fmt.Fprint(w, err)
               return
           }
   
           w.Header().Set("Content-Type", "text/html; charset=utf-8")
           fmt.Fprint(w, response.Text())
   
       })
   
       port := os.Getenv("PORT")
   
       if port == "" {
           port = "8080"
       }
       if err := http.ListenAndServe(":"+port, nil); err != nil {
           log.Fatal(err)
       }
   }
   

9. 建立 animal-facts.prompt 檔案：

   touch animal-facts.prompt
   

10. 在 Cloud Shell 編輯器中開啟 animal-facts.prompt 檔案：

    cloudshell edit animal-facts.prompt
    

11. 編輯 animal-facts.prompt，並將下列程式碼貼入其中：

    ---
    model: vertexai/gemini-1.5-flash
    config:
    temperature: 0.9
    input:
    schema:
        animal: string
    default:
        animal: dog
    ---
    
    Give me 10 fun facts about {{animal}}. Return the results as HTML without markdown backticks.
    

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"
   

建構作業可能需要幾分鐘的時間才能完成，您才能看到變更。

您可以在此處查看所有修訂版本的記錄：https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions

13. (選用) 稽核 Vertex AI 用量

您可以稽核 Vertex AI 作業，這與其他 Google Cloud 服務相同。稽核記錄可協助您回答「從事活動的人員、內容、地點及時間為何？」Vertex AI 的管理稽核記錄預設為啟用。如要稽核產生內容的要求，請啟用資料存取稽核記錄：

資料稽核記錄可能會產生額外費用。

1. 在 Google Cloud 控制台中，前往「Audit Logs」頁面：
   前往「Audit Logs」
   如果您是使用搜尋列尋找這個頁面，請選取子標題為「IAM 與管理員」的結果。
2. 請確認您建立 Cloud Run 應用程式的 Google Cloud 專案為現有專案。
3. 在「資料存取稽核記錄設定」表格中，找出「Service」欄中的 Vertex AI API。
4. 在「Log Types」分頁中，選取資料存取稽核記錄類型 Admin read 和 Data read。
5. 按一下 [儲存]。

啟用後，您就能查看應用程式每次叫用作業的稽核記錄。如要查看含有叫用詳細資料的稽核記錄，請執行下列操作：

1. 返回已部署的應用程式，然後重新整理頁面，觸發記錄。
2. 前往 Google Cloud 控制台的「Logs Explorer」頁面：
   前往「Logs Explorer」
   
3. 在查詢視窗中輸入：

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

4. 點選「執行查詢」

稽核記錄會記錄 Vertex AI API 的使用情形，但無法讓您查看工作負載相關資料，例如提示或回覆詳細資料。

14. (選用) 清除

不使用服務時，Cloud Run 不會收費，但您可能仍須針對已儲存於 Artifact Registry 中的容器映像檔，支付儲存費用。您可以刪除 Cloud 專案，避免產生費用。刪除 Cloud 專案後，系統就會停止對專案使用的所有資源收取費用。

如有需要，請刪除專案：

gcloud projects delete $GOOGLE_CLOUD_PROJECT

您也可以從雲端磁碟中刪除不必要的資源。您可以：

15. 恭喜

在本實驗室中，您編寫了網頁應用程式，並設定 Cloud Run，以便在應用程式原始碼變更時自動部署應用程式。然後修改應用程式並重新部署。

如果您喜歡這個實驗室，可以嘗試使用其他程式語言或架構：

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

如有意參與使用者體驗 (UX) 研究，協助改善您目前使用的產品，請按這裡註冊。

以下提供一些繼續學習的選項：

• 文件：使用 Firebase GenKit 做為彈性模型抽象，輕鬆整合任何模型 API 並使用社群維護的模型。
• 程式碼研究室：如何在 Cloud Run 上部署 Gemini 支援的即時通訊應用程式
• 如何搭配使用 Gemini 函式呼叫與 Cloud Run
• 隨選工作坊：Google Kubernetes Engine 新手上路
• 如何使用 Cloud Run 工作單元 Video Intelligence API 逐場景處理影片