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

  • Tüm Firebase ürünleri için Firebase projesi gereklidir. Yeni proje oluşturabilirsiniz veya şunu kullanarak Firebase'i mevcut bir Google Cloud projesinde etkinleştirin: Firebase konsolu.
  • Ek olarak, Cloud Functions'a akış dağıtmak istiyorsanız projenizi yükseltme Blaze kullandıkça öde planına.

Yapılandırma

Proje kimliği

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. Tekliflerinizi otomatikleştirmek ve optimize etmek için Firebase proje kimliğinizi aşağıdaki yöntemlerden biriyle değiştirebilirsiniz:

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

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

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

Firebase kimlik bilgilerini sağlamak için Google Cloud'u da kurmanız gerekir Application Default Credentials. (Uygulama Varsayılan Kimlik Bilgileri) Kimlik bilgilerinizi belirtmek için:

  • Akışınızı bir Google Cloud ortamından (Cloud Functions, Cloud Run vb.) 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 Hizmet hesabı sayfasındaki talimatları uygulayın.
    2. GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini dosyaya ayarlayın hizmet hesabı anahtarınızı içeren JSON dosyasının yolu.

Telemetri

Eklenti, Google Cloud eklentisine doğrudan bağımlıdır ve dolayısıyla telemetrinin Google'ın Cloud işlem paketine aktarılmasını sağlayacak özelliklere sahiptir. Telemetri dışa aktarımını etkinleştirmek için enableTracingAndMetrics öğesini true olarak ayarlayın ve Genkit yapılandırmasına bir telemetri bölümü ekleyin:

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

configureGenkit({
  plugins: [firebase()],
  enableTracingAndMetrics: true,
  telemetry: {
    instrumentation: 'firebase',
    logger: 'firebase',
  },
});

Tüm yapılandırma seçenekleri ve projede etkinleştirilmesi gereken gerekli API'ler için Google Cloud eklentisi belgelerini inceleyin.

Kullanım

Bu eklenti, Firebase hizmetleriyle birçok entegrasyon sağlar. Bu entegrasyonları kullanabileceğiniz en iyi araçtır.

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'a özel bilgiler yer alır Firestore'un vektör arama özelliği. Daha ayrıntılı bilgi için Almayla artırılmış oluşturma sayfasına bakın ve Genkit kullanarak RAG uygulaması üzerine konuşacağız.

firebase eklentisi, Firestore'u tanımlamak için kolaylık sağlayan bir işlev sunar. retriever'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 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: Şunu aramak için varsayılan koleksiyonu geçersiz kılın: Ör. alt koleksiyon araması.

Firestore koleksiyonunuzu doldurmak için bir yerleştirme oluşturma aracı ile birlikte Yönetici SDK'si. Örneğin, Almayla artırılmış oluşturma sayfası Firestore'a uyarlanabilir kullanabilirsiniz:

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, hızlı ve verimli bir şekilde sorgu yürütmek için dizinlere bağlıdır koleksiyonlar oluşturun. (Buradaki "dizin" ifadesinin, veritabanı dizinlerini değil Genkit'in dizinleyici ve retriever soyutlamaları.)

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

  • Şu konumda açıklanan gcloud komutunu çalıştırın: Tek alanlı vektör dizini oluşturma bölümünde bulabilirsiniz.

    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, dizine ekleme yapılandırmasının doğru olması, marka ve kullandığınız yerleştirme modelini seçin.

  • Alternatif olarak, retrieve() yöntemini çağırın. Firestore doğru komutla birlikte kullanabilirsiniz.

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

Varsayılan olarak eklenti, izleri genkit-traces adlı bir koleksiyonda depolar. projenin varsayılan veritabanını kullanır. İ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, onFlow() Cloud Functions for Firebase'in HTTPS tarafından tetiklenen işlevi. Bu işlevler Firebase'in çağrılabilir işlev arayüzünün yanı sıra Cloud Functions istemci SDK'ları onları aramaktır.

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: HttpsOptions nesne (Cloud Functions işlevinizi yapılandırmak için kullanılır):

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

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

  • 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:

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

Kimlik doğrulama politikası tanımlamak için firebaseAuth() ürününe şu özelliklere sahip bir geri çağırma işlevi sağlayın: alır DecodedIdToken olarak kullanır. Bu fonksiyonda, kullanıcı jetonunu inceleyin ve hatasını gösterir.

Aşağıdakilerle ilgili daha ayrıntılı bir tartışma için Yetkilendirme ve bütünlük bölümüne bakın daha iyi olur.