Sử dụng Cấu hình từ xa trong môi trường máy chủ

Firebase Remote Config hỗ trợ cấu hình phía máy chủ bằng Firebase Admin SDK cho Node.js (phiên bản 12.1.0 trở lên), Python (phiên bản 6.7.0 trở lên), Java (phiên bản 9.7.0 trở lên) và Go (phiên bản 4.17.0 trở lên).

Khả năng này cho phép bạn quản lý linh hoạt hành vi và cấu hình của các ứng dụng phía máy chủ bằng Remote Config. Điều này bao gồm các hoạt động triển khai không máy chủ như Cloud Functions for Firebase và các dịch vụ được chứa trong vùng chứa trên Cloud Run.

Không giống như Firebase SDK phía máy khách (tìm nạp một cấu hình dành riêng cho máy khách xuất phát từ mẫu Remote Config), SDK Remote Config phía máy chủ sẽ tải xuống hoặc tìm nạp một mẫu hoàn chỉnh Remote Config từ Firebase. Sau đó, máy chủ của bạn có thể đánh giá mẫu này bằng từng yêu cầu đến và sử dụng logic riêng để phân phát một phản hồi tuỳ chỉnh với độ trễ rất thấp. Bạn có thể sử dụng điều kiện để kiểm soát và tuỳ chỉnh các phản hồi dựa trên tỷ lệ phần trăm ngẫu nhiên và các thuộc tính của khách hàng được xác định trong tín hiệu tuỳ chỉnh.

Với Remote Config phía máy chủ, bạn có thể:

  • Xác định các thông số cấu hình cho những ứng dụng đang chạy hoặc được truy cập thông qua máy chủ của bạn, cho phép các trường hợp sử dụng như định cấu hình từ xa các thông số và câu lệnh của mô hình AI cũng như các hoạt động tích hợp khác, để đảm bảo khoá API của bạn luôn an toàn.
  • Điều chỉnh các tham số một cách linh hoạt để phản hồi những thay đổi trong môi trường của bạn hoặc các thay đổi khác của ứng dụng, chẳng hạn như cập nhật các tham số LLM và điểm cuối của mô hình.
  • Kiểm soát chi phí bằng cách cập nhật từ xa các API mà máy chủ của bạn gọi.
  • Tạo cấu hình tuỳ chỉnh ngay lập tức cho những ứng dụng khách truy cập vào máy chủ của bạn.
  • Ghi lại những ứng dụng nhận được một giá trị tham số và sử dụng giá trị này trong Cloud Functions for Firebase như một phần của hệ thống xác minh quyền.

Bạn có thể triển khai Remote Config phía máy chủ trên Cloud Run, Cloud Functions for Firebase hoặc môi trường máy chủ tự lưu trữ.

Trước khi bắt đầu

Làm theo hướng dẫn trong phần Thêm SDK của Firebase dành cho quản trị viên vào máy chủ để tạo một dự án Firebase, thiết lập tài khoản dịch vụ và thêm SDK của Firebase dành cho quản trị viên vào máy chủ. Đảm bảo bạn sử dụng phiên bản được hỗ trợ của SDK dành cho quản trị viên cho nền tảng của mình:

  • Node.js: Firebase Admin Node.js SDK phiên bản 12.1.0 trở lên
  • Python: Firebase Admin Python SDK phiên bản 6.7.0 trở lên
  • Java: Firebase Admin Java SDK phiên bản 9.7.0 trở lên
  • Go: Firebase Admin Go SDK phiên bản 4.17.0 trở lên

Bước 1: Khởi tạo SDK của Firebase dành cho quản trị viên và uỷ quyền các yêu cầu API

Khi bạn khởi chạy SDK dành cho quản trị viên mà không có tham số, SDK sẽ sử dụng Thông tin xác thực mặc định của ứng dụng Google và đọc các lựa chọn từ biến môi trường GOOGLE_APPLICATION_CREDENTIALS. Khởi chạy SDK và định cấu hình Remote Config cho nền tảng của bạn:

Node.js

Nhập initializeApp và getRemoteConfig, sau đó khởi động phiên bản ứng dụng Firebase của bạn:

import { initializeApp } from "firebase-admin/app";
import { getRemoteConfig } from "firebase-admin/remote-config";

// Initialize Firebase
const firebaseApp = initializeApp();

Python

Nhập firebase_admin (cùng với asyncio và json để tải mẫu không đồng bộ và phân tích cú pháp JSON), sau đó khởi chạy ứng dụng:

import firebase_admin
import asyncio
import json

firebase_admin.initialize_app()

Java

Khởi chạy SDK của Firebase dành cho quản trị viên bằng FirebaseOptions và thông tin đăng nhập tài khoản dịch vụ của bạn:

// Initialize the Firebase Admin SDK
FirebaseOptions options = new FirebaseOptions.Builder()
    .setCredentials(GoogleCredentials.fromStream(serviceAccount))
    .build();
FirebaseApp.initializeApp(options);

Bắt đầu

Khởi chạy ứng dụng Firebase và tạo một phiên bản RemoteConfig:

ctx := context.Background()

// Initialize Firebase
app, err := firebase.NewApp(ctx, nil)
if err != nil {
    log.Fatalln("Error initializing app:", err)
}

remoteConfig, err := app.RemoteConfig(ctx)
if err != nil {
    log.Fatalln("Error initializing remote config client:", err)
}

Bước 2: Xác định các giá trị tham số mặc định cho ứng dụng máy chủ

Xác định các biến trong ứng dụng mà bạn muốn cập nhật linh hoạt bằng Remote Config. Sau đó, hãy cân nhắc những biến nào phải được đặt theo mặc định trong ứng dụng của bạn và giá trị mặc định của chúng là gì. Điều này đảm bảo rằng ứng dụng của bạn chạy thành công ngay cả khi kết nối của ứng dụng với máy chủ phụ trợ Remote Config bị gián đoạn.

Ví dụ: nếu đang viết một ứng dụng máy chủ quản lý một chức năng AI tạo sinh, bạn có thể đặt tên mô hình mặc định, phần mở đầu của câu lệnh và cấu hình AI tạo sinh, chẳng hạn như sau:

Tên tham số Nội dung mô tả Loại Giá trị mặc định
model_name Tên API mô hình Chuỗi gemini-2.0-flash
preamble_prompt Câu lệnh cần 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 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}

Bước 3: Định cấu hình ứng dụng máy chủ

Sau khi xác định các thông số bạn muốn sử dụng với Remote Config, hãy định cấu hình ứng dụng của bạn để đặt các giá trị mặc định, tìm nạp mẫu Remote Config dành riêng cho máy chủ và đánh giá các giá trị của mẫu đó.

  1. Truy cập và tải mẫu máy chủ Remote Config.

    Node.js

    Khởi tạo mẫu máy chủ bằng cách sử dụng initServerTemplate() và gọi load() để tìm nạp mẫu từ phần phụ trợ:

    // Initialize server-side Remote Config
    const rc = getRemoteConfig(firebaseApp);
    const template = rc.initServerTemplate();
    
    // Load Remote Config
    await template.load();
    

    Nếu đang sử dụng Node.js trong Cloud Functions for Firebase, bạn có thể dùng hàm getServerTemplate() không đồng bộ để khởi động và tải mẫu trong một bước duy nhất:

    // Initialize server-side Remote Config
    const rc = getRemoteConfig(firebaseApp);
    const template = await rc.getServerTemplate();
    

    Python

    Khởi tạo mẫu máy chủ bằng cách sử dụng init_server_template() và gọi load() để tìm nạp mẫu từ phần phụ trợ:

    from firebase_admin import remote_config
    
    # Initialize server-side Remote Config
    template = remote_config.init_server_template()
    
    # Load the template from the backend
    asyncio.run(template.load())
    

    Ngoài ra, nếu đang sử dụng Python với Cloud Functions for Firebase, bạn có thể dùng hàm get_server_template() không đồng bộ để khởi chạy và tải mẫu trong một bước duy nhất:

    # Initialize server-side Remote Config
    template = await remote_config.get_server_template()
    

    Java

    Khởi chạy ứng dụng Remote Config phía máy chủ bằng cách sử dụng FirebaseRemoteConfig.getInstance():

    // Initialize server-side Remote Config client
    FirebaseRemoteConfig rc = FirebaseRemoteConfig.getInstance();
    

    Ngoài ra, nếu đang dùng Java với Cloud Functions for Firebase, bạn có thể dùng getServerTemplate() để khởi động và tải mẫu trong một bước duy nhất:

    ServerTemplate template = rc.getServerTemplate();
    

    Bắt đầu

    Khởi tạo mẫu máy chủ bằng cách sử dụng InitServerTemplate() và gọi Load() để tìm nạp mẫu từ phần phụ trợ:

    // Initialize server-side Remote Config
    defaultConfig := make(map[string]any)
    templateDataJSON := ""
    template, err := remoteConfig.InitServerTemplate(defaultConfig, templateDataJSON)
    if err != nil {
        log.Fatalln("Error initializing server template:", err)
    }
    
    // Load Remote Config
    err = template.Load(ctx)
    if err != nil {
        log.Fatalln("Error fetching server template:", err)
    }
    

    Một cách khác để khởi chạy mẫu là sử dụng hàm GetServerTemplate để truy xuất mẫu máy chủ cần thiết. Bạn có thể chuyển đổi mẫu này sang định dạng JSON có thể lưu trữ cục bộ, sau đó khởi tạo mẫu JSON này bằng hàm InitServerTemplate.

  2. Để đảm bảo ứng dụng của bạn chạy thành công ngay cả khi kết nối với máy chủ phụ trợ Remote Config bị gián đoạn, hãy thêm giá trị mặc định cho từng tham số trong ứng dụng.

    Node.js

    Thêm một đối tượng defaultConfig vào bên trong hàm mẫu initServerTemplate hoặc getServerTemplate:

    const template = rc.initServerTemplate({
      defaultConfig: {
        model_name: "gemini-pro",
        generation_config: '{"stopSequences": [], "temperature": 0.7, "maxOutputTokens": 512, "topP": 0.1, "topK": 20}',
        preamble_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!"
      },
    });
    
    // Load Remote Config
    await template.load();
    

    Python

    Thêm một từ điển default_config vào bên trong hàm mẫu init_server_template hoặc get_server_template:

    template = remote_config.init_server_template({
      'default_config': {
        'model_name': "gemini-pro",
        'generation_config': '{"stopSequences": [], "temperature": 0.7, "maxOutputTokens": 512, "topP": 0.1, "topK": 20}',
        'preamble_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!"
      },
    })
    
    # Load Remote Config
    asyncio.run(template.load())
    

    Một cách khác để khởi chạy mẫu là sử dụng hàm get_server_template để truy xuất mẫu máy chủ cần thiết. Bạn có thể chuyển đổi mẫu này sang định dạng JSON bằng hàm template.to_json. Bạn có thể lưu trữ mẫu JSON này trên máy và sau đó khởi chạy mẫu JSON này bằng hàm init_server_template.

    Java

    Thêm một đối tượng defaultConfig bằng cách dùng KeysAndValues bên trong hàm getServerTemplate:

    // Initialize default config using KeysAndValues
    KeysAndValues defaultConfig = new KeysAndValues.Builder()
                                      .put("rc_param_1", "default value 1")
                                      .put("rc_param_2", "default value 2")
                                      .build();
    ServerTemplate template = rc.getServerTemplate(defaultConfig);
    

    Ngoài ra, bạn có thể truyền một mẫu mặc định được lưu vào bộ nhớ đệm trong khi khởi tạo Remote Config. Mẫu này có thể được dùng ngay cả khi kết nối với máy chủ Remote Config bị gián đoạn:

    String templateDataJSON = "{}"; // add your default template as JSON
    ServerTemplate template = rc.serverTemplateBuilder()
                        .defaultConfig(defaultConfig)
                        .cachedTemplate(templateDataJSON)
                        .build();
    

    Bắt đầu

    Thêm một bản đồ defaultConfig vào bên trong hàm mẫu InitServerTemplate hoặc GetServerTemplate:

    // Initialize server-side Remote Config
    defaultConfig := make(map[string]any)
    defaultConfig["model_name"] = "gemini-2.0-flash"
    
    // Assume the type generationConfig has been defined
    defaultConfig["generation_config"] = &generationConfig{
        StopSequences:   []string{"I hope this helps"},
        Temperature:     0.7,
        MaxOutputTokens: 512,
        TopP:            0.9,
        TopK:            30,
    }
    
    defaultConfig["preamble_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!"
    
    templateDataJSON := ""
    template, err := remoteConfig.InitServerTemplate(defaultConfig, templateDataJSON)
    if err != nil {
        log.Fatalln("Error initializing server template:", err)
    }
    
    // Load Remote Config
    err = template.Load(ctx)
    if err != nil {
        log.Fatalln("Error fetching server template:", err)
    }
    
  3. Sau khi mẫu tải, hãy đánh giá mẫu để nhập các thông số và giá trị từ mẫu:

    Node.js

    Cách sử dụng template.evaluate():

    // Add template parameters to config
    const config = template.evaluate();
    

    Python

    Cách sử dụng template.evaluate():

    # Add template parameters to config
    config = template.evaluate()
    

    Java

    Cách sử dụng template.evaluate():

    // Add template parameters to config
    ServerConfig config = template.evaluate();
    

    Bắt đầu

    Sử dụng template.Evaluate() với một bối cảnh đánh giá trống khi không có điều kiện nào được áp dụng:

    // An empty evaluation context means no conditions are applied.
    evaluationContext := make(map[string]any)
    config, err := template.Evaluate(evaluationContext)
    if err != nil {
        log.Fatalln("Error evaluating template:", err)
    }
    
  4. Nếu bạn đặt điều kiện trong mẫu Remote Config, hãy xác định và cung cấp các giá trị ngữ cảnh mà bạn muốn:

    • Nếu sử dụng điều kiện phần trăm, hãy thêm mã nhận dạng ngẫu nhiên (randomizationId, randomization_id hoặc randomizationID) mà bạn muốn dùng để đánh giá các điều kiện trong hàm đánh giá mẫu.
    • Nếu sử dụng tín hiệu tuỳ chỉnh, hãy xác định các thuộc tính và giá trị của chúng. Bạn có thể sử dụng tín hiệu tuỳ chỉnh với Firebase Admin Node.js SDK phiên bản 12.5.0 trở lên, Python SDK phiên bản 6.7.0 trở lên, Java SDK phiên bản 9.7.0 trở lên và Go SDK phiên bản 4.17.0 trở lên.

    Ví dụ: bạn có thể đặt mã nhận dạng lượt cài đặt Firebase hoặc mã nhận dạng người dùng làm mã nhận dạng ngẫu nhiên để đảm bảo rằng mỗi người dùng liên hệ với máy chủ của bạn đều được thêm vào nhóm ngẫu nhiên thích hợp, version làm tín hiệu tuỳ chỉnh để nhắm đến các phiên bản ứng dụng cụ thể và platform làm tín hiệu tuỳ chỉnh để nhắm đến các nền tảng ứng dụng.

    Để biết thêm thông tin về các điều kiện, hãy xem Các loại quy tắc điều kiện.

    Node.js

    Truyền một đối tượng ngữ cảnh đánh giá chứa randomizationId và mọi tín hiệu tuỳ chỉnh đến template.evaluate():

    // Add template parameters to `config`. Evaluates the
    // template and returns the parameter value assigned to
    // the group assigned to the {randomizationId} and version.
    const config = template.evaluate({
      randomizationId: "2ac93c28-c459-4760-963d-a3974ec26c04",
      version: "1.0",
      platform: "Android"
    });
    

    Python

    Truyền một từ điển chứa randomization_id và mọi tín hiệu tuỳ chỉnh đến template.evaluate():

    # Add template parameters to `config`. Evaluates the
    # template and returns the parameter value assigned to
    # the group assigned to the {randomization_id} and version.
    config = template.evaluate({
      'randomization_id': "2ac93c28-c459-4760-963d-a3974ec26c04",
      'version': "1.0",
      'platform': "Android"
    })
    

    Java

    Tạo một ngữ cảnh KeysAndValues chứa randomizationId và mọi tín hiệu tuỳ chỉnh, rồi truyền ngữ cảnh đó đến template.evaluate():

    // Add custom signals and randomizationId
    KeysAndValues context = new KeysAndValues.Builder()
                                    .put("custom_signal_key", "99")
                                    .put("randomizationId", "2ac93c28")
                                    .build();
    
    // Evaluate the template with signals
    ServerConfig config = template.evaluate(context);
    

    Bắt đầu

    Truyền bản đồ ngữ cảnh đánh giá chứa randomizationID và mọi tín hiệu tuỳ chỉnh đến template.Evaluate():

    // Add template parameters to `config`. Evaluates the
    // template and returns the parameter value assigned to
    // the group assigned to the {randomizationID}, version, and platform.
    evaluationContext := make(map[string]any)
    evaluationContext["randomizationID"] = "2ac93c28-c459-4760-963d-a3974ec26c04"
    evaluationContext["version"] = "1.0"
    evaluationContext["platform"] = "Android"
    
    config, err := template.Evaluate(evaluationContext)
    if err != nil {
        log.Fatalln("Error evaluating template:", err)
    }
    
  5. Tiếp theo, hãy trích xuất các giá trị tham số bạn cần từ đối tượng cấu hình được đánh giá. Sử dụng các phương thức getter để truyền các giá trị từ Remote Config sang định dạng dự kiến.

    Ví dụ: nếu đang triển khai Agent Platform trên máy chủ và muốn thay đổi mô hình cũng như các tham số mô hình, bạn có thể định cấu hình các tham số cho model_name và generation_config. Sau đây là các phương thức getter được hỗ trợ và ví dụ về cách truy cập vào các giá trị Remote Config cho từng nền tảng:

    Node.js

    Các phương thức getter được hỗ trợ:

    • Boolean: getBoolean
    • Đồ vật: getValue
    • Số: getNumber
    • Chuỗi: getString

    // Replace defaults with values from Remote Config.
    const generationConfig =
      JSON.parse(
        config.getString('generation_config'));
    
    const is_ai_enabled = config.getBoolean('is_ai_enabled');
    
    const model = config.getString('model_name');
    
    // Generates a prompt comprised of the Remote Config
    // parameter and prepends it to the user prompt
    const prompt = `${config.getString('preamble_prompt')} ${req.query.prompt}`;
    

    Python

    Các phương thức getter được hỗ trợ:

    • Boolean: get_bool
    • Số nguyên: get_int
    • Độ chính xác đơn: get_float
    • Chuỗi: get_string
    • Nguồn giá trị: get_value_source

    # Replace defaults with values from Remote Config.
    generation_config = json.loads(config.get_string('generation_config'))
    is_ai_enabled = config.get_bool('is_ai_enabled')
    model = config.get_string('model_name')
    
    # Generates a prompt comprised of the Remote Config
    # parameter and prepends it to the user prompt.
    prompt = f"{config.get_string('preamble_prompt')}{req.args.get('prompt')}"
    

    Java

    Các phương thức getter được hỗ trợ:

    • Boolean: getBoolean
    • Chuỗi: getString
    • Double: getDouble
    • Dài: getLong
    • Nguồn giá trị: getValueSource

    // Get the model name
    String modelName = config.getString("model_name");
    // Get the origin of value assigned to param
    ValueSource modelNameSource = config.getValueSource("model_name");
    

    Phương thức getValueSource trả về một ValueSource cho biết nguồn giá trị của tham số là STATIC, REMOTE hay DEFAULT.

    Bắt đầu

    Các phương thức getter được hỗ trợ:

    • Boolean: GetBoolean
    • Số nguyên: GetInt
    • Độ chính xác đơn: GetFloat
    • Chuỗi: GetString
    • Nguồn giá trị: GetValueSource

    // Replace defaults with values from Remote Config.
    
    // Assume the type generationConfig has been defined
    var genConfig generationConfig
    err = json.Unmarshal([]byte(config.GetString("generation_config")), &genConfig)
    if err != nil {
        log.Fatalln("Error unmarshaling generation config:", err)
    }
    model := config.GetString("model_name")
    
    // Parameter created on the console
    isAIEnabled := config.GetBoolean("is_ai_enabled")
    
    // Generates a prompt comprised of the Remote Config
    // parameter and prepends it to the user prompt (assume it is extracted from the request body)
    userPrompt := "What is Remote Config?"
    prompt := fmt.Sprintf("%s %s", config.GetString("preamble_prompt"), userPrompt)
    
  6. Nếu máy chủ của bạn đang chạy trong thời gian dài, thay vì môi trường không máy chủ, hãy định kỳ tải lại mẫu (ví dụ: sử dụng setInterval trong Node.js hoặc java.util.Timer trong Java) để xác nhận rằng bạn đang tìm nạp mẫu mới nhất từ máy chủ Remote Config.

Bước 4: Đặt các giá trị tham số dành riêng cho máy chủ trong Remote Config

Tiếp theo, hãy tạo một mẫu Remote Config máy chủ và định cấu hình các tham số cũng như giá trị để sử dụng trong ứng dụng của bạn.

Sau đây là 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 trang DevOps & Engagement (DevOps và mức độ tương tác) > Remote Config (Cấu hình từ xa) > Parameters (Tham số).

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

  3. Xác định các tham số Remote Config có cùng tên và kiểu dữ liệu với các tham số mà bạn đã xác định trong ứng dụng của mình và cung cấp các giá trị. Các giá trị này sẽ ghi đè cấu hình mặc định (defaultConfig hoặc default_config) mà bạn đặt trong phần Định cấu hình ứng dụng máy chủ khi bạn tìm nạp và đánh giá mẫu, đồng thời chỉ định các giá trị này cho các biến của bạn.

  4. Bạn có thể tuỳ ý đặt các điều kiện để liên tục áp dụng các giá trị cho một mẫu ngẫu nhiên gồm các phiên bản hoặc tín hiệu tuỳ chỉnh mà bạn xác định. Để biết thêm thông tin về các điều kiện, hãy xem phần Các loại quy tắc điều kiện.

  5. Khi bạn thêm xong các thông số, hãy nhấp vào Xuất bản thay đổi.

  6. Xem lại các thay đổi rồi nhấp vào Xuất bản các thay đổi một lần nữa.

Bước 5: Triển khai bằng Cloud Functions for Firebase hoặc Cloud Run

Nếu ứng dụng máy chủ của bạn có dung lượng nhẹ và dựa trên sự kiện, bạn nên cân nhắc triển khai mã bằng cách sử dụng Cloud Functions for Firebase. Ví dụ: giả sử bạn có một ứng dụng có chứa đoạn hội thoại của nhân vật do một API AI tạo sinh cung cấp (ví dụ: Google AI hoặc Agent Platform). Trong trường hợp này, bạn có thể lưu trữ logic phân phát LLM trong một hàm mà ứng dụng của bạn gọi theo yêu cầu.

Nếu bạn đang tạo một ứng dụng web được kết xuất phía máy chủ, thì App Hosting có hỗ trợ các khung web phổ biến.

Nếu không, bạn có thể cân nhắc Cloud Run. Để triển khai ứng dụng máy chủ bằng Cloud Run, hãy làm theo hướng dẫn bắt đầu nhanh cho ngôn ngữ của bạn:

Để biết thêm thông tin về các trường hợp sử dụng phù hợp nhất cho Cloud Run và Cloud Functions for Firebase, hãy xem bài viết Cloud Functions for Firebase so với Cloud Run: khi nào nên dùng loại này thay vì loại kia.

Các bước tiếp theo