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 tagów drugiej generacjiCloud Functions z tagowaniem po stronie serweraRemote Config, aby wykonywać wywołania po stronie serwera do tagu Vertex AI Gemini API.

W tym samouczku dodasz funkcję podobną do chatbota, która korzysta z modelu Gemini, aby odpowiadać na pytania użytkowników.Remote Config Remote Config będzie zarządzać danymi wejściowymi Gemini API (w tym promptem, który będzie dodawany do przychodzących zapytań użytkowników). Możesz aktualizować te dane według potrzeb w konsoli Firebase. Użyjesz też funkcji Firebase Local Emulator Suite do testowania i debugowania funkcji, a potem, gdy się upewnisz, że działa, wdrożysz ją i przetestujesz na Google Cloud.

Wymagania wstępne

W tym przewodniku zakładamy, że znasz JavaScript i wiesz, jak używać go do tworzenia aplikacji.

Konfigurowanie projektu Firebase

Jeśli nie masz jeszcze projektu Firebase:

  1. Zaloguj się w konsoli Firebase.

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

    • Opcja 1: utwórz nowy projekt Firebase (a także jego podstawowy projekt Google 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 jego nazwę Google Cloud w menu w pierwszym kroku procesu „Tworzenie projektu”.

  3. Aby korzystać z tego rozwiązania, nie musisz konfigurować usługi Google Analytics.

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

Jeśli masz już projekt Firebase:

Przejdź do sekcji Konfigurowanie środowiska programistycznego.

Konfigurowanie środowiska programistycznego

Do tworzenia funkcji potrzebujesz środowiska Node.js, a do wdrażania funkcji w czasie wykonywania potrzebujesz interfejsu wiersza poleceń Firebase.Cloud Functions

  1. Zainstaluj Node.js i npm.

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

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

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

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

Teraz możesz przejść do wdrażania tego rozwiązania.

Implementacja

Aby utworzyć, przetestować i wdrażać model Cloud Functions 2 generacji z użyciem Remote Config i Vertex AI, wykonaj te czynności:

  1. Włącz zalecane interfejsy API Vertex AI w konsoli Google Cloud.
  2. Inicjalizuj 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 dla konkretnego serwera.
  6. Wdróż funkcję i przetestuj ją w Firebase Local Emulator Suite.
  7. Wdróż funkcję do usługi Google Cloud.

Krok 1. Włącz zalecane interfejsy API w konsoli Google CloudVertex AI

  1. Otwórz konsolę Google Cloud i po wyświetleniu odpowiedniego komunikatu wybierz swój projekt.
  2. W polu Szukaj u góry konsoli wpisz Vertex AI i zaczekaj, aż w wyniku pojawi się Vertex AI.
  3. Kliknij 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 tej strony, dopóki proces włączania nie zostanie ukończony.

  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 AI i sprawdź, czy wszystkie zalecane interfejsy API są włączone.

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

  1. Otwórz terminal na komputerze i otwórz katalog, 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 klawisz Enter.

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

    W bieżącym katalogu zostanie utworzony katalog functions. Znajdziesz w nim plik index.js, który posłuży Ci do skompilowania funkcji, katalog node_modules zawierający zależności funkcji oraz plik package.json z zależностями pakietu.

  7. Dodaj pakiety Admin SDK i Vertex AI, wykonując te polecenia za pomocą --save, aby mieć pewność, że plik package.json zostanie zapisany:

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

Plik functions/package.json powinien teraz wyglądać tak, jak pokazano poniżej. Podano w nim najnowsze wersje:

  {
    "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 zwrotkę, która go zawiera. Dodatkowo sprawdź, czy wersja silnika node jest zgodna z zainstalowaną wersją Node.js i wersją, która jest uruchomiona w Google Cloud. Jeśli na przykład zwrotka engines w pliku package.json jest skonfigurowana jako wersja Node.js 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 wykonywania funkcji używasz konta usługi Admin SDK Firebase.

  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 osobę główną. Pojawi się strona Edytuj uprawnienia.
  3. Kliknij Dodaj kolejną rolę i wybierz Remote Config Widz.
  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ływacz 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 wybrana jest opcja JSON, a następnie kliknij Utwórz.
  6. Pobierz klucz 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 z wykorzystaniem 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 kodzie otwórz functions/index.js w edytorze tekstu lub środowisku IDE.

  2. Usuń istniejące treści, a następnie dodaj pakiety SDK Admin SDK, Remote Config i Vertex AI oraz zainicjuj aplikację, wklejając w 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 uda jej się połączyć z serwerem Remote Config. To rozwiązanie konfiguruje parametry textModel, generationConfig, safetySettings, textPrompt i location jako parametry Remote Config odpowiadające parametrom Remote Config, które skonfigurujesz w dalszej części tego przewodnika. Więcej informacji o tych parametrach znajdziesz w artykule Biblioteka klienta Vertex AI w Node.js.

    Opcjonalnie możesz też skonfigurować parametr, który steruje dostępem 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 ta wartość jest ustawiona na false, co spowoduje pominięcie użycia funkcji Vertex AI podczas testowania podstawowego wdrażania funkcji. Ustawienie go na 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
};
    index.js

  4. Utwórz funkcję i skonfiguruj ją 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 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 Configdla konkretnego 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 kliknij Serwer.

    • Jeśli po raz pierwszy używasz szablonów Remote Config lub serwerów, kliknij Utwórz konfigurację. Pojawi się panel Tworzenie pierwszego parametru 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 do użycia w kodzie znajdziesz w artykule Wersje i cykle życia modeli lub Dostępne nazwy modeli.     		Ciąg znaków gemini-1.5-flash-002
    prompt Prośba 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, w której ma być uruchamiana usługa Vertex AI i model. Ciąg znaków us-central1
    is_vertex_enabled Opcjonalny parametr określający, czy zapytania są wysyłane do adresu Vertex AI. Wartość logiczna true
    .

  4. Po dodaniu parametrów sprawdź, czy są one prawidłowe, a ich typy danych są zgodne z oczekiwaniami. 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ą funkcji 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ł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. Powinieneś zobaczyć, że funkcja została załadowana.

  3. Uzyskaj dostęp do funkcji, uruchamiając to polecenie, w którym 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ę dziennikó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 uzyskiwać dostęp do Gemini przez 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 sprawdzić zmiany.

Krok 7. Wdróż funkcję do Google Cloud

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

Wdrażanie funkcji

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

firebase deploy --only functions

Blokowanie dostępu do funkcji przez osoby niezautentifikowane

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

Aby zablokować dostęp do funkcji bez uwierzytelniania:

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

  2. Kliknij kolejno generateWithVertex i kartę Bezpieczeństwo.

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

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

Konto usługi Admin SDK ma wszystkie wymagane role i uprawnienia do wykonywania funkcji oraz do interakcji z kontami Remote Config i Vertex AI Gemini API, dlatego warto go użyć do wykonania funkcji. Aby to zrobić, musisz mieć możliwość tworzenia tokenów dla tego konta ze swojego konta użytkownika.

W następujących krokach opisujemy, 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 API Dane logowania konta usługi IAM.
  2. Przypisz do konta użytkownika rolę Twórca tokena konta usługi: w konsoli Google Cloud otwórz Administracja > Uprawnienia, wybierz konto użytkownika i kliknij Edytuj podmiot > Dodaj kolejną rolę.

  3. Wybierz Twórca tokena konta usługi, a następnie kliknij Zapisz.

    Więcej informacji o przejmowaniu tożsamości konta usługi znajdziesz w dokumentacji Google Cloud (w języku angielskim) w sekcji Przejmowanie tożsamości konta usługi.

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

  5. Kliknij Reguła > Edytuj i rozwiń sekcję 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 kolejno Dalej i Wdróż.

Konfigurowanie gcloud CLI

Aby bezpiecznie uruchamiać i testować funkcję z poziomu wiersza poleceń, musisz się uwierzytelnić 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. Aby uzyskać 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, podając dane przesłane 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 wprowadzić zmiany w szablonie serwera Remote Config, opublikować te zmiany i przetestować różne opcje.

Dalsze kroki