El complemento de Firebase proporciona varias integraciones con los servicios de Firebase:
- Indexadores y recuperadores que usan el almacén de vectores de Cloud Firestore
- Haz un seguimiento del almacenamiento con Cloud Firestore
- Implementación de flujos con Cloud Functions
- Políticas de autorización para los usuarios de Firebase Authentication
Instalación
npm i --save @genkit-ai/firebase
Requisitos previos
- Todos los productos de Firebase requieren un proyecto de Firebase. Puedes crear un proyecto nuevo o habilitar Firebase en un proyecto existente de Google Cloud con Firebase console.
- Además, si quieres implementar flujos en Cloud Functions, debes actualizar tu proyecto al plan Blaze (prepago).
Configuración
Para usar este complemento, especifícalo cuando llames a configureGenkit()
:
import {configureGenkit} from "@genkit-ai/core";
import {firebase} from "@genkit-ai/firebase";
configureGenkit({
plugins: [firebase({projectId: "your-firebase-project"})],
});
El complemento requiere que especifiques el ID de tu proyecto de Firebase. Puedes especificar el ID del proyecto de Firebase de cualquiera de las siguientes maneras:
Configura
projectId
en el objeto de configuraciónfirebase()
.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 configura de forma automática en el ID del proyecto del entorno.Si configuras
GCLOUD_PROJECT
, puedes omitir el parámetro de configuración:firebase()
.
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.), se configura de forma automática.
Para otros entornos:
- 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.
- Establece la variable de entorno
GOOGLE_APPLICATION_CREDENTIALS
en la ruta de acceso del archivo JSON que contiene la clave de tu cuenta de servicio.
Uso
Este complemento proporciona varias integraciones con los servicios de Firebase, que puedes usar en conjunto o de forma individual.
Almacén de vectores de Cloud Firestore
Puedes usar Cloud Firestore como almacén de vectores para la indexación y recuperación RAG.
En esta sección, se incluye información específica del complemento firebase
y de la función de búsqueda de vectores de Cloud Firestore.
Consulta la página de generación de recuperación aumentada para ver un análisis más detallado sobre la implementación de RAG con Genkit.
El complemento firebase
proporciona una función conveniente para definir los recuperadores de 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 usarlo, pásalo a la función retrieve()
:
const docs = await retrieve({
retriever: yourRetrieverRef,
query: "look for something",
options: {limit: 5},
});
Las opciones de recuperación disponibles incluyen las siguientes:
limit
: Especifica la cantidad de resultados coincidentes que se mostrarán.where
: Pares de campo/valor que deben coincidir (p.ej.,{category: 'food'}
) además de la búsqueda de vectores.collection
: Anula la colección predeterminada para buscar, p.ej., la búsqueda de subcolecciones.
Para propagar la 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ú de la página de generación aumentada de recuperación podría adaptarse a Firestore de la siguiente manera:
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;
}
Firestore depende de los índices para proporcionar consultas rápidas y eficientes en las colecciones. (Ten en cuenta que, en este caso, “índice” hace referencia a índices de bases de datos y no a abstracciones de indexador y retriever de Genkit).
El ejemplo anterior requiere que se indexe el campo embedding
para que funcione. Para crear el índice, sigue estos pasos:
Ejecuta el comando
gcloud
que se describe en la sección Crea un índice vectorial de campo único de los documentos 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
retrieve()
y Firestore arrojará un error con el comando correcto para crear el índice.
Más información
- Consulta la página de generación aumentada de recuperación para ver un análisis general sobre los indexadores y los retrievers en Genkit.
- Consulta Busca con incorporaciones de vectores en los documentos de Cloud Firestore para obtener más información sobre la función de búsqueda de vectores.
Almacenamiento de seguimiento de Cloud Firestore
Puedes usar Cloud Firestore para almacenar seguimientos:
import {firebase} from "@genkit-ai/firebase";
configureGenkit({
plugins: [firebase()],
traceStore: "firebase",
enableTracingAndMetrics: true,
});
De forma predeterminada, el complemento almacena seguimientos en una colección llamada genkit-traces
en la base de datos predeterminada del proyecto. Para cambiar cualquiera de las opciones, sigue estos pasos:
firebase({
traceStore: {
collection: "your-collection";
databaseId: "your-db";
}
})
Cuando uses el almacenamiento de seguimientos basado en Firestore, deberás habilitar el TTL para los documentos de seguimiento: https://firebase.google.com/docs/firestore/ttl
Cloud Functions
El complemento proporciona el constructor onFlow()
, que crea un flujo respaldado por una
función activada por HTTPS de Cloud Functions para Firebase. Estas funciones cumplen
con la
interfaz de las funciones que admiten llamadas de Firebase y puedes usar los
SDKs cliente de Cloud Functions
para llamarlas.
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;
}
);
Implementa tu flujo con Firebase CLI:
firebase deploy --only functions
La función onFlow()
tiene algunas opciones que no están presentes en defineFlow()
:
httpsOptions
: Un objetoHttpsOptions
que se usa para configurar la función de Cloud Functions:js export const exampleFlow = onFlow( { name: "exampleFlow", httpsOptions: { cors: true, }, // ... }, async (prompt) => { // ... } );
enforceAppCheck
: Cuando estrue
, rechaza las solicitudes con tokens de la Verificación de aplicaciones que falten o no sean válidos.consumeAppCheckToken
: Cuando estrue
, invalida el token de la Verificación de aplicaciones después de verificarlo.Consulta Protección contra la repetición.
Firebase Auth
Este complemento proporciona una función auxiliar para crear políticas de autorización en 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 una política de autenticación, proporciona a firebaseAuth()
una función de devolución de llamada que
tome DecodedIdToken
como único parámetro. En esta función, examina el token de usuario y arroja un
error si el usuario no cumple con alguno de los criterios que quieres exigir.
Consulta Integridad y autorización para obtener un análisis más detallado de este tema.