Plug-in do Firebase

O plug-in do Firebase oferece integrações com os serviços do Firebase, permitindo que você crie aplicativos de IA inteligentes e escalonáveis. Os principais recursos incluem:

  • Firestore Vector Store: use o Firestore para indexação e recuperação com embeddings de vetor.
  • Cloud Functions: implante fluxos como funções acionadas por HTTPS.
  • Firebase Authentication: implemente políticas de autorização.
  • Telemetria: exporte a telemetria para o pacote de operações do Google Cloud e confira visualizações especializadas no console do Firebase

Instalação

Instale o plug-in do Firebase com o npm:

npm install @genkit-ai/firebase

Pré-requisitos

Configuração do projeto do Firebase

  1. 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.
  2. Se você estiver implantando fluxos com o Cloud Functions, faça upgrade do seu projeto do Firebase para o plano Blaze.
  3. Se você quiser executar localmente um código que exporta a telemetria, instale a ferramenta Google Cloud CLI.

Inicialização do SDK Admin do Firebase

É necessário inicializar o SDK Admin do Firebase no seu aplicativo. Isso não é gerenciado automaticamente pelo plug-in.

import { initializeApp } from 'firebase-admin/app';

initializeApp({
  projectId: 'your-project-id',
});

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 initializeApp(), conforme mostrado no snippet acima.

  • 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 em initializeApp().

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.

Recursos e uso

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.

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

Definir um recuperador do Firestore

Use defineFirestoreRetriever() para criar um recuperador para consultas baseadas em vetor do Firestore.

import { defineFirestoreRetriever } from '@genkit-ai/firebase';
import { initializeApp } from 'firebase-admin/app';
import { getFirestore } from 'firebase-admin/firestore';

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

const retriever = defineFirestoreRetriever(ai, {
  name: 'exampleRetriever',
  firestore,
  collection: 'documents',
  contentField: 'text', // Field containing document content
  vectorField: 'embedding', // Field containing vector embeddings
  embedder: yourEmbedderInstance, // Embedder to generate embeddings
  distanceMeasure: 'COSINE', // Default is 'COSINE'; other options: 'EUCLIDEAN', 'DOT_PRODUCT'
});

Recuperar documentos

Para recuperar documentos usando o extrator definido, transmita a instância do extrator e as opções de consulta para ai.retrieve.

const docs = await ai.retrieve({
  retriever,
  query: 'search query',
  options: {
    limit: 5, // Options: Return up to 5 documents
    where: { category: 'example' }, // Optional: Filter by field-value pairs
    collection: 'alternativeCollection', // Optional: Override default collection
  },
});

Opções de recuperação disponíveis

As opções a seguir podem ser transmitidas para o campo options em ai.retrieve:

  • limit: (número)
    especifica o número máximo de documentos a serem recuperados. O padrão é 10.

  • where: (Record<string, any>)
    Adicione outros filtros com base nos campos do Firestore. Exemplo:

    where: { category: 'news', status: 'published' }

  • collection: (string)
    substitua a coleção padrão especificada na configuração do retriever. Isso é útil para consultar subcoleções ou alternar dinamicamente entre coleções.

Preencher o Firestore com incorporações

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, não a abstrações de indexador e recuperador 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 da 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

Implantar fluxos como funções do Cloud

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, rejeitar 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 Authentication

Esse plug-in fornece 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.