Plug-in do Firebase

O plug-in do Firebase oferece várias integrações com os serviços do Firebase:

  • Indexadores e recuperados usando o armazenamento de vetores do Cloud Firestore
  • Armazenamento de traces usando o Cloud Firestore
  • Implantação de fluxo usando o Cloud Functions
  • Políticas de autorização para usuários do Firebase Authentication

Instalação

npm i --save @genkit-ai/firebase

Pré-requisitos

  • Todos os produtos do Firebase exigem um projeto do Firebase. É possível criar um novo projeto ou ativar o Firebase em um projeto atual do Google Cloud usando o Console do Firebase.
  • Além disso, se você quiser implantar fluxos no Cloud Functions, será necessário fazer upgrade do seu projeto para o plano de pagamento por utilização Blaze.

Configuração

Para usar esse plug-in, especifique-o ao chamar configureGenkit():

import {configureGenkit} from "@genkit-ai/core";
import {firebase} from "@genkit-ai/firebase";

configureGenkit({
  plugins: [firebase({projectId: "your-firebase-project"})],
});

O plug-in exige que você especifique o ID do projeto do Firebase. É possível especificar o ID do projeto do Firebase de uma das seguintes maneiras:

  • Defina projectId no objeto de configuração firebase().

  • Defina a variável de ambiente GCLOUD_PROJECT. Se você estiver executando seu fluxo em um ambiente do Google Cloud (Cloud Functions, Cloud Run e assim por diante), GCLOUD_PROJECT será definido automaticamente como o ID do projeto do ambiente.

    Se você definir GCLOUD_PROJECT, poderá omitir o parâmetro de configuração: firebase()

Para fornecer credenciais do Firebase, você também precisa configurar o Application Default Credentials do Google Cloud. Para especificar suas credenciais:

  • Se você estiver executando seu fluxo em um ambiente do Google Cloud (Cloud Functions, Cloud Run e assim por diante), isso será definido automaticamente.

  • Para outros ambientes:

    1. Gere credenciais da conta de serviço para seu projeto do Firebase e faça o download do arquivo de chave JSON. Faça isso na página Conta de serviço do Console do Firebase.
    2. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço.

Uso

Este plug-in oferece várias integrações com serviços do Firebase, que podem ser usadas em conjunto ou individualmente.

Armazenamento de vetores do Cloud Firestore

É possível usar o Cloud Firestore como um armazenamento de vetores para indexação e recuperação de RAG.

Esta seção contém informações específicas sobre o plug-in firebase e o recurso de pesquisa vetorial do Cloud Firestore. Consulte a página Geração aumentada de recuperação para ver uma discussão mais detalhada sobre a implementação de RAG usando o Genkit.

O plug-in firebase fornece uma função de conveniência para definir os coletores do Firestore, defineFirestoreRetriever():

import {defineFirestoreRetriever} from "@genkit-ai/firebase";
import {retrieve} from "@genkit-ai/ai/retriever";

import {initializeApp} from "firebase-admin/app";
import {getFirestore} from "firebase-admin/firestore";

const app = initializeApp();
const firestore = getFirestore(app);

const yourRetrieverRef = defineFirestoreRetriever({
  name: "yourRetriever",
  firestore: getFirestore(app),
  collection: "yourCollection",
  contentField: "yourDataChunks",
  vectorField: "embedding",
  embedder: textEmbeddingGecko, // Import from '@genkit-ai/googleai' or '@genkit-ai/vertexai'
  distanceMeasure: "COSINE", // "EUCLIDEAN", "DOT_PRODUCT", or "COSINE" (default)
});

Para usá-lo, transmita-o para a função retrieve():

const docs = await retrieve({
  retriever: yourRetrieverRef,
  query: "look for something",
  options: {limit: 5},
});

As opções de recuperação disponíveis incluem:

  • limit: especifica o número de resultados correspondentes a serem retornados.
  • where: pares de campo/valor a serem correspondidos (por exemplo, {category: 'food'}), além da pesquisa de vetor.
  • collection: substitui o conjunto padrão para pesquisar, por exemplo, pesquisa de subcoleções.

Para preencher sua coleção do Firestore, use um gerador de embedding com o SDK Admin. Por exemplo, o script de processamento de menu da página Geração aumentada de recuperação pode ser adaptado para o Firestore da seguinte maneira:

import { configureGenkit } from "@genkit-ai/core";
import { embed } from "@genkit-ai/ai/embedder";
import { defineFlow, run } from "@genkit-ai/flow";
import { textEmbeddingGecko, vertexAI } from "@genkit-ai/vertexai";

import { applicationDefault, initializeApp } from "firebase-admin/app";
import { FieldValue, getFirestore } from "firebase-admin/firestore";

import { chunk } from "llm-chunk";
import pdf from "pdf-parse";
import * as z from "zod";

import { readFile } from "fs/promises";
import path from "path";

// Change these values to match your Firestore config/schema
const indexConfig = {
  collection: "menuInfo",
  contentField: "text",
  vectorField: "embedding",
  embedder: textEmbeddingGecko,
};

configureGenkit({
  plugins: [vertexAI({ location: "us-central1" })],
  enableTracingAndMetrics: false,
});

const app = initializeApp({ credential: applicationDefault() });
const firestore = getFirestore(app);

export const indexMenu = defineFlow(
  {
    name: "indexMenu",
    inputSchema: z.string().describe("PDF file path"),
    outputSchema: z.void(),
  },
  async (filePath: string) => {
    filePath = path.resolve(filePath);

    // Read the PDF.
    const pdfTxt = await run("extract-text", () =>
      extractTextFromPdf(filePath)
    );

    // Divide the PDF text into segments.
    const chunks = await run("chunk-it", async () => chunk(pdfTxt));

    // Add chunks to the index.
    await run("index-chunks", async () => indexToFirestore(chunks));
  }
);

async function indexToFirestore(data: string[]) {
  for (const text of data) {
    const embedding = await embed({
      embedder: indexConfig.embedder,
      content: text,
    });
    await firestore.collection(indexConfig.collection).add({
      [indexConfig.vectorField]: FieldValue.vector(embedding),
      [indexConfig.contentField]: text,
    });
  }
}

async function extractTextFromPdf(filePath: string) {
  const pdfFile = path.resolve(filePath);
  const dataBuffer = await readFile(pdfFile);
  const data = await pdf(dataBuffer);
  return data.text;
}

O Firestore depende de índices para fornecer consultas rápidas e eficientes em coleções. Observe que "índice" aqui se refere aos índices do banco de dados, e não às abstrações do indexador e do retriever do Genkit.

O exemplo anterior exige que o campo embedding seja indexado para funcionar. Para criar o índice:

  • Execute o comando gcloud descrito na seção Criar um índice vetorial de campo único dos documentos do Firestore.

    O comando se parece com isto:

    gcloud alpha firestore indexes composite create --project=your-project-id \
  --collection-group=yourCollectionName --query-scope=COLLECTION \
  --field-config=vector-config='{"dimension":"768","flat": "{}"}',field-path=yourEmbeddingField

    No entanto, a configuração de indexação correta depende das consultas que serão feitas e do modelo de incorporação que você está usando.

  • Se preferir, chame retrieve(), e o Firestore vai gerar um erro com o comando correto para criar o índice.

Saiba mais

Armazenamento de traces do Cloud Firestore

Use o Cloud Firestore para armazenar traces:

import {firebase} from "@genkit-ai/firebase";

configureGenkit({
  plugins: [firebase()],
  traceStore: "firebase",
  enableTracingAndMetrics: true,
});

Por padrão, o plug-in armazena traces em uma coleção chamada genkit-traces no banco de dados padrão do projeto. Para mudar uma das configurações:

firebase({
  traceStore: {
    collection: "your-collection";
    databaseId: "your-db";
  }
})

Ao usar o armazenamento de traces baseado no Firestore, ative o TTL para os documentos de trace: https://firebase.google.com/docs/firestore/ttl

Cloud Functions

O plug-in fornece o construtor onFlow(), que cria um fluxo com o apoio de uma função acionada por HTTPS do Cloud Functions para Firebase. Essas funções estão em conformidade com a interface de função chamável do Firebase, e é possível usar os SDKs de cliente do Cloud Functions para chamá-las.

import {firebase} from "@genkit-ai/firebase";
import {onFlow, noAuth} from "@genkit-ai/firebase/functions";

configureGenkit({
  plugins: [firebase()],
});

export const exampleFlow = onFlow(
  {
    name: "exampleFlow",
    authPolicy: noAuth(), // WARNING: noAuth() creates an open endpoint!
  },
  async (prompt) => {
    // Flow logic goes here.

    return response;
  }
);

Implante seu fluxo usando a CLI do Firebase:

firebase deploy --only functions

A função onFlow() tem algumas opções que não estão presentes em defineFlow():

  • httpsOptions: um objeto HttpsOptions usado para configurar a função do Cloud: js export const exampleFlow = onFlow( { name: "exampleFlow", httpsOptions: { cors: true, }, // ... }, async (prompt) => { // ... } );

  • enforceAppCheck: quando true, rejeitar solicitações com tokens do App Check inválidos ou ausentes.

  • consumeAppCheckToken: quando true, invalida o token do App Check depois de verificá-lo.

    Consulte Proteção contra repetição.

Firebase Auth

Este plug-in oferece uma função auxiliar para criar políticas de autorização com base no Firebase Auth:

import {firebaseAuth} from "@genkit-ai/firebase/auth";

export const exampleFlow = onFlow(
  {
    name: "exampleFlow",
    authPolicy: firebaseAuth((user) => {
      if (!user.email_verified) throw new Error("Requires verification!");
    }),
  },
  async (prompt) => {
    // ...
  }
);

Para definir uma política de autenticação, forneça a firebaseAuth() uma função de callback que use um DecodedIdToken como único parâmetro. Nessa função, examine o token do usuário e gere um erro se o usuário não atender a algum dos critérios que você quer exigir.

Consulte Autorização e integridade para uma discussão mais completa sobre esse tópico.