مكوّن Firebase الإضافي

يوفّر مكوّن Firebase الإضافي العديد من عمليات الدمج مع خدمات Firebase:

  • أدوات الفهرسة وبرامج استرداد البيانات باستخدام متجر المتجهات Cloud Firestore
  • تتبع التخزين باستخدام Cloud Firestore
  • سير عملية النشر باستخدام دوال السحابة الإلكترونية
  • سياسات التفويض لمستخدمي مصادقة Firebase

تثبيت

npm i --save @genkit-ai/firebase

المتطلّبات الأساسية

  • تتطلب جميع منتجات Firebase مشروعًا على Firebase. يمكنك إنشاء مشروع جديد أو تفعيل Firebase في مشروع حالي على Google Cloud باستخدام وحدة تحكُّم Firebase.
  • بالإضافة إلى ذلك، إذا كنت تريد تفعيل مسارات لخدمة Cloud Functions، عليك ترقية مشروعك إلى خطة Blaze "الدفع حسب الاستخدام".

الإعداد

لاستخدام هذا المكوّن الإضافي، حدده عند استدعاء configureGenkit():

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

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

يتطلب منك المكوّن الإضافي تحديد رقم تعريف مشروع Firebase. يمكنك تحديد رقم تعريف مشروع Firebase بإحدى الطريقتين التاليتين:

  • ضبط projectId في كائن الإعداد firebase()

  • اضبط متغيّر بيئة GCLOUD_PROJECT. في حال تشغيل التدفق من بيئة Google Cloud (مثل Cloud Functions وCloud Run وما إلى ذلك)، يتم ضبط GCLOUD_PROJECT تلقائيًا على رقم تعريف مشروع البيئة.

    في حال ضبط GCLOUD_PROJECT، يمكنك حذف مَعلمة الضبط: firebase()

لتقديم بيانات اعتماد Firebase، يجب أيضًا إعداد بيانات الاعتماد التلقائية لتطبيق Google Cloud. لتحديد بيانات الاعتماد:

  • إذا كنت تشغِّل المسار من بيئة Google Cloud (مثل دوال Cloud وCloud Run وما إلى ذلك)، يتم ضبط الإعدادات تلقائيًا.

  • بالنسبة إلى البيئات الأخرى:

    1. أنشئ بيانات اعتماد حساب الخدمة لمشروع Firebase ونزِّل ملف مفتاح JSON. ويمكنك إجراء ذلك من خلال صفحة حساب الخدمة في "وحدة تحكُّم Firebase".
    2. اضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS على مسار ملف JSON الذي يحتوي على مفتاح حساب الخدمة

الاستخدام

يوفّر هذا المكوّن الإضافي العديد من عمليات الدمج مع خدمات Firebase، والتي يمكنك استخدامها معًا أو بشكلٍ فردي.

متجر متّجِهات في Cloud Firestore

يمكنك استخدام Cloud Firestore كمتجر متّجه لفهرسة RAG واسترجاعها.

يحتوي هذا القسم على معلومات خاصة بالمكوّن الإضافي firebase وميزة بحث المتجه في Cloud Firestore. يمكنك الاطّلاع على صفحة الإنشاء المعزز للاسترجاع للاطّلاع على مناقشة أكثر تفصيلاً حول تنفيذ RAG باستخدام Genkit.

يوفر المكوّن الإضافي 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، استخدِم أداة إنشاء تضمين مع "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 على الفهارس لتقديم استعلامات سريعة وفعالة بشأن المجموعات. (لاحظ أن كلمة "index" هنا تشير إلى فهارس قواعد البيانات، وليس إلى أداة الفهرسة وبرنامج الاسترجاع من 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

    مع ذلك، تعتمد إعدادات الفهرسة الصحيحة على طلبات البحث التي ستُجريها ونموذج التضمين الذي تستخدمه.

  • بدلاً من ذلك، يمكنك طلب 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 لدالة يتم تشغيلها باستخدام HTTPS في Firebase. وتتوافق هذه الدوال مع واجهة الدوال القابلة للاستدعاء في 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:

firebase deploy --only functions

تتضمّن الدالة onFlow() بعض الخيارات غير المتوفّرة في defineFlow():

  • httpsOptions: كائن HttpsOptions يُستخدَم لضبط دالة السحابة الإلكترونية: js export const exampleFlow = onFlow( { name: "exampleFlow", httpsOptions: { cors: true, }, // ... }, async (prompt) => { // ... } );

  • enforceAppCheck: عند true، يتم رفض الطلبات التي تتضمّن رموز فحص تطبيق غير صالحة أو غير متوفرة.

  • consumeAppCheckToken: عند true، يتم إلغاء صلاحية الرمز المميّز لفحص التطبيقات بعد إثبات ملكيته.

    يُرجى الاطّلاع على مقالة حماية إعادة التشغيل.

Firebase Auth

يوفر هذا المكوّن الإضافي وظيفة مساعِدة في إنشاء سياسات تفويض بشأن مصادقة Firebase:

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) => {
    // ...
  }
);

لتحديد سياسة مصادقة، يمكنك تزويد firebaseAuth() بوظيفة استدعاء تتعامل مع DecodedIdToken كمعلمة الوحيدة. في هذه الدالة، افحص الرمز المميز للمستخدم واعرض خطأ إذا فشل المستخدم في تلبية أي من المعايير التي تريد طلبها.

ويمكنك الاطّلاع على قسم الترخيص والنزاهة للاطّلاع على مناقشة أكثر دقة لهذا الموضوع.