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

Z tego przewodnika dowiesz się, jak zacząć korzystać z Cloud Functions drugiej generacji z Remote Config po stronie serwera, 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 zostanie dodany na początku przychodzących zapytań użytkowników). Możesz aktualizować te dane wejściowe na żądanie w konsoli Firebase. Użyjesz też Firebase Local Emulator Suite do przetestowania i debugowania funkcji, a po sprawdzeniu, czy działa, wdrożysz ją i przetestujesz w Google Cloud.

Wymagania wstępne

W tym przewodniku zakładamy, że znasz język JavaScript i używasz go do tworzenia aplikacji.

Konfigurowanie projektu w Firebase

Jeśli nie masz jeszcze projektu w Firebase:

  1. Zaloguj się w konsoli Firebase.

  2. Kliknij Utwórz projekt, a następnie wybierz jedną z tych opcji:

    • Opcja 1. Utwórz nowy projekt w Firebase (i automatycznie powiązany z nim projekt Google Cloud), 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ę prośba, nie musisz konfigurować Google Analytics, aby korzystać z tego rozwiązania.

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

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 – interfejsu wiersza poleceń Firebase.

  1. Zainstaluj Node.js i npm.

    Do zainstalowania Node.js i npm zalecamy użycie menedżera wersji Node.

  2. Zainstaluj interfejs wiersza poleceń Firebase, korzystając z preferowanej metody. Aby na przykład zainstalować interfejs wiersza poleceń za pomocą npm, uruchom to polecenie:

    npm install -g firebase-tools@latest

    To polecenie instaluje ogólnodostępne polecenie firebase. Jeśli to polecenie się nie powiedzie, może być konieczna 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ć funkcję Cloud Functions drugiej generacji za pomocą Remote Config i Agent Platform, wykonaj te czynności:

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

Krok 1. Włącz Agent Platform zalecane interfejsy API w konsoli Google Cloud

  1. Otwórz konsolę Google Cloud i po wyświetleniu prośby wybierz projekt.
  2. W polu Szukaj u góry konsoli wpisz Agent Platform i poczekaj, aż Agent Platform pojawi się jako wynik.
  3. Wybierz Agent Platform. Pojawi się panel Agent Platform.

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

    Włączenie interfejsu API może chwilę potrwać. Nie zamykaj strony i nie przechodź na inną, dopóki proces się nie zakończy.

  5. Jeśli płatności nie są włączone, pojawi się prośba o dodanie lub połączenie konta Cloud Billing. 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. Wybierz 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 wszystkich pozostałych opcji wybierz ustawienia domyślne.

    W bieżącym katalogu zostanie utworzony katalog functions. Wewnątrz 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, uruchamiając te polecenia, i 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. Upewnij się też, że wersja silnika węzła jest zgodna z zainstalowaną wersją Node.js i wersją, którą ostatecznie uruchomisz w Google Cloud. Jeśli na przykład w pliku package.json sekcja engines jest skonfigurowana jako Node w wersji 18, a używasz Node.js 20, zaktualizuj plik, aby używać wersji 20:

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

Krok 3. Skonfiguruj uprawnienia do 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ę Administracja i znajdź konto usługi Admin SDK (o nazwie firebase-adminsdk).
  2. Wybierz konto i kliknij Edytuj podmiot zabezpieczeń. Pojawi się strona uprawnień do edycji.
  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 Użytkownik Agent Platform.
  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 i zapisz go w bezpiecznym miejscu 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 odpowiedź z powrotem do użytkownika.

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

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

    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. 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 artykule o kliencie Vertex AI w Node.js.

    Opcjonalnie możesz też skonfigurować parametr, który będzie kontrolować, czy masz dostęp do Agent Platform Gemini API (formerly Vertex AI) (w tym przykładzie jest to parametr o nazwie vertex_enabled). Taka konfiguracja może być przydatna podczas testowania funkcji. We fragmentach kodu poniżej ta wartość 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 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 po stronie serwera 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. 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 dla konkretnego serwera

Następnie utwórz szablon Remote Config po stronie serwera i skonfiguruj parametry oraz wartości, których chcesz używać w funkcji. Aby utworzyć szablon Remote Config dla konkretnego serwera:

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

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

    • Jeśli po raz pierwszy korzystasz z Remote Config lub szablonów serwera, kliknij Utwórz konfigurację. Pojawi się panel Utwórz pierwszy parametr po stronie serwera.
    • Jeśli nie korzystasz z szablonów serwera Remote Config 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 artykule na temat wersji i cykli życia modeli lub dostępnych nazw modeli.     		Ciąg znaków gemini-2.0-flash
    prompt Prompt, który ma zostać dodany 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 być uruchomiona usługa i model Agent Platform 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, sprawdź je i upewnij się, że ich typy danych są prawidłowe, a potem 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 sekcji Krok 3. Skonfiguruj uprawnienia dla konta 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. Powinien pojawić się komunikat informujący o załadowaniu funkcji.

  3. Uzyskaj dostęp do funkcji, uruchamiając to polecenie, gdzie PROJECT_ID to identyfikator projektu, a LOCATION to region, w którym wdrożono funkcję (np. us-central1):

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

  4. Poczekaj na odpowiedź, a następnie wróć na stronę logów emulatora Firebase lub do konsoli i sprawdź, czy nie ma błędów lub 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 przez Agent Platform Gemini API (formerly Vertex AI) i może 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 szablonie serwera Remote Config w konsoli Firebase, a następnie ponownie uzyskaj dostęp do funkcji, aby zobaczyć zmiany.

Krok 7. Wdróż funkcję w Google Cloud

Po przetestowaniu i zweryfikowaniu funkcji możesz wdrożyć ją w Google Cloud i przetestować działanie 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, nieuwierzytelnione wywołania są domyślnie dozwolone, jeśli nie zabraniają tego zasady organizacji. Podczas testowania i przed zabezpieczeniem za pomocą App Check zalecamy zablokowanie nieuwierzytelnionego dostępu.

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ło danych logowania konta usługi Admin SDK.

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

Poniższe kroki opisują, jak skonfigurować konto użytkownika i funkcję do uruchamiania z uprawnieniami konta usługi Admin SDK.

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

  3. Wybierz Twórca tokenów kont usługi, a następnie kliknij 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ę konsoli Google Cloud Cloud Functions i na liście Funkcje kliknij funkcję generateWithVertex.

  5. Kliknij Aktywator > 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 następnie Wdróż.

Konfigurowanie gcloud CLI

Aby bezpiecznie uruchomić i przetestować funkcję z poziomu wiersza poleceń, musisz uwierzytelnić się w usłudze Cloud Functions i uzyskać prawidłowy token uwierzytelniania.

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

  1. Jeśli nie masz jeszcze zainstalowanego interfejsu wiersza poleceń gcloud na komputerze, zainstaluj go zgodnie z opisem 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, używając danych przekazywanych 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