Firebase eklentisi

Firebase eklentisi, Firebase hizmetleriyle çeşitli entegrasyonlar sağlar:

  • Cloud Firestore vektör mağazasını kullanan dizine ekleyenler ve veri alıcıları
  • Cloud Firestore'u kullanarak depolama alanını izleme
  • Cloud Functions'ı kullanarak akış dağıtımı
  • Firebase Authentication kullanıcıları için yetkilendirme politikaları
  • Google Cloud'un işlem paketine telemetri aktarma

Kurulum

npm i --save @genkit-ai/firebase

Ön koşullar

  • Tüm Firebase ürünleri için bir Firebase projesi gerekir. Firebase konsolunu kullanarak yeni bir proje oluşturabilir veya mevcut bir Google Cloud projesinde Firebase'i etkinleştirebilirsiniz.
  • Ayrıca, akışları Cloud Functions'a dağıtmak istiyorsanız projenizi kullandıkça öde Blaze planına yükseltmeniz gerekir.
  • Telemetriyi yerel olarak dışa aktaran kod çalıştırmak istiyorsanız Google Cloud KSA aracının yüklü olması gerekir.

Yapılandırma

Proje kimliği

Bu eklentiyi kullanmak için Genkit'i ilk kez başlattığınızda belirtin:

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

const ai = genkit({
  plugins: [firebase({ projectId: "your-firebase-project" })],
});

Eklenti, Firebase proje kimliğinizi belirtmenizi gerektirir. Firebase proje kimliğinizi aşağıdaki yöntemlerden biriyle belirtebilirsiniz:

  • firebase() yapılandırma nesnesinde projectId değerini ayarlayın.

  • GCLOUD_PROJECT ortam değişkenini ayarlayın. Akışınızı bir Google Cloud ortamından (Cloud Functions, Cloud Run vb.) çalıştırıyorsanız GCLOUD_PROJECT otomatik olarak ortamın proje kimliğine ayarlanır.

    GCLOUD_PROJECT değerini ayarlarsanız yapılandırma parametresini atlayabilirsiniz: firebase()

Kimlik bilgileri

Firebase kimlik bilgilerini sağlamak için Google Cloud Uygulama Varsayılan Kimlik Bilgileri'ni de ayarlamanız gerekir. Kimlik bilgilerinizi belirtmek için:

  • Akışınızı bir Google Cloud ortamından (Cloud Functions, Cloud Run vb.) çalıştırıyorsanız bu ayar otomatik olarak yapılır.

  • Diğer ortamlar için:

    1. Firebase projeniz için hizmet hesabı kimlik bilgileri oluşturun ve JSON anahtar dosyasını indirin. Bunu Firebase konsolunun Hizmet hesabı sayfasından yapabilirsiniz.
    2. GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini, hizmet hesabı anahtarınızı içeren JSON dosyasının dosya yoluna ayarlayabilir veya GCLOUD_SERVICE_ACCOUNT_CREDS ortam değişkenini JSON dosyasının içeriğine ayarlayabilirsiniz.

Telemetri

Bu eklenti, Google Cloud eklentisine doğrudan bağımlı olduğundan Google'ın Cloud Operations Suite'ine telemetri dışa aktarma özelliğini etkinleştirmeye yönelik hükümlere sahiptir. Telemetri dışa aktarma çağrısını enableFirebaseTelemetry() etkinleştirmek için:

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

enableFirebaseTelemetry();

Tüm yapılandırma seçenekleri ve projede etkinleştirilmesi gereken gerekli API'ler için Google Cloud eklentisi dokümanlarına bakın.

Kullanım

Bu eklenti, Firebase hizmetleriyle birlikte veya ayrı olarak kullanabileceğiniz çeşitli entegrasyonlar sağlar.

Cloud Firestore vektör mağazası

Cloud Firestore'u, RAG dizine ekleme ve getirme için bir vektör deposu olarak kullanabilirsiniz.

Bu bölümde, firebase eklentisine ve Cloud Firestore'un vektör arama özelliğine özel bilgiler yer almaktadır. Genkit'i kullanarak RAG'yi uygulama hakkında daha ayrıntılı bilgi için Almayla Artırılmış Üretim sayfasına bakın.

GCLOUD_SERVICE_ACCOUNT_CREDS ve Firestore'u kullanma

Kimlik bilgilerini doğrudan GCLOUD_SERVICE_ACCOUNT_CREDS üzerinden ileterek hizmet hesabı kimlik bilgilerini kullanıyorsanız ve vektör deposu olarak da Firestore'u kullanıyorsanız, kimlik bilgilerini başlatma sırasında doğrudan Firestore örneğine iletmeniz gerekir. Aksi takdirde, tekil nesne, eklenti başlatma sırasına bağlı olarak uygulamanın varsayılan kimlik bilgileriyle başlatılabilir.

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);
}

Retriever

firebase eklentisi, Firestore alıcılarını tanımlamak için kullanışlı bir işlev sağlar 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)
});

Kullanmak için ai.retrieve() işlevine iletin:

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

Kullanılabilen alma seçenekleri şunlardır:

  • limit: Döndürülecek eşleşen sonuçların sayısını belirtin.
  • where: Vektör aramaya ek olarak eşlenecek alan/değer çiftleri (ör. {category: 'food'}).
  • collection: Örneğin, alt koleksiyon araması yapmak için varsayılan koleksiyonu geçersiz kılın.

Dizine ekleme ve yerleştirme

Firestore koleksiyonunuzu doldurmak için Admin SDK ile birlikte bir yerleştirme oluşturucu kullanın. Örneğin, Arama destekli oluşturma sayfasındaki menü besleme komut dosyası, Firestore için aşağıdaki şekilde uyarlanabilir:

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, koleksiyonlarda hızlı ve verimli sorgu sağlamak için dizinlerden yararlanır. (Burada "dizin"in, Genkit'in dizine ekleyen ve veri alan soyutlamalarının değil, veritabanı dizinlerinin kastedildiğini unutmayın.)

Önceki örnekte, embedding alanının çalışması için dizine eklenmiş olması gerekir. Dizin oluşturmak için:

  • Firestore dokümanlarının Tek alanlı vektör dizini oluşturma bölümünde açıklanan gcloud komutunu çalıştırın.

    Komut aşağıdaki gibi görünür:

    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

    Ancak doğru dizine ekleme yapılandırması, göndereceğiniz sorgulara ve kullandığınız yerleştirme modeline bağlıdır.

  • Alternatif olarak ai.retrieve() işlevini çağırabilirsiniz. Bu durumda Firestore, dizini oluşturmak için doğru komutu içeren bir hata mesajı döndürür.

Daha fazla bilgi

Cloud Functions

Eklenti, onFlow() kurucusunu sağlar. Bu kurucu, Firebase için Cloud Functions HTTPS tarafından tetiklenen bir işlevle desteklenen bir akış oluşturur. Bu işlevler Firebase'in çağrılabilir işlev arayüzüne uygundur ve bunları çağırmak için Cloud Functions istemci SDK'larını kullanabilirsiniz.

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;
  }
);

Akışınızı Firebase CLI'yi kullanarak dağıtın:

firebase deploy --only functions

onFlow() işlevinde defineFlow() işlevinde bulunmayan bazı seçenekler vardır:

  • httpsOptions: Cloud Function'ınızı yapılandırmak için kullanılan bir HttpsOptions nesnesi:

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

  • enforceAppCheck: true olduğunda, eksik veya geçersiz Uygulama Kontrolü jetonu içeren istekleri reddedin.

  • consumeAppCheckToken: true olduğunda, doğruladıktan sonra App Check jetonunu geçersiz kıl.

    Yeniden oynatma koruması başlıklı makaleyi inceleyin.

Firebase Auth

Bu eklenti, Firebase Auth ile ilgili yetkilendirme politikaları oluşturmak için bir yardımcı işlev sağlar:

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

Kimlik doğrulama politikası tanımlamak için firebaseAuth()'e tek parametresi DecodedIdToken olan bir geri çağırma işlevi sağlayın. Bu işlevde, kullanıcı jetonunu inceleyin ve kullanıcı, zorunlu kılmak istediğiniz ölçütlerden herhangi birini karşılamıyorsa hata atın.

Bu konuyla ilgili daha ayrıntılı bir tartışma için Yetkilendirme ve bütünlük başlıklı makaleyi inceleyin.