自動將生成式 AI Node.js Genkit 網路應用程式從版本控制部署至 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. 編寫程式碼

如要使用 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. 按一下「授權 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/index.js \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 指令。

將 Genkit 和 Vertex AI 新增至應用程式

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

   cd ~/codelab-genai
   

3. 安裝 Node.js Genkit SDK：

   npm install @genkit-ai/ai
   

4. 安裝 Vertex AI 適用的 Node.js 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. (選用) 使用 .prompt 檔案搭配 Genkit

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 應用程式新增可觀測性：在 JavaScript 中為生成式 AI 應用程式提供實用的可觀測性技術
• 程式碼研究室：使用 Next.js 為應用程式新增前端：自動將生成式 AI Next.js 網路應用程式從版本控制工具部署至 Cloud Run
• 程式碼研究室：如何使用函式呼叫功能：如何搭配使用 Gemini 函式呼叫功能與 Cloud Run
• 程式碼研究室：如何使用 AI 處理影片內容：如何使用 Cloud Run Jobs Video Intelligence API 逐場處理影片