Plug-in do Firebase

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

  • Indexadores e extratores que usam a loja de vetores do Cloud Firestore
  • Armazenamento de rastros usando o Cloud Firestore
  • Implantação de fluxos usando o Cloud Functions
  • Políticas de autorização para usuários do Firebase Authentication
  • Exportação de telemetria para o pacote de operações do Google Cloud

Instalação

npm i --save @genkit-ai/firebase

Pré-requisitos

  • Todos os produtos do Firebase exigem um projeto do Firebase. Você pode criar um novo projeto ou ativar o Firebase em um projeto do Google Cloud usando o console do Firebase.
  • Além disso, se você quiser implantar fluxos no Cloud Functions, é necessário fazer upgrade do seu projeto para o plano Blaze de pagamento por uso.
  • Se você quiser executar localmente um código que exporta a telemetria, instale a ferramenta Google Cloud CLI.

Configuração

ID do projeto

Para usar esse plug-in, especifique-o ao inicializar o Genkit:

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

const ai = genkit({
  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 duas 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 etc.), o 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()

Credenciais

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 outros), isso é 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. Para fazer isso, acesse a 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 ou defina a variável de ambiente GCLOUD_SERVICE_ACCOUNT_CREDS como o conteúdo do arquivo JSON.

Telemetria

O plug-in tem uma dependência direta do plug-in do Google Cloud e, portanto, tem disposições para ativar a exportação de telemetria para o pacote de operações do Google Cloud. Para ativar a exportação de telemetria, chame enableFirebaseTelemetry():

import { enableFirebaseTelemetry } from '@genkit-ai/firebase';

enableFirebaseTelemetry();

Consulte a documentação do plug-in do Google Cloud para conferir todas as opções de configuração e as APIs necessárias que precisam ser ativadas no projeto.

Uso

Esse plug-in oferece várias integrações com os serviços do Firebase, que podem ser usados juntos ou individualmente.

Loja de vetores do Cloud Firestore

É possível usar o Cloud Firestore como uma loja 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 de vetor do Cloud Firestore. Consulte a página Geração aumentada de recuperação para uma discussão mais detalhada sobre a implementação da RAG usando o Genkit.

Como usar GCLOUD_SERVICE_ACCOUNT_CREDS e o Firestore

Se você estiver usando credenciais da conta de serviço transmitindo-as diretamente pelo GCLOUD_SERVICE_ACCOUNT_CREDS e também estiver usando o Firestore como uma loja de vetores, será necessário transmitir credenciais diretamente para a instância do Firestore durante a inicialização. Caso contrário, o singleton poderá ser inicializado com as credenciais padrão do aplicativo, dependendo da ordem de inicialização do plug-in.

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

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

if (process.env.GCLOUD_SERVICE_ACCOUNT_CREDS) {
  const serviceAccountCreds = JSON.parse(process.env.GCLOUD_SERVICE_ACCOUNT_CREDS);
  const authOptions = { credentials: serviceAccountCreds };
  firestore.settings(authOptions);
}

Recuperadores

O plug-in firebase fornece uma função conveniente para definir os extratores 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 ai.retrieve():

const docs = await ai.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 vetorial.
  • collection: substitui a coleção padrão para pesquisar, por exemplo, a pesquisa de subcoleções.

Indexação e incorporação

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

import { genkit } from 'genkit';
import { vertexAI, textEmbedding004 } 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 { 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: textEmbedding004,
};

const ai = genkit({
  plugins: [vertexAI({ location: "us-central1" })],
});

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

export async function indexMenu(filePath: string) {
  filePath = path.resolve(filePath);

  // Read the PDF.
  const pdfTxt = await extractTextFromPdf(filePath);

  // Divide the PDF text into segments.
  const chunks = await chunk(pdfTxt);

  // Add chunks to the index.
  await indexToFirestore(chunks);
}

async function indexToFirestore(data: string[]) {
  for (const text of data) {
    const embedding = await ai.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 nas coleções. "Índice" aqui se refere a índices de banco de dados, e não às abstrações de indexador e 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 de vetor 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 correta de indexação depende das consultas que você vai fazer e do modelo de incorporação que está usando.

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

Saiba mais

Cloud Functions

O plug-in fornece o construtor onFlow(), que cria um fluxo com suporte 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 você pode usar os SDKs de cliente do Cloud Functions para chamá-las.

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

export const exampleFlow = onFlow(
  ai, // Provide the Genkit instance
  {
    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 o Cloud Function:

    export const exampleFlow = onFlow(
  ai,
  {
    name: "exampleFlow",
    httpsOptions: {
      cors: true,
    },
    // ...
  },
  async (prompt) => {
    // ...
  }
);

  • enforceAppCheck: quando true, rejeita solicitações com tokens de verificação de app ausentes ou inválidos.

  • consumeAppCheckToken: quando true, invalida o token do App Check após a verificação.

    Consulte Proteção contra repetição.

Firebase Auth

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

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

export const exampleFlow = onFlow(
  ai,
  {
    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 firebaseAuth() com 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 nenhum dos critérios que você quer exigir.

Consulte Autorização e integridade para uma discussão mais detalhada sobre o assunto.