افزونه Firebase

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

  • Firestore Vector Store : از Firestore برای نمایه سازی و بازیابی با جاسازی های برداری استفاده کنید.
  • توابع ابری : جریان‌ها را به‌عنوان توابع راه‌اندازی‌شده با HTTPS اجرا کنید.
  • احراز هویت Firebase : سیاست های مجوز را اجرا کنید.
  • تله متری : صادرات تله متری به مجموعه عملیات Google Cloud و مشاهده نماهای تخصصی در کنسول Firebase

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

افزونه 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 تنظیم کنید.

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

تله متری

این افزونه وابستگی مستقیمی به افزونه Google Cloud دارد و بنابراین مقرراتی برای فعال کردن صادرات تله متری به مجموعه عملیات Google Cloud دارد. برای فعال کردن صادرات تله متری، enableFirebaseTelemetry() فراخوانی کنید: 

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

enableFirebaseTelemetry();

برای همه گزینه های پیکربندی و API های لازم که باید در پروژه فعال شوند، به مستندات افزونه 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 : (تعداد)
    حداکثر تعداد اسناد را برای بازیابی مشخص کنید. پیش فرض 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,
    });
    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 با دستور صحیح خطایی برای ایجاد ایندکس ایجاد می کند.

بیشتر بدانید

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

این افزونه سازنده onFlow() را ارائه می‌کند که جریانی را ایجاد می‌کند که توسط یک تابع Cloud Functions برای Firebase HTTPS راه‌اندازی می‌شود. این توابع با رابط تابع قابل فراخوانی Firebase مطابقت دارند و می‌توانید از SDKهای سرویس گیرنده Cloud Functions برای فراخوانی آنها استفاده کنید. 

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

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

firebase deploy --only functions

تابع onFlow() دارای گزینه هایی است که در defineFlow() وجود ندارند:

  • httpsOptions : یک شی HttpsOptions که برای پیکربندی عملکرد ابری شما استفاده می شود: 

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

  • enforceAppCheck : در صورت true ، درخواست‌های دارای نشانه‌های بررسی برنامه گم یا نامعتبر را رد کنید.

  • consumeAppCheckToken : در صورت true ، پس از تأیید کد App Check آن را باطل کنید.

    به محافظت از پخش مجدد مراجعه کنید.

احراز هویت Firebase

این افزونه یک تابع کمکی برای ایجاد سیاست های مجوز در اطراف 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) => {
    // ...
  }
);

برای تعریف یک خط مشی auth، یک تابع callback firebaseAuth() ارائه دهید که یک DecodedIdToken به عنوان تنها پارامتر خود می گیرد. در این تابع، توکن کاربر را بررسی کنید و اگر کاربر هر یک از معیارهای مورد نیاز خود را برآورده نکند، خطا ایجاد کنید.

برای بحث کامل تر در مورد این موضوع ، مجوز و یکپارچگی را ببینید.