Plugin Firebase

Plugin Firebase menyediakan integrasi dengan layanan Firebase, sehingga Anda dapat membangun aplikasi AI yang cerdas dan skalabel. Fitur utama meliputi:

  • Firestore Vector Store: Gunakan Firestore untuk pengindeksan dan pengambilan dengan penyematan vektor.
  • Telemetri: Mengekspor telemetri ke Google Cloud Operations Suite yang mendukung konsol Monitoring Firebase Genkit.

Penginstalan

Instal plugin Firebase dengan npm:

npm install @genkit-ai/firebase

Prasyarat

Penyiapan Project Firebase

  1. Semua produk Firebase memerlukan project Firebase. Anda dapat membuat project baru atau mengaktifkan Firebase di project Google Cloud yang ada menggunakan Firebase console.
  2. Jika men-deploy alur dengan Cloud Functions, upgrade project Firebase Anda ke paket Blaze.
  3. Jika ingin menjalankan kode secara lokal yang mengekspor telemetri, Anda perlu menginstal alat Google Cloud CLI.

Inisialisasi Firebase Admin SDK

Anda harus melakukan inisialisasi Firebase Admin SDK di aplikasi. Hal ini tidak ditangani secara otomatis oleh plugin.

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

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

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

  • Tetapkan projectId dalam objek konfigurasi initializeApp() seperti yang ditunjukkan dalam cuplikan di atas.

  • 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 di initializeApp().

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.

Fitur dan penggunaan

Telemetri

Pemantauan Firebase Genkit didukung oleh Google Cloud Operations Suite. Hal ini memerlukan API terkait telemetri untuk diaktifkan untuk project Anda. Silakan baca dokumentasi plugin Google Cloud untuk mengetahui detail selengkapnya.

Berikan peran berikut ke "Default compute service account" dalam Konsol IAM Google Cloud:

  • Monitoring Metric Writer (roles/monitoring.metricWriter)
  • Cloud Trace Agent (roles/cloudtrace.agent)
  • Logs Writer (roles/logging.logWriter)

Untuk mengaktifkan ekspor telemetri, panggil enableFirebaseTelemetry():

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

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

Plugin ini memiliki opsi konfigurasi yang sama dengan plugin Google Cloud.

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 secara langsung melalui GCLOUD_SERVICE_ACCOUNT_CREDS dan juga menggunakan Firestore sebagai penyimpanan vektor, Anda harus meneruskan kredensial secara 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);
}

Menentukan pengambil Firestore

Gunakan defineFirestoreRetriever() untuk membuat pengambil kueri berbasis vektor 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'
});

Mengambil dokumen

Untuk mengambil dokumen menggunakan pengambil yang ditentukan, teruskan instance pengambil dan opsi kueri ke 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
  },
});

Opsi Pengambilan yang Tersedia

Opsi berikut dapat diteruskan ke kolom options di ai.retrieve:

  • limit: (angka) Menentukan jumlah maksimum dokumen yang akan diambil. Default-nya adalah 10.

  • where: (Record<string, any>) Menambahkan filter tambahan berdasarkan kolom Firestore. Contoh:

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

  • collection: (string) Ganti koleksi default yang ditentukan dalam konfigurasi pengambil.

  • Hal ini berguna untuk membuat kueri subkoleksi atau beralih secara dinamis di antara

  • koleksi.

Mengisi Firestore dengan Embedding

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,
    }))[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 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 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

Men-deploy alur sebagai Cloud Functions

Untuk men-deploy alur dengan Cloud Functions, gunakan dukungan bawaan library Firebase Functions untuk genkit. Metode onCallGenkit memungkinkan Anda membuat fungsi callable dari flow. API ini secara otomatis mendukung streaming dan permintaan JSON. Anda dapat menggunakan SDK klien Cloud Functions untuk memanggilnya.

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

Deploy alur Anda menggunakan Firebase CLI:

firebase deploy --only functions