Używanie Zdalnej konfiguracji po stronie serwera z Cloud Functions i platformą Agent

Z tego przewodnika dowiesz się, jak zacząć korzystać z 2 generacji Cloud Functionstagowania po stronie serwera Remote Config, aby wykonywać wywołania po stronie serwera do Agent Platform Gemini API (formerly Vertex AI).

W tym samouczku dodasz Remote Config do funkcji podobnej do czatbota, która używa modelu Gemini do odpowiadania na pytania użytkowników. Remote Config będzie zarządzać danymi wejściowymi Gemini API (w tym promptem, który dodasz na początku przychodzących zapytań użytkowników), a Ty możesz aktualizować te dane na żądanie w Firebase konsoli. Za pomocą Firebase Local Emulator Suite przetestujesz i zdebugujesz funkcję, a następnie po sprawdzeniu, czy działa ona prawidłowo, wdrożysz ją i przetestujesz w usłudze Google Cloud.

Wymagania wstępne

W tym przewodniku zakładamy, że znasz już język JavaScript i umiesz tworzyć aplikacje.

Konfigurowanie projektu w Firebase

Jeśli nie masz jeszcze projektu w Firebase:

  1. Zaloguj się w Firebasekonsoli.

  2. Kliknij Utwórz projekt, a potem skorzystaj z jednej z tych opcji:

    • Opcja 1: utwórz nowy projekt w Firebase (i powiązany z nim projektGoogle Cloud automatycznie), wpisując nową nazwę projektu w pierwszym kroku procesu „Utwórz projekt”.
    • Opcja 2: „Dodaj Firebase” do istniejącego projektu Google Cloud, wybierając nazwę projektu Google Cloud z menu w pierwszym kroku procesu „Utwórz projekt”.

  3. Gdy pojawi się odpowiedni komunikat, nie musisz konfigurować Google Analytics, aby korzystać z tego rozwiązania.

  4. Aby utworzyć projekt, postępuj zgodnie z instrukcjami wyświetlanymi na ekranie.

Jeśli masz już projekt w Firebase:

Przejdź do sekcji Konfigurowanie środowiska programistycznego.

Konfigurowanie środowiska programistycznego

Do pisania funkcji potrzebujesz środowiska Node.js, a do wdrażania funkcji w środowisku wykonawczym Cloud Functions potrzebujesz interfejsu wiersza poleceń Firebase.

  1. Zainstaluj Node.js i npm.

    Do instalacji Node.js i npm zalecamy użycie Menedżera wersji Node.

  2. Zainstaluj Firebase CLI wybraną metodą. Aby na przykład zainstalować interfejs wiersza poleceń za pomocą npm, uruchom to polecenie:

    npm install -g firebase-tools@latest

    To polecenie instaluje polecenie firebase dostępne globalnie. Jeśli to polecenie się nie powiedzie, może być konieczne zmiana uprawnień npm.

    Aby zaktualizować firebase-tools do najnowszej wersji, uruchom ponownie to samo polecenie.

  3. Zainstaluj firebase-functions i firebase-admin, a następnie użyj --save, aby zapisać je na urządzeniu package.json:

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

Możesz teraz przejść do wdrożenia tego rozwiązania.

Implementacja

Aby utworzyć, przetestować i wdrożyć urządzenie 2 generacji Cloud Functions z Remote Config i Agent Platform:

  1. Włącz Agent Platform zalecane interfejsy API w Google Cloudkonsoli.
  2. Zainicjuj projekt i zainstaluj zależności Node.
  3. Skonfiguruj uprawnienia IAM dla konta usługi Admin SDK i zapisz klucz.
  4. Utwórz funkcję.
  5. Utwórz szablon Remote Configspecyficzny dla serwera.
  6. Wdróż funkcję i przetestuj ją w Firebase Local Emulator Suite.
  7. Wdróż funkcję w Google Cloud.

Krok 1. Włącz Agent Platform zalecanych interfejsów API w konsoli Google Cloud

  1. Otwórz Google Cloudkonsolę i gdy pojawi się odpowiedni komunikat, wybierz projekt.
  2. W polu Wyszukaj u góry konsoli wpisz Agent Platform i poczekaj, aż w wynikach pojawi się Agent Platform.
  3. Wybierz Agent Platform. Wyświetli się panel Agent Platform.

  4. Kliknij Włącz wszystkie zalecane interfejsy API.

    Włączenie interfejsu API może potrwać kilka minut. Nie zamykaj strony i nie przechodź do innych stron, dopóki włączanie nie zostanie zakończone.

  5. Jeśli płatności nie są włączone, pojawi się prośba o dodanie lub połączenie Cloud Billingkonta. Po włączeniu konta rozliczeniowego wróć do panelu Agent Platform i sprawdź, czy wszystkie zalecane interfejsy API są włączone.

Krok 2. Zainicjuj projekt i zainstaluj zależności Node

  1. Otwórz terminal na komputerze i przejdź do katalogu, w którym chcesz utworzyć funkcję.

  2. Zaloguj się w Firebase:

    firebase login

  3. Aby zainicjować Cloud Functions for Firebase, uruchom to polecenie:

    firebase init functions

  4. Kliknij Użyj istniejącego projektu i podaj identyfikator projektu.

  5. Gdy pojawi się prośba o wybranie języka, wybierz JavaScript i naciśnij Enter.

  6. W przypadku pozostałych opcji wybierz ustawienia domyślne.

    W bieżącym katalogu zostanie utworzony katalog functions. W nim znajdziesz plik index.js, którego użyjesz do utworzenia funkcji, katalog node_modules zawierający zależności funkcji oraz plik package.json zawierający zależności pakietu.

  7. Dodaj pakiety Admin SDK i Agent Platform, wykonując te polecenia. Użyj --save, aby zapisać je w pliku package.json:

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

Plik functions/package.json powinien teraz wyglądać tak, z określonymi najnowszymi wersjami:

  {
    "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
  }

Jeśli używasz ESLint, zobaczysz sekcję, która go zawiera. Dodatkowo upewnij się, że wersja silnika węzła jest zgodna z zainstalowaną wersją Node.js i wersją, która będzie ostatecznie uruchamiana na Google Cloud. Jeśli na przykład sekcja engines w pliku package.json jest skonfigurowana jako wersja 18 środowiska Node, a Ty używasz Node.js 20, zaktualizuj plik, aby używać wersji 20:

  "engines": {
    "node": "20"
  },

Krok 3. Skonfiguruj uprawnienia IAM dla konta usługi Admin SDK i zapisz klucz

W tym rozwiązaniu do uruchomienia funkcji użyjesz konta usługi Firebase Admin SDK.

  1. W konsoli Google Cloud otwórz stronę Uprawnienia i administracja i znajdź konto usługi Admin SDK (o nazwie firebase-adminsdk).
  2. Wybierz konto i kliknij Edytuj podmiot. Wyświetli się strona Edytowanie dostępu.
  3. Kliknij Dodaj kolejną rolę i wybierz Remote Config Wyświetlający.
  4. Kliknij Dodaj kolejną rolę i wybierz Deweloper platformy AI.
  5. Kliknij Dodaj kolejną rolę i wybierz Agent Platform użytkownik.
  6. Kliknij Dodaj kolejną rolę i wybierz Wywołujący Cloud Run.
  7. Kliknij Zapisz.

Następnie wyeksportuj dane logowania do konta usługi Admin SDK i zapisz je w zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS.

  1. W konsoli Google Cloud otwórz stronę Dane logowania.
  2. Kliknij konto usługi Admin SDK, aby otworzyć stronę Szczegóły.
  3. Kliknij Klucze.
  4. Kliknij Dodaj klucz > Utwórz nowy klucz.
  5. Upewnij się, że jako Typ klucza wybrano JSON, a następnie kliknij Utwórz.
  6. Pobierz klucz w bezpieczne miejsce na komputerze.

  7. W terminalu wyeksportuj klucz jako zmienną środowiskową:

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

Krok 4. Utwórz funkcję

W tym kroku utworzysz funkcję, która obsługuje dane wejściowe użytkownika i generuje odpowiedzi oparte na AI. Połączysz kilka fragmentów kodu, aby utworzyć kompleksową funkcję, która inicjuje Admin SDK i Agent Platform Gemini API (formerly Vertex AI), konfiguruje parametry domyślne za pomocą Remote Config, pobiera najnowsze parametry Remote Config, przetwarza dane wejściowe użytkownika i przesyła strumieniowo odpowiedź do użytkownika.

  1. W bazie kodu otwórz plik functions/index.js w edytorze tekstu lub IDE.

  2. Usuń dotychczasową zawartość, a następnie dodaj pakiety SDK Admin SDK,Remote Config i Agent Platform oraz zainicjuj aplikację, wklejając do pliku ten kod:

    const { onRequest } = require("firebase-functions/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();

  3. Skonfiguruj wartości domyślne, których funkcja będzie używać, jeśli nie będzie mogła połączyć się z serwerem Remote Config. To rozwiązanie konfiguruje parametry textModel, generationConfig, safetySettings, textPrompt i location jako parametry Remote Config, które odpowiadają parametrom Remote Config, które skonfigurujesz w dalszej części tego przewodnika. Więcej informacji o tych parametrach znajdziesz w dokumentacji klienta Vertex AI w Node.js.

    Opcjonalnie możesz też skonfigurować parametr, który będzie określać, czy masz dostęp do Agent Platform Gemini API (formerly Vertex AI) (w tym przykładzie parametr o nazwie vertex_enabled). Ta konfiguracja może być przydatna podczas testowania funkcji. W tych fragmentach kodu wartość ta jest ustawiona na false, co spowoduje pominięcie użycia Agent Platform podczas testowania podstawowego wdrożenia funkcji. Ustawienie wartości true spowoduje wywołanie funkcji 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. Utwórz funkcję i skonfiguruj tagowanie po stronie serweraRemote 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. Skonfiguruj Agent Platform i dodaj logikę czatu i odpowiedzi:

      // 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. Zapisz i zamknij plik.

Krok 5. Utwórz szablon Remote Config specyficzny dla serwera

Następnie utwórz szablon po stronie serwera Remote Config i skonfiguruj parametry oraz wartości, które będą używane w funkcji. Aby utworzyć szablon specyficzny dla serwera:Remote Config

  1. W konsoli Firebase kliknij DevOps i zaangażowanie > Zdalna konfiguracja.

  2. W selektorze Klient/serwer u góry strony wybierz Serwer.

    • Jeśli korzystasz z Remote Config lub szablonów serwera po raz pierwszy, kliknij Utwórz konfigurację. Pojawi się panel Utwórz pierwszy parametr po stronie serwera.
    • Jeśli nie korzystasz z Remote Config szablonów serwera po raz pierwszy, kliknij Dodaj parametr.

  3. Zdefiniuj te parametry Remote Config:

    Nazwa parametru Opis Typ Wartość domyślna
    model_name Nazwa modelu
    Aktualne listy nazw modeli, których możesz używać w kodzie, znajdziesz w artykułach Wersje modeli i cykle życia oraz Dostępne nazwy modeli.     		Ciąg znaków gemini-2.0-flash
    prompt Prompt do dodania na początku zapytania użytkownika. Ciąg znaków 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 Parametry do wysłania do modelu JSON [{"stopSequences": ["I hope this helps"],"temperature": 0.7,"maxOutputTokens": 512, "topP": 0.1,"topK": 20}]
    safety_settings Ustawienia bezpieczeństwa dla Agent Platform JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
    location Lokalizacja, w której ma działać usługa Agent Platform i model Ciąg znaków global
    is_vertex_enabled Opcjonalny parametr, który określa, czy zapytania są wysyłane do Agent Platform. Wartość logiczna true

  4. Gdy skończysz dodawać parametry, dokładnie je sprawdź i upewnij się, że ich typy danych są prawidłowe. Następnie kliknij Opublikuj zmiany.

Krok 6. Wdróż funkcję i przetestuj ją w Firebase Local Emulator Suite

Teraz możesz wdrożyć i przetestować funkcję lokalnie za pomocą Firebase Local Emulator Suite.

  1. Upewnij się, że zmienna środowiskowa GOOGLE_APPLICATION_CREDENTIALS została ustawiona zgodnie z opisem w kroku 3. Skonfiguruj uprawnienia na koncie usługi Admin SDK i zapisz klucz. Następnie w katalogu nadrzędnym katalogu functions wdróż funkcję w emulatorze Firebase:

    firebase emulators:start --project PROJECT_ID --only functions

  2. Otwórz stronę logów emulatora. Powinno to wskazywać, że funkcja została wczytana.

  3. Aby uzyskać dostęp do funkcji, uruchom to polecenie, gdzie PROJECT_ID to identyfikator projektu, a LOCATION to region, w którym została wdrożona funkcja (np. us-central1):

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex

  4. Poczekaj na odpowiedź, a potem wróć na stronę logów emulatora Firebase lub do konsoli i sprawdź, czy nie ma błędów ani ostrzeżeń.

  5. Spróbuj wysłać dane wejściowe użytkownika. Pamiętaj, że ponieważ w szablonie serwera Remote Config skonfigurowano is_vertex_enabled, powinno to umożliwić dostęp do modelu Gemini za pomocą Agent Platform Gemini API (formerly Vertex AI). Może to wiązać się z opłatami:

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats

  6. Wprowadź zmiany w Remote Config szablonie serwera w Firebase konsoli, a następnie ponownie otwórz funkcję, aby zobaczyć zmiany.

Krok 7. Wdróż funkcję w Google Cloud

Po przetestowaniu i zweryfikowaniu funkcji możesz ją wdrożyć w Google Cloud i przetestować na żywo.

Wdrażanie funkcji

Wdróż funkcję za pomocą interfejsu wiersza poleceń Firebase:

firebase deploy --only functions

Blokowanie nieuwierzytelnionego dostępu do funkcji

Gdy funkcje są wdrażane za pomocą Firebase, domyślnie dozwolone są wywołania bez uwierzytelniania, o ile nie ograniczają tego zasady organizacji. Podczas testowania i przed zabezpieczeniem za pomocą App Check zalecamy zablokowanie dostępu bez uwierzytelniania.

Aby zablokować nieuwierzytelniony dostęp do funkcji:

  1. W konsoli Google Cloud otwórz Cloud Run.

  2. Kliknij generateWithVertex, a następnie kartę Bezpieczeństwo.

  3. Włącz opcję Wymagaj uwierzytelniania, a następnie kliknij Zapisz.

Skonfiguruj konto użytkownika, aby używać Admin SDK danych logowania konta usługi.

Konto usługi Admin SDK ma wszystkie role i uprawnienia niezbędne do uruchomienia funkcji oraz interakcji z Remote Config i Agent Platform Gemini API (formerly Vertex AI), dlatego warto użyć go do uruchomienia funkcji. Aby to zrobić, musisz mieć możliwość tworzenia tokenów na koncie z poziomu konta użytkownika.

Poniższe kroki opisują, jak skonfigurować konto użytkownika i funkcję, która ma być uruchamiana z uprawnieniami konta usługi Admin SDK.

  1. W konsoli Google Cloud włącz interfejs IAM Service Account Credentials API.
  2. Przypisz kontu użytkownika rolę Twórca tokenów konta usługi: w konsoli Google Cloud otwórz Administracja > Uprawnienia, wybierz konto użytkownika, a następnie kliknij Edytuj podmiot > Dodaj kolejną rolę.

  3. Wybierz Service Account Token Creator (Kreator tokenów konta usługi), a potem kliknij Save (Zapisz).

    Więcej informacji o przejmowaniu tożsamości konta usługi znajdziesz w artykule Przejmowanie tożsamości konta usługi w dokumentacji Google Cloud.

  4. Otwórz stronę Google Cloud konsoli Cloud Functions i na liście Funkcje kliknij funkcję generateWithVertex.

  5. Kliknij Reguła > Edytuj i rozwiń Ustawienia środowiska wykonawczego, kompilacji, połączeń i zabezpieczeń.

  6. Na karcie Środowisko wykonawcze zmień Konto usługi środowiska wykonawczego na Konto pakietu Admin SDK.

  7. Kliknij Dalej, a potem Wdróż.

Konfigurowanie gcloud CLI

Aby bezpiecznie uruchamiać i testować funkcję z wiersza poleceń, musisz uwierzytelnić się w usłudze Cloud Functions i uzyskać prawidłowy token uwierzytelniający.

Aby włączyć generowanie tokenów, zainstaluj i skonfiguruj gcloud CLI:

  1. Jeśli interfejs wiersza poleceń gcloud nie jest jeszcze zainstalowany na komputerze, zainstaluj go zgodnie z instrukcjami w artykule Instalowanie interfejsu wiersza poleceń gcloud.

  2. Uzyskaj dane logowania do konta Google Cloud:

    gcloud auth login

  3. Ustaw identyfikator projektu w gcloud:

    gcloud config set project PROJECT_ID

Testowanie funkcji

Możesz teraz przetestować funkcję w Google Cloud. Aby przetestować funkcję, uruchom to polecenie:

curl -X POST https://LOCATION-PROJECT_ID.cloudfunctions.net/generateWithVertex \
  -H "Authorization: bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json"

Spróbuj ponownie z danymi przekazywanymi przez użytkowników:

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"

Możesz teraz wprowadzać zmiany w szablonie serwera Remote Config, publikować je i testować różne opcje.

Dalsze kroki