Utilizza Remote Config in ambienti server

Firebase Remote Config supporta la configurazione lato server utilizzando gli SDK Firebase Admin per Node.js (v12.1.0 e versioni successive), Python (v6.7.0 e versioni successive), Java (v9.7.0 e versioni successive) e Go (v4.17.0 e versioni successive).

Questa funzionalità consente di gestire in modo dinamico il comportamento e la configurazione delle applicazioni lato server utilizzando Remote Config. Sono incluse implementazioni serverless come Cloud Functions for Firebase e servizi in container su Cloud Run.

A differenza degli SDK client Firebase, che recuperano una configurazione specifica del client derivata dal modello Remote Config, l'SDK Remote Config lato server scarica o recupera un modello Remote Config completo da Firebase. Il server può quindi valutare il modello con ogni richiesta in entrata e utilizzare la propria logica per fornire una risposta personalizzata con una latenza molto bassa. Puoi utilizzare le condizioni per controllare e personalizzare le risposte in base a percentuali casuali e agli attributi dei clienti definiti negli indicatori personalizzati.

Con Remote Config lato server, puoi:

  • Definisci i parametri di configurazione per le applicazioni in esecuzione o a cui si accede tramite il server, consentendo casi d'uso come la configurazione remota di parametri e prompt del modello di AI e altre integrazioni, per garantire la sicurezza delle chiavi API.
  • Regola dinamicamente i parametri in risposta alle modifiche apportate all'ambiente o ad altre applicazioni, ad esempio l'aggiornamento dei parametri LLM e degli endpoint del modello.
  • Controlla i costi aggiornando da remoto le API chiamate dal server.
  • Genera configurazioni personalizzate al volo per i client che accedono al tuo server.
  • Registra i client che hanno ricevuto un valore parametro e utilizzalo in Cloud Functions for Firebase nell'ambito di un sistema di verifica dei diritti.

Puoi eseguire il deployment di Remote Config lato server su Cloud Run, Cloud Functions for Firebase o in ambienti server self-hosted.

Prima di iniziare

Segui le istruzioni riportate in Aggiungere l'SDK Firebase Admin al server per creare un progetto Firebase, configurare un service account e aggiungere l'SDK Firebase Admin al server. Assicurati di utilizzare una versione supportata dell'SDK Admin per la tua piattaforma:

  • Node.js: SDK Firebase Admin Node.js v12.1.0 o successive
  • Python: SDK Firebase Admin Python v6.7.0 o versioni successive
  • Java: Firebase Admin Java SDK v9.7.0 o versioni successive
  • Go: SDK Firebase Admin Go v4.17.0 o versioni successive

Passaggio 1: inizializza l'SDK Firebase Admin e autorizza le richieste API

Quando inizializzi l'SDK Admin senza parametri, l'SDK utilizza le credenziali predefinite dell'applicazione Google e legge le opzioni dalla variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS. Inizializza l'SDK e configura Remote Config per la tua piattaforma:

Node.js

Importa initializeApp e getRemoteConfig, quindi inizializza l'istanza dell'applicazione Firebase:

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

// Initialize Firebase
const firebaseApp = initializeApp();

Python

Importa firebase_admin (insieme a asyncio e json per il caricamento asincrono dei modelli e l'analisi JSON), quindi inizializza l'applicazione:

import firebase_admin
import asyncio
import json

firebase_admin.initialize_app()

Java

Inizializza l'SDK Firebase Admin utilizzando FirebaseOptions e le credenziali del service account:

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

Vai

Inizializza l'applicazione Firebase e crea un'istanza client 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)
}

Passaggio 2: identifica i valori predefiniti dei parametri per l'applicazione server

Identifica le variabili nella tua app che vuoi aggiornare dinamicamente con Remote Config. Poi, considera quali variabili devono essere impostate per impostazione predefinita nella tua applicazione e quali devono essere i loro valori predefiniti. In questo modo, la tua applicazione viene eseguita correttamente anche se la connessione al server di backend Remote Config viene interrotta.

Ad esempio, se stai scrivendo un'applicazione server che gestisce una funzione AI generativa, puoi impostare un nome del modello predefinito, un preambolo del prompt e una configurazione di AI generativa, come la seguente:

Nome parametro Descrizione Tipo Valore predefinito
model_name Nome dell'API del modello Stringa gemini-2.0-flash
preamble_prompt Prompt da anteporre alla query dell'utente Stringa 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 Parametri da inviare al modello JSON {"stopSequences": ["I hope this helps"], "temperature": 0.7, "maxOutputTokens": 512, "topP": 0.1, "topK": 20}

Passaggio 3: configura l'applicazione server

Dopo aver determinato i parametri che vuoi utilizzare con Remote Config, configura l'applicazione per impostare i valori predefiniti, recuperare il modello Remote Config specifico del server e valutarne i valori.

  1. Accedi e carica il modello di server Remote Config.

    Node.js

    Inizializza il modello del server utilizzando initServerTemplate() e chiama load() per recuperare il modello dal backend:

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

// Load Remote Config
await template.load();

    Se utilizzi Node.js in Cloud Functions for Firebase, puoi utilizzare la funzione asincrona getServerTemplate() per inizializzare e caricare il modello in un unico passaggio:

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

    Python

    Inizializza il modello del server utilizzando init_server_template() e chiama load() per recuperare il modello dal backend:

    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())

    In alternativa, se utilizzi Python con Cloud Functions for Firebase, puoi utilizzare la funzione asincrona get_server_template() per inizializzare e caricare il modello in un unico passaggio:

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

    Java

    Inizializza il client Remote Config lato server utilizzando FirebaseRemoteConfig.getInstance():

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

    In alternativa, se utilizzi Java con Cloud Functions for Firebase, puoi utilizzare getServerTemplate() per inizializzare e caricare il modello in un unico passaggio:

    ServerTemplate template = rc.getServerTemplate();

    Vai

    Inizializza il modello del server utilizzando InitServerTemplate() e chiama Load() per recuperare il modello dal backend:

    // 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)
}

    Un altro modo per inizializzare il modello è utilizzare la funzione GetServerTemplate per recuperare il modello di server richiesto. Puoi convertire questo modello in un formato JSON che può essere archiviato localmente e inizializzarlo successivamente utilizzando la funzione InitServerTemplate.

  2. Per assicurarti che l'applicazione venga eseguita correttamente anche se la connessione al server backend Remote Config viene interrotta, aggiungi valori predefiniti per ogni parametro nell'app.

    Node.js

    Aggiungi un oggetto defaultConfig all'interno della funzione di modello initServerTemplate o 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

    Aggiungi un dizionario default_config all'interno della funzione di modello init_server_template o 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())

    Un altro modo per inizializzare un modello è utilizzare la funzione get_server_template per recuperare il modello di server richiesto. Puoi convertire questo modello in formato JSON utilizzando la funzione template.to_json. Questo modello JSON può essere archiviato localmente e puoi inizializzarlo successivamente utilizzando la funzione init_server_template.

    Java

    Aggiungi un oggetto defaultConfig utilizzando KeysAndValues all'interno della funzione 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);

    In alternativa, puoi passare un modello memorizzato nella cache predefinito durante l'inizializzazione di Remote Config, che può essere utilizzato anche quando la connessione al server Remote Config viene interrotta:

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

    Vai

    Aggiungi una mappa defaultConfig all'interno della funzione di modello InitServerTemplate o 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. Dopo il caricamento del modello, valutalo per importare parametri e valori dal modello:

    Node.js

    Utilizza template.evaluate():

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

    Python

    Utilizza template.evaluate():

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

    Java

    Utilizza template.evaluate():

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

    Vai

    Utilizza template.Evaluate() con un contesto di valutazione vuoto quando non vengono applicate condizioni:

    // 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. (Facoltativo) Se imposti condizioni nel modello Remote Config, definisci e fornisci i valori di contesto che preferisci:

    • Se utilizzi condizioni percentuali, aggiungi l'ID randomizzazione (randomizationId, randomization_id o randomizationID) che vuoi utilizzare per valutare le condizioni all'interno della funzione di valutazione del modello.
    • Se utilizzi indicatori personalizzati, definisci gli attributi e i relativi valori. Gli indicatori personalizzati sono disponibili con l'SDK Firebase Admin Node.js 12.5.0+, l'SDK Python 6.7.0+, l'SDK Java 9.7.0+ e l'SDK Go 4.17.0+.

    Ad esempio, puoi impostare un ID installazione Firebase o un ID utente come ID randomizzazione per assicurarti che ogni utente che contatta il tuo server venga aggiunto al gruppo randomizzato corretto, version come segnale personalizzato per scegliere come target versioni specifiche del client e platform come segnale personalizzato per scegliere come target piattaforme client.

    Per saperne di più sulle condizioni, vedi Tipi di regole di condizione.

    Node.js

    Passa un oggetto contesto di valutazione contenente randomizationId e qualsiasi indicatore personalizzato a 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

    Trasmetti un dizionario contenente randomization_id e tutti gli indicatori personalizzati a 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

    Crea un contesto KeysAndValues contenente randomizationId e tutti gli indicatori personalizzati e passalo a 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);

    Vai

    Trasmetti una mappa del contesto di valutazione contenente randomizationID e qualsiasi segnale personalizzato a 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. Successivamente, estrai i valori dei parametri che ti servono dall'oggetto di configurazione valutato. Utilizza i metodi getter per convertire i valori da Remote Config nel formato previsto.

    Ad esempio, se stai implementando Agent Platform sul tuo server e vuoi modificare il modello e i parametri del modello, puoi configurare i parametri per model_name e generation_config. Di seguito sono riportati i metodi getter supportati e un esempio di come accedere ai valori di Remote Config per ogni piattaforma:

    Node.js

    Metodi getter supportati:

    • Booleano: getBoolean
    • Oggetto: getValue
    • Numero: getNumber
    • Stringa: 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

    Metodi getter supportati:

    • Booleano: get_bool
    • Numero intero: get_int
    • Fluttuazione: get_float
    • Stringa: get_string
    • Origine del valore: 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

    Metodi getter supportati:

    • Booleano: getBoolean
    • Stringa: getString
    • Doppia: getDouble
    • Lungo: getLong
    • Origine del valore: 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");

    Il metodo getValueSource restituisce un ValueSource che indica se l'origine del valore del parametro è STATIC, REMOTE o DEFAULT.

    Vai

    Metodi getter supportati:

    • Booleano: GetBoolean
    • Numero intero: GetInt
    • Fluttuazione: GetFloat
    • Stringa: GetString
    • Origine del valore: 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. Se il tuo server è in esecuzione da molto tempo, anziché in un ambiente serverless, ricarica periodicamente il modello (ad esempio utilizzando setInterval in Node.js o java.util.Timer in Java) per verificare di recuperare il modello più aggiornato dal server Remote Config.

Passaggio 4: imposta i valori dei parametri specifici del server in Remote Config

Successivamente, crea un modello Remote Config del server e configura i parametri e i valori da utilizzare nell'app.

Ecco come creare un modello Remote Config specifico per il server:

  1. Nella console Firebase, vai alla pagina DevOps & Engagement > Remote Config > Parametri.

  2. Nel selettore Client/Server nella parte superiore della pagina, seleziona Server.

  3. Definisci i parametri Remote Config con gli stessi nomi e tipi di dati dei parametri definiti nella tua app e fornisci i valori. Questi valori ignorano la configurazione predefinita (defaultConfig o default_config) impostata in Configura l'applicazione server quando recuperi e valuti il modello e assegni questi valori alle tue variabili.

  4. (Facoltativo) Imposta le condizioni per applicare in modo permanente i valori a un campione casuale di istanze o ai segnali personalizzati che definisci. Per saperne di più sulle condizioni, consulta Tipi di regole di condizione.

  5. Al termine dell'aggiunta dei parametri, fai clic su Pubblica modifiche.

  6. Rivedi le modifiche e fai di nuovo clic su Pubblica modifiche.

Passaggio 5: esegui il deployment con Cloud Functions for Firebase o Cloud Run

Se la tua applicazione server è leggera e basata su eventi, ti consigliamo di eseguire il deployment del codice utilizzando Cloud Functions for Firebase. Ad esempio, supponiamo che tu abbia un'app che include dialoghi tra personaggi basati su un'API AI generativa (ad esempio Google AI o Agent Platform). In questo caso, potresti ospitare la logica di servizio del tuo LLM in una funzione che la tua app chiama on demand.

Se stai creando un'app web con rendering lato server, App Hosting supporta i framework web più diffusi.

In caso contrario, potresti prendere in considerazione Cloud Run. Per eseguire il deployment dell'app server con Cloud Run, segui la guida rapida per la tua lingua:

Per saperne di più sui casi d'uso migliori per Cloud Run e Cloud Functions for Firebase, consulta Cloud Functions for Firebase e Cloud Run: quando utilizzare uno o l'altro.

Passaggi successivi