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

W tym przewodniku znajdziesz informacje o tym, jak zacząć korzystać z 2 generacjiCloud Functionspo stronie serweraRemote Config, aby wykonywać wywołania po stronie serwera do 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 możesz aktualizować te dane 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 na Google Cloud.

Wymagania wstępne

W tym przewodniku założyliśmy, że znasz JavaScript i umiesz go używać do tworzenia aplikacji.

Konfigurowanie projektu Firebase

Jeśli nie masz jeszcze projektu Firebase:

  1. Zaloguj się w Firebase konsoli.

  2. Kliknij Utwórz projekt, a następnie skorzystaj z jednej z tych opcji:

    • Opcja 1: utwórz nowy projekt Firebase (i powiązany z nim projektGoogle Cloud automatycznie), wpisując nową nazwę projektu w pierwszym kroku procesu „Tworzenie projektu”.
    • 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. Postępuj zgodnie z instrukcjami wyświetlanymi na ekranie, aby utworzyć projekt.

Jeśli masz już projekt 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 instalowania Node.js i npm zalecamy używanie Node Version Manager.

  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 na całym świecie. Jeśli to polecenie się nie powiedzie, może być konieczna zmiana uprawnień npm.

    Aby zaktualizować firebase-tools do najnowszej wersji, ponownie uruchom 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 Vertex AI, wykonaj te czynności:

  1. Włącz Vertex AI zalecanych interfejsów API w Google Cloudkonsoli.
  2. Zainicjuj projekt i zainstaluj zależności Node.js.
  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 Vertex AI zalecane interfejsy API w Google Cloud konsoli

  1. Otwórz Google Cloudkonsolę i po wyświetleniu prośby wybierz projekt.
  2. W polu Wyszukaj u góry konsoli wpisz Vertex AI i poczekaj, aż Vertex AI pojawi się w wynikach.
  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 chwil. Nie zamykaj strony i nie przełączaj się na inną, 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 konta Cloud Billing. Po włączeniu konta rozliczeniowego wróć do panelu Vertex AIi 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 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 Vertex AI, 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, 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. 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 Node.js w wersji 18, a Ty używasz Node.js w wersji 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 Admin SDKkonta usługi FirebaseAdmin 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. 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 Cloud Run Invoker.
  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 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 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 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 Vertex AI oraz zainicjuj aplikację, wklejając do pliku ten kod:

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

  3. Skonfiguruj wartości domyślne, których funkcja będzie używać, jeśli nie może 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 bibliotece klienta Vertex AI w Node.js.

    Opcjonalnie możesz też skonfigurować parametr, który będzie określać, czy masz 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 poniższych fragmentach kodu ta wartość jest ustawiona na false, co spowoduje pominięcie użycia Vertex AI podczas testowania podstawowego wdrożenia funkcji. Ustawienie wartości true spowoduje wywołanie funkcji 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
};
    index.js

  4. Utwórz funkcję i skonfiguruj tagowanie 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;
    index.js

  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');
  }
});
    index.js

  6. Zapisz i zamknij plik.

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

Następnie utwórz szablon Remote Config po stronie serwera i skonfiguruj parametry oraz wartości, które mają być używane w funkcji. Aby utworzyć szablon dotyczący konkretnego serwera:Remote Config

  1. Otwórz Firebase konsolę i w menu nawigacyjnym rozwiń Uruchom, a następnie kliknij Remote Config.

  2. U góry stronyRemote Config w selektorze Klient/serwer kliknij 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 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 tych artykułach: Wersje i cykle życia modeli lub 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 przesłania do modelu. JSON [{"stopSequences": ["I hope this helps"],"temperature": 0.7,"maxOutputTokens": 512, "topP": 0.1,"topK": 20}]
    safety_settings Ustawienia bezpieczeństwaVertex AI. JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
    location Lokalizacja, aby uruchomić Vertex AI usługę i model. Ciąg znaków us-central1
    is_vertex_enabled Opcjonalny parametr, który określa, czy zapytania są wysyłane do Vertex AI. Wartość logiczna true

  4. Gdy skończysz dodawać parametry, dokładnie sprawdź je i ich typy danych, a następnie kliknij Opublikuj zmiany.

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

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

  1. Sprawdź, czy zmienna środowiskowa GOOGLE_APPLICATION_CREDENTIALS została ustawiona zgodnie z opisem w Kroku 3. Skonfiguruj uprawnienia IAM 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ę z logami 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 tam 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ą Vertex AI Gemini API. 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 szablonie serwera Remote Config w konsoli Firebase, a potem ponownie otwórz funkcję, aby zobaczyć zmiany.

Krok 7. Wdróż funkcję w Google Cloud

Po przetestowaniu i zweryfikowaniu funkcji możesz wdrożyć ją w Google Cloud i sprawdzić, czy działa.

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 zabraniają 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 potem 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.

Ponieważ Admin SDK konto usługi ma wszystkie niezbędne role i uprawnienia 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 dla konta z poziomu konta użytkownika.

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

  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 Twórca tokenów konta 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 CloudCloud 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 poziomu 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 przekazanymi 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 Remote Config szablonie serwera, publikować te zmiany i testować różne opcje.

Dalsze kroki