Firebase eklentisi

Firebase eklentisi, Firebase hizmetleriyle entegrasyon sağlar. Böylece akıllı ve ölçeklenebilir yapay zeka uygulamaları oluşturabilirsiniz. Temel özellikler:

  • Firestore Vektör Deposu: Vektör yerleştirmeleriyle dizine ekleme ve getirme için Firestore'u kullanın.
  • Telemetri: Telemetriyi, Firebase Genkit İzleme Konsolu'nu destekleyen Google Cloud işlem paketine aktarı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 yerel olarak dışa aktaran kod çalıştırmak istiyorsanız Google Cloud CLI 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

Firebase Genkit İzleme, Google'ın Cloud işlem paketi tarafından desteklenir. Bunun için projenizde telemetriyle ilgili API'lerin etkinleştirilmesi gerekir. Daha fazla bilgi için lütfen Google Cloud eklentisi belgelerine bakın.

Google Cloud IAM Console'da "Varsayılan bilgi işlem hizmet hesabı"na aşağıdaki rolleri verin:

  • Monitoring Metriği Yazıcısı (roles/monitoring.metricWriter)
  • Cloud Trace Aracısı (roles/cloudtrace.agent)
  • Günlük Yazıcı (roles/logging.logWriter)

Telemetri dışa aktarma çağrısını enableFirebaseTelemetry() etkinleştirmek için:

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

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

Bu eklenti, Google Cloud eklentisiyle yapılandırma seçeneklerini paylaşır.

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

Hizmet hesabı kimlik bilgilerini doğrudan GCLOUD_SERVICE_ACCOUNT_CREDS üzerinden ileterek 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() işlevini 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'e 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ı) Getirilecek maksimum belge 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.

Firestore'u yerleştirilmiş öğelerle doldurma

Firestore koleksiyonunuzu doldurmak için Yönetici SDK'sı 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,
    }))[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, 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önderdiğ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

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

Bir akışı Cloud Functions ile dağıtmak için Firebase Functions kitaplığının genkit için yerleşik desteğini kullanın. onCallGenkit yöntemi, bir akıştan çağrılabilir işlev oluşturmanıza olanak tanır. Akış ve JSON isteklerini otomatik olarak destekler. Bu işlevleri çağırmak için Cloud Functions istemci SDK'larını kullanabilirsiniz.

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

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

firebase deploy --only functions