פלאגין של Firebase

הפלאגין של Firebase מספק שילובים עם שירותי Firebase, כך שתוכלו ליצור אפליקציות AI חכמות וניתנות להתאמה. התכונות העיקריות כוללות:

  • Firestore Vector Store: שימוש ב-Firestore להוספה לאינדקס ולאחזור באמצעות הטמעת וקטורים.
  • טלמטריה: ייצוא טלמטריה לחבילת התפעול של Google Cloud שמפעילה את מסוף המעקב של Firebase Genkit.

התקנה

מתקינים את הפלאגין של Firebase באמצעות npm:

npm install @genkit-ai/firebase

דרישות מוקדמות

הגדרת פרויקט ב-Firebase

  1. כל מוצרי Firebase דורשים פרויקט Firebase. אפשר ליצור פרויקט חדש או להפעיל את Firebase בפרויקט קיים ב-Google Cloud באמצעות מסוף Firebase.
  2. אם אתם פורסים תהליכים באמצעות Cloud Functions, עליכם לשדרג את פרויקט Firebase לתוכנית Blaze.
  3. אם רוצים להריץ קוד באופן מקומי שמייצא נתוני טלמטריה, צריך להתקין את הכלי Google Cloud CLI.

איפוס של Firebase Admin SDK

צריך לאתחל את Firebase Admin SDK באפליקציה. הפלאגין לא מטפל בכך באופן אוטומטי.

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

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

כדי להשתמש בפלאגין, צריך לציין את מזהה הפרויקט ב-Firebase. אפשר לציין את מזהה הפרויקט ב-Firebase באחת מהדרכים הבאות:

  • מגדירים את projectId באובייקט התצורה initializeApp(), כפי שמוצג בקטע הקוד שלמעלה.

  • מגדירים את משתנה הסביבה GCLOUD_PROJECT. אם אתם מריצים את התהליך מסביבת Google Cloud (Cloud Functions,‏ Cloud Run וכו'), הערך של GCLOUD_PROJECT מוגדר באופן אוטומטי למזהה הפרויקט של הסביבה.

    אם מגדירים את GCLOUD_PROJECT, אפשר להשמיט את פרמטר ההגדרה ב-initializeApp().

פרטי כניסה

כדי לספק את פרטי הכניסה ל-Firebase, צריך גם להגדיר את Application Default Credentials של Google Cloud. כדי לציין את פרטי הכניסה:

  • אם אתם מריצים את התהליך מסביבת Google Cloud (Cloud Functions,‏ Cloud Run וכו'), ההגדרה הזו מוגדרת באופן אוטומטי.

  • בסביבות אחרות:

    1. יוצרים פרטי כניסה לחשבון השירות של פרויקט Firebase ומורידים את קובץ המפתח בפורמט JSON. אפשר לעשות זאת בדף Service account במסוף Firebase.
    2. מגדירים את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS לנתיב של קובץ ה-JSON שמכיל את המַפְתח של חשבון השירות, או מגדירים את משתנה הסביבה GCLOUD_SERVICE_ACCOUNT_CREDS לתוכן של קובץ ה-JSON.

תכונות ושימוש

טלמטריה

Firebase Genkit Monitoring פועל על בסיס חבילת התפעול של Google Cloud. לשם כך, צריך להפעיל בפרויקט את ממשקי ה-API שקשורים לטלמטריה. פרטים נוספים זמינים במסמכים של הפלאגין של Google Cloud.

מקצים את התפקידים הבאים לחשבון השירות Default compute service account במסוף IAM של Google Cloud:

  • כתיבה של מדדי מעקב (roles/monitoring.metricWriter)
  • סוכן Cloud Trace (roles/cloudtrace.agent)
  • כתיבה ביומן (roles/logging.logWriter)

כדי להפעיל את ייצוא הטלמטריה, קוראים לפונקציה enableFirebaseTelemetry():

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

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

הפלאגין הזה משתף אפשרויות הגדרה עם הפלאגין של Google Cloud.

אפשר להשתמש ב-Cloud Firestore כאחסון וקטורים להוספה לאינדקס של RAG ולאחזור.

הקטע הזה מכיל מידע ספציפי על הפלאגין firebase ועל תכונת החיפוש לפי וקטור ב-Cloud Firestore. בדף יצירה עם שיפור לאחזור מוסבר בהרחבה איך מטמיעים את ה-RAG באמצעות Genkit.

שימוש ב-GCLOUD_SERVICE_ACCOUNT_CREDS וב-Firestore

אם אתם משתמשים בפרטי כניסה של חשבון שירות על ידי העברת פרטי הכניסה ישירות דרך GCLOUD_SERVICE_ACCOUNT_CREDS, ואתם משתמשים גם ב-Firestore כמאגר וקטורים, עליכם להעביר את פרטי הכניסה ישירות למכונה של Firestore במהלך האיפוס. אחרת, ייתכן שהמופע היחיד יופעל עם פרטי הכניסה שמוגדרים כברירת מחדל באפליקציה, בהתאם לסדר האיפוס של הפלאגין.

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

הגדרת אחזור של Firestore

משתמשים ב-defineFirestoreRetriever() כדי ליצור אחזור של שאילתות מבוססות-וקטור ב-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'
});

אחזור מסמכים

כדי לאחזר מסמכים באמצעות המאגר שהוגדר, מעבירים את המכונה של המאגר ואת אפשרויות השאילתה אל 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
  },
});

אפשרויות אחזור זמינות

אפשר להעביר את האפשרויות הבאות לשדה options ב-ai.retrieve:

  • limit: (number) מציינים את המספר המקסימלי של מסמכים לאחזור. ברירת המחדל היא 10.

  • where: (Record<string, any>) הוספת מסננים נוספים על סמך שדות של Firestore. דוגמה:

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

  • collection: (מחרוזת) שינוי ברירת המחדל של האוסף שצוינה בתצורה של האחזור.

  • אפשר להשתמש בזה כדי לשלוח שאילתות על אוספי משנה או לעבור באופן דינמי בין

  • אוספים.

איך מאכלסים את Firestore באמצעות הטמעות

כדי לאכלס את האוסף ב-Firestore, משתמשים ב-Admin SDK ובכלי ליצירת הטמעות. לדוגמה, אפשר להתאים את הסקריפט להטמעת התפריט מהדף יצירה עם שיפור לאחזור ל-Firestore באופן הבא:

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 מסתמך על אינדקסים כדי לספק שאילתות מהירות ויעילות על אוספי נתונים. (הערה: המונח 'אינדקס' מתייחס כאן לאינדקסים של מסדי נתונים, ולא לשירותי ה-indexer וה-retriever של Genkit).

כדי שהדוגמה הקודמת תפעל, צריך להוסיף את השדה embedding לאינדקס. כדי ליצור את המדד:

  • מריצים את הפקודה gcloud שמתוארת בקטע יצירת אינדקס וקטור של שדה יחיד במסמכי העזרה של Firestore.

    הפקודה נראית כך:

    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

    עם זאת, ההגדרה הנכונה להוספה לאינדקס תלויה בשאילתות שאתם שולחים ובמודל ההטמעה שבו אתם משתמשים.

  • לחלופין, אפשר להפעיל את ai.retrieve() ומערכת Firestore תציג שגיאה עם הפקודה הנכונה ליצירת האינדקס.

מידע נוסף

פריסת תהליכים כ-Cloud Functions

כדי לפרוס תהליך באמצעות Cloud Functions, משתמשים בתמיכה המובנית של ספריית Firebase Functions ב-genkit. השיטה onCallGenkit מאפשרת ליצור פונקציה שניתן לקרוא לה מתהליך. הוא תומך באופן אוטומטי בשידור ובבקשות JSON. אפשר להשתמש בחבילות ה-SDK של לקוחות Cloud Functions כדי לבצע קריאות אליהן.

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

פורסים את התהליך באמצעות CLI של Firebase:

firebase deploy --only functions