程式碼研究室簡介
2. 必要條件
- 如果您還沒有 Google 帳戶,請務必建立 Google 帳戶。
- 請改用個人帳戶,而非公司或學校帳戶。工作和學校帳戶可能有限制,導致您無法啟用本實驗室所需的 API。
- 如果您還沒有 GitHub 帳戶,請務必建立 GitHub 帳戶
- 如果您已有 GitHub 帳戶,請使用該帳戶。GitHub 更有可能將新帳戶視為垃圾內容而封鎖。
- 為 GitHub 帳戶設定雙重驗證,降低帳戶被標示為垃圾內容的機率。
3. 專案設定
- 登入 Google Cloud 控制台。
- 在 Cloud 控制台中啟用帳單。
- 完成本研究室所需的 Cloud 資源費用應低於 $1 美元。
- 您可以按照本實驗室課程結尾的步驟刪除資源,避免產生其他費用。
- 新使用者可享有價值 $300 美元的免費試用期。
- 您是否參加「Gen AI for Devs」活動?你可能會獲得 $1 美元的抵免額。
- 建立新專案或選擇重複使用現有專案。
- 在 Cloud Billing 的「我的專案」
-
中確認已啟用計費功能。
- 如果新專案的
Billing account
欄顯示Billing is disabled
,請按照下列步驟操作:- 按一下
Actions
欄中的三點圖示 - 按一下「變更帳單」
- 選取要使用的帳單帳戶
- 按一下
- 如果您參加「Gen AI for Devs」活動,帳戶名稱可能會是「Google Cloud Platform Trial Billing Account」
- 如果新專案的
4. 開啟 Cloud Shell 編輯器
- 前往 Cloud Shell 編輯器
- 如果終端機未顯示在畫面底部,請按照下列步驟開啟:
- 按一下漢堡選單
- 按一下「Terminal」
- 按一下「New Terminal」
- 按一下漢堡選單
- 在終端機中,使用以下指令設定專案:
- 格式:
gcloud config set project [PROJECT_ID]
- 範例:
gcloud config set project lab-project-id-example
- 如果忘記專案 ID,請按照下列步驟操作:
- 您可以使用下列指令列出所有專案 ID:
gcloud projects list | awk '/PROJECT_ID/{print $2}'
- 您可以使用下列指令列出所有專案 ID:
- 格式:
- 如果出現授權提示訊息,請點選「授權」繼續操作。
- 您應該會看到下列訊息:
如果您看到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
- 設定全域 Git 使用者電子郵件:
git config --global user.email "you@example.com"
- 設定全域 Git 使用者名稱:
git config --global user.name "Your Name"
- 將全域 Git 預設分支設為
main
:git config --global init.defaultBranch main
7. 編寫程式碼
如要使用 Node.js 編寫應用程式,請按照下列步驟操作:
- 前往主目錄:
cd ~
- 建立新的
codelab-genai
Angular 應用程式:npx @angular/cli new codelab-genai \
--minimal \
--inline-template \
--inline-style \
--ssr \
--defaults - 如果系統要求安裝
@angular/cli
,請按下Enter
繼續操作:Need to install the following packages: @angular/cli@18.2.4 Ok to proceed? (y)
- 請前往
codelab-genai
目錄:cd codelab-genai
- 在 Cloud Shell 編輯器中開啟
app.component.ts
檔案: 畫面頂端應該會顯示空白檔案。您可以在這裡編輯cloudshell edit src/app/app.component.ts
app.component.ts
檔案。 - 複製下列程式碼,並貼到已開啟的
app.component.ts
檔案中: 幾秒後,Cloud Shell 編輯器會自動儲存程式碼。這個程式碼會以「Hello world!」問候語回應 HTTP 要求。import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';
@Component({
selector: 'app-root',
standalone: true,
imports: [RouterOutlet],
template: `
<h1>Hello world!</h1>
<router-outlet />
`,
styles: [],
})
export class AppComponent { }
應用程式的初始程式碼已完成,可以儲存在版本控制中。
8. 建立存放區
- 返回畫面底部的 Cloud Shell 終端機。
- 請確認您仍位於正確的目錄:
cd ~/codelab-genai
- 初始化 Git 存放區
git init -b main
- 登入 GitHub CLI
按下gh auth login
Enter
接受預設選項,然後按照 GitHub CLI 工具中的操作說明進行,包括:- 您要登入哪個帳戶?
GitHub.com
- 您偏好的主機 Git 操作協定為何?
HTTPS
- 是否要使用 GitHub 憑證驗證 Git?
Y
(如果沒有這個選項,請略過)。 - 您想如何驗證 GitHub CLI?
Login with a web browser
- 複製動態驗證碼
- 開啟 https://github.com/login/device
- 貼上一次性代碼
- 按一下「授權 GitHub」
- 完成登入
- 您要登入哪個帳戶?
- 確認您已登入:
如果您已成功登入,這段程式碼應會輸出您的 GitHub 使用者名稱。gh api user -q ".login"
- 建立
GITHUB_USERNAME
變數GITHUB_USERNAME=$(gh api user -q ".login")
- 確認您已建立環境變數:
如果您已成功建立變數,這應該會輸出您的 GitHub 使用者名稱。echo ${GITHUB_USERNAME}
- 建立名為
codelab-genai
的空 GitHub 存放區: 如果收到以下錯誤訊息:gh repo create codelab-genai --private
您已擁有名為GraphQL: Name already exists on this account (createRepository)
codelab-genai
的存放區。您可以透過下列兩種方式繼續完成本教學課程:- 刪除現有的 GitHub 存放區
- 請使用其他名稱建立存放區,並記得在後續指令中變更名稱。
- 將
codelab-genai
存放區新增為遠端origin
:git remote add origin https://github.com/${GITHUB_USERNAME}/codelab-genai
9. 分享代碼
- 確認您位於正確的目錄:
cd ~/codelab-genai
- 將目前目錄中的所有檔案新增至此版本:
git add .
- 建立第一個修訂版本:
git commit -m "add http server"
- 將修訂版本推送至
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/src/app/app.component.ts \n\n"
10. 設定自動部署
- 請保持 Cloud Shell 編輯器分頁開啟。我們稍後會再回到這個分頁。
- 在新分頁中前往「Cloud Run」頁面
- 在控制台中選取正確的 Google Cloud 專案
- 按一下「連結存放區」
- 按一下「Set up with Cloud Build」(設定 Cloud Build)
- 選取「GitHub」做為「存放區供應商」
- 如果您尚未在瀏覽器中登入 GitHub 帳戶,請使用憑證登入。
- 依序點選「驗證」和「繼續」。
- 登入後,Cloud Run 頁面會顯示「您的所有存放區均未安裝 GitHub 應用程式」的訊息。
- 按一下「INSTALL GOOGLE CLOUD BUILD」按鈕。
- 在「安裝設定」頁面中,選取「Only select repositories」,然後選擇您透過 CLI 建立的 codelab-genai 存放區。
- 按一下「安裝」
- 注意:如果您有許多 GitHub 存放區,載入作業可能需要幾分鐘的時間。
- 選取
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
) 則保留預設值。
- 其他欄位 (
- 點選「儲存」。
- 選取「GitHub」做為「存放區供應商」
- 向下捲動至「驗證」
- 按一下「允許未經驗證的叫用」
- 按一下 [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 編輯器,可以略過這些步驟。
- 前往 Cloud Shell 編輯器
- 如果終端機未顯示在畫面底部,請按照下列步驟開啟:
- 按一下漢堡選單
- 按一下「Terminal」
- 按一下「New Terminal」
- 按一下漢堡選單
- 在終端機中,使用以下指令設定專案:
- 格式:
gcloud config set project [PROJECT_ID]
- 範例:
gcloud config set project lab-project-id-example
- 如果忘記專案 ID,請按照下列步驟操作:
- 您可以使用下列指令列出所有專案 ID:
gcloud projects list | awk '/PROJECT_ID/{print $2}'
- 您可以使用下列指令列出所有專案 ID:
- 格式:
- 如果出現授權提示訊息,請點選「授權」繼續操作。
- 您應該會看到下列訊息:
如果您看到Updated property [core/project].
WARNING
並收到Do you want to continue (Y/N)?
要求,表示您可能輸入的專案 ID 有誤。按下N
和Enter
鍵,然後再次嘗試執行gcloud config set project
指令。
將 Vertex AI 新增至應用程式
- 返回畫面底部的 Cloud Shell 終端機。
- 請確認您仍位於正確的目錄:
cd ~/codelab-genai
- 安裝 Node.js Vertex AI SDK:
npm install @google-cloud/vertexai
- 安裝 Node.js Google Auth SDK:
npm install google-auth-library
- 在 Cloud Shell 編輯器中重新開啟
server.ts
cloudshell edit server.ts
- 將
server.ts
檔案中的程式碼替換為:// server.ts
import { APP_BASE_HREF } from '@angular/common';
import { CommonEngine } from '@angular/ssr';
import express from 'express';
import { fileURLToPath } from 'node:url';
import { dirname, join, resolve } from 'node:path';
import bootstrap from './src/main.server';
import { VertexAI } from '@google-cloud/vertexai';
import { GoogleAuth } from 'google-auth-library';
// The Express app is exported so that it can be used by serverless Functions.
export function app(): express.Express {
const server = express();
const serverDistFolder = dirname(fileURLToPath(import.meta.url));
const browserDistFolder = resolve(serverDistFolder, '../browser');
const indexHtml = join(serverDistFolder, 'index.server.html');
const commonEngine = new CommonEngine();
const auth = new GoogleAuth();
server.set('view engine', 'html');
server.set('views', browserDistFolder);
// Example Express Rest API endpoints
server.get('/api/facts', async (req, res) => {
const project = await auth.getProjectId();
const vertex = new VertexAI({ project: project });
const generativeModel = vertex.getGenerativeModel({
model: 'gemini-1.5-flash',
generationConfig: { responseMimeType: 'application/json' }
});
const animal = req.query['animal'] || 'dog';
const prompt = `Give me 10 fun facts about ${animal}.
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);
let factArray = '';
if (resp.response.candidates) {
factArray = JSON.parse(resp.response.candidates[0].content.parts[0].text || '');
}
res.send(factArray);
});
// Serve static files from /browser
server.get('**', express.static(browserDistFolder, {
maxAge: '1y',
index: 'index.html',
}));
// All regular routes use the Angular engine
server.get('**', (req, res, next) => {
const { protocol, originalUrl, baseUrl, headers } = req;
commonEngine
.render({
bootstrap,
documentFilePath: indexHtml,
url: `${protocol}://${headers.host}${originalUrl}`,
publicPath: browserDistFolder,
providers: [{ provide: APP_BASE_HREF, useValue: baseUrl }],
})
.then((html) => res.send(html))
.catch((err) => next(err));
});
return server;
}
function run(): void {
const port = process.env['PORT'] || 4000;
// Start up the Node server
const server = app();
server.listen(port, () => {
console.log(`Node Express server listening on http://localhost:${port}`);
});
}
run(); - 在 Cloud Shell 編輯器中開啟
app.component.ts
cloudshell edit src/app/app.component.ts
- 將
app.components.ts
檔案中的程式碼替換為:// app.component.ts
import { Component, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { RouterOutlet } from '@angular/router';
@Component({
selector: 'app-root',
standalone: true,
imports: [RouterOutlet, FormsModule],
template: `
<section>
<input
type="text"
placeholder="dog"
[(ngModel)]="animal"
class="text-black border-2 p-2 m-2 rounded"
/>
<button
(click)="getNewFunFacts()"
>
Get New Fun Facts
</button>
<ol>
@for(fact of facts(); track fact) {
<li>{{fact}}</li>
} @empty {
<li>No facts are available</li>
}
</ol>
</section>
`,
styles: '',
})
export class AppComponent {
animal = '';
facts = signal<string[]>([]);
getNewFunFacts() {
fetch(`/api/facts?animal=${this.animal}`).then(response => response.json()).then(facts => {
this.facts.set(facts);
});
}
}
12. 重新部署
- 請確認您仍在 Cloud Shell 的正確目錄中:
cd ~/codelab-genai
- 執行下列指令,將應用程式的新版本提交至本機 Git 存放區:
git add .
git commit -m "add latest changes" - 將變更推送至 GitHub:
git push
- 建構作業完成後,請執行下列指令並前往已部署的應用程式:
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 的管理稽核記錄預設為啟用。如要稽核產生內容的要求,請啟用資料存取稽核記錄:
- 在 Google Cloud 控制台中,前往「Audit Logs」頁面:
如果您是使用搜尋列尋找這個頁面,請選取子標題為「IAM 與管理員」的結果。 - 請確認您建立 Cloud Run 應用程式的 Google Cloud 專案為現有專案。
- 在「資料存取稽核記錄設定」表格中,找出「Service」欄中的
Vertex AI API
。 - 在「Log Types」分頁中,選取資料存取稽核記錄類型
Admin read
和Data read
。 - 按一下 [儲存]。
啟用後,您就能查看應用程式每次叫用作業的稽核記錄。如要查看含有叫用詳細資料的稽核記錄,請執行下列操作:
- 返回已部署的應用程式,然後重新整理頁面,觸發記錄。
- 前往 Google Cloud 控制台的「Logs Explorer」頁面:
- 在查詢視窗中輸入:
LOG_ID("cloudaudit.googleapis.com%2Fdata_access")
protoPayload.serviceName="aiplatform.googleapis.com" - 點選「執行查詢」
稽核記錄會記錄 Vertex AI API 的使用情形,但無法讓您查看工作負載相關資料,例如提示或回覆詳細資料。
14. (選用) 提高 AI 工作負載的觀測能力
稽核記錄不會擷取工作負載相關資訊。為了提高工作負載的可觀察性,您必須明確記錄這項資訊。您可以使用喜愛的記錄架構執行這項操作。以下步驟說明如何使用原生 Node.js 記錄機制執行此操作。
- 在 Cloud Shell 編輯器中重新開啟
server.ts
cloudshell edit ~/codelab-genai/server.ts
- 在呼叫
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
- 重新開啟 Cloud Shell,然後輸入下列指令,確認您位於正確的目錄:
cd ~/codelab-genai
- 修訂變更:
git commit -am "observe generated content"
- 將變更推送至 GitHub,觸發修改版本的重新部署作業:
git push
新版本部署完成後,您可以查看 Vertex AI 呼叫的偵錯資訊。
如要查看應用程式記錄,請按照下列步驟操作:
- 前往 Google Cloud 控制台的「Logs Explorer」頁面:
- 在查詢視窗中輸入:
LOG_ID("run.googleapis.com%2Fstdout")
severity=DEBUG - 點選「執行查詢」
查詢結果會顯示含有提示和 Vertex AI 回應的記錄,其中包含可用於監控安全做法的「安全評分」
15. (選用) 清除
不使用服務時,Cloud Run 不會收費,但您可能仍須針對已儲存於 Artifact Registry 中的容器映像檔,支付儲存費用。您可以刪除 Cloud 專案,避免產生費用。刪除 Cloud 專案後,系統就會停止對專案使用的所有資源收取費用。
如有需要,請刪除專案:
gcloud projects delete $GOOGLE_CLOUD_PROJECT
您也可以從雲端磁碟中刪除不必要的資源。您可以:
16. 恭喜
在本實驗室中,您編寫了網頁應用程式,並設定 Cloud Run,以便在應用程式原始碼變更時自動部署應用程式。然後修改應用程式並重新部署。
如果您喜歡這個實驗室,可以嘗試使用其他程式語言或架構:
如有意參與使用者體驗 (UX) 研究,協助改善您目前使用的產品,請按這裡註冊。
以下提供一些繼續學習的選項:
- 文件:使用 Firebase GenKit 做為彈性模型抽象,輕鬆整合任何模型 API 並使用社群維護的模型。
- 程式碼研究室:如何在 Cloud Run 上部署 Gemini 支援的即時通訊應用程式
- 如何搭配使用 Gemini 函式呼叫與 Cloud Run
- 如何使用 Cloud Run 工作單元 Video Intelligence API 逐場景處理影片
- 隨選工作坊:Google Kubernetes Engine 新手上路