1. Giới thiệu
Tổng quan
Trong lớp học lập trình này, bạn sẽ thấy cách tạo một bot trò chuyện cơ bản được viết bằng nút bằng cách sử dụng Vertex AI Gemini API và thư viện ứng dụng Vertex AI. Ứng dụng này sử dụng kho lưu trữ phiên nhanh được hỗ trợ bởi Google Cloud Firestore.
Kiến thức bạn sẽ học được
- Cách sử dụng htmx, tailwindcss và express.js để tạo một dịch vụ Cloud Run
- Cách sử dụng thư viện ứng dụng Vertex AI để xác thực với API của Google
- Cách tạo chatbot để tương tác với mô hình Gemini
- Cách triển khai vào một dịch vụ Cloud Run mà không cần tệp Docker
- Cách sử dụng kho lưu trữ phiên nhanh được hỗ trợ bởi Google Cloud Firestore
2. Thiết lập và yêu cầu
Điều kiện tiên quyết
- Bạn đã đăng nhập vào Cloud Console.
- Trước đây, bạn đã triển khai một dịch vụ Cloud Run. Ví dụ: bạn có thể làm theo hướng dẫn nhanh về cách triển khai dịch vụ web từ mã nguồn để bắt đầu.
Kích hoạt Cloud Shell
- Trong Cloud Console, hãy nhấp vào Kích hoạt Cloud Shell
.
Nếu đây là lần đầu tiên bạn khởi động Cloud Shell, bạn sẽ thấy một màn hình trung gian mô tả về Cloud Shell. Nếu bạn thấy màn hình trung gian, hãy nhấp vào Tiếp tục.
Quá trình cung cấp và kết nối với Cloud Shell chỉ mất vài giây.
Máy ảo này được trang bị tất cả các công cụ phát triển cần thiết. Nền tảng này cung cấp một thư mục chính có dung lượng 5 GB và chạy trong Google Cloud, giúp tăng cường đáng kể hiệu suất mạng và hoạt động xác thực. Bạn có thể thực hiện hầu hết, nếu không muốn nói là tất cả, công việc của mình trong lớp học lập trình này bằng trình duyệt.
Sau khi kết nối với Cloud Shell, bạn sẽ thấy rằng mình đã được xác thực và dự án được đặt thành mã dự án của bạn.
- Chạy lệnh sau trong Cloud Shell để xác nhận rằng bạn đã được xác thực:
gcloud auth list
Đầu ra của lệnh
Credentialed Accounts
ACTIVE ACCOUNT
* <my_account>@<my_domain.com>
To set the active account, run:
$ gcloud config set account `ACCOUNT`
- Chạy lệnh sau trong Cloud Shell để xác nhận rằng lệnh gcloud biết về dự án của bạn:
gcloud config list project
Đầu ra của lệnh
[core] project = <PROJECT_ID>
Nếu không, bạn có thể đặt nó bằng lệnh sau:
gcloud config set project <PROJECT_ID>
Đầu ra của lệnh
Updated property [core/project].
3. Bật API và đặt các biến môi trường
Bật API
Để có thể bắt đầu sử dụng lớp học lập trình này, bạn cần bật một số API. Lớp học lập trình này yêu cầu bạn sử dụng các API sau. Bạn có thể bật các API đó bằng cách chạy lệnh sau:
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
aiplatform.googleapis.com \
secretmanager.googleapis.com
Thiết lập các biến môi trường
Bạn có thể thiết lập các biến môi trường sẽ được dùng trong suốt lớp học lập trình này.
PROJECT_ID=<YOUR_PROJECT_ID> REGION=<YOUR_REGION, e.g. us-central1> SERVICE=chat-with-gemini SERVICE_ACCOUNT="vertex-ai-caller" SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com SECRET_ID="SESSION_SECRET"
4. Tạo và định cấu hình dự án Firebase
- Trong bảng điều khiển của Firebase, hãy nhấp vào Thêm dự án.
- Nhập <YOUR_PROJECT_ID> để thêm Firebase vào một trong các dự án hiện có trên Google Cloud
- Nếu được nhắc, hãy xem xét và chấp nhận các điều khoản của Firebase.
- Nhấp vào Tiếp tục.
- Nhấp vào Xác nhận gói để xác nhận gói thanh toán Firebase.
- Bạn không bắt buộc phải Bật Google Analytics cho lớp học lập trình này.
- Nhấp vào Thêm Firebase.
- Khi dự án đã được tạo, hãy nhấp vào Tiếp tục.
- Trong trình đơn Build (Xây dựng), hãy nhấp vào Cơ sở dữ liệu Firestore.
- Nhấp vào Tạo cơ sở dữ liệu.
- Chọn khu vực của bạn trong trình đơn thả xuống Vị trí, rồi nhấp vào Tiếp theo.
- Sử dụng chế độ mặc định Bắt đầu ở chế độ phát hành công khai, rồi nhấp vào Tạo.
5. Tạo một tài khoản dịch vụ
Cloud Run sẽ dùng tài khoản dịch vụ này để gọi Vertex AI Gemini API. Tài khoản dịch vụ này cũng sẽ có quyền đọc và ghi vào Firestore, cũng như đọc các khoá bí mật từ Secret Manager.
Trước tiên, hãy tạo tài khoản dịch vụ bằng cách chạy lệnh sau:
gcloud iam service-accounts create $SERVICE_ACCOUNT \ --display-name="Cloud Run to access Vertex AI APIs"
Thứ hai, cấp vai trò Người dùng Vertex AI cho tài khoản dịch vụ.
gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \ --role=roles/aiplatform.user
Bây giờ, hãy tạo một bí mật trong Secret Manager. Dịch vụ Cloud Run sẽ truy cập vào khoá bí mật này dưới dạng biến môi trường, được phân giải tại thời điểm khởi động phiên bản. Bạn có thể tìm hiểu thêm về các bí mật và Cloud Run.
gcloud secrets create $SECRET_ID --replication-policy="automatic" printf "keyboard-cat" | gcloud secrets versions add $SECRET_ID --data-file=-
Đồng thời cấp cho tài khoản dịch vụ quyền truy cập vào bí mật của phiên hoạt động nhanh trong Trình quản lý bí mật.
gcloud secrets add-iam-policy-binding $SECRET_ID \
--member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
--role='roles/secretmanager.secretAccessor'
Cuối cùng, hãy cấp cho tài khoản dịch vụ quyền đọc và ghi vào Firestore.
gcloud projects add-iam-policy-binding $PROJECT_ID \ --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \ --role=roles/datastore.user
6. Tạo dịch vụ Cloud Run
Trước tiên, hãy tạo một thư mục cho mã nguồn và chuyển đến thư mục đó.
mkdir chat-with-gemini && cd chat-with-gemini
Sau đó, hãy tạo một tệp package.json có nội dung sau:
{
"name": "chat-with-gemini",
"version": "1.0.0",
"description": "",
"main": "app.js",
"scripts": {
"start": "node app.js",
"nodemon": "nodemon app.js",
"cssdev": "npx tailwindcss -i ./input.css -o ./public/output.css --watch",
"tailwind": "npx tailwindcss -i ./input.css -o ./public/output.css",
"dev": "npm run tailwind && npm run nodemon"
},
"keywords": [],
"author": "",
"license": "ISC",
"dependencies": {
"@google-cloud/connect-firestore": "^3.0.0",
"@google-cloud/firestore": "^7.5.0",
"@google-cloud/vertexai": "^0.4.0",
"axios": "^1.6.8",
"express": "^4.18.2",
"express-session": "^1.18.0",
"express-ws": "^5.0.2",
"htmx.org": "^1.9.10"
},
"devDependencies": {
"nodemon": "^3.1.0",
"tailwindcss": "^3.4.1"
}
}
Tiếp theo, hãy tạo một tệp nguồn app.js có nội dung bên dưới. Tệp này chứa điểm truy cập cho dịch vụ và chứa logic chính cho ứng dụng.
const express = require("express");
const app = express();
app.use(express.urlencoded({ extended: true }));
app.use(express.json());
const path = require("path");
const fs = require("fs");
const util = require("util");
const { spinnerSvg } = require("./spinnerSvg.js");
// cloud run retrieves secret at instance startup time
const secret = process.env.SESSION_SECRET;
const { Firestore } = require("@google-cloud/firestore");
const { FirestoreStore } = require("@google-cloud/connect-firestore");
var session = require("express-session");
app.set("trust proxy", 1); // trust first proxy
app.use(
session({
store: new FirestoreStore({
dataset: new Firestore(),
kind: "express-sessions"
}),
secret: secret,
/* set secure to false for local dev session history testing */
/* see more at https://expressjs.com/en/resources/middleware/session.html */
cookie: { secure: true },
resave: false,
saveUninitialized: true
})
);
const expressWs = require("express-ws")(app);
app.use(express.static("public"));
// Vertex AI Section
const { VertexAI } = require("@google-cloud/vertexai");
// instance of Vertex model
let generativeModel;
// on startup
const port = parseInt(process.env.PORT) || 8080;
app.listen(port, async () => {
console.log(`demo1: listening on port ${port}`);
// get project and location from metadata service
const metadataService = require("./metadataService.js");
const project = await metadataService.getProjectId();
const location = await metadataService.getRegion();
// Vertex client library instance
const vertex_ai = new VertexAI({
project: project,
location: location
});
// Instantiate models
generativeModel = vertex_ai.getGenerativeModel({
model: "gemini-1.0-pro-001"
});
});
app.ws("/sendMessage", async function (ws, req) {
if (!req.session.chathistory || req.session.chathistory.length == 0) {
req.session.chathistory = [];
}
let chatWithModel = generativeModel.startChat({
history: req.session.chathistory
});
ws.on("message", async function (message) {
console.log("req.sessionID: ", req.sessionID);
// get session id
let questionToAsk = JSON.parse(message).message;
console.log("WebSocket message: " + questionToAsk);
ws.send(`<div hx-swap-oob="beforeend:#toupdate"><div
id="questionToAsk"
class="text-black m-2 text-right border p-2 rounded-lg ml-24">
${questionToAsk}
</div></div>`);
// to simulate a natural pause in conversation
await sleep(500);
// get timestamp for div to replace
const now = "fromGemini" + Date.now();
ws.send(`<div hx-swap-oob="beforeend:#toupdate"><div
id=${now}
class=" text-blue-400 m-2 text-left border p-2 rounded-lg mr-24">
${spinnerSvg}
</div></div>`);
const results = await chatWithModel.sendMessage(questionToAsk);
const answer =
results.response.candidates[0].content.parts[0].text;
ws.send(`<div
id=${now}
hx-swap-oob="true"
hx-swap="outerHTML"
class="text-blue-400 m-2 text-left border p-2 rounded-lg mr-24">
${answer}
</div>`);
// save to current chat history
let userHistory = {
role: "user",
parts: [{ text: questionToAsk }]
};
let modelHistory = {
role: "model",
parts: [{ text: answer }]
};
req.session.chathistory.push(userHistory);
req.session.chathistory.push(modelHistory);
// console.log(
// "newly saved chat history: ",
// util.inspect(req.session.chathistory, {
// showHidden: false,
// depth: null,
// colors: true
// })
// );
req.session.save();
});
ws.on("close", () => {
console.log("WebSocket was closed");
});
});
function sleep(ms) {
return new Promise((resolve) => {
setTimeout(resolve, ms);
});
}
// gracefully close the web sockets
process.on("SIGTERM", () => {
server.close();
});
Tạo tệp tailwind.config.js cho tailwindCSS.
/** @type {import('tailwindcss').Config} */
module.exports = {
content: ["./**/*.{html,js}"],
theme: {
extend: {}
},
plugins: []
};
Tạo tệp metadataService.js để lấy mã dự án và khu vực cho dịch vụ Cloud Run đã triển khai. Các giá trị này sẽ được dùng để tạo một thực thể của thư viện ứng dụng Vertex AI.
const your_project_id = "YOUR_PROJECT_ID";
const your_region = "YOUR_REGION";
const axios = require("axios");
module.exports = {
getProjectId: async () => {
let project = "";
try {
// Fetch the token to make a GCF to GCF call
const response = await axios.get(
"http://metadata.google.internal/computeMetadata/v1/project/project-id",
{
headers: {
"Metadata-Flavor": "Google"
}
}
);
if (response.data == "") {
// running locally on Cloud Shell
project = your_project_id;
} else {
// running on Clodu Run. Use project id from metadata service
project = response.data;
}
} catch (ex) {
// running locally on local terminal
project = your_project_id;
}
return project;
},
getRegion: async () => {
let region = "";
try {
// Fetch the token to make a GCF to GCF call
const response = await axios.get(
"http://metadata.google.internal/computeMetadata/v1/instance/region",
{
headers: {
"Metadata-Flavor": "Google"
}
}
);
if (response.data == "") {
// running locally on Cloud Shell
region = your_region;
} else {
// running on Clodu Run. Use region from metadata service
let regionFull = response.data;
const index = regionFull.lastIndexOf("/");
region = regionFull.substring(index + 1);
}
} catch (ex) {
// running locally on local terminal
region = your_region;
}
return region;
}
};
Tạo một tệp có tên là spinnerSvg.js
module.exports.spinnerSvg = `<svg class="animate-spin -ml-1 mr-3 h-5 w-5 text-blue-500"
xmlns="http://www.w3.org/2000/svg"
fill="none"
viewBox="0 0 24 24"
>
<circle
class="opacity-25"
cx="12"
cy="12"
r="10"
stroke="currentColor"
stroke-width="4"
></circle>
<path
class="opacity-75"
fill="currentColor"
d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
></path></svg>`;
Cuối cùng, hãy tạo một tệp input.css cho tailwindCSS.
@tailwind base; @tailwind components; @tailwind utilities;
Bây giờ, hãy tạo một thư mục public mới.
mkdir public cd public
Trong thư mục công khai đó, hãy tạo tệp index.html cho giao diện người dùng sẽ sử dụng htmx.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1.0"
/>
<script
src="https://unpkg.com/htmx.org@1.9.10"
integrity="sha384-D1Kt99CQMDuVetoL1lrYwg5t+9QdHe7NLX/SoJYkXDFfX37iInKRy5xLSi8nO7UC"
crossorigin="anonymous"
></script>
<link href="./output.css" rel="stylesheet" />
<script src="https://unpkg.com/htmx.org/dist/ext/ws.js"></script>
<title>Demo 1</title>
</head>
<body>
<div id="herewego" text-center>
<!-- <div id="replaceme2" hx-swap-oob="true">Hello world</div> -->
<div
class="container mx-auto mt-8 text-center max-w-screen-lg"
>
<div
class="overflow-y-scroll bg-white p-2 border h-[500px] space-y-4 rounded-lg m-auto"
>
<div id="toupdate"></div>
</div>
<form
hx-trigger="submit, keyup[keyCode==13] from:body"
hx-ext="ws"
ws-connect="/sendMessage"
ws-send=""
hx-on="htmx:wsAfterSend: document.getElementById('message').value = ''"
>
<div class="mb-6 mt-6 flex gap-4">
<textarea
rows="2"
type="text"
id="message"
name="message"
class="block grow rounded-lg border p-6 resize-none"
required
>
Is C# a programming language or a musical note?</textarea
>
<button
type="submit"
class="bg-blue-500 text-white px-4 py-2 rounded-lg text-center text-sm font-medium"
>
Send
</button>
</div>
</form>
</div>
</div>
</body>
</html>
7. Chạy dịch vụ cục bộ
Trước tiên, hãy đảm bảo bạn đang ở thư mục gốc chat-with-gemini cho codelab của mình.
cd .. && pwd
Tiếp theo, hãy cài đặt các phần phụ thuộc bằng cách chạy lệnh sau:
npm install
Sử dụng ADC khi chạy cục bộ
Nếu đang chạy trong Cloud Shell, tức là bạn đang chạy trên một máy ảo Google Compute Engine. Thông tin xác thực của bạn được liên kết với máy ảo này (như khi chạy gcloud auth list) sẽ được Thông tin xác thực mặc định của ứng dụng tự động sử dụng, nên bạn không cần dùng lệnh gcloud auth application-default login. Bạn có thể bỏ qua đến phần Tạo khoá bí mật của phiên cục bộ
Tuy nhiên, nếu đang chạy trên thiết bị đầu cuối cục bộ (tức là không phải trong Cloud Shell), bạn sẽ cần sử dụng Thông tin xác thực mặc định của ứng dụng để xác thực với các API của Google. Bạn có thể 1) đăng nhập bằng thông tin đăng nhập của mình (miễn là bạn có cả vai trò Người dùng Vertex AI và Người dùng kho dữ liệu) hoặc 2) bạn có thể đăng nhập bằng cách mạo danh tài khoản dịch vụ được dùng trong lớp học lập trình này.
Cách 1) Sử dụng thông tin đăng nhập của bạn cho ADC
Nếu muốn sử dụng thông tin đăng nhập của mình, trước tiên, bạn có thể chạy gcloud auth list để xác minh cách bạn được xác thực trong gcloud. Tiếp theo, bạn có thể cần cấp cho danh tính của mình vai trò Người dùng Vertex AI. Nếu danh tính của bạn có vai trò Chủ sở hữu, thì bạn đã có vai trò người dùng Vertex AI này. Nếu không, bạn có thể chạy lệnh này để cấp cho danh tính của mình vai trò người dùng Vertex AI và vai trò Người dùng Datastore.
USER=<YOUR_PRINCIPAL_EMAIL> gcloud projects add-iam-policy-binding $PROJECT_ID \ --member user:$USER \ --role=roles/aiplatform.user gcloud projects add-iam-policy-binding $PROJECT_ID \ --member user:$USER \ --role=roles/datastore.user
Sau đó, hãy chạy lệnh sau
gcloud auth application-default login
Cách 2) Mạo danh tài khoản dịch vụ cho ADC
Nếu muốn sử dụng tài khoản dịch vụ được tạo trong lớp học lập trình này, tài khoản người dùng của bạn cần có vai trò Trình tạo mã thông báo tài khoản dịch vụ. Bạn có thể nhận được vai trò này bằng cách chạy lệnh sau:
gcloud projects add-iam-policy-binding $PROJECT_ID \ --member user:$USER \ --role=roles/iam.serviceAccountTokenCreator
Tiếp theo, bạn sẽ chạy lệnh sau để sử dụng ADC với tài khoản dịch vụ
gcloud auth application-default login --impersonate-service-account=$SERVICE_ACCOUNT_ADDRESS
Tạo một khoá bí mật cho phiên cục bộ
Bây giờ, hãy tạo một khoá bí mật phiên cục bộ để phát triển cục bộ.
export SESSION_SECRET=local-secret
Chạy ứng dụng cục bộ
Cuối cùng, bạn có thể chạy ứng dụng bằng cách chạy tập lệnh sau. Tập lệnh này cũng sẽ tạo tệp output.css từ tailwindCSS.
npm run dev
Bạn có thể xem trước trang web bằng cách mở nút Web Preview (Xem trước trang web) rồi chọn Preview Port 8080 (Xem trước cổng 8080)
8. Triển khai dịch vụ
Trước tiên, hãy chạy lệnh này để bắt đầu triển khai và chỉ định tài khoản dịch vụ sẽ được dùng. Nếu bạn không chỉ định tài khoản dịch vụ, thì tài khoản dịch vụ tính toán mặc định sẽ được dùng.
gcloud run deploy $SERVICE \ --service-account $SERVICE_ACCOUNT_ADDRESS \ --source . \ --region $REGION \ --allow-unauthenticated \ --set-secrets="SESSION_SECRET=$(echo $SECRET_ID):1"
Nếu bạn nhận được lời nhắc "Triển khai từ nguồn yêu cầu một kho lưu trữ Docker Artifact Registry để lưu trữ các vùng chứa đã tạo. Một kho lưu trữ có tên [cloud-run-source-deploy] ở khu vực [us-central1] sẽ được tạo.
9. Kiểm thử dịch vụ
Sau khi triển khai, hãy mở URL dịch vụ trong trình duyệt web. Sau đó, hãy đặt câu hỏi cho Gemini, ví dụ: "Tôi tập chơi đàn guitar nhưng cũng là một kỹ sư phần mềm. Khi thấy "C#", tôi nên nghĩ đó là một ngôn ngữ lập trình hay một nốt nhạc? Tôi nên chọn cái nào?
10. Xin chúc mừng!
Chúc mừng bạn đã hoàn thành lớp học lập trình này!
Bạn nên xem tài liệu về Cloud Run và Vertex AI Gemini API.
Nội dung đã đề cập
- Cách sử dụng htmx, tailwindcss và express.js để tạo một dịch vụ Cloud Run
- Cách sử dụng thư viện ứng dụng Vertex AI để xác thực với API của Google
- Cách tạo một chatbot để tương tác với mô hình Gemini
- Cách triển khai vào một dịch vụ Cloud Run mà không cần tệp Docker
- Cách sử dụng kho lưu trữ phiên nhanh được hỗ trợ bởi Google Cloud Firestore
11. Dọn dẹp
Để tránh bị tính phí ngoài ý muốn (ví dụ: nếu các dịch vụ Cloud Run được gọi nhiều lần hơn hạn mức gọi Cloud Run hằng tháng của bạn trong cấp miễn phí), bạn có thể xoá Cloud Run hoặc xoá dự án mà bạn đã tạo ở Bước 2.
Để xoá dịch vụ Cloud Run, hãy truy cập Cloud Console của Cloud Run tại https://console.cloud.google.com/run rồi xoá dịch vụ chat-with-gemini. Bạn cũng có thể xoá tài khoản dịch vụ vertex-ai-caller hoặc thu hồi vai trò Người dùng Vertex AI để tránh vô tình gọi Gemini.
Nếu chọn xoá toàn bộ dự án, bạn có thể truy cập vào https://console.cloud.google.com/cloud-resource-manager, chọn dự án bạn đã tạo ở Bước 2 rồi chọn Xoá. Nếu xoá dự án, bạn sẽ cần thay đổi dự án trong Cloud SDK. Bạn có thể xem danh sách tất cả các dự án có sẵn bằng cách chạy gcloud projects list.