Firebase eklentisi

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

  • Cloud Firestore vektör deposunu kullanan dizinleyiciler ve retriever'lar
  • Cloud Firestore ile Trace depolama alanı
  • Cloud Functions kullanarak akış dağıtımı
  • Firebase Authentication kullanıcıları için yetkilendirme politikaları

Kurulum

npm i --save @genkit-ai/firebase

Ön koşullar

Yapılandırma

Bu eklentiyi kullanmak için configureGenkit() çağırırken eklentiyi belirtin:

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

configureGenkit({
  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 için değer belirtirseniz yapılandırma parametresini çıkarabilirsiniz: firebase()

Firebase kimlik bilgilerini sağlamak için Google Cloud Uygulaması 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 ayarlanır.

  • Diğer ortamlar için:

    1. Firebase projeniz için hizmet hesabı kimlik bilgilerini oluşturun ve JSON anahtar dosyasını indirin. Bu işlemi Firebase konsolunun Hizmet hesabı sayfasında yapabilirsiniz.
    2. GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini, hizmet hesabı anahtarınızı içeren JSON dosyasının dosya yoluna ayarlayın.

Kullanım

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

Cloud Firestore vektör deposu

RAG dizine ekleme ve alma işlemleri için Cloud Firestore'u vektör deposu olarak kullanabilirsiniz.

Bu bölümde firebase eklentisine ve Cloud Firestore'un vektör arama özelliğine özel bilgiler yer alır. Genkit kullanarak RAG uygulaması hakkında daha ayrıntılı bir tartışma için Almayla artırılmış oluşturma sayfasına bakın.

firebase eklentisi, Firestore alıcılarını (defineFirestoreRetriever()) tanımlamak için kolaylık sağlayan bir işlev sağlar:

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 kodu retrieve() işlevine iletin:

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

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

  • limit: Döndürülecek eşleşen sonuçların sayısını belirtin.
  • where: Vektör aramasının yanı sıra eşleştirilecek alan/değer çiftleri (ör. {category: 'food'}).
  • collection: Alt koleksiyon araması gibi aramalar yapmak için varsayılan koleksiyonu geçersiz kılın.

Firestore koleksiyonunuzu doldurmak için Admin SDK ile birlikte bir yerleştirme oluşturma aracı kullanın. Örneğin, Almayla artırılmış oluşturma sayfasındaki menü alma komut dosyası, Firestore için aşağıdaki şekilde uyarlanabilir:

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, koleksiyonlarda hızlı ve etkili sorgulama sağlamak için dizinlerden yararlanır. (Buradaki "dizin" ifadesinin, Genkit'in dizinleyici ve retriever soyutlamalarını değil, veritabanı dizinlerini ifade ettiğini unutmayın.)

Önceki örnekte, embedding alanının iş için dizine eklenmesi gerekir. Dizini oluşturmak için:

  • Firestore belgelerinin 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ı, yapacağınız sorgulara ve kullandığınız yerleştirme modeline bağlıdır.

  • Alternatif olarak retrieve() komutunu çağırın. Firestore, dizini oluşturmak için doğru komutu içeren bir hata bildirir.

Daha fazla bilgi

Cloud Firestore izleme depolama alanı

İzleri depolamak için Cloud Firestore'u kullanabilirsiniz:

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

configureGenkit({
  plugins: [firebase()],
  traceStore: "firebase",
  enableTracingAndMetrics: true,
});

Eklenti varsayılan olarak, izleri projenin varsayılan veritabanında genkit-traces adlı bir koleksiyonda depolar. İki ayardan birini değiştirmek için:

firebase({
  traceStore: {
    collection: "your-collection";
    databaseId: "your-db";
  }
})

Firestore tabanlı iz depolama kullanırken izleme belgeleri için TTL'yi etkinleştirmelisiniz: https://firebase.google.com/docs/firestore/ttl

Cloud Functions

Eklenti, HTTPS tarafından tetiklenen Cloud Functions for Firebase işleviyle desteklenen bir akış oluşturan onFlow() oluşturucuyu sağlar. Bu işlevler Firebase'in çağrılanabilir işlev arayüzüne uygundur ve Cloud Functions istemci SDK'larını kullanarak bunları çağırabilirsiniz.

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

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

firebase deploy --only functions

onFlow() işlevi, defineFlow() öğesinde bulunmayan bazı seçeneklere sahiptir:

  • httpsOptions: Cloud Functions işlevinizi yapılandırmak için kullanılan HttpsOptions nesnesi: js export const exampleFlow = onFlow( { name: "exampleFlow", httpsOptions: { cors: true, }, // ... }, async (prompt) => { // ... } );

  • enforceAppCheck: true olduğunda, eksik veya geçersiz Uygulama Kontrolü jetonları olan istekleri reddedin.

  • consumeAppCheckToken: true olduğunda, uygulama kontrolü jetonunu doğruladıktan sonra geçersiz kılın.

    Tekrar oynatma koruması bölümüne bakın.

Firebase Auth

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

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

Bir kimlik doğrulama politikası tanımlamak için firebaseAuth() öğesine, tek parametresi olarak DecodedIdToken değerini alan bir geri çağırma işlevi sağlayın. Bu işlevde, kullanıcı jetonunu inceleyin ve kullanıcı ihtiyaç duyduğunuz ölçütlerden herhangi birini karşılayamazsa hata bildirin.

Bu konuyu daha ayrıntılı şekilde incelemek için Yetkilendirme ve bütünlük bölümüne bakın.