Firebase eklentisi

Firebase eklentisi, Firebase hizmetleriyle entegrasyon sağlayarak akıllı ve ölçeklenebilir yapay zeka uygulamaları geliştirmenize olanak tanır. Temel özellikler:

  • Firestore Vektör Deposu: Vektör yerleştirmeleriyle dizine ekleme ve veri alma için Firestore'u kullanın.
  • Cloud Functions: Akışları HTTPS ile tetiklenen işlevler olarak dağıtın.
  • Firebase Authentication: Yetkilendirme politikalarını uygulayın.
  • Telemetri: Telemetriyi Google Cloud'un operasyonlar paketine aktarın ve Firebase konsolunda özel görünümleri görün

Kurulum

Firebase eklentisini npm ile yükleyin:

npm install @genkit-ai/firebase

Ön koşullar

Firebase Projesi Kurulumu

  1. Tüm Firebase ürünleri için bir Firebase projesi gerekir. Firebase Konsolu'nu kullanarak yeni bir proje oluşturabilir veya mevcut bir Google Cloud projesinde Firebase'i etkinleştirebilirsiniz.
  2. Cloud Functions ile akış dağıtıyorsanız Firebase projenizi Blaze planına yükseltin.
  3. Telemetriyi dışa aktaran kodu yerel olarak çalıştırmak istiyorsanız Google Cloud KSA aracının yüklü olması gerekir.

Firebase Admin SDK'sı'nın Başlatılması

Uygulamanızda Firebase Admin SDK'sını başlatmanız gerekir. Bu işlem, eklenti tarafından otomatik olarak yapılmaz.

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

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

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

  • Yukarıdaki snippet'te gösterildiği gibi initializeApp() 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 initializeApp() parametresinde yapılandırma parametresini atlayabilirsiniz.

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.

Özellikler ve kullanım

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ştirmek için gerekli 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.

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

Firestore retriever'ı tanımlama

Firestore vektör tabanlı sorgular için bir alıcı oluşturmak üzere defineFirestoreRetriever() öğesini kullanın.

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

Dokümanları alma

Tanımlanmış alıcıyı kullanarak doküman almak için alıcı örneğini ve sorgu seçeneklerini ai.retrieve parametresine iletin.

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

Kullanılabilir Alma Seçenekleri

Aşağıdaki seçenekler ai.retrieve içindeki options alanına iletilebilir:

  • limit: (sayı)
    Alınan maksimum doküman sayısını belirtin. Varsayılan değer 10'tir.

  • where: (Kayıt<dize, herhangi bir>)
    Firestore alanlarına göre ek filtreler ekleyin. Örnek:

    where: { category: 'news', status: 'published' }

  • collection: (dize)
    Alıcı yapılandırmasında belirtilen varsayılan koleksiyonu geçersiz kılar. Bu, alt koleksiyonları sorgulamak veya koleksiyonlar arasında dinamik olarak geçiş yapmak için kullanışlıdır.

Firestore'u yerleştirilmiş öğelerle doldurma

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 alan 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 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

Akışları Cloud Functions olarak dağıtma

Bu eklenti, onFlow() kurucusunu sağlar. Bu kurucu, Firebase için Cloud Functions HTTPS tetiklemeli işlevi tarafından 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 Uygulama Kontrolü jetonunu geçersiz kıl.

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

Firebase Authentication

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 kriterleri 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.