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 bir proje oluşturabilir veya Firebase konsolunu kullanarak mevcut bir Google Cloud projesinde Firebase'i etkinleştirebilirsiniz.
- Ayrıca, Cloud Functions'a akış dağıtmak istiyorsanız projenizi Blaze kullandıkça öde planına yükseltmeniz gerekir.
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. Firebase proje kimliğinizi aşağıdaki yöntemlerden biriyle belirtebilirsiniz:
firebase()
yapılandırma nesnesindeprojectId
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ızGCLOUD_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:
- 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.
GOOGLE_APPLICATION_CREDENTIALS
ortam değişkenini, hizmet hesabı anahtarınızı içeren JSON dosyasının dosya yoluna ayarlayın.
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 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
- Genkit'teki dizinleyiciler ve retriever'lar hakkında genel bir tartışma için Almayla artırılmış oluşturma sayfasına bakın.
- Vektör arama özelliğiyle ilgili daha fazla bilgi için Cloud Firestore belgelerindeki Vektör yerleştirilmiş öğelerle arama bölümüne bakın.
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ılanHttpsOptions
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.