Complemento de Firebase

El complemento de Firebase proporciona integraciones con los servicios de Firebase, de modo que puedas compilar aplicaciones de IA inteligentes y escalables. Las funciones clave incluyen las siguientes:

  • Firestore Vector Store: Usa Firestore para la indexación y recuperación con incorporaciones de vectores.
  • Telemetría: Exporta la telemetría a Google Cloud's operations suite, que potencia la consola de supervisión de Firebase Genkit.

Instalación

Instala el complemento de Firebase con npm:

npm install @genkit-ai/firebase

Requisitos previos

Configuración del proyecto de Firebase

  1. Todos los productos de Firebase requieren un proyecto de Firebase. Puedes crear un proyecto nuevo o habilitar Firebase en un proyecto de Google Cloud existente con Firebase console.
  2. Si implementas flujos con Cloud Functions, actualiza tu proyecto de Firebase al plan Blaze.
  3. Si quieres ejecutar código de forma local que exporte la telemetría, debes tener instalada la herramienta Google Cloud CLI.

Inicialización del SDK de Firebase Admin

Debes inicializar el SDK de Firebase Admin en tu aplicación. El complemento no controla esto automáticamente.

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

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

El complemento requiere que especifiques el ID de tu proyecto de Firebase. Puedes especificar el ID de tu proyecto de Firebase de las siguientes maneras:

  • Establece projectId en el objeto de configuración initializeApp() como se muestra en el fragmento anterior.

  • Configura la variable de entorno GCLOUD_PROJECT. Si ejecutas tu flujo desde un entorno de Google Cloud (Cloud Functions, Cloud Run, etc.), GCLOUD_PROJECT se establece automáticamente en el ID del proyecto del entorno.

    Si configuras GCLOUD_PROJECT, puedes omitir el parámetro de configuración en initializeApp().

Credenciales

Para proporcionar credenciales de Firebase, también debes configurar las credenciales predeterminadas de la aplicación de Google Cloud. Para especificar tus credenciales, haz lo siguiente:

  • Si ejecutas tu flujo desde un entorno de Google Cloud (Cloud Functions, Cloud Run, etc.), esto se configura automáticamente.

  • Para otros entornos, haz lo siguiente:

    1. Genera credenciales de cuenta de servicio para tu proyecto de Firebase y descarga el archivo de claves JSON. Puedes hacerlo en la página Cuenta de servicio de Firebase console.
    2. Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta del archivo JSON que contiene la clave de tu cuenta de servicio, o bien puedes configurar la variable de entorno GCLOUD_SERVICE_ACCOUNT_CREDS en el contenido del archivo JSON.

Funciones y uso

Telemetría

La supervisión de Firebase Genkit se basa en Google Cloud's operations suite. Para ello, las APIs relacionadas con la telemetría deben estar habilitadas en tu proyecto. Consulta la documentación del complemento de Google Cloud para obtener más detalles.

Otorga los siguientes roles a la "Cuenta de servicio de Compute predeterminada" en la consola de Google Cloud IAM:

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

Para habilitar la exportación de telemetría, llama a enableFirebaseTelemetry():

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

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

Este complemento comparte opciones de configuración con el complemento de Google Cloud.

Puedes usar Cloud Firestore como un almacén de vectores para el indexado y la recuperación de RAG.

En esta sección, se incluye información específica del complemento firebase y la función de búsqueda vectorial de Cloud Firestore. Consulta la página de generación mejorada de recuperación para ver un debate más detallado sobre la implementación de RAG con Genkit.

Usa GCLOUD_SERVICE_ACCOUNT_CREDS y Firestore

Si usas credenciales de cuenta de servicio pasando credenciales directamente a través de GCLOUD_SERVICE_ACCOUNT_CREDS y también usas Firestore como un almacén de vectores, debes pasar las credenciales directamente a la instancia de Firestore durante la inicialización, o bien el singleton se puede inicializar con las credenciales predeterminadas de la aplicación según el orden de inicialización del complemento.

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

Define un recuperador de Firestore

Usa defineFirestoreRetriever() para crear un recuperador para las consultas basadas en vectores de 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'
});

Cómo recuperar documentos

Para recuperar documentos con el retriever definido, pasa la instancia del retriever y las opciones de consulta a 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
  },
});

Opciones de recuperación disponibles

Las siguientes opciones se pueden pasar al campo options en ai.retrieve:

  • limit: (número) Especifica la cantidad máxima de documentos que se recuperarán. El valor predeterminado es 10.

  • where: (Record<string, any>) Agrega filtros adicionales basados en campos de Firestore. Ejemplo:

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

  • collection: (cadena) Anula la colección predeterminada especificada en la configuración del recuperador.

  • Esto es útil para consultar subcolecciones o cambiar de una a otra de forma dinámica.

  • colecciones.

Cómo propagar Firestore con incorporaciones

Para propagar tu colección de Firestore, usa un generador de incorporaciones junto con el SDK de Admin. Por ejemplo, la secuencia de comandos de transferencia de menús de la página Generación con recuperación mejorada se podría adaptar para Firestore de la siguiente manera:

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

Firestore depende de los índices para proporcionar consultas rápidas y eficientes en colecciones. (Ten en cuenta que “índice” aquí se refiere a los índices de la base de datos y no a las abstracciones del indexador y el recuperador de Genkit).

El ejemplo anterior requiere que el campo embedding esté indexado para funcionar. Para crear el índice, sigue estos pasos:

  • Ejecuta el comando gcloud que se describe en la sección Cómo crear un índice vectorial de campo único de la documentación de Firestore.

    El comando se ve de la siguiente manera:

    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

    Sin embargo, la configuración de indexación correcta depende de las consultas que realices y del modelo de incorporación que uses.

  • Como alternativa, llama a ai.retrieve() y Firestore mostrará un error con el comando correcto para crear el índice.

Más información

Implementa flujos como Cloud Functions

Para implementar un flujo con Cloud Functions, usa la compatibilidad integrada de la biblioteca de Firebase Functions para genkit. El método onCallGenkit te permite crear una función que admite llamadas a partir de un flujo. Admite automáticamente las solicitudes de transmisión y JSON. Puedes usar los SDK de cliente de Cloud Functions para llamarlos.

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

Implementa tu flujo con Firebase CLI:

firebase deploy --only functions