Plugin Firebase

Plugin Firebase menyediakan beberapa integrasi dengan layanan Firebase:

  • Pengindeksan dan pengambilan menggunakan penyimpanan vektor Cloud Firestore
  • Mencatat penyimpanan menggunakan Cloud Firestore
  • Deployment alur menggunakan Cloud Functions
  • Kebijakan otorisasi untuk pengguna Firebase Authentication
  • Ekspor telemetri ke Google Cloud Operations Suite

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 alur ke Cloud Functions, Anda harus mengupgrade project ke paket Blaze bayar sesuai penggunaan.
  • Jika ingin menjalankan kode secara lokal yang mengekspor telemetri, Anda perlu menginstal alat Google Cloud CLI.

Konfigurasi

Project ID

Untuk menggunakan plugin ini, tentukan saat Anda menginisialisasi Genkit:

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

const ai = genkit({
  plugins: [firebase({ projectId: "your-firebase-project" })],
});

Plugin ini mengharuskan Anda menentukan project ID Firebase. Anda dapat menentukan project ID Firebase 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 akan otomatis ditetapkan ke project ID lingkungan.

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

Kredensial

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

  • Jika Anda menjalankan flow dari lingkungan Google Cloud (Cloud Functions, Cloud Run, dan sebagainya), kredensial tersebut ditetapkan secara otomatis.

  • Untuk lingkungan lain:

    1. Buat kredensial akun layanan untuk project Firebase Anda dan download file kunci JSON. Anda dapat melakukannya di halaman Akun layanan di Firebase console.
    2. Tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur file JSON yang berisi kunci akun layanan Anda, 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 ketentuan untuk mengaktifkan ekspor telemetri ke Google Cloud Operations Suite. Untuk mengaktifkan ekspor telemetri, panggil enableFirebaseTelemetry():

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

enableFirebaseTelemetry();

Lihat dokumentasi plugin Google Cloud untuk semua opsi konfigurasi dan API yang diperlukan yang perlu diaktifkan di project.

Penggunaan

Plugin ini menyediakan beberapa integrasi dengan layanan Firebase, yang dapat Anda gunakan secara bersamaan atau terpisah.

Penyimpanan vektor Cloud Firestore

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

Bagian ini berisi informasi khusus untuk plugin firebase dan fitur penelusuran vektor Cloud Firestore. Lihat halaman Retrieval-augmented generation untuk mengetahui diskusi yang lebih mendetail tentang cara menerapkan 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 pengambil 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)
});

Untuk menggunakannya, teruskan ke fungsi ai.retrieve():

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

Opsi pengambilan yang tersedia mencakup:

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

Pengindeksan dan Penyematan

Untuk mengisi koleksi Firestore, gunakan generator penyematan bersama dengan Admin SDK. Misalnya, skrip penyerapan menu dari halaman Pembuatan yang dilengkapi pengambilan dapat disesuaikan untuk Firestore dengan cara berikut:

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

Firestore bergantung pada indeks untuk memberikan kueri yang cepat dan efisien pada koleksi. (Perhatikan bahwa "indeks" di sini mengacu pada indeks database, bukan abstraksi pengindeksan dan pengambilan Genkit.)

Contoh sebelumnya mengharuskan kolom embedding diindeks agar dapat berfungsi. Untuk membuat indeks:

  • Jalankan perintah gcloud yang dijelaskan di bagian Membuat indeks vektor kolom tunggal dalam dokumen 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 Anda buat dan model penyematan yang Anda gunakan.

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

Pelajari lebih lanjut

Cloud Functions

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

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

Deploy alur Anda menggunakan Firebase CLI:

firebase deploy --only functions

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

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

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

  • enforceAppCheck: jika true, tolak permintaan dengan token App Check yang tidak ada atau tidak valid.

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

    Lihat Perlindungan replay.

Firebase Auth

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

Untuk menentukan kebijakan autentikasi, berikan firebaseAuth() dengan fungsi callback yang menggunakan DecodedIdToken sebagai parameter satu-satunya. Dalam fungsi ini, periksa token pengguna dan tampilkan error jika pengguna gagal memenuhi salah satu kriteria yang ingin Anda tetapkan.

Lihat Otorisasi dan integritas untuk pembahasan topik ini secara lebih menyeluruh.