自動將生成式 AI Next.js 網頁應用程式從版本控制工具部署至 Cloud Run

1. 總覽

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

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

學習目標

• 使用 Cloud Shell 編輯器編寫網頁應用程式
• 將應用程式程式碼儲存在 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 的「我的專案」
   中確認已啟用計費功能。
   • 如果新專案的 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. 編寫程式碼

如要在 Next.js 中編寫應用程式，請按照下列步驟操作：

1. 前往主目錄：

   cd ~
   

2. 建立新的 codelab-genai Next.js 應用程式：

   npx create-next-app@latest codelab-genai \
       --ts \
       --eslint \
       --tailwind \
       --no-src-dir \
       --app \
       --no-import-alias
   

3. 如果系統要求安裝 create-next-app，請按下 Enter 繼續操作：

   Need to install the following packages:
   create-next-app@14.2.14
   Ok to proceed? (y)
   

4. 請前往 codelab-genai 目錄：

   cd codelab-genai
   

5. 在 Cloud Shell 編輯器中開啟 page.tsx 檔案：

   cloudshell edit app/page.tsx
   

   現在畫面頂端應該會顯示檔案。您可以在這裡編輯 page.tsx 檔案。
6. 刪除現有程式碼。複製下列程式碼，並貼到已開啟的 page.tsx 檔案中：

   import React from "react";
   
   export default function Home() {
   return (
       <main>
           Hello World!
       </main>
   );
   }
   

   幾秒後，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/app/page.tsx \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. 變更程式碼

返回 Cloud Shell 編輯器

如果您仍未關閉 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 指令。

將 Vertex AI 新增至應用程式

1. 返回畫面底部的 Cloud Shell 終端機。
2. 請確認您仍位於正確的目錄：

   cd ~/codelab-genai
   

3. 安裝 Node.js Vertex AI SDK：

   npm install @google-cloud/vertexai
   

4. 安裝 Node.js Google Auth SDK：

   npm install google-auth-library
   

5. 在終端機中建立 app/actions.ts

   touch app/actions.ts
   

6. 在 Cloud Shell 編輯器中開啟 actions.ts

   cloudshell edit app/actions.ts
   

7. 複製下列程式碼，並貼到已開啟的 actions.ts 檔案中：

   'use server'
   
   import { VertexAI } from '@google-cloud/vertexai';
   import { GoogleAuth } from 'google-auth-library';
   const auth = new GoogleAuth();
   
   export async function getFunFactsAction(animal: string) {
       const project = await auth.getProjectId();
   
       const vertex = new VertexAI({ project: project });
       const generativeModel = vertex.getGenerativeModel({
           model: 'gemini-1.5-flash'
       });
   
       const prompt = `Give me 10 fun facts about ${animal || 'dog'}. 
               Return as json as an array in the format ['fact 1', 'fact 2']
               Remove backticks and other markdown formatting.`;
       const resp = await generativeModel.generateContent(prompt);
   
       if (!resp.response.candidates) {
           throw new Error('Did not receive response candidates.')
       }
   
       console.log({ text: resp.response.candidates[0].content.parts[0].text })
   
       const factArray = JSON.parse(resp.response.candidates[0].content.parts[0].text || '');
       return factArray;
   };
   

8. 在 Cloud Shell 編輯器中開啟 page.tsx

   cloudshell edit ~/codelab-genai/app/page.tsx
   

9. 將 page.tsx 檔案中的程式碼替換為：

   'use client'
   
   import React, { useState } from "react";
   import { getFunFactsAction } from "./actions";
   
   export default function Home() {
       const [animal, setAnimal] = useState('');
       const [funFacts, setFunFacts] = useState<string[]>([]);
       async function getNewFunFacts() {
           const funFacts = await getFunFactsAction(animal);
           setFunFacts(funFacts);
       }
       return (
           <main>
               <h1 className="text-xl">Animal Fun Facts!</h1>
               <label className="text-lg p-2 m-2">Animal</label>
               <input
                   placeholder="dog"
                   value={animal}
                   onChange={(e) => setAnimal(e.target.value)}
                   className="text-black border-2 p-2 m-2 rounded"
               />
               <button
                   onClick={getNewFunFacts}
                   className="font-bold border-2 p-2 m-2 rounded hover:bg-white hover:text-black"
               >
                   Get New Fun Facts
               </button>
               <ul className="list-disc list-inside">
                   {funFacts.map(function (thing) {
                       return <li key={thing}>{thing}</li>
                   })}
               </ul>
           </main>
       );
   }
   

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. (選用) 提高 AI 工作負載的觀測能力

稽核記錄不會擷取工作負載相關資訊。為了提高工作負載的可觀察性，您必須明確記錄這項資訊。您可以使用喜愛的記錄架構執行這項操作。以下步驟說明如何使用原生 Node.js 記錄機制執行此操作。

1. 在 Cloud Shell 編輯器中重新開啟 actions.ts

   cloudshell edit ~/codelab-genai/app/actions.ts
   

2. 在呼叫 await generativeModel.generateContent(prompt) (第 19 行) 後，新增下列程式碼行：

       console.log(JSON.stringify({
           severity: 'DEBUG',
           message: 'Content is generated',
           prompt: prompt,
           response: resp.response,
       }));
   

   這段程式碼會使用結構化記錄格式，將產生內容的資訊寫入 stdout。Cloud Run 中的記錄代理程式會擷取輸出內容，並將此格式寫入 Cloud Logging。stdout
3. 重新開啟 Cloud Shell，然後輸入下列指令，確認您位於正確的目錄：

   cd ~/codelab-genai
   

4. 修訂變更：

   git commit -am "observe generated content"
   

5. 將變更推送至 GitHub，觸發修改版本的重新部署作業：

   git push
   

新版本部署完成後，您可以查看 Vertex AI 呼叫的偵錯資訊。

如要查看應用程式記錄，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Logs Explorer」頁面：
   前往「Logs Explorer」
   
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

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

16. 恭喜

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

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

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

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

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