Plug-in do Firebase

O plug-in do Firebase oferece integrações com os serviços do Firebase para que você possa criar 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.
  • Telemetria: exporte telemetria para o pacote de operações do Google Cloud que alimenta o console de monitoramento do Firebase Genkit.

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 as funções do Cloud, 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 monitoramento do Firebase Genkit é feito pelo pacote de operações do Cloud do Google. Isso exige que as APIs relacionadas à telemetria sejam ativadas no projeto. Consulte a documentação do plug-in do Google Cloud para mais detalhes.

Conceda os seguintes papéis à "Conta de serviço padrão do Compute" no console do Google Cloud IAM:

  • Gravador de métricas do Monitoring (roles/monitoring.metricWriter)
  • Agente do Cloud Trace (roles/cloudtrace.agent)
  • Gravador de registros (roles/logging.logWriter)

Para ativar a exportação de telemetria, chame enableFirebaseTelemetry():

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

enableFirebaseTelemetry({
  forceDevExport: false, // Set this to true to export telemetry for local runs
});

Esse plug-in compartilha opções de configuração com o plug-in do Google Cloud.

É 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 por GCLOUD_SERVICE_ACCOUNT_CREDS e também estiver usando o Firestore como uma loja vetorial, 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 retriever do Firestore

Use defineFirestoreRetriever() para criar um retriever 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) substitui a coleção padrão especificada na configuração do extrator.

  • 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 ingestão 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,
    }))[0].embedding;
    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 extrator 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ê faz e do modelo de embedding 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

Para implantar um fluxo com o Cloud Functions, use o suporte integrado do genkit para a biblioteca do Firebase Functions. O método onCallGenkit permite criar uma função chamável em um fluxo. Ele oferece suporte automático a transmissões e solicitações JSON. É possível usar os SDKs do cliente do Cloud Functions para fazer isso.

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

export const exampleFlow = ai.defineFlow({
  name: "exampleFlow",
}, async (prompt) => {
    // Flow logic goes here.

    return response;
  }
);

// WARNING: This has no authentication or app check protections.
// See github.com/firebase/genkit/blob/main/docs/auth.md for more information.
export const example = onCallGenkit({ secrets: [apiKey] }, exampleFlow);

Implante o fluxo usando a CLI do Firebase:

firebase deploy --only functions