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

يقدّم المكوّن الإضافي Firebase عمليات دمج مع خدمات Firebase، ما يتيح لك إنشاء تطبيقات ذكية وقابلة للتطوير باستخدام الذكاء الاصطناعي. تشمل الميزات الرئيسية ما يلي:

  • Firestore Vector Store: استخدِم Firestore للفهرسة والاسترجاع باستخدام عمليات تضمين المتجهات.
  • وظائف السحابة الإلكترونية: يمكنك نشر عمليات المعالجة كوظائف يتم تشغيلها باستخدام بروتوكول HTTPS.
  • Firebase Authentication: يمكنك تنفيذ سياسات التفويض.
  • بيانات القياس: تصدير بيانات القياس إلى مجموعة عمليات Google Cloud والاطّلاع على طرق عرض مخصّصة في وحدة تحكّم Firebase

تثبيت

ثبِّت المكوّن الإضافي Firebase باستخدام npm:

npm install @genkit-ai/firebase

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

إعداد مشروع Firebase

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

إعداد حزمة تطوير البرامج (SDK) لإدارة Firebase

يجب إعداد حزمة تطوير البرامج (SDK) الخاصة بمسؤول Firebase في تطبيقك. ولا يعالج المكوّن الإضافي ذلك تلقائيًا.

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

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

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

  • اضبط projectId في عنصر الضبط initializeApp() كما هو موضّح في المقتطف أعلاه.

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

    في حال ضبط GCLOUD_PROJECT، يمكنك حذف مَعلمة الإعدادات في initializeApp().

بيانات الاعتماد

لتقديم بيانات اعتماد Firebase، عليك أيضًا إعداد بيانات الاعتماد التلقائية لتطبيق Google Cloud. لتحديد بيانات الاعتماد، يُرجى اتّباع الخطوات التالية:

  • إذا كنت تشغّل عملية المعالجة من بيئة 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 الإضافي للاطّلاع على جميع خيارات الضبط وواجهات برمجة التطبيقات اللازمة التي يجب تفعيلها في المشروع.

يمكنك استخدام 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);
}

تحديد أداة استرجاع في 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 بالعناصر المضمّنة

لتعبئة مجموعة 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 الموضّح في قسم إنشاء فهرس متّجه لحقل واحد من مستندات 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 خطأ يتضمّن الأمر الصحيح لإنشاء الفهرس.

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

نشر مسارات الإحالات الناجحة كوظائف Cloud

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

يقدّم هذا المكوّن الإضافي دالة مساعدة لإنشاء سياسات تفويض حول 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 كمعلَمتها الوحيدة. في هذه الدالة، تفحص رمز أمان المستخدم وتُظهر خطأ إذا لم يستوفِ المستخدم أيًا من المعايير التي تريد فرضها.

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