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

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

  • أدوات الفهرسة والاسترجاع التي تستخدم "متجر الرسومات البيانية" في Cloud Firestore
  • تتبُّع مساحة التخزين باستخدام Cloud Firestore
  • نشر Flow باستخدام Cloud Functions
  • سياسات التفويض لمستخدمي Firebase Authentication
  • تصدير بيانات القياس إلى مجموعة عمليات Google Cloud

تثبيت

npm i --save @genkit-ai/firebase

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

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

الإعداد

رقم تعريف المشروع

لاستخدام هذا المكوّن الإضافي، حدِّده عند إعداد Genkit:

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

const ai = genkit({
  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 Application Default Credentials (بيانات الاعتماد التلقائية للتطبيق). لتحديد بيانات الاعتماد، اتّبِع الخطوات التالية:

  • إذا كنت تشغّل عملية المعالجة من بيئة Google Cloud (Cloud Functions و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();

راجِع مستندات مكوّن Google Cloud الإضافي للاطّلاع على جميع خيارات الضبط وواجهات برمجة التطبيقات اللازمة التي يجب تفعيلها في المشروع.

الاستخدام

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

متجر الرسومات المتجهّة في Cloud Firestore

يمكنك استخدام Cloud Firestore كمساحة تخزين للأشكال الهندسية لفهرسة وعرض "العناصر التي تتطلب الانتباه".

يحتوي هذا القسم على معلومات خاصة بالإضافة firebase وميزة البحث باستخدام الرسومات في Cloud Firestore. اطّلِع على صفحة الإنشاء المعزّز بالاسترجاع للحصول على مناقشة أكثر تفصيلاً حول تنفيذ ميزة "الإنشاء المعزّز بالاسترجاع" باستخدام 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 دالة مساعدة لتحديد 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)
});

لاستخدامها، يجب تمريرها إلى الدالة ai.retrieve():

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

تشمل خيارات الاسترداد المتاحة ما يلي:

  • limit: حدِّد عدد النتائج المطابقة المطلوب عرضها.
  • ‫where: أزواج من الحقول/القيم لمطابقتها (مثل {category: 'food'}) بالإضافة إلى البحث باستخدام المتجهات
  • collection: إلغاء المجموعة التلقائية للبحث عن مجموعة فرعية مثلاً

الفهرسة والتضمين

لتعبئة مجموعة 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 ليكون work. لإنشاء الفهرس:

  • نفِّذ الأمر 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 خطأ يتضمن الأمر الصحيح لإنشاء الفهرس.

مزيد من المعلومات

وظائف السحابة الإلكترونية

يقدّم المكوّن الإضافي أداة الإنشاء onFlow() التي تنشئ عملية مستندة إلى دالة مدعومة من Cloud Functions لبرنامج Firebase يتم تشغيلها من خلال بروتوكول HTTPS. تتوافق هذه الدوال مع واجهة الدالة القابلة للاستدعاء في Firebase، ويمكنك استخدام حِزم تطوير البرامج (SDK) لعملاء وظائف السحابة الإلكترونية للاستدعاء.

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:

firebase deploy --only functions

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

  • httpsOptions: HttpsOptions عنصر يُستخدَم لضبط Cloud Function:

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

  • enforceAppCheck: عند true، يُرجى رفض الطلبات التي تتضمّن رموزًا مميّزة غير متوفّرة أو غير صالحة من App Check.

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

    راجِع مقالة حماية ميزة إعادة التشغيل.

Firebase Auth

يقدّم هذا المكوّن الإضافي دالة مساعدة لإنشاء سياسات تفويض حول 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) => {
    // ...
  }
);

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

اطّلِع على التفويض والنزاهة لمناقشة أكثر تفصيلاً حول هذا الموضوع.