Plugin Firebase

Plugin Firebase menyediakan beberapa integrasi dengan layanan Firebase:

  • Pengindeks dan pengambil yang menggunakan penyimpanan vektor Cloud Firestore
  • Melacak penyimpanan menggunakan Cloud Firestore
  • Deployment alur menggunakan Cloud Functions
  • Kebijakan otorisasi untuk pengguna Firebase Authentication

Penginstalan

npm i --save @genkit-ai/firebase

Prasyarat

  • Semua produk Firebase memerlukan project Firebase. Anda dapat membuat project baru atau mengaktifkan Firebase di project Google Cloud yang ada menggunakan Firebase console.
  • Selain itu, jika ingin men-deploy flow ke Cloud Functions, Anda harus mengupgrade project Anda ke paket Blaze bayar sesuai penggunaan.

Konfigurasi

Project ID

Untuk menggunakan plugin ini, tentukan saat Anda memanggil configureGenkit():

import {configureGenkit} from "@genkit-ai/core";
import {firebase} from "@genkit-ai/firebase";

configureGenkit({
  plugins: [firebase({projectId: "your-firebase-project"})],
});

Plugin ini mengharuskan Anda menentukan project ID Firebase. Anda dapat menentukan project ID Firebase Anda dengan salah satu cara berikut:

  • Tetapkan projectId di objek konfigurasi firebase().

  • Menetapkan variabel lingkungan GCLOUD_PROJECT. Jika Anda menjalankan flow dari lingkungan Google Cloud (Cloud Functions, Cloud Run, dan sebagainya), GCLOUD_PROJECT secara otomatis ditetapkan ke project ID lingkungan.

    Jika menetapkan GCLOUD_PROJECT, Anda dapat menghapus parameter konfigurasi: firebase()

Kredensial

Untuk memberikan kredensial Firebase, Anda juga perlu menyiapkan Google Cloud Kredensial Default Aplikasi. Untuk menentukan kredensial Anda:

  • Jika Anda menjalankan alur dari lingkungan Google Cloud (Cloud Functions, Cloud Run, dan sebagainya), setelan ini diatur secara otomatis.

  • Untuk lingkungan lainnya:

    1. Buat kredensial akun layanan untuk project Firebase Anda dan download file kunci JSON. Anda dapat melakukannya di Akun layanan halaman Firebase console.
    2. Tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke file jalur file JSON yang berisi kunci akun layanan, atau Anda dapat menetapkan variabel lingkungan GCLOUD_SERVICE_ACCOUNT_CREDS ke konten file JSON.

Telemetri

Plugin ini memiliki dependensi langsung pada plugin Google Cloud, sehingga memiliki penyediaan untuk mengaktifkan ekspor telemetri ke Google Cloud Operations Suite. Untuk mengaktifkan ekspor telemetri, tetapkan enableTracingAndMetrics ke true dan tambahkan bagian telemetri ke konfigurasi Genkit:

import {configureGenkit} from "@genkit-ai/core";
import {firebase} from "@genkit-ai/firebase";

configureGenkit({
  plugins: [firebase()],
  enableTracingAndMetrics: true,
  telemetry: {
    instrumentation: 'firebase',
    logger: 'firebase',
  },
});

Lihat dokumentasi plugin Google Cloud untuk mengetahui semua opsi konfigurasi dan API yang diperlukan yang harus diaktifkan pada project.

Penggunaan

Plugin ini menyediakan beberapa integrasi dengan layanan Firebase, yang dapat Anda gunakan bersama-sama atau satu per satu.

Penyimpanan vektor Cloud Firestore

Anda dapat menggunakan Cloud Firestore sebagai penyimpanan vektor untuk pengindeksan dan pengambilan RAG.

Bagian ini berisi informasi khusus tentang plugin firebase dan Cloud Fitur penelusuran vektor Firestore. Lihat halaman Pembuatan yang ditingkatkan untuk detail yang lebih mendetail diskusi tentang penerapan RAG menggunakan Genkit.

Menggunakan GCLOUD_SERVICE_ACCOUNT_CREDS dan Firestore

Jika menggunakan kredensial akun layanan dengan meneruskan kredensial langsung melalui GCLOUD_SERVICE_ACCOUNT_CREDS dan juga menggunakan Firestore sebagai penyimpanan vektor, Anda harus meneruskan kredensial langsung ke instance Firestore selama inisialisasi atau singleton dapat diinisialisasi dengan kredensial default aplikasi, bergantung pada urutan inisialisasi plugin.

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

Retriever

Plugin firebase menyediakan fungsi praktis untuk menentukan Firestore pengambil, 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)
});

Untuk menggunakannya, teruskan ke fungsi retrieve():

const docs = await retrieve({
  retriever: yourRetrieverRef,
  query: "look for something",
  options: {limit: 5},
});

Opsi pengambilan yang tersedia meliputi:

  • limit: Menentukan jumlah hasil yang cocok yang akan ditampilkan.
  • where: Pasangan kolom/nilai yang akan dicocokkan (misalnya, {category: 'food'}) selain penelusuran vektor.
  • collection: Mengganti koleksi default untuk menelusuri mis. penelusuran subkoleksi.

Pengindeksan dan Penyematan

Untuk mengisi koleksi Firestore Anda, gunakan generator penyematan bersama dengan Admin SDK. Misalnya, skrip penyerapan menu dari Halaman Pembuatan hasil yang ditingkatkan dapat diadaptasi untuk Firestore dengan cara berikut:

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 bergantung pada indeks untuk menyediakan kueri yang cepat dan efisien koleksi baru. (Perhatikan bahwa "indeks" di sini mengacu pada indeks database, dan bukan abstraksi pengindeks dan retriever Genkit.)

Contoh sebelumnya mengharuskan kolom embedding diindeks ke Anda. Untuk membuat indeks:

  • Menjalankan perintah gcloud yang dijelaskan dalam Membuat indeks vektor kolom tunggal pada dokumentasi Firestore.

    Perintahnya terlihat seperti berikut:

    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

    Namun, konfigurasi pengindeksan yang benar bergantung pada kueri yang akan buat dan model embedding yang Anda gunakan.

  • Atau, panggil retrieve() dan Firestore akan menampilkan error dengan perintah yang benar untuk membuat indeks.

Pelajari lebih lanjut

Penyimpanan rekaman aktivitas Cloud Firestore

Anda dapat menggunakan Cloud Firestore untuk menyimpan rekaman aktivitas:

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

configureGenkit({
  plugins: [firebase()],
  traceStore: "firebase",
  enableTracingAndMetrics: true,
});

Secara default, plugin menyimpan rekaman aktivitas dalam koleksi yang disebut genkit-traces di dari database default project. Untuk mengubah salah satu setelan:

firebase({
  traceStore: {
    collection: "your-collection";
    databaseId: "your-db";
  }
})

Saat menggunakan penyimpanan trace berbasis Firestore, Anda perlu mengaktifkan TTL untuk dokumen trace: https://firebase.google.com/docs/firestore/ttl

Cloud Functions

Plugin ini menyediakan konstruktor onFlow(), yang membuat alur yang didukung oleh Fungsi yang dipicu HTTPS Cloud Functions for Firebase. Fungsi-fungsi ini sesuai ke Firebase antarmuka fungsi callable dan Anda dapat menggunakan SDK klien Cloud Functions memanggil mereka.

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

Deploy alur Anda menggunakan Firebase CLI:

firebase deploy --only functions

Fungsi onFlow() memiliki beberapa opsi yang tidak ada di defineFlow():

  • httpsOptions: HttpsOptions yang digunakan untuk mengonfigurasi Cloud Function Anda:

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

  • enforceAppCheck: jika true, tolak permintaan yang tidak memiliki App Check token kata.

  • consumeAppCheckToken: saat true, batalkan token App Check setelah memverifikasinya.

    Baca Perlindungan replay.

Firebase Auth

Plugin ini menyediakan fungsi bantuan untuk membuat kebijakan otorisasi terkait 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) => {
    // ...
  }
);

Untuk menentukan kebijakan autentikasi, berikan firebaseAuth() dengan fungsi callback yang mengambil DecodedIdToken sebagai satu-satunya parameter. Dalam fungsi ini, periksa token pengguna dan tampilkan {i>error<i} jika pengguna gagal memenuhi kriteria yang Anda inginkan.

Lihat Otorisasi dan integritas untuk diskusi yang lebih menyeluruh tentang topik ini.