Развертывание потоков с помощью облачных функций для Firebase

В Cloud Functions for Firebase есть метод onCallGenkit , который позволяет быстро создать вызываемую функцию с помощью действия Genkit (например, Flow). Эти функции можно вызывать с помощью genkit/beta/client или SDK клиента Functions , который автоматически добавляет информацию для аутентификации.

Прежде чем начать

  • Вы должны быть знакомы с концепцией потоков Genkit и тем, как их писать. Инструкции на этой странице предполагают, что у вас уже определены некоторые потоки, которые вы хотите развернуть.
  • Это было бы полезно, но не обязательно, если вы уже использовали Cloud Functions для Firebase.

1. Настройте проект Firebase

Если у вас еще нет проекта Firebase с настроенными облачными функциями TypeScript, выполните следующие действия:

  1. Создайте новый проект Firebase с помощью консоли Firebase или выберите существующий.

  2. Обновите проект до плана Blaze, который необходим для развертывания облачных функций.

  3. Установите Firebase CLI .

  4. Войдите в систему с помощью Firebase CLI:

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

  5. Создайте новый каталог проекта:

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

  6. Инициализируйте проект Firebase в каталоге:

    cd $PROJECT_ROOT
firebase init genkit

    В оставшейся части этой страницы предполагается, что вы решили писать свои функции на TypeScript, но вы также можете развернуть свои потоки Genkit, если используете JavaScript.

2. Оберните поток в onCallGenkit

После настройки проекта Firebase с облачными функциями вы можете скопировать или записать определения потоков в каталоге functions/src проекта и экспортировать их в index.ts .

Чтобы ваши потоки можно было развернуть, вам необходимо обернуть их в onCallGenkit . Этот метод обладает всеми функциями обычного onCall . Он автоматически поддерживает как потоковую передачу, так и ответы JSON.

Предположим, у вас есть следующий поток:

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;
  }
);

Вы можете представить этот поток как вызываемую функцию, используя onCallGenkit :

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

export generatePoem = onCallGenkit(generatePoemFlow);

Определить политику авторизации

Все развернутые потоки, независимо от того, развернуты ли они в Firebase или нет, должны иметь политику авторизации; без него любой сможет вызвать ваши потенциально дорогостоящие генеративные потоки ИИ. Чтобы определить политику авторизации, используйте параметр authPolicy onCallGenkit :

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

В этом примере в качестве политики аутентификации используется ручная функция. Кроме того, библиотека https экспортирует помощники signedIn() и hasClaim() . Вот тот же код с использованием одного из этих помощников:

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

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

Сделайте учетные данные API доступными для развернутых потоков.

После развертывания вашим потокам необходим какой-то способ аутентификации с любыми удаленными службами, от которых они зависят. Большинству потоков требуются как минимум учетные данные для доступа к используемому ими сервису API модели.

В этом примере выполните одно из следующих действий, в зависимости от выбранного вами поставщика модели:

Близнецы (ИИ Google)

  1. Убедитесь, что Google AI доступен в вашем регионе .

  2. Создайте ключ API для Gemini API с помощью Google AI Studio.

  3. Сохраните свой ключ API в Cloud Secret Manager:

    firebase functions:secrets:set GOOGLE_GENAI_API_KEY

    Этот шаг важен для предотвращения случайной утечки вашего ключа API, который предоставляет доступ к потенциально измеряемой услуге.

    Дополнительные сведения об управлении секретами см. в разделе Хранение и доступ к конфиденциальной информации о конфигурации .

  4. Отредактируйте src/index.ts и добавьте следующее после существующего импорта:

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

    Затем в определении потока объявите, что облачной функции необходим доступ к этому секретному значению: 

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

Теперь, когда вы развертываете эту функцию, ваш ключ API хранится в Cloud Secret Manager и доступен из среды Cloud Functions.

Близнецы (Vertex AI)

  1. В облачной консоли включите API Vertex AI для вашего проекта Firebase.

  2. На странице IAM убедитесь, что учетной записи службы вычислений по умолчанию предоставлена ​​роль пользователя Vertex AI .

Единственный секрет, который вам нужно настроить для этого руководства, — это поставщик модели, но в целом вы должны сделать что-то подобное для каждой службы, которую использует ваш поток.

Добавить принудительное применение проверки приложений

Firebase App Check использует встроенный механизм аттестации, чтобы убедиться, что ваш API вызывается только вашим приложением. onCallGenkit поддерживает принудительное применение проверки приложений декларативно. 

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);

Установите политику CORS

Вызываемые функции по умолчанию разрешают любому домену вызывать вашу функцию. Если вы хотите настроить домены, которые могут это сделать, используйте опцию cors . При правильной аутентификации (особенно при проверке приложений) CORS часто не нужен. 

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

Полный пример

После внесения всех описанных ранее изменений ваш процесс развертывания будет выглядеть примерно так, как показано в следующем примере: 

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. Развертывание потоков в Firebase

После того как вы определили потоки с помощью onCallGenkit , вы можете развернуть их так же, как и другие облачные функции: 

cd $PROJECT_ROOT
firebase deploy --only functions

Теперь вы развернули поток как облачную функцию! Но вы не можете получить доступ к развернутой конечной точке с помощью curl или аналогичного средства из-за политики авторизации потока. В следующем разделе объясняется, как безопасно получить доступ к потоку.

Необязательно: попробуйте развернутый поток

Чтобы опробовать конечную точку потока, вы можете развернуть следующий минимальный пример веб-приложения:

  1. В разделе «Настройки проекта» консоли Firebase добавьте новое веб-приложение, выбрав опцию также настроить хостинг.

  2. В разделе «Аутентификация» консоли Firebase включите провайдера Google , используемого в этом примере.

  3. В каталоге вашего проекта настройте хостинг Firebase, где вы будете развертывать пример приложения: 

    cd $PROJECT_ROOT
firebase init hosting

    Примите значения по умолчанию для всех запросов.

  4. Замените public/index.html следующим: 

    <!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. Разверните веб-приложение и облачную функцию: 

    cd $PROJECT_ROOT
firebase deploy

Откройте веб-приложение, посетив URL-адрес, напечатанный командой deploy . Приложение требует входа в систему с учетной записью Google, после чего вы можете инициировать запросы к конечным точкам.

Необязательно: запускайте потоки в пользовательском интерфейсе разработчика.

Вы можете запускать потоки, определенные с помощью onCallGenkit в пользовательском интерфейсе разработчика, точно так же, как вы запускаете потоки, определенные с помощью defineFlow , поэтому нет необходимости переключаться между ними между развертыванием и разработкой. 

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

или 

cd $PROJECT_ROOT/functions
npm run genkit:start

Теперь вы можете перейти к URL-адресу, напечатанному командой genkit start для доступа.

Необязательно: разработка с использованием пакета локального эмулятора Firebase.

Firebase предлагает набор эмуляторов для локальной разработки , которые вы можете использовать с Genkit.

Чтобы использовать пользовательский интерфейс Genkit Dev с пакетом эмуляторов Firebase, запустите эмуляторы Firebase следующим образом: 

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

Эта команда запускает ваш код в эмуляторе и запускает платформу Genkit в режиме разработки. При этом запускается и предоставляется API отражения Genkit (но не пользовательский интерфейс Dev).

Чтобы увидеть трассировки из Firestore в пользовательском интерфейсе разработчика, вы можете перейти на вкладку «Проверка» и переключить переключатель Dev/Prod . При переключении на prod он загружает следы из Firestore.