Korzystanie z Zdalnej konfiguracji po stronie serwera w połączeniu z Cloud Functions i Vertex AI

Z tego przewodnika dowiesz się, jak zacząć korzystać z 2. generacji Cloud Functions z po stronie serwera Remote Config, aby wywoływać po stronie serwera interfejs Vertex AI Gemini API.

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 będziesz mieć możliwość aktualizowania tych danych 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 ona prawidłowo, 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 konsoli Firebase.

  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. 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 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, 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 polecenie firebase dostępne globalnie. 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 Vertex AI:

  1. Włącz Vertex AI 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 Vertex AI API w konsoli Google Cloud

  1. Otwórz konsolę Google Cloud Google Cloud i, gdy pojawi się prośba, wybierz projekt.
  2. W polu Szukaj u góry konsoli wpisz Vertex AI i poczekaj, aż Vertex AI pojawi się jako wynik.
  3. Wybierz Vertex AI. Wyświetli się panel Vertex AI.

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

    Włączenie interfejsu API może potrwać kilka minut. 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 Vertex AI 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. Znajdziesz w nim 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 Vertex AI, uruchamiając te polecenia. Użyj --save, aby zapisać je w pliku package.json:

    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
  }

Pamiętaj, że jeśli używasz ESLint, zobaczysz sekcję, która go zawiera. Upewnij się też, że wersja silnika Node.js 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 znajdź konto usługi Admin SDK (o nazwie firebase-adminsdk).
  2. Wybierz konto i kliknij Edytuj podmiot zabezpieczeń. 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 Vertex AI 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 Vertex AI Gemini API, 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 Vertex AI 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 Vertex AI Node.js client.

    Opcjonalnie możesz też skonfigurować parametr, który będzie określać, czy chcesz mieć dostęp do Vertex AI Gemini API (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żywania Vertex AI podczas testowania podstawowego wdrożenia funkcji. Ustawienie wartości true spowoduje wywołanie Vertex AI Gemini API.

    // 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 Vertex AI 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. Otwórz konsolę Firebase i w menu nawigacyjnym rozwiń Uruchom i wybierz Remote Config.

  2. U góry strony Remote Config w selektorze Klient/Serwer wybierz Serwer.

    • Jeśli po raz pierwszy korzystasz z Remote Config lub szablonów serwera, kliknij Utwórz konfigurację. Wyświetli 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 Vertex AI. 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 Vertex AI. Ciąg znaków us-central1
    is_vertex_enabled Opcjonalny parametr, który określa, czy zapytania mają być wysyłane do Vertex AI. Wartość logiczna true

  4. Gdy skończysz dodawać parametry, sprawdź je 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 zmienna środowiskowa GOOGLE_APPLICATION_CREDENTIALS jest ustawiona zgodnie z opisem w kroku 3. Skonfiguruj uprawnienia IAM dla konta usługiAdmin 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 się na niej wyświetlić, ż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 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ą Vertex AI Gemini API, 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 nieuwierzytelnionego dostępu do funkcji

Gdy funkcje są wdrażane za pomocą Firebase, domyślnie dozwolone są nieuwierzytelnione wywołania, jeśli nie zabraniają tego zasady organizacji. Podczas testowania i przed zabezpieczeniem za pomocą App Check zalecamy blokowanie 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 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

Ponieważ konto usługi Admin SDK ma wszystkie role i uprawnienia niezbędne do uruchamiania funkcji oraz interakcji z Remote Config i Vertex AI Gemini API, warto używać go 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 kont usługi: w Google Cloud konsoli otwórz Uprawnienia i administrator > 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.

    Szczegółowe informacje 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ły > Edytuj i rozwiń Ustawienia środowiska wykonawczego, kompilacji, połączeń i zabezpieczeń.

  6. Na karcie Środowisko wykonawcze zmień Konto usługi środowiska wykonawczego na Konto 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 instrukcjami 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