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 Functions z 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 te dane wejściowe możesz aktualizować na żądanie w konsoli Firebase. Użyjesz też Firebase Local Emulator Suite do testowania i debugowania funkcji, a następnie, po sprawdzeniu, czy działa, wdrożysz ją i przetestujesz w Google Cloud.

Wymagania wstępne

W tym przewodniku założyliśmy, że znasz język JavaScript i wiesz, jak tworzyć aplikacje.

Konfigurowanie projektu w Firebase

Jeśli nie masz jeszcze projektu w Firebase:

  1. Zaloguj się w Firebase konsoli.

  2. Kliknij Utwórz projekt, a następnie wykonaj jedną z tych czynności:

    • Opcja 1: utwórz nowy projekt w Firebase (i powiązany z nim Google Cloud projekt 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ę 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 Cloud Functions wykonawczym – interfejsu wiersza poleceń Firebase.

  1. Zainstaluj Node.js i npm.

    Do instalowania Node.js i npm, zalecamy używanie Menedżera wersji Node.

  2. Zainstaluj interfejs wiersza poleceń Firebase za pomocą 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 globalnie dostę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 to samo polecenie ponownie.

  3. Zainstaluj firebase-functions i firebase-admin oraz użyj --save, aby zapisać je w package.json:

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

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

Implementacja

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

  1. Włącz Agent Platform zalecane interfejsy API w Google Cloud konsoli.
  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 Config specyficzny dla serwera.
  6. Wdróż funkcję i przetestuj ją w Firebase Local Emulator Suite.
  7. Wdróż funkcję w Google Cloud.

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

  1. Otwórz konsolę Google Cloud i gdy pojawi się prośba, wybierz swój 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 potrwać kilka chwil. Nie zamykaj strony, dopóki włączanie się nie zakończy.

  5. Jeśli rozliczenia nie są włączone, pojawi się prośba o dodanie lub połączenie konta Cloud Billing. Po włączeniu konta rozliczeniowego wróć do Agent Platform panelu 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 innych opcji wybierz ustawienia domyślne.

    W bieżącym katalogu zostanie utworzony katalog functions. W nim znajdziesz plik index.js, którego użyjesz do tworzenia 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żywając --save, aby zapisać je w swoim package.json pliku:

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

Twój plik functions/package.json powinien teraz wyglądać tak jak poniżej, 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 Node jest zgodna z zainstalowaną wersją Node.js i wersją, której ostatecznie używasz w Google Cloud. Jeśli na przykład sekcja engines w pliku package.json jest skonfigurowana jako Node w wersji 18, 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 uruchamiania 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 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 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 w polu Typ klucza jest wybrana opcja 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 będzie obsługiwać dane wejściowe użytkownika i generować 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ź do użytkownika.

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

  2. Usuń dotychczasową zawartość, a następnie dodaj Admin SDK, Remote Config, i Agent Platform SDK 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 textModel, generationConfig, safetySettings, textPrompt, i location jako Remote Config parametry, które odpowiadają Remote Config parametrom, które skonfigurujesz w dalszej części tego przewodnika. Więcej informacji o tych parametrach znajdziesz w artykule Klient Vertex AI Node.js.

    Opcjonalnie możesz też skonfigurować parametr, który będzie określać, czy chcesz uzyskiwać 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 ta wartość jest ustawiona na false, co spowoduje pominięcie używania 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 specyficzny dla serwera Remote Config

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 specyficzny dla serwera:

  1. W konsoli Firebase otwórz DevOps i zaangażowanie > Zdalna konfiguracja.

  2. U góry strony w selektorze Klient/Serwer 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 Remote Config parametry:

    Nazwa parametru Opis Typ Wartość domyślna
    model_name Nazwa modelu
    Aktualne listy nazw modeli, których można używać w kodzie, znajdziesz w artykułach Wersje i cykle życia modeli oraz Dostępne nazwy modeli.     		Ciąg znaków gemini-2.0-flash
    prompt Prompt, który ma być dodawany 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ć uruchamiana usługa i model Agent Platform Ciąg znaków global
    is_vertex_enabled Opcjonalny parametr, który określa, czy zapytania mają być 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, a następnie kliknij Opublikuj zmiany.

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

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

  1. Upewnij się, że GOOGLE_APPLICATION_CREDENTIALS jest ustawiona jako zmienna środowiskowa zgodnie z opisem w kroku 3. Skonfiguruj uprawnienia IAM dla konta usługi i zapisz klucz.Admin SDK 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 się na niej wyświetlić, że funkcja została załadowana.

  3. Aby uzyskać dostęp do funkcji, uruchom 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 ani ostrzeżeń.

  5. Spróbuj wysłać dane wejściowe użytkownika. Pamiętaj, że ponieważ is_vertex_enabled jest skonfigurowany w szablonie serwera Remote Config, powinien on uzyskiwać dostęp do modelu Gemini za pomocą Agent Platform Gemini API (formerly Vertex AI), co 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 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 nieautoryzowanego dostępu do funkcji

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

Aby zablokować nieautoryzowany dostęp do funkcji:

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

  2. Kliknij generateWithVertex, a następnie kliknij kartę Zabezpieczenia.

  3. Włącz opcję Wymagaj uwierzytelnienia i kliknij Zapisz.

Konfigurowanie konta użytkownika do używania danych logowania konta usługi Admin SDK

Konto usługi Admin SDK ma wszystkie role i uprawnienia niezbędne do uruchamiania funkcji oraz interakcji z Remote Config i Agent Platform Gemini API (formerly Vertex AI), dlatego warto go używać do uruchamiania 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ę , aby działały z uprawnieniami konta usługi Admin SDK.

  1. W konsoli Google Cloud włącz interfejs IAM Service Account Credentials API.
  2. Przyznaj swojemu kontu użytkownika rolę Twórca tokenów konta usługi: w konsoli Google Cloud otwórz Administracja i dostęp > 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 dokumentacji w artykule Przejmowanie tożsamości konta usługi .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 kliknij 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 nie masz jeszcze zainstalowanego gcloud CLI na komputerze, zainstaluj go zgodnie z opisem w artykule Instalowanie gcloud CLI.

  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 dostarczonymi przez użytkownika:

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