Hướng dẫn này mô tả cách bắt đầu sử dụng Cloud Functions thế hệ 2 với Remote Config phía máy chủ để thực hiện các lệnh gọi phía máy chủ đến Vertex AI Gemini API.
Trong hướng dẫn này, bạn sẽ thêm Remote Config vào một hàm giống như chatbot sử dụng mô hình Gemini để trả lời câu hỏi của người dùng. Remote Config sẽ quản lý dữ liệu đầu vào Gemini API (bao gồm cả lời nhắc mà bạn sẽ thêm vào đầu truy vấn của người dùng sắp tới) và bạn có thể cập nhật các dữ liệu đầu vào này theo yêu cầu từ bảng điều khiển Firebase. Bạn cũng sẽ sử dụng Firebase Local Emulator Suite để kiểm thử và gỡ lỗi hàm, sau đó, sau khi xác minh rằng hàm này hoạt động, bạn sẽ triển khai và kiểm thử hàm này trên Google Cloud.
Điều kiện tiên quyết
Hướng dẫn này giả định rằng bạn đã quen thuộc với việc sử dụng JavaScript để phát triển ứng dụng.
Thiết lập dự án Firebase
Nếu bạn chưa có dự án Firebase:
Đăng nhập vào bảng điều khiển Firebase.
Nhấp vào Tạo dự án, rồi sử dụng một trong các tuỳ chọn sau:
- Cách 1: Tạo một dự án Firebase mới (và tự động tạo dự án Google Cloud cơ bản) bằng cách nhập tên dự án mới ở bước đầu tiên trong quy trình "Tạo dự án".
- Cách 2: "Thêm Firebase" vào dự án Google Cloud hiện có bằng cách chọn tên dự án Google Cloud trong trình đơn thả xuống ở bước đầu tiên của quy trình "Tạo dự án".
Khi được nhắc, bạn không cần thiết lập Google Analytics để sử dụng giải pháp này.
Tiếp tục làm theo hướng dẫn trên màn hình để tạo dự án.
Nếu bạn đã có một dự án Firebase:
Tiếp tục Định cấu hình môi trường phát triển.
Định cấu hình môi trường phát triển
Bạn sẽ cần môi trường Node.js để viết hàm và bạn sẽ cần CLI Firebase để triển khai các hàm vào môi trường thời gian chạy Cloud Functions.
-
Để cài đặt Node.js và npm, bạn nên sử dụng Trình quản lý phiên bản nút.
Cài đặt CLI Firebase bằng phương thức bạn muốn. Ví dụ: để cài đặt CLI bằng npm, hãy chạy lệnh sau:
npm install -g firebase-tools@latest
Lệnh này sẽ cài đặt lệnh
firebase
có sẵn trên toàn cầu. Nếu lệnh này không thành công, bạn có thể cần phải thay đổi quyền npm.Để cập nhật lên phiên bản
firebase-tools
mới nhất, hãy chạy lại cùng một lệnh.Cài đặt
firebase-functions
vàfirebase-admin
rồi sử dụng--save
để lưu các tệp này vàopackage.json
:npm install firebase-functions@latest firebase-admin@latest --save
Bây giờ, bạn đã sẵn sàng để tiến hành triển khai giải pháp này.
Triển khai
Hãy làm theo các bước sau để tạo, kiểm thử và triển khai Cloud Functions thế hệ 2 bằng Remote Config và Vertex AI:
- Bật các API đề xuất Vertex AI trong bảng điều khiển Google Cloud.
- Khởi chạy dự án và cài đặt các phần phụ thuộc Node.
- Định cấu hình quyền IAM cho tài khoản dịch vụ Admin SDK và lưu khoá.
- Tạo hàm.
- Tạo mẫu Remote Config dành riêng cho máy chủ.
- Triển khai và kiểm thử hàm trong Firebase Local Emulator Suite.
- Triển khai hàm của bạn đến Google Cloud.
Bước 1: Bật các API đề xuất Vertex AI trong bảng điều khiển Google Cloud
- Mở bảng điều khiển Google Cloud và chọn dự án của bạn khi được nhắc.
- Trong trường Search (Tìm kiếm) ở đầu bảng điều khiển, hãy nhập Vertex AI rồi đợi Vertex AI xuất hiện.
- Chọn Vertex AI. Trang tổng quan Vertex AI sẽ xuất hiện.
Nhấp vào Bật tất cả API được đề xuất.
Quá trình bật API có thể mất vài phút. Hãy giữ cho trang hoạt động và mở cho đến khi quá trình bật hoàn tất.
Nếu chưa bật tính năng thanh toán, bạn sẽ được nhắc thêm hoặc liên kết tài khoản Cloud Billing. Sau khi bật tài khoản thanh toán, hãy quay lại trang tổng quan Vertex AI và xác minh rằng bạn đã bật tất cả API được đề xuất.
Bước 2: Khởi chạy dự án và cài đặt các phần phụ thuộc của Node
- Mở một cửa sổ dòng lệnh trên máy tính và chuyển đến thư mục mà bạn dự định tạo hàm.
Đăng nhập vào Firebase:
firebase login
Chạy lệnh sau để khởi chạy Cloud Functions for Firebase:
firebase init functions
Chọn Sử dụng dự án hiện có rồi chỉ định mã dự án của bạn.
Khi được nhắc chọn ngôn ngữ để sử dụng, hãy chọn Javascript rồi nhấn Enter.
Đối với tất cả các tuỳ chọn khác, hãy chọn tuỳ chọn mặc định.
Thư mục
functions
được tạo trong thư mục hiện tại. Bên trong, bạn sẽ thấy một tệpindex.js
mà bạn sẽ sử dụng để tạo hàm, một thư mụcnode_modules
chứa các phần phụ thuộc cho hàm và một tệppackage.json
chứa các phần phụ thuộc gói.Thêm các gói Admin SDK và Vertex AI bằng cách chạy các lệnh sau, sử dụng
--save
để đảm bảo rằng gói được lưu vào tệppackage.json
:cd functions npm install firebase-admin@latest @google-cloud/vertexai --save
Tệp functions/package.json
của bạn hiện sẽ có dạng như sau, với các phiên bản mới nhất được chỉ định:
{
"name": "functions",
"description": "Cloud Functions for Firebase",
"scripts": {
"serve": "firebase emulators:start --only functions",
"shell": "firebase functions:shell",
"start": "npm run shell",
"deploy": "firebase deploy --only functions",
"logs": "firebase functions:log"
},
"engines": {
"node": "20"
},
"main": "index.js",
"dependencies": {
"@google-cloud/vertexai": "^1.1.0",
"firebase-admin": "^12.1.0",
"firebase-functions": "^5.0.0"
},
"devDependencies": {
"firebase-functions-test": "^3.1.0"
},
"private": true
}
Xin lưu ý rằng nếu đang sử dụng ESLint, bạn sẽ thấy một khổ thơ có chứa ESLint. Ngoài ra, hãy đảm bảo rằng phiên bản công cụ nút khớp với phiên bản Node.js đã cài đặt và phiên bản mà bạn cuối cùng chạy trên Google Cloud. Ví dụ: nếu bạn định cấu hình khổ engines
trong package.json
là Node phiên bản 18 và bạn đang sử dụng Node.js 20, hãy cập nhật tệp để sử dụng 20:
"engines": {
"node": "20"
},
Bước 3: Định cấu hình quyền IAM cho tài khoản dịch vụ Admin SDK và lưu khoá
Trong giải pháp này, bạn sẽ sử dụng tài khoản dịch vụ Admin SDK của Firebase để chạy hàm.
- Trong bảng điều khiển Google Cloud, hãy mở trang IAM & Admin (Quản trị viên và IAM) rồi tìm tài khoản dịch vụ Admin SDK (có tên là
firebase-adminsdk
). - Chọn tài khoản rồi nhấp vào Chỉnh sửa chủ sở hữu. Trang Chỉnh sửa quyền truy cập sẽ xuất hiện.
- Nhấp vào Thêm vai trò khác, chọn Remote Config Người xem.
- Nhấp vào Thêm vai trò khác, chọn Nhà phát triển nền tảng AI.
- Nhấp vào Thêm vai trò khác, chọn người dùng Vertex AI.
- Nhấp vào Thêm vai trò khác, chọn Trình gọi Cloud Run.
- Nhấp vào Lưu.
Tiếp theo, hãy xuất thông tin xác thực cho tài khoản dịch vụ Admin SDK và lưu thông tin đó vào biến môi trường GOOGLE_APPLICATION_CREDENTIALS
.
- Trong bảng điều khiển Google Cloud, hãy mở trang Thông tin xác thực.
- Nhấp vào tài khoản dịch vụ Admin SDK để mở trang Chi tiết.
- Nhấp vào Keys (Phím).
- Nhấp vào Thêm khoá > Tạo khoá mới.
- Đảm bảo bạn đã chọn JSON làm Loại khoá, sau đó nhấp vào Tạo.
- Tải khoá xuống một nơi an toàn trên máy tính.
Từ thiết bị đầu cuối, hãy xuất khoá dưới dạng biến môi trường:
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"
Bước 4: Tạo hàm
Ở bước này, bạn sẽ tạo một hàm xử lý dữ liệu đầu vào của người dùng và tạo phản hồi dựa trên AI. Bạn sẽ kết hợp nhiều đoạn mã để tạo một hàm toàn diện khởi chạy Admin SDK và Vertex AI Gemini API, định cấu hình các tham số mặc định bằng Remote Config, tìm nạp các tham số Remote Config mới nhất, xử lý dữ liệu đầu vào của người dùng và truyền phản hồi lại cho người dùng.
- Trong cơ sở mã, hãy mở
functions/index.js
trong trình soạn thảo văn bản hoặc IDE. Xoá nội dung hiện có, sau đó thêm SDK Admin SDK, Remote Config và Vertex AI rồi khởi chạy ứng dụng bằng cách dán mã sau vào tệp:
const { onRequest } = require("firebase-functions/v2/https"); const logger = require("firebase-functions/logger"); const { initializeApp } = require("firebase-admin/app"); const { VertexAI } = require('@google-cloud/vertexai'); const { getRemoteConfig } = require("firebase-admin/remote-config"); // Set and check environment variables. const project = process.env.GCLOUD_PROJECT; // Initialize Firebase. const app = initializeApp();
Định cấu hình các giá trị mặc định mà hàm của bạn sẽ sử dụng nếu không thể kết nối với máy chủ Remote Config. Giải pháp này định cấu hình
textModel
,generationConfig
,safetySettings
,textPrompt
vàlocation
dưới dạng tham số Remote Config tương ứng với các tham số Remote Config mà bạn sẽ định cấu hình thêm trong hướng dẫn này. Để biết thêm thông tin về các tham số này, hãy xem Ứng dụng Vertex AI Node.js.Nếu muốn, bạn cũng có thể định cấu hình một tham số để kiểm soát việc bạn có truy cập vào Vertex AI Gemini API hay không (trong ví dụ này, một tham số có tên là
vertex_enabled
). Chế độ thiết lập này có thể hữu ích khi kiểm thử hàm. Trong các đoạn mã sau, giá trị này được đặt thànhfalse
. Giá trị này sẽ bỏ qua việc sử dụng Vertex AI trong khi bạn kiểm thử việc triển khai hàm cơ bản. Việc đặt giá trị này thànhtrue
sẽ gọi Vertex AI Gemini API.// Define default (fallback) parameter values for Remote Config. const defaultConfig = { // Default values for Vertex AI. model_name: "gemini-1.5-flash-002", generation_config: [{ "stopSequences": [], "temperature": 0.7, "maxOutputTokens": 64, "topP": 0.1, "topK": 20 }], prompt: "I'm a developer who wants to learn about Firebase and you are a \ helpful assistant who knows everything there is to know about Firebase!", safety_settings: [{ "category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE" }], location: 'us-central1', // Disable Vertex AI Gemini API access for testing. vertex_enabled: false };
Tạo hàm và thiết lập Remote Config phía máy chủ:
// Export the function. exports.generateWithVertex = onRequest(async (request, response) => { try { // Set up Remote Config. const rc = getRemoteConfig(app); // Get the Remote Config template and assign default values. const template = await rc.getServerTemplate({ defaultConfig: defaultConfig }); // Add the template evaluation to a constant. const config = template.evaluate(); // Obtain values from Remote Config. const textModel = config.getString("model_name") || defaultConfig.model_name; const textPrompt = config.getString("prompt") || defaultConfig.prompt; const generationConfig = config.getString("generation_config") || defaultConfig.generation_config; const safetySettings = config.getString("safety_settings") || defaultConfig.safety_settings; const location = config.getString("location") || defaultConfig.location; const vertexEnabled = config.getBoolean("is_vertex_enabled") || defaultConfig.vertex_enabled;
Thiết lập Vertex AI và thêm logic trò chuyện và phản hồi:
// Allow user input. const userInput = request.query.prompt || ''; // Instantiate Vertex AI. const vertex_ai = new VertexAI({ project: project, location: location }); const generativeModel = vertex_ai.getGenerativeModel({ model: textModel, safety_settings: safetySettings, generation_config: generationConfig, }); // Combine prompt from Remote Config with optional user input. const chatInput = textPrompt + " " + userInput; if (!chatInput) { return res.status(400).send('Missing text prompt'); } // If vertexEnabled isn't true, do not send queries to Vertex AI. if (vertexEnabled !== true) { response.status(200).send({ message: "Vertex AI call skipped. Vertex is not enabled." }); return; } logger.log("\nRunning with model ", textModel, ", prompt: ", textPrompt, ", generationConfig: ", generationConfig, ", safetySettings: ", safetySettings, " in ", location, "\n"); const result = await generativeModel.generateContentStream(chatInput); response.writeHead(200, { 'Content-Type': 'text/plain' }); for await (const item of result.stream) { const chunk = item.candidates[0].content.parts[0].text; logger.log("Received chunk:", chunk); response.write(chunk); } response.end(); } catch (error) { logger.error(error); response.status(500).send('Internal server error'); } });
Lưu và đóng tệp.
Bước 5: Tạo mẫu Remote Config dành riêng cho máy chủ
Tiếp theo, hãy tạo một mẫu Remote Config phía máy chủ và định cấu hình các thông số cũng như giá trị để sử dụng trong hàm. Cách tạo mẫu Remote Config dành riêng cho máy chủ:
- Mở bảng điều khiển Firebase, rồi trong trình đơn điều hướng, hãy mở rộng mục Run (Chạy) rồi chọn Remote Config.
Chọn Máy chủ trong bộ chọn Máy khách/Máy chủ ở đầu trang Remote Config.
- Nếu đây là lần đầu tiên bạn sử dụng Remote Config hoặc mẫu máy chủ, hãy nhấp vào Tạo cấu hình. Ngăn Tạo tham số phía máy chủ đầu tiên sẽ xuất hiện.
- Nếu đây không phải là lần đầu tiên bạn sử dụng mẫu máy chủ Remote Config, hãy nhấp vào Thêm thông số.
Xác định các tham số Remote Config sau:
Tên tham số Nội dung mô tả Loại Giá trị mặc định model_name
Tên mô hình
Để biết danh sách tên mô hình mới nhất để sử dụng trong mã, hãy xem nội dung Vòng đời và phiên bản mô hình hoặc Tên mô hình có sẵn.Chuỗi gemini-1.5-flash-002
prompt
Lời nhắc thêm vào cụm từ tìm kiếm của người dùng. Chuỗi I'm a developer who wants to learn about Firebase and you are a helpful assistant who knows everything there is to know about Firebase!
generation_config
Các tham số cần gửi đến mô hình. JSON [{"stopSequences": ["I hope this helps"],"temperature": 0.7,"maxOutputTokens": 512, "topP": 0.1,"topK": 20}]
safety_settings
Chế độ cài đặt an toàn cho Vertex AI. JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
location
Vị trí để chạy dịch vụ và mô hình Vertex AI. Chuỗi us-central1
is_vertex_enabled
Tham số không bắt buộc kiểm soát việc có gửi truy vấn đến Vertex AI hay không. Boolean true
Khi bạn thêm xong các thông số, hãy kiểm tra kỹ các thông số đó và đảm bảo rằng loại dữ liệu của các thông số đó là chính xác, sau đó nhấp vào Xuất bản các thay đổi.
Bước 6: Triển khai và kiểm thử hàm trong Firebase Local Emulator Suite
Giờ thì bạn đã sẵn sàng triển khai và kiểm thử hàm trên máy cục bộ bằng Firebase Local Emulator Suite.
Đảm bảo rằng bạn đã đặt
GOOGLE_APPLICATION_CREDENTIALS
làm biến môi trường như mô tả trong Bước 3: Định cấu hình quyền IAM cho tài khoản dịch vụ Admin SDK và lưu khoá. Sau đó, từ thư mục mẹ của thư mụcfunctions
, hãy triển khai hàm của bạn cho trình mô phỏng Firebase:firebase emulators:start --project PROJECT_ID --only functions
Mở trang nhật ký của trình mô phỏng. Điều này cho thấy hàm của bạn đã tải.
Truy cập vào hàm của bạn bằng cách chạy lệnh sau, trong đó PROJECT_ID là mã dự án và LOCATION là khu vực mà bạn đã triển khai hàm (ví dụ:
us-central1
):curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex
Chờ phản hồi, sau đó quay lại trang nhật ký của Trình mô phỏng Firebase hoặc bảng điều khiển của bạn rồi kiểm tra xem có lỗi hoặc cảnh báo nào không.
Hãy thử gửi một số dữ liệu đầu vào của người dùng, lưu ý rằng vì
is_vertex_enabled
được định cấu hình trong mẫu máy chủ Remote Config, nên thao tác này sẽ truy cập vào Gemini thông qua Vertex AI Gemini API và có thể phải trả phí:curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats
Thực hiện thay đổi đối với mẫu máy chủ Remote Config trên bảng điều khiển Firebase, sau đó truy cập lại hàm để quan sát các thay đổi.
Bước 7: Triển khai hàm của bạn đến Google Cloud
Sau khi kiểm thử và xác minh hàm, bạn có thể triển khai vào Google Cloud và kiểm thử hàm trực tiếp.
Triển khai hàm
Triển khai hàm bằng CLI Firebase:
firebase deploy --only functions
Chặn quyền truy cập chưa xác thực vào hàm
Khi các hàm được triển khai bằng Firebase, các lệnh gọi chưa xác thực sẽ được phép theo mặc định nếu chính sách của tổ chức không hạn chế việc này. Trong quá trình kiểm thử và trước khi bảo mật bằng App Check, bạn nên chặn quyền truy cập chưa xác thực.
Cách chặn quyền truy cập chưa xác thực vào hàm:
Trong bảng điều khiển Google Cloud, hãy mở Cloud Run.
Nhấp vào
generateWithVertex
, rồi nhấp vào thẻ Bảo mật.Bật chế độ Yêu cầu xác thực rồi nhấp vào Lưu.
Định cấu hình tài khoản người dùng để sử dụng thông tin xác thực tài khoản dịch vụ Admin SDK
Vì tài khoản dịch vụ Admin SDK có tất cả các vai trò và quyền cần thiết để chạy hàm và tương tác với Remote Config và Vertex AI Gemini API, nên bạn nên sử dụng tài khoản này để chạy hàm. Để làm điều này, bạn phải có thể tạo mã thông báo cho tài khoản từ tài khoản người dùng của mình.
Các bước sau đây mô tả cách định cấu hình tài khoản người dùng và hàm để chạy bằng các đặc quyền của tài khoản dịch vụ Admin SDK.
- Trong bảng điều khiển Google Cloud, hãy bật IAM Service Account Credentials API.
- Cấp cho tài khoản người dùng của bạn vai trò Trình tạo mã thông báo tài khoản dịch vụ: Trên bảng điều khiển Google Cloud, hãy mở IAM & Admin (Quản trị viên và IAM) > IAM, chọn tài khoản người dùng của bạn, sau đó nhấp vào Edit principal (Chỉnh sửa chủ thể) > Add another role (Thêm vai trò khác).
Chọn Trình tạo mã thông báo tài khoản dịch vụ, sau đó nhấp vào Lưu.
Để biết thêm thông tin chi tiết về việc mạo danh tài khoản dịch vụ, hãy tham khảo phần Mạo danh tài khoản dịch vụ trong tài liệu về Google Cloud.
Mở trang Google Cloud của bảng điều khiển Cloud Functions rồi nhấp vào hàm generateWithVertex trong danh sách Hàm.
Chọn Trình kích hoạt > Chỉnh sửa rồi mở rộng Thời gian chạy, bản dựng, kết nối và cài đặt bảo mật.
Trong thẻ Thời gian chạy, hãy thay đổi Tài khoản dịch vụ thời gian chạy thành Tài khoản SDK dành cho quản trị viên.
Nhấp vào Tiếp theo, rồi nhấp vào Triển khai.
Thiết lập gcloud CLI
Để chạy và kiểm thử hàm một cách an toàn từ dòng lệnh, bạn cần xác thực bằng dịch vụ Cloud Functions và lấy mã thông báo xác thực hợp lệ.
Để bật tính năng tạo mã thông báo, hãy cài đặt và định cấu hình CLI gcloud:
Nếu chưa cài đặt trên máy tính, hãy cài đặt gcloud CLI như mô tả trong phần Cài đặt gcloud CLI.
Lấy thông tin xác thực quyền truy cập cho tài khoản Google Cloud:
gcloud auth login
Đặt mã dự án trong gcloud:
gcloud config set project PROJECT_ID
Kiểm thử hàm
Giờ thì bạn đã sẵn sàng kiểm thử hàm trong Google Cloud. Để kiểm thử hàm này, hãy chạy lệnh sau:
curl -X POST https://LOCATION-PROJECT_ID.cloudfunctions.net/generateWithVertex \
-H "Authorization: bearer $(gcloud auth print-identity-token)" \
-H "Content-Type: application/json"
Thử lại bằng dữ liệu do người dùng cung cấp:
curl -X POST https://LOCATION-PROJECT_ID.cloudfunctions.net/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20dogs \
-H "Authorization: bearer $(gcloud auth print-identity-token)" \
-H "Content-Type: application/json"
Giờ đây, bạn có thể thực hiện các thay đổi đối với mẫu máy chủ Remote Config, phát hành các thay đổi đó và thử nghiệm nhiều tuỳ chọn.
Các bước tiếp theo
- Firebase khuyên bạn nên sử dụng App Check để bảo mật Cloud Functions. Xem phần Bật tính năng thực thi App Check cho Cloud Functions để biết thêm thông tin về cách bảo mật hàm bằng App Check
- Thử một hàm có thể gọi mẫu với Remote Config và App Check phía máy chủ tại Gọi Vertex AI Gemini API bằng Remote Config và App Check.
- Tìm hiểu thêm về Cloud Functions cho Firebase.
- Tìm hiểu thêm về cách sử dụng Remote Config trong môi trường máy chủ.