Używanie Zdalnej konfiguracji po stronie serwera z Cloud Functions i Vertex AI

Z tego przewodnika dowiesz się, jak zacząć korzystać z funkcji w Cloud Functions 2 generacji ze zdalną konfiguracją po stronie serwera do wywoływania po stronie serwera interfejsu Vertex AI Gemini API.

W tym samouczku dodasz Zdalną konfigurację do funkcji przypominającej czatbota, która używa modelu Gemini do odpowiadania na pytania użytkowników. Zdalna konfiguracja będzie zarządzać danymi wejściowymi interfejsu Gemini API (w tym promptem, który będzie się dodawany na początku zapytań użytkowników). Możesz je aktualizować na żądanie z poziomu konsoli Firebase. Będziesz też używać Pakietu emulatorów lokalnych Firebase do testowania i debugowania funkcji, a gdy upewnisz się, że działa, możesz ją wdrożyć i przetestować w Google Cloud.

Wymagania wstępne

W tym przewodniku zakładamy, że umiesz tworzyć aplikacje za pomocą JavaScriptu.

Skonfiguruj projekt Firebase

Jeśli nie masz jeszcze projektu Firebase:

  1. Zaloguj się w konsoli Firebase.

  2. Kliknij Utwórz projekt, a potem użyj jednej z tych opcji:

    • Opcja 1. Automatycznie utwórz nowy projekt Firebase (i powiązany z nim projekt Google Cloud), wpisując nazwę nowego projektu na pierwszym etapie procedury „Utwórz projekt”.
    • Opcja 2. „Dodaj Firebase” do istniejącego projektu Google Cloud, wybierając w menu nazwę projektu Google Cloud w pierwszym kroku procedury tworzenia projektu.

  3. Jeśli pojawi się taka 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 Firebase:

Przejdź do artykułu Konfigurowanie środowiska programistycznego.

Konfigurowanie środowiska programistycznego

Aby zapisywać funkcje, potrzebujesz środowiska Node.js, a do wdrażania funkcji w środowisku wykonawczym Cloud Functions będziesz potrzebować interfejsu wiersza poleceń Firebase.

  1. Zainstaluj Node.js i npm.

    Do instalowania Node.js i npm zalecamy użycie Menedżera wersji węzłów.

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

    npm install -g firebase-tools@latest

    Instaluje ono dostępne globalnie polecenie firebase. Jeśli to polecenie nie powiedzie się, być może trzeba zmienić uprawnienia npm.

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

  3. Zainstaluj aplikacje firebase-functions i firebase-admin, a potem 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 wdrażania tego rozwiązania.

Implementacja

Wykonaj te czynności, aby utworzyć, przetestować i wdrożyć funkcje w Cloud Functions 2 generacji za pomocą Zdalnej konfiguracji i Vertex AI:

  1. Włącz zalecane interfejsy API Vertex AI w konsoli Google Cloud.
  2. Zainicjuj projekt i zainstaluj zależności węzłów.
  3. Skonfiguruj uprawnienia konta usługi pakietu Admin SDK i zapisz klucz.
  4. Utwórz funkcję.
  5. Utwórz odpowiedni dla serwera szablon Zdalnej konfiguracji.
  6. Wdróż funkcję i przetestuj ją w Pakiecie emulatorów lokalnych Firebase.
  7. wdrożyć funkcję w Google Cloud,

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

  1. Otwórz konsolę Google Cloud, a potem, gdy pojawi się prośba, wybierz projekt.
  2. W polu wyszukiwania u góry konsoli wpisz Vertex AI i zaczekaj, aż Vertex AI się wyświetli.
  3. Wybierz Vertex AI. Pojawi się panel Vertex AI.

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

    Włączanie interfejsu API może chwilę potrwać. Nie zamykaj strony, 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 rozliczeniowego Cloud. Po włączeniu konta rozliczeniowego wróć do panelu Vertex AI i sprawdź, czy wszystkie zalecane interfejsy API są włączone.

Krok 2. Zainicjuj projekt i zainstaluj zależności węzłów

  1. Otwórz terminal na komputerze i przejdź do katalogu, w którym zamierzasz utworzyć funkcję.

  2. Zaloguj się w Firebase:

    firebase login

  3. Uruchom to polecenie, aby zainicjować funkcje Cloud Functions dla Firebase:

    firebase init functions

  4. Wybierz Użyj istniejącego projektu i podaj identyfikator projektu.

  5. Gdy pojawi się prośba o wybór języka, wybierz JavaScript i naciśnij Enter.

  6. Aby wyświetlić pozostałe opcje, wybierz wartości 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, który zawiera zależności pakietów.

  7. Dodaj pakiety Admin SDK i Vertex AI, uruchamiając następujące polecenia przy użyciu polecenia --save, aby mieć pewność, że plik zostanie zapisany 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ć podobnie do tego 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 języka ESLint, zobaczysz informację, która go zawiera. Dodatkowo sprawdź, czy wersja silnika węzłów odpowiada zainstalowanej wersji Node.js i wersji, którą ostatecznie uruchamiasz w Google Cloud. Jeśli na przykład sekcja engines w package.json jest skonfigurowana jako węzeł w wersji 18 i używasz Node.js 20, zaktualizuj plik do wersji 20:

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

Krok 3. Skonfiguruj uprawnienia dla 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 Uprawnienia do edycji.
  3. Kliknij Dodaj kolejną rolę i wybierz Wyświetlający Zdalnej konfiguracji.
  4. Kliknij kolejno Dodaj kolejną rolę i Deweloper platformy AI.
  5. Kliknij Dodaj kolejną rolę i wybierz Użytkownik Vertex AI.
  6. Kliknij kolejno Dodaj kolejną rolę i Wywołujący Cloud Run.
  7. Kliknij Zapisz.

Następnie wyeksportuj dane logowania do konta usługi pakietu 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. Wybierz JSON jako Typ klucza, a następnie kliknij Utwórz.
  6. Pobierz klucz w bezpieczne miejsce na komputerze.

  7. Z terminala 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. Musisz połączyć kilka fragmentów kodu, aby utworzyć kompleksową funkcję, która inicjuje pakiet Admin SDK i interfejs Vertex AI Gemini API, konfiguruje parametry domyślne za pomocą Zdalnej konfiguracji, pobiera najnowsze parametry Zdalnej konfiguracji, przetwarza dane wejściowe użytkownika i przesyła odpowiedź strumieniowo do użytkownika.

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

  2. Usuń istniejącą treść, dodaj pakiet Admin SDK, zdalną konfigurację i pakiet Vertex AI SDK, a następnie 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 będzie używać Twoja funkcja, gdy nie może połączyć się z serwerem Zdalnej konfiguracji. To rozwiązanie konfiguruje textModel, generationConfig, safetySettings, textPrompt i location jako parametry Zdalnej konfiguracji odpowiadające parametrom Zdalnej konfiguracji, które skonfigurujesz w dalszej części tego przewodnika. Więcej informacji o tych parametrach znajdziesz w artykule o kliencie Vertex AI Node.js.

    Opcjonalnie możesz też skonfigurować parametr, aby kontrolować, czy masz dostęp do interfejsu Vertex AI Gemini API (w tym przykładzie jest to parametr o nazwie vertex_enabled). Taka konfiguracja może być przydatna podczas testowania funkcji. W poniższych fragmentach kodu ta wartość jest ustawiona na false, co oznacza, że podczas testowania wdrażania podstawowych funkcji pomijane jest za pomocą Vertex AI. Ustawienie go na wartość true spowoduje wywoływanie interfejsu 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-preview-0514",
  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 zdalną konfigurację po stronie serwera:

    // 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 oraz 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 Zdalnej konfiguracji dla serwera

Następnie utwórz szablon Zdalnej konfiguracji po stronie serwera i skonfiguruj parametry oraz wartości do użycia w funkcji. Aby utworzyć specyficzny dla serwera szablon Zdalnej konfiguracji:

  1. Otwórz konsolę Firebase i w menu nawigacyjnym rozwiń Uruchom i wybierz Zdalna konfiguracja.

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

    • Jeśli po raz pierwszy używasz Zdalnej konfiguracji lub szablonów serwera, kliknij Utwórz konfigurację. Pojawi się panel Utwórz pierwszy parametr po stronie serwera.
    • Jeśli nie używasz szablonów serwera Zdalnej konfiguracji po raz pierwszy, kliknij Dodaj parametr.

  3. Zdefiniuj te parametry Zdalnej konfiguracji:

    Nazwa parametru Opis Typ Wartość domyślna
    model_name Nazwa modelu
    Aktualne listy nazw modeli do użycia w kodzie znajdziesz w artykułach o wersjach modeli i cyklach życia lub dostępnych nazwach modeli.     		Ciąg znaków gemini-1.5-pro-preview-0514
    prompt Prompt 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 Vertex AI. JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
    location Lokalizacja, w którym zostanie uruchomiona usługa i model Vertex AI. Ciąg znaków us-central1
    is_vertex_enabled Opcjonalny parametr określający, czy zapytania są wysyłane do Vertex AI. Wartość logiczna true

  4. Po dodaniu parametrów dokładnie sprawdź, czy typy danych są prawidłowe, a następnie kliknij Opublikuj zmiany.

Krok 6. Wdróż funkcję i przetestuj ją w Pakiecie emulatorów lokalnych Firebase.

Możesz teraz wdrożyć i przetestować swoją funkcję lokalnie przy użyciu Pakietu emulatorów lokalnych Firebase.

  1. Sprawdź, czy ustawiono GOOGLE_APPLICATION_CREDENTIALS jako zmienną środowiskową zgodnie z opisem w kroku 3. Skonfiguruj uprawnienia dla konta usługi Admin SDK i zapisz klucz. Następnie w katalogu nadrzędnym katalogu functions wdróż swoją funkcję w emulatorze Firebase:

    firebase emulators:start --project PROJECT_ID --only functions

  2. Otwórz stronę logów emulatora. Powinno to pokazać, że funkcja została wczytana.

  3. Uzyskaj dostęp do funkcji, uruchamiając to polecenie, gdzie PROJECT_ID to identyfikator projektu, a LOCATION to region, w którym funkcja została wdrożona (na przykład 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 żadnych błędów lub ostrzeżeń.

  5. Spróbuj przesłać dane wejściowe użytkownika. Ponieważ usługa is_vertex_enabled jest skonfigurowana w szablonie serwera Zdalnej konfiguracji, powinna mieć dostęp do Gemini przez interfejs Vertex AI Gemini API i może powodować naliczanie opłat:

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats

  6. Wprowadź zmiany w szablonie serwera Zdalnej konfiguracji w konsoli Firebase, a następnie ponownie otwórz swoją funkcję, aby je obserwować.

Krok 7. Wdróż funkcję w Google Cloud

Po przetestowaniu i zweryfikowaniu funkcji możesz ją wdrożyć w Google Cloud i przetestować aktywną funkcję.

Wdrażanie funkcji

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

firebase deploy --only functions

Blokuj nieuwierzytelniony dostęp do funkcji

Gdy funkcje są wdrażane z użyciem Firebase, nieuwierzytelnione wywołania są domyślnie dozwolone, o ile zasady organizacji go nie ograniczają. Podczas testów i przed zabezpieczeniem za pomocą Sprawdzania aplikacji 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 kliknij kartę Zabezpieczenia.

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

Skonfiguruj konto użytkownika pod kątem używania danych logowania do konta usługi pakietu Admin SDK

Konto usługi pakietu Admin SDK ma wszystkie role i uprawnienia niezbędne do uruchamiania funkcji oraz interakcji z interfejsem Zdalnej konfiguracji i interfejsem Vertex AI Gemini API, dlatego warto go używać do uruchamiania funkcji. Aby to zrobić, musisz mieć możliwość tworzenia tokenów na koncie użytkownika.

Poniżej znajdziesz instrukcje konfigurowania konta użytkownika oraz funkcji uruchamiania z uprawnieniami konta usługi Admin SDK.

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

  3. Wybierz Service Account Token Creator (Twórca tokenów konta usługi) i kliknij Save (Zapisz).

    Więcej informacji o przejmowaniu tożsamości konta usługi znajdziesz w sekcji na temat przejmowania tożsamości konta usługi w dokumentacji Google Cloud.

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

  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 kolejno Dalej i Wdróż.

Konfigurowanie interfejsu wiersza poleceń gcloud

Aby bezpiecznie uruchamiać i testować 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 interfejs wiersza poleceń gcloud:

  1. Jeśli gcloud CLI nie jest jeszcze zainstalowany na komputerze, zainstaluj go zgodnie z opisem w sekcji 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ć swoją 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 podanych 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 Zdalnej konfiguracji, opublikować te zmiany i przetestować różne opcje.

Dalsze kroki