Wdrażanie procesów za pomocą Cloud Functions dla Firebase

Cloud Functions dla Firebase ma metodę onCallGenkit, która umożliwia szybkie tworzenie funkcji wywoływalnej za pomocą działania Genkit (np. przepływu). Te funkcje można wywołać za pomocą funkcji genkit/beta/client lub pakietu SDK klienta Functions, który automatycznie dodaje informacje uwierzytelniające.

Zanim zaczniesz

• Musisz znać pojęcie przepływów w Genkit i wiedzieć, jak je pisać. Instrukcje na tej stronie zakładają, że masz już zdefiniowane przepływy, które chcesz wdrożyć.
• Przydatne, choć nieobowiązkowe, może być wcześniejsze korzystanie z funkcji Cloud Functions for Firebase.

1. Konfigurowanie projektu Firebase

Jeśli nie masz jeszcze projektu Firebase z skonfigurowanymi funkcjami TypeScript Cloud Functions, wykonaj te czynności:

1. Utwórz nowy projekt Firebase w konsoli Firebase lub wybierz istniejący.

2. Przekształć projekt na abonament Blaze, który jest wymagany do wdrażania funkcji Cloud Functions.

3. Zainstaluj Firebase CLI.

4. Zaloguj się za pomocą wiersza poleceń Firebase:

   firebase login
   firebase login --reauth # alternative, if necessary
   firebase login --no-localhost # if running in a remote shell

5. Utwórz nowy katalog projektu:

   export PROJECT_ROOT=~/tmp/genkit-firebase-project1
   mkdir -p $PROJECT_ROOT

6. Aby zainicjować projekt Firebase w katalogu:

   cd $PROJECT_ROOT
   firebase init genkit

   Pozostała część tej strony zakłada, że funkcje zostały napisane w TypeScript, ale jeśli używasz JavaScriptu, możesz też wdrożyć przepływy Genkit.

2. Zakończ pracę nad przepływem w onCallGenkit

Po skonfigurowaniu projektu Firebase za pomocą Cloud Functions możesz skopiować lub napisać definicje przepływu w katalogu functions/src projektu i wyeksportować je w folderze index.ts.

Aby można było wdrażać przepływy, musisz je owinąć w onCallGenkit. Ta metoda ma wszystkie funkcje zwykłego onCall. Obsługuje automatycznie zarówno strumieniowanie, jak i odpowiedzi w formacie JSON.

Załóżmy, że masz taki proces:

const generatePoemFlow = ai.defineFlow(
  {
    name: "generatePoem",
    inputSchema: z.string(),
    outputSchema: z.string(),
  },
  async (subject: string) => {
    const { text } = await ai.generate(`Compose a poem about ${subject}.`);
    return text;
  }
);

Możesz udostępnić ten przepływ jako funkcję wywołującą za pomocą onCallGenkit:

import { onCallGenkit } from 'firebase-functions/https';

export generatePoem = onCallGenkit(generatePoemFlow);

Definiowanie zasady autoryzacji

Wszystkie wdrożone przepływy danych, niezależnie od tego, czy zostały wdrożone w Firebase, powinny mieć zasadę autoryzacji. Bez niej każdy może wywołać potencjalnie kosztowne przepływy generative AI. Aby zdefiniować zasady autoryzacji, użyj parametru authPolicy w elementach onCallGenkit:

export const generatePoem = onCallGenkit({
  authPolicy: (auth) => auth?.token?.email_verified,
}, generatePoemFlow);

W tym przykładzie jako polityki uwierzytelniania używana jest funkcja ręczna. Dodatkowo biblioteka https eksportuje pomocnicze pliki signedIn() i hasClaim(). Oto ten sam kod, który używa jednej z tych funkcji pomocniczych:

import { hasClaim } from 'firebase-functions/https';

export const generatePoem = onCallGenkit({
  authPolicy: hasClaim('email_verified'),
}, generatePoemFlow);

Udostępnianie danych logowania interfejsu API wdrożonym przepływom

Po wdrożeniu procesy muszą mieć możliwość uwierzytelniania się w usługach zdalnych, z których korzystają. Większość przepływów wymaga co najmniej danych logowania do interfejsu API modelu, którego używają.

W tym przykładzie wykonaj jedną z tych czynności w zależności od wybranego dostawcy modelu:

Gemini (Google AI)

1. Upewnij się, że Google AI jest dostępny w Twoim regionie.

2. Wygeneruj klucz interfejsu API dla Gemini API za pomocą Google AI Studio.

3. Zapisz klucz interfejsu API w usłudze Cloud Secret Manager:

   firebase functions:secrets:set GOOGLE_GENAI_API_KEY

   Ten krok jest ważny, ponieważ zapobiega przypadkowemu ujawnieniu klucza interfejsu API, który umożliwia dostęp do usługi z możliwym naliczaniem opłat.

   Więcej informacji o zarządzaniu obiektami tajnymi znajdziesz w artykule Przechowywanie informacji o konfiguracji o charakterze poufnym i dostęp do nich.

4. Zmień plik src/index.ts i po dotychczasowych instrukcjach importu dodaj te informacje:

   import {defineSecret} from "firebase-functions/params";
   const googleAIapiKey = defineSecret("GOOGLE_GENAI_API_KEY");
   

   Następnie w definicji przepływu zadeklaruj, że funkcja w chmurze potrzebuje dostępu do tej wartości tajnej:

   export const generatePoem = onCallGenkit({
     secrets: [googleAIapiKey]
   }, generatePoemFlow);
   

Gdy teraz wdrożesz tę funkcję, klucz interfejsu API zostanie zapisany w usłudze Cloud Secret Manager i będzie dostępny z poziomu środowiska Cloud Functions.

Gemini (Vertex AI)

1. W konsoli Cloud włącz interfejs API Vertex AI w projekcie Firebase.

2. Na stronie Uprawnienia sprawdź, czy domyślnemu kontu usługi obliczeniowej przypisano rolę Użytkownik Vertex AI.

W tym samouczku musisz skonfigurować tylko jeden sekret – dla dostawcy modelu. Ogólnie jednak musisz wykonać podobne czynności w przypadku każdej usługi używanej przez przepływ danych.

Dodawanie wymuszania Sprawdzania aplikacji

Sprawdzanie aplikacji Firebase używa wbudowanego mechanizmu atestacji, aby sprawdzić, czy interfejs API jest wywoływany tylko przez Twoją aplikację. onCallGenkit obsługuje deklaratywnie egzekwowanie weryfikacji aplikacji.

export const generatePoem = onCallGenkit({
  enforceAppCheck: true,
  // Optional. Makes App Check tokens only usable once. This adds extra security
  // at the expense of slowing down your app to generate a token for every API
  // call
  consumeAppCheckToken: true,
}, generatePoemFlow);

Ustawianie zasady CORS

Domyślnie funkcje wywoływane mogą być wywoływane z dowolnej domeny. Jeśli chcesz dostosować domeny, które mogą to zrobić, użyj opcji cors. Przy prawidłowym uwierzytelnieniu (zwłaszcza w przypadku App Check) CORS często nie jest potrzebny.

export const generatePoem = onCallGenkit({
  cors: 'mydomain.com',
}, generatePoemFlow);

Pełny przykład

Po wprowadzeniu wszystkich opisanych wcześniej zmian proces wdrażania będzie wyglądał mniej więcej tak:

import { genkit } from 'genkit';
import { onCallGenkit, hasClaim } from 'firebase-functions/https';
import { defineSecret } from 'firebase-functions/params';

const apiKey = defineSecret("GOOGLE_GENAI_API_KEY");

const generatePoemFlow = ai.defineFlow({
  name: "generatePoem",
  inputSchema: z.string(),
  outputSchema: z.string(),
}, async (subject: string) => {
  const { text } = await ai.generate(`Compose a poem about ${subject}.`);
  return text;
});

export const generateFlow = onCallGenkit({
  secrets: [apiKey],
  authPolicy: hasClaim("email_verified"),
  enforceAppCheck: true,
}, generatePoemFlow);

3. Wdrażanie procesów w Firebase

Po zdefiniowaniu przepływów za pomocą onCallGenkit możesz je wdrożyć w taki sam sposób jak inne funkcje w Cloud Functions:

cd $PROJECT_ROOT
firebase deploy --only functions

Twój przepływ został wdrożony jako funkcja w Cloud Functions. Nie możesz jednak uzyskać dostępu do wdrożonego punktu końcowego za pomocą curl ani podobnej metody ze względu na zasady autoryzacji przepływu danych. W następnej sekcji wyjaśniamy, jak bezpiecznie uzyskać dostęp do procesu.

Opcjonalnie: wypróbuj wdrożony proces

Aby wypróbować punkt końcowy przepływu, możesz wdrożyć tę minimalną przykładową aplikację internetową:

1. W sekcji Ustawienia projektu w konsoli Firebase dodaj nową aplikację internetową, wybierając opcję konfiguracji hostingu.

2. W sekcji Uwierzytelnianie konsoli Firebase włącz dostawcę Google, który jest używany w tym przykładzie.

3. W katalogu projektu skonfiguruj Hosting Firebase, w którym wdrożesz przykładową aplikację:

   cd $PROJECT_ROOT
   firebase init hosting

   Zaakceptuj domyślne wartości dla wszystkich promptów.

4. Zastąp public/index.html tymi wartościami:

   <!DOCTYPE html>
   <html>
     <head>
       <title>Genkit demo</title>
     </head>
     <body>
       <div id="signin" hidden>
         <button id="signinBtn">Sign in with Google</button>
       </div>
       <div id="callGenkit" hidden>
         Subject: <input type="text" id="subject" />
         <button id="generatePoem">Compose a poem on this subject</button>
         <p id="generatedPoem"></p>
       </div>
       <script type="module">
         import { initializeApp } from "https://www.gstatic.com/firebasejs/11.0.1/firebase-app.js";
         import {
           getAuth,
           onAuthStateChanged,
           GoogleAuthProvider,
           signInWithPopup,
         } from "https://www.gstatic.com/firebasejs/11.0.1/firebase-auth.js";
         import {
           getFunctions,
           httpsCallable,
         } from "https://www.gstatic.com/firebasejs/11.0.1/firebase-functions.js";
   
         const firebaseConfig = await fetch("/__/firebase/init.json");
         initializeApp(await firebaseConfig.json());
   
         async function generatePoem() {
           const poemFlow = httpsCallable(getFunctions(), "generatePoem");
           const subject = document.querySelector("#subject").value;
           const response = await poemFlow(subject);
           document.querySelector("#generatedPoem").innerText = response.data;
         }
   
         function signIn() {
           signInWithPopup(getAuth(), new GoogleAuthProvider());
         }
   
         document.querySelector("#signinBtn").addEventListener("click", signIn);
         document
           .querySelector("#generatePoem")
           .addEventListener("click", generatePoem);
   
         const signinEl = document.querySelector("#signin");
         const genkitEl = document.querySelector("#callGenkit");
   
         onAuthStateChanged(getAuth(), (user) => {
           if (!user) {
             signinEl.hidden = false;
             genkitEl.hidden = true;
           } else {
             signinEl.hidden = true;
             genkitEl.hidden = false;
           }
         });
       </script>
     </body>
   </html>
   

5. Wdróż aplikację internetową i funkcję w Cloud Functions:

   cd $PROJECT_ROOT
   firebase deploy

Otwórz aplikację internetową, klikając adres URL wydrukowany przez polecenie deploy. Aplikacja wymaga zalogowania się na konto Google, po czym można inicjować żądania dotyczące urządzeń końcowych.

Opcjonalnie: uruchamianie procesów w interfejsie programisty

Możesz uruchamiać przepływy zdefiniowane za pomocą onCallGenkit w interfejsie dla deweloperów w taki sam sposób, jak przepływy zdefiniowane za pomocą defineFlow. Dzięki temu nie musisz przełączać się między tymi dwoma interfejsami podczas wdrażania i tworzenia.

cd $PROJECT_ROOT/functions
npx genkit start -- npx tsx --watch src/index.ts

lub

cd $PROJECT_ROOT/functions
npm run genkit:start

Teraz możesz przejść do adresu URL wydrukowanego przez polecenie genkit start.

Opcjonalnie: tworzenie aplikacji za pomocą Pakietu emulatorów lokalnych Firebase

Firebase oferuje pakiet emulatorów do lokalnego tworzenia aplikacji, których możesz używać z Genkit.

Aby korzystać z interfejsu Genkit Dev w pakiecie Emulator Suite Firebase, uruchom emulatory Firebase w ten sposób:

npx genkit start -- firebase emulators:start --inspect-functions

To polecenie uruchamia kod w emulatorze i ramówce Genkit w trybie programowania. Spowoduje to uruchomienie i ujawnienie interfejsu API Genkit (ale nie interfejsu dla programistów).

Aby zobaczyć ścieżki z Firestore w interfejsie dewelopera, przejdź na kartę Sprawdź i przełącz przełącznik Dev/Prod. Gdy przełączysz się na produkcję, aplikacja będzie wczytywać dane z Firestore.