افزونه Firebase

افزونه Firebase چندین ادغام با خدمات Firebase ارائه می دهد:

  • ایندکسرها و رتریورها با استفاده از فروشگاه وکتور Cloud Firestore
  • ردیابی ذخیره سازی با استفاده از Cloud Firestore
  • استقرار جریان با استفاده از توابع ابری
  • سیاست های مجوز برای کاربران Firebase Authentication

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

npm i --save @genkit-ai/firebase

پیش نیازها

پیکربندی

شناسه پروژه

برای استفاده از این افزونه، هنگام فراخوانی configureGenkit() آن را مشخص کنید: 

import {configureGenkit} from "@genkit-ai/core";
import {firebase} from "@genkit-ai/firebase";

configureGenkit({
  plugins: [firebase({projectId: "your-firebase-project"})],
});

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

  • projectId در جسم پیکربندی firebase() تنظیم کنید.

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

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

اعتبارنامه

برای ارائه اعتبار 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 دارد. برای فعال کردن صادرات تله متری، enableTracingAndMetrics را روی true تنظیم کنید و یک بخش تله متری را به پیکربندی Genkit اضافه کنید: 

import {configureGenkit} from "@genkit-ai/core";
import {firebase} from "@genkit-ai/firebase";

configureGenkit({
  plugins: [firebase()],
  enableTracingAndMetrics: true,
  telemetry: {
    instrumentation: 'firebase',
    logger: 'firebase',
  },
});

برای همه گزینه‌های پیکربندی و APIهای لازم که باید در پروژه فعال شوند، به اسناد افزونه Google Cloud مراجعه کنید.

استفاده

این افزونه چندین ادغام با سرویس های Firebase ارائه می دهد که می توانید با هم یا به صورت جداگانه از آنها استفاده کنید.

فروشگاه وکتور Cloud Firestore

می‌توانید از 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);
}

رتریورها

افزونه firebase یک تابع راحت برای تعریف بازیابی های 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)
});

برای استفاده از آن، آن را به تابع retrieve() ارسال کنید: 

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

گزینه های بازیابی موجود عبارتند از:

  • limit : تعداد نتایج منطبق برای بازگشت را مشخص کنید.
  • where : جفت‌های فیلد/مقدار برای مطابقت (مثلا {category: 'food'} ) علاوه بر جستجوی برداری.
  • collection : برای جستجوی مثلاً جستجوی مجموعه فرعی، مجموعه پیش فرض را لغو کنید.

نمایه سازی و جاسازی

برای پر کردن مجموعه Firestore خود، از یک مولد جاسازی به همراه Admin SDK استفاده کنید. به عنوان مثال، اسکریپت ورود منو از صفحه نسل افزوده شده بازیابی می تواند برای Firestore به روش زیر تطبیق داده شود: 

import { configureGenkit } from "@genkit-ai/core";
import { embed } from "@genkit-ai/ai/embedder";
import { defineFlow, run } from "@genkit-ai/flow";
import { textEmbeddingGecko, vertexAI } 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 * as z from "zod";

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: textEmbeddingGecko,
};

configureGenkit({
  plugins: [vertexAI({ location: "us-central1" })],
  enableTracingAndMetrics: false,
});

const app = initializeApp({ credential: applicationDefault() });
const firestore = getFirestore(app);

export const indexMenu = defineFlow(
  {
    name: "indexMenu",
    inputSchema: z.string().describe("PDF file path"),
    outputSchema: z.void(),
  },
  async (filePath: string) => {
    filePath = path.resolve(filePath);

    // Read the PDF.
    const pdfTxt = await run("extract-text", () =>
      extractTextFromPdf(filePath)
    );

    // Divide the PDF text into segments.
    const chunks = await run("chunk-it", async () => chunk(pdfTxt));

    // Add chunks to the index.
    await run("index-chunks", async () => indexToFirestore(chunks));
  }
);

async function indexToFirestore(data: string[]) {
  for (const text of data) {
    const embedding = await 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

    با این حال، پیکربندی صحیح نمایه سازی به پرس و جوهایی که انجام می دهید و مدل جاسازی که استفاده می کنید بستگی دارد.

  • از طرف دیگر، retrieve() فراخوانی کنید و Firestore با دستور صحیح خطایی برای ایجاد ایندکس ایجاد می کند.

بیشتر بدانید

ذخیره سازی ردیابی Cloud Firestore

می توانید از Cloud Firestore برای ذخیره ردیابی ها استفاده کنید: 

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

configureGenkit({
  plugins: [firebase()],
  traceStore: "firebase",
  enableTracingAndMetrics: true,
});

به طور پیش فرض، این افزونه ردیابی ها را در مجموعه ای به نام genkit-traces در پایگاه داده پیش فرض پروژه ذخیره می کند. برای تغییر هر یک از تنظیمات: 

firebase({
  traceStore: {
    collection: "your-collection";
    databaseId: "your-db";
  }
})

هنگام استفاده از ذخیره‌سازی ردیابی مبتنی بر Firestore، می‌خواهید TTL را برای اسناد ردیابی فعال کنید: https://firebase.google.com/docs/firestore/ttl

توابع ابری

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

import {firebase} from "@genkit-ai/firebase";
import {onFlow, noAuth} from "@genkit-ai/firebase/functions";

configureGenkit({
  plugins: [firebase()],
});

export const exampleFlow = onFlow(
  {
    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(
  {
    name: "exampleFlow",
    httpsOptions: {
      cors: true,
    },
    // ...
  },
  async (prompt) => {
    // ...
  }
);

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

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

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

Firebase Auth

این افزونه یک تابع کمکی برای ایجاد سیاست های مجوز در اطراف Firebase Auth ارائه می دهد: 

import {firebaseAuth} from "@genkit-ai/firebase/auth";

export const exampleFlow = onFlow(
  {
    name: "exampleFlow",
    authPolicy: firebaseAuth((user) => {
      if (!user.email_verified) throw new Error("Requires verification!");
    }),
  },
  async (prompt) => {
    // ...
  }
);

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

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