Sử dụng Cấu hình từ xa phía máy chủ với Cloud Functions và Agent Platform

Hướng dẫn này mô tả cách bắt đầu sử dụng Cloud Functions thế hệ thứ 2 với Remote Config phía máy chủ để thực hiện lệnh gọi phía máy chủ đến Agent Platform Gemini API (formerly Vertex AI).

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 của Gemini API (bao gồm cả câu lệnh mà bạn sẽ thêm vào trước các truy vấn của người dùng), đồng thời 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 hoạt động, bạn sẽ triển khai và kiểm thử hàm 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 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:

  1. Đăng nhập vào bảng điều khiển Firebase.

  2. Nhấp vào Tạo dự án, rồi sử dụng một trong các lựa chọn sau:

    • Cách 1: Tạo một dự án Firebase mới (và dự án Google Cloud cơ bản của dự án đó một cách tự động) 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 một 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".
  3. 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.

  4. 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ó 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 cần có môi trường Node.js để viết hàm và cần có CLI Firebase để triển khai hàm cho thời gian chạy Cloud Functions.

  1. Cài đặt Node.js và npm.

    Để 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.

  2. Cài đặt Giao diện dòng lệnh (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 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 mới nhất của firebase-tools, hãy chạy lại lệnh đó.

  3. Cài đặt firebase-functions và firebase-admin rồi dùng --save để lưu vào package.json:

    npm install firebase-functions@latest firebase-admin@latest --save
    

Giờ đây, bạn đã sẵn sàng 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ệ thứ 2 bằng Remote Config và Agent Platform:

  1. Bật Agent Platform API được đề xuất trong Google Cloud console.
  2. Khởi chạy dự án và cài đặt các phần phụ thuộc Node.
  3. Định cấu hình quyền IAM cho tài khoản dịch vụ Admin SDK và lưu khoá của bạn.
  4. Tạo hàm.
  5. Tạo mẫu Remote Config dành riêng cho máy chủ.
  6. Triển khai hàm và kiểm thử hàm đó trong Firebase Local Emulator Suite.
  7. Triển khai hàm của bạn cho Google Cloud.

Bước 1: Bật Agent Platform API được đề xuất trong bảng điều khiển Google Cloud

  1. Mở bảng điều khiển Google Cloud rồi chọn dự án của bạn khi được nhắc.
  2. Trong trường Search (Tìm kiếm) ở đầu bảng điều khiển, hãy nhập Agent Platform và đợi Agent Platform xuất hiện dưới dạng kết quả.
  3. Chọn Agent Platform. Trang tổng quan Agent Platform sẽ xuất hiện.
  4. Nhấp vào Bật tất cả API được đề xuất.

    Có thể mất vài phút để hoàn tất quá trình bật API. Hãy luôn mở và duy trì hoạt động cho trang này cho đến khi quá trình bật hoàn tất.

  5. 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 mộ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 Agent Platform và xác minh rằng tất cả API được đề xuất đều đã được bật.

Bước 2: Khởi chạy dự án và cài đặt các phần phụ thuộc Node

  1. Mở một cửa sổ dòng lệnh trên máy tính rồi chuyển đến thư mục mà bạn dự định tạo hàm.
  2. Đăng nhập vào Firebase:

    firebase login
    
  3. Chạy lệnh sau để khởi chạy Cloud Functions for Firebase:

    firebase init functions
    
  4. Chọn Sử dụng dự án hiện có rồi chỉ định mã dự án.

  5. Khi được nhắc chọn ngôn ngữ để sử dụng, hãy chọn Javascript rồi nhấn phím Enter.

  6. Đối với tất cả các lựa chọn khác, hãy chọn chế độ 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ệp index.js mà bạn sẽ dùng để xây dựng hàm, một thư mục node_modules chứa các phần phụ thuộc cho hàm và một tệp package.json chứa các phần phụ thuộc của gói.

  7. Thêm các gói Admin SDK và Agent Platform 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ệp package.json của bạn:

    cd functions
    npm install firebase-admin@latest @google-cloud/vertexai --save
    

Bây giờ, tệp functions/package.json của bạ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
  }

Lưu ý rằng nếu đang sử dụng ESLint, bạn sẽ thấy một đoạn mã bao gồm 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 bạn chạy trên Google Cloud. Ví dụ: nếu khổ thơ engines trong package.json được định cấu hình 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: Thiết lập quyền truy cập 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.

  1. Trong bảng điều khiển Google Cloud, hãy mở trang IAM và Quản trị rồi tìm tài khoản dịch vụ Admin SDK (có tên là firebase-adminsdk).
  2. Chọn tài khoản rồi nhấp vào Chỉnh sửa tài khoản chính. Trang Chỉnh sửa quyền truy cập sẽ xuất hiện.
  3. Nhấp vào Thêm vai trò khác, chọn Người xem Remote Config.
  4. Nhấp vào Thêm vai trò khác, chọn Nhà phát triển nền tảng AI.
  5. Nhấp vào Thêm vai trò khác, chọn Người dùng Agent Platform.
  6. Nhấp vào Thêm vai trò khác, chọn Cloud Run Invoker (Trình gọi Cloud Run).
  7. Nhấp vào Lưu.

Tiếp theo, hãy xuất thông tin đăng nhập cho tài khoản dịch vụ Admin SDK rồi lưu thông tin đó vào biến môi trường GOOGLE_APPLICATION_CREDENTIALS.

  1. Trong bảng điều khiển Google Cloud, hãy mở trang Thông tin đăng nhập.
  2. Nhấp vào tài khoản dịch vụ Admin SDK để mở trang Chi tiết.
  3. Nhấp vào Khoá.
  4. Nhấp vào Thêm khoá > Tạo khoá mới.
  5. Đảm bảo bạn đã chọn JSON làm Loại khoá, sau đó nhấp vào Tạo.
  6. Tải khoá xuống một nơi an toàn trên máy tính.
  7. Trong 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

Trong 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 câu trả lời dựa trên AI. Bạn sẽ kết hợp nhiều đoạn mã để xây dựng một hàm toàn diện giúp khởi chạy Admin SDK và Agent Platform Gemini API (formerly Vertex AI), đị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 trực tuyến câu trả lời cho người dùng.

  1. Trong toàn bộ mã nguồn, hãy mở functions/index.js trong trình chỉnh sửa văn bản hoặc IDE.
  2. Xoá nội dung hiện có, sau đó thêm SDK Admin SDK, Remote Config và Agent Platform 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/https");
    const { requiresRole, requiresAPI } = require("firebase-functions");
    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");
    
    requiresRole("roles/aiplatform.user");
    requiresRole("roles/cloudconfig.viewer");
    requiresAPI("aiplatform.googleapis.com", "Needed to query Vertex AI Gemini models");
    requiresAPI("firebaseremoteconfig.googleapis.com", "Needed to fetch server-side Remote Config templates");
    
    // Set and check environment variables.
    const project = process.env.GCLOUD_PROJECT;
    
    // Initialize Firebase.
    const app = initializeApp();
    
  3. Đị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 các 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 bài viết Ứng dụng Node.js của Vertex AI.

    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 Agent Platform Gemini API (formerly Vertex AI) hay không (trong ví dụ này, tham số có tên là vertex_enabled). Cách thiết lập này có thể hữu ích khi bạn kiểm thử hàm. Trong các đoạn mã sau, giá trị này được đặt thành false, tức là sẽ bỏ qua việc sử dụng Agent Platform trong khi bạn kiểm thử việc triển khai hàm cơ bản. Việc đặt thành true sẽ gọi Agent Platform Gemini API (formerly Vertex AI).

    // 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
    };
    
  4. Tạo hàm và thiết lập phía máy chủ Remote Config:

    // 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;
    
  5. Thiết lập Agent Platform 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');
      }
    });
    
  6. 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 tham số cũng như giá trị để sử dụng trong hàm của bạn. Cách tạo mẫu Remote Config dành riêng cho máy chủ:

  1. Trong bảng điều khiển Firebase, hãy chuyển đến DevOps & Engagement (DevOps và mức độ tương tác) > Remote Config (Cấu hình từ xa).

  2. Trong bộ chọn Ứng dụng/Máy chủ ở đầu trang, hãy chọn Máy chủ.

    • 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 thông 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 tham số.
  3. 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 mà bạn có thể dùng trong mã, hãy xem phần Phiên bản và vòng đời của mô hình hoặc Tên mô hình hiện có.
    Chuỗi gemini-2.0-flash
    prompt Câu lệnh để thêm vào trước 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 Tham số để 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 Agent Platform 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 Agent Platform Chuỗi global
    is_vertex_enabled Tham số không bắt buộc kiểm soát việc các truy vấn có được gửi đến Agent Platform hay không. Boolean true
  4. Khi bạn đã thêm xong các tham số, hãy kiểm tra kỹ các tham số và kiểu dữ liệu của các tham số đó, sau đó nhấp vào Xuất bản thay đổi.

Bước 6: Triển khai hàm và kiểm thử trong Firebase Local Emulator Suite

Giờ đây, bạn đã sẵn sàng triển khai và kiểm thử hàm của mình trên máy bằng Firebase Local Emulator Suite.

  1. Đả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á của bạn. Sau đó, từ thư mục mẹ của thư mục functions, 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
    
  2. 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 đã được tải.

  3. 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 của bạ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
    
  4. 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.

  5. 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 mẫu này sẽ truy cập vào mô hình Gemini thông qua Agent Platform Gemini API (formerly Vertex AI) và điều này có thể phát sinh phí:

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats
    
  6. Thực hiện thay đổi đối với mẫu máy chủ Remote Config trong bảng điều khiển Firebase, sau đó truy cập lại vào hàm để quan sát các thay đổi.

Bước 7: Triển khai hàm lên Google Cloud

Sau khi thử nghiệm và xác minh hàm, bạn có thể triển khai hàm đó lên Google Cloud và thử nghiệm hàm đang hoạt động.

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 được 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 được xác thực sẽ được cho phép theo mặc định nếu chính sách của tổ chức bạn không hạn chế. Trong quá trình thử nghiệm 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 được xác thực.

Cách chặn quyền truy cập chưa được xác thực vào hàm:

  1. Trong bảng điều khiển Google Cloud, hãy mở Cloud Run.

  2. Nhấp vào generateWithVertex, rồi nhấp vào thẻ Bảo mật.

  3. 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 đăng nhập của 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à Agent Platform Gemini API (formerly Vertex AI), nên bạn sẽ muốn sử dụng tài khoản này để chạy hàm. Để làm việc 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 quyền của tài khoản dịch vụ Admin SDK.

  1. Trong bảng điều khiển Google Cloud, hãy bật API thông tin đăng nhập tài khoản dịch vụ IAM.
  2. Cấp cho tài khoản người dùng của bạn vai trò Người 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 (IAM và Quản trị) > 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 tài khoản chính) > Add another role (Thêm vai trò khác).
  3. Chọn Người 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 bài viết Mạo danh tài khoản dịch vụ trong tài liệu về Google Cloud.

  4. Mở trang bảng điều khiển Google Cloud Cloud Functions rồi nhấp vào hàm generateWithVertex trong danh sách Functions (Hàm).

  5. Chọn Trigger (Điều kiện kích hoạt) > Edit (Chỉnh sửa) rồi mở rộng phần Runtime, build, connections and security settings (Thời gian chạy, bản dựng, kết nối và chế độ cài đặt bảo mật).

  6. 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.

  7. 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ã 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 gcloud CLI:

  1. Nếu bạn chưa cài đặt gcloud CLI trên máy tính, hãy cài đặt theo hướng dẫn trong phần Cài đặt gcloud CLI.

  2. Lấy thông tin đăng nhập cho tài khoản Google Cloud của bạn:

    gcloud auth login
    
  3. Đặ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, 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ể thay đổi mẫu phía máy chủ Remote Config, xuất bản những thay đổi đó và thử nghiệm nhiều lựa chọn.

Các bước tiếp theo