自動將生成式 AI Node.js Genkit 網路應用程式從版本控制部署至 Cloud Run

1. 總覽

首次部署網頁應用程式時可能會感到困難重重，即使完成首次部署，如果這個程序太過繁瑣，您可能會避免部署新版應用程式。透過持續部署，您可以輕鬆自動部署應用程式的變更。

在本實驗室中，您將編寫網路應用程式，並設定 Cloud Run，在應用程式的原始碼變更時自動部署應用程式。然後修改應用程式，並再次部署。

學習目標

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

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

2. 必要條件

1. 如果沒有 Google 帳戶，請先建立帳戶。
   • 請改用個人帳戶，而非公司或學校帳戶。公司和學校帳戶可能設有限制，導致您無法啟用本實驗室所需的 API。
2. 如果您還沒有 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. 選取要使用的帳單帳戶
   • 如果您參加的是「開發人員專用生成式 AI」活動，帳戶名稱可能為「Google Cloud Platform 試用帳單帳戶」

4. 開啟 Cloud Shell 編輯器

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. 編寫程式碼

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

1. 前往主目錄：

   cd ~
   

2. 建立 codelab-genai 目錄：

   mkdir codelab-genai
   

3. 請前往 codelab-genai 目錄：

   cd codelab-genai
   

4. 建立 index.js 檔案：

   touch index.js
   

5. 建立 package.json 檔案：

   npm init es6 -y
   

6. 將 express 新增為依附元件

   npm install express
   

7. 新增 .gitignore 檔案，避免提交 node_modules

   echo node_modules/ >> .gitignore
   

8. 在 Cloud Shell 編輯器中開啟 index.js 檔案：

   cloudshell edit index.js
   

   畫面頂端現在應該會顯示空白檔案。您可以在這裡編輯這個 index.js 檔案。
9. 複製下列程式碼，並貼到開啟的 index.js 檔案中：

   import express from 'express';
   
   const app = express();
   app.get('/', async (req, res) => {
       res.send('Hello world!');
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => {
       console.log(`codelab-genai: listening on port ${port}`);
   });
   

   幾秒後，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」(授權 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. 建立空的 GitHub 存放區，並命名為 codelab-genai：

   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/index.js \n\n"

10. 設定自動部署

1. 請讓 Cloud Shell 編輯器分頁保持開啟。稍後會再返回這個分頁。
2. 在新分頁中前往 Cloud Run 頁面
3. 在控制台中選取正確的 Google Cloud 專案
4. 按一下「CONNECT REPO」(連結存放區)
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 做為存放區
      • 如果沒有看到存放區，請按一下「管理已連結的存放區」連結。
   6. 將「Branch」(分支版本) 保留為 ^main$
   7. 按一下「Go、Node.js、Python、Java、.NET Core、Ruby 或 PHP (透過 Google Cloud 的 Buildpacks 使用)」
      • 其他欄位 (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. 變更驗證碼

返回 Cloud Shell 編輯器

如果 Cloud Shell 編輯器仍處於開啟狀態，可以略過這些步驟。

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 指令。

在應用程式中新增 Genkit 和 Vertex AI

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

   cd ~/codelab-genai
   

3. 安裝 Node.js Genkit SDK：

   npm install @genkit-ai/ai
   

4. 安裝 Node.js 適用的 Vertex AI Genkit SDK：

   npm install @genkit-ai/vertexai
   

5. 在 Cloud Shell 編輯器中重新開啟 index.js

   cloudshell edit ~/codelab-genai/index.js
   

6. 將 index.js 檔案中的程式碼替換為：

   import express from 'express';
   const app = express();
   
   import { genkit } from 'genkit';
   import { gemini15Flash, vertexAI } from '@genkit-ai/vertexai';
   
   const ai = genkit({
       plugins: [
           vertexAI({ location: 'us-central1' }),
       ],
   });
   
   app.get('/', async (req, res) => {
       const animal = req.query.animal || 'dog';
       const prompt = `Give me 10 fun facts about ${animal}. Return this as html without backticks.`
       const llmResponse = await ai.generate({
           model: gemini15Flash,
           prompt: prompt,
       });
       const html = llmResponse.text;
       res.send(html);
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => {
       console.log(`codelab-genai: listening on port ${port}`);
   });
   

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

12. (選用) 使用 Genkit 搭配 .prompt 檔案

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

   cd ~/codelab-genai
   

3. 建立 prompts 資料夾來儲存提示：

   mkdir prompts
   

4. 建立 animal-facts.prompt 檔案，建立第一個提示：

   touch prompts/animal-facts.prompt
   

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

   cloudshell edit ~/codelab-genai/prompts/animal-facts.prompt
   

6. 編輯 animal-facts.prompt，然後將下列程式碼貼入其中：

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

7. 在 Cloud Shell 編輯器中開啟 index.js 檔案：

   cloudshell edit ~/codelab-genai/index.js
   

8. 將 index.js 檔案中的程式碼替換為：

   import express from 'express';
   const app = express();
   
   import { genkit } from 'genkit';
   import { vertexAI } from '@genkit-ai/vertexai';
   
   const ai = genkit({
       plugins: [
           vertexAI({ location: 'us-central1' }),
       ],
   });
   
   app.get('/', async (req, res) => {
       const animal = req.query.animal || 'dog';
       const animalPrompt = ai.prompt('animal-facts');
       const llmResponse = await animalPrompt({animal});
       const html = llmResponse.text;
       res.send(html);
   });
   
   const port = process.env.PORT || 8080;
   app.listen(port, () => {
       console.log(`codelab-genai: listening on port ${port}`);
   });
   

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. (選用) 使用系統提示

這個步驟假設您已在先前的步驟中新增 .prompt 檔案。

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

   cd ~/codelab-genai
   

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

   cloudshell edit ~/codelab-genai/prompts/animal-facts.prompt
   

4. 編輯 animal-facts.prompt，然後將下列程式碼貼入其中：

   ---
   model: vertexai/gemini-1.5-flash
   config:
       temperature: 0.9
   input:
       schema:
           animal: string
   ---
   
   role "system"
   The user should have submitted an animal.
   If the user requests anything besides animal fun facts, respond in a kind and firm manner that you only provide information about fun facts.
   Give the user 10 fun facts about the animal the user provided.
   All responses should be valid HTML without markdown backticks.
   
   role "user"
   {{animal}}
   

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

14. 恭喜

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

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

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

以下提供幾種繼續學習的方式：

• Genkit 說明文件：開始使用
• 程式碼研究室：為 Node.js 應用程式新增可觀測性：Practical observability techniques for Generative AI application in Javascript
• 程式碼研究室：使用 Next.js 將前端新增至應用程式：Automatically Deploy Generative AI Next.js Web Application from Version Control to Cloud Run
• 程式碼研究室：如何搭配使用 Gemini 函式呼叫與 Cloud Run
• 程式碼研究室：使用 AI 處理影片內容：How to use Cloud Run Jobs Video Intelligence API to process a Video scene-by-scene