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

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

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

تثبيت

ثبِّت المكوّن الإضافي 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.

الميزات وطريقة الاستخدام

القياس عن بُعد

تستند ميزة "مراقبة Genkit في Firebase" إلى مجموعة عمليات Google Cloud. يتطلب ذلك تفعيل واجهات برمجة التطبيقات ذات الصلة بالقياسات لمشروعك. يُرجى الرجوع إلى مستندات مكوّن Google Cloud الإضافي للحصول على مزيد من التفاصيل.

امنح الأدوار التالية إلى "حساب خدمة الحوسبة التلقائي" ضمن وحدة تحكّم إدارة الهوية وإمكانية الوصول في Google Cloud:

  • كاتب مقاييس المراقبة (roles/monitoring.metricWriter)
  • موظّف دعم Cloud Trace (roles/cloudtrace.agent)
  • كاتب السجلات (roles/logging.logWriter)

لتفعيل تصدير بيانات القياس عن بُعد، يُرجى الاتصال على enableFirebaseTelemetry():

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

enableFirebaseTelemetry({
  forceDevExport: false, // Set this to true to export telemetry for local runs
});

يشترك هذا المكوّن الإضافي في خيارات الضبط مع مكوّن 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() لإنشاء أداة استرجاع طلبات البحث المستندة إلى 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، استخدِم أداة إنشاء محتوى مضمّن مع حزمة 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,
    }))[0].embedding;
    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

لنشر مسار باستخدام Cloud Functions، استخدِم الميزة المضمّنة في مكتبة Firebase Functions لمعالجة genkit. تتيح لك طريقة onCallGenkit إنشاء دالة قابلة للاستدعاء من عملية. وتتيح تلقائيًا طلبات البث وJSON. يمكنك استخدام حِزم تطوير البرامج (SDK) لعملاء Cloud Functions للاتصال بها.

import { onCallGenkit } from 'firebase-functions/https';
import { defineSecret } from 'firebase-functions/params';

export const exampleFlow = ai.defineFlow({
  name: "exampleFlow",
}, async (prompt) => {
    // Flow logic goes here.

    return response;
  }
);

// WARNING: This has no authentication or app check protections.
// See github.com/firebase/genkit/blob/main/docs/auth.md for more information.
export const example = onCallGenkit({ secrets: [apiKey] }, exampleFlow);

يمكنك نشر مسار الإحالة الناجحة باستخدام واجهة سطر أوامر Firebase:

firebase deploy --only functions