افزونه Firebase

افزونه Firebase با خدمات Firebase ادغام می شود، بنابراین می توانید برنامه های هوش مصنوعی هوشمند و مقیاس پذیر بسازید. ویژگی های کلیدی عبارتند از:

  • Firestore Vector Store : از Firestore برای نمایه سازی و بازیابی با جاسازی های برداری استفاده کنید.
  • تله متری : تله متری را به مجموعه عملیات Google Cloud صادر کنید که کنسول مانیتورینگ Firebase Genkit را تامین می کند.

نصب و راه اندازی

افزونه Firebase را با npm نصب کنید:

npm install @genkit-ai/firebase

پیش نیازها

راه اندازی پروژه Firebase

  1. همه محصولات Firebase به پروژه Firebase نیاز دارند. می‌توانید با استفاده از کنسول Firebase یک پروژه جدید ایجاد کنید یا Firebase را در یک پروژه Google Cloud موجود فعال کنید.
  2. اگر جریان‌ها را با توابع Cloud اجرا می‌کنید، پروژه Firebase خود را به طرح Blaze ارتقا دهید .
  3. اگر می خواهید کدی را به صورت محلی اجرا کنید که تله متری را صادر می کند، باید ابزار Google Cloud CLI را نصب کنید.

Firebase Admin SDK Initialization

شما باید Firebase Admin SDK را در برنامه خود مقداردهی کنید. این به طور خودکار توسط افزونه مدیریت نمی شود. 

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

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

این افزونه از شما می خواهد که ID پروژه Firebase خود را مشخص کنید. شما می توانید ID پروژه Firebase خود را به یکی از روش های زیر مشخص کنید:

  • همانطور که در قطعه بالا نشان داده شده است، projectId در شی پیکربندی initializeApp() تنظیم کنید.

  • متغیر محیطی GCLOUD_PROJECT را تنظیم کنید. اگر جریان خود را از یک محیط Google Cloud (توابع Cloud، Cloud Run و غیره) اجرا می کنید، GCLOUD_PROJECT به طور خودکار روی شناسه پروژه محیط تنظیم می شود.

    اگر GCLOUD_PROJECT تنظیم کنید، می توانید پارامتر پیکربندی را در initializeApp() حذف کنید.

اعتبارنامه

برای ارائه اعتبار Firebase، باید اعتبار پیش فرض برنامه Google Cloud را نیز تنظیم کنید. برای مشخص کردن اعتبار خود:

  • اگر جریان خود را از یک محیط Google Cloud (توابع Cloud، Cloud Run و غیره) اجرا می کنید، این به طور خودکار تنظیم می شود.

  • برای محیط های دیگر:

    1. اعتبار حساب سرویس را برای پروژه Firebase خود ایجاد کنید و فایل کلید JSON را دانلود کنید. می توانید این کار را در صفحه حساب سرویس کنسول Firebase انجام دهید.
    2. متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را روی مسیر فایل فایل JSON که حاوی کلید حساب سرویس شما است، تنظیم کنید، یا می توانید متغیر محیطی GCLOUD_SERVICE_ACCOUNT_CREDS را روی محتوای فایل JSON تنظیم کنید.

ویژگی ها و کاربرد

تله متری

Firebase Genkit Monitoring توسط مجموعه عملیات Google Cloud پشتیبانی می‌شود. برای این کار باید API های مرتبط با تله متری برای پروژه شما فعال شوند. لطفاً برای جزئیات بیشتر به اسناد افزونه Google Cloud مراجعه کنید.

نقش‌های زیر را به «حساب پیش‌فرض خدمات محاسباتی» در Google Cloud IAM Console اعطا کنید:

  • نظارت بر متریک رایتر (roles/monitoring.metricWriter)
  • Cloud Trace Agent (roles/cloudtrace.agent)
  • Logs Writer (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);
}

فایرستور رتریور را تعریف کنید

از 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 : (تعداد) حداکثر تعداد اسناد را برای بازیابی مشخص کنید. پیش فرض 10 است.

  • where : (Record<string, any>) فیلترهای اضافی را بر اساس فیلدهای Firestore اضافه کنید. مثال:

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

  • collection : (رشته) نادیده گرفتن مجموعه پیش فرض مشخص شده در پیکربندی بازیابی.

  • این برای جستجو در زیر مجموعه ها یا جابجایی پویا بین آنها مفید است

  • مجموعه ها

Firestore را با Embedding ها پر کنید

برای پر کردن مجموعه 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 برای ارائه پرس و جوی سریع و کارآمد در مجموعه ها به ایندکس ها بستگی دارد. (توجه داشته باشید که "شاخص" در اینجا به نمایه های پایگاه داده اشاره دارد، نه انتزاعات نمایه ساز و بازیابی Genkit.)

مثال قبلی نیاز به ایندکس شدن فیلد embedding برای کار دارد. برای ایجاد ایندکس:

  • دستور gcloud را اجرا کنید که در بخش Create a single-field vector index در اسناد 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 با دستور صحیح خطایی برای ایجاد ایندکس ایجاد می کند.

بیشتر بدانید

استقرار جریان ها به عنوان توابع ابری

برای استقرار یک جریان با توابع ابری، از پشتیبانی داخلی کتابخانه 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);

جریان خود را با استفاده از Firebase CLI مستقر کنید: 

firebase deploy --only functions