Firebase 플러그인

Firebase 플러그인은 Firebase 서비스와의 여러 통합 기능을 제공합니다.

• Cloud Firestore 벡터 저장소를 사용하는 색인 생성기 및 검색기
• Cloud Firestore를 사용한 스토리지 추적
• Cloud Functions를 사용한 흐름 배포
• Firebase 인증 사용자를 위한 승인 정책

설치

npm i --save @genkit-ai/firebase

기본 요건

• 모든 Firebase 제품에는 Firebase 프로젝트가 필요합니다. Firebase Console을 사용하여 새 프로젝트를 만들거나 기존 Google Cloud 프로젝트에서 Firebase를 사용 설정할 수 있습니다.
• 또한 Cloud Functions에 흐름을 배포하려면 사용한 만큼만 지불하는 Blaze 요금제로 프로젝트를 업그레이드해야 합니다.

구성

이 플러그인을 사용하려면 configureGenkit()를 호출할 때 지정합니다.

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

configureGenkit({
  plugins: [firebase({projectId: "your-firebase-project"})],
});

플러그인을 사용하려면 Firebase 프로젝트 ID를 지정해야 합니다. 다음 방법 중 하나로 Firebase 프로젝트 ID를 지정할 수 있습니다.

• firebase() 구성 객체에서 projectId를 설정합니다.

• GCLOUD_PROJECT 환경 변수를 설정합니다. Google Cloud 환경 (Cloud Functions, Cloud Run 등)에서 흐름을 실행하는 경우 GCLOUD_PROJECT는 환경의 프로젝트 ID로 자동 설정됩니다.

  GCLOUD_PROJECT를 설정하면 구성 매개변수를 생략할 수 있습니다. firebase()

Firebase 사용자 인증 정보를 제공하려면 Google Cloud 애플리케이션 기본 사용자 인증 정보도 설정해야 합니다. 사용자 인증 정보를 지정하려면 다음 안내를 따르세요.

• Google Cloud 환경 (Cloud Functions, Cloud Run 등)에서 흐름을 실행하는 경우 자동으로 설정됩니다.

• 기타 환경의 경우:

  1. Firebase 프로젝트의 서비스 계정 사용자 인증 정보를 생성하고 JSON 키 파일을 다운로드합니다. Firebase Console의 서비스 계정 페이지에서 이 작업을 수행할 수 있습니다.
  2. 환경 변수 GOOGLE_APPLICATION_CREDENTIALS를 서비스 계정 키가 포함된 JSON 파일의 파일 경로로 설정합니다.

사용량

이 플러그인은 함께 또는 개별적으로 사용할 수 있는 Firebase 서비스와의 여러 통합을 제공합니다.

Cloud Firestore 벡터 저장소

Cloud Firestore를 RAG 색인 생성 및 검색을 위한 벡터 저장소로 사용할 수 있습니다.

이 섹션에는 firebase 플러그인 및 Cloud Firestore의 벡터 검색 기능과 관련된 정보가 포함되어 있습니다. Genkit를 사용한 RAG 구현에 관한 자세한 내용은 검색 증강 생성 페이지를 참고하세요.

firebase 플러그인은 Firestore 검색기 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)
});

이를 사용하려면 retrieve() 함수에 전달합니다.

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

사용 가능한 가져오기 옵션은 다음과 같습니다.

• limit: 반환할 일치하는 결과의 수를 지정합니다.
• where: 벡터 검색 외에 일치시킬 필드/값 쌍입니다 (예: {category: 'food'}).
• collection: 검색할 기본 컬렉션(예: 하위 컬렉션 검색)을 재정의합니다.

Firestore 컬렉션을 채우려면 임베딩 생성기를 Admin SDK와 함께 사용합니다. 예를 들어 검색 증강 생성 페이지의 메뉴 수집 스크립트를 Firestore에 맞게 다음과 같이 조정할 수 있습니다.

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는 빠르고 효율적인 컬렉션 쿼리를 제공하기 위해 색인을 사용합니다. (여기서 '색인'은 데이터베이스 색인을 나타내며 Genkit의 색인 생성기 및 검색기 추상화가 아닙니다.)

이전 예에서는 embedding 필드가 작동하려면 색인을 생성해야 합니다. 색인을 만들려면 다음 안내를 따르세요.

• Firestore 문서의 단일 필드 벡터 색인 만들기 섹션에 설명된 gcloud 명령어를 실행합니다.

  명령어는 다음과 같습니다.

  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
  

  그러나 올바른 색인 생성 구성은 사용자가 실행하는 쿼리와 사용하는 임베딩 모델에 따라 다릅니다.

• 또는 retrieve()를 호출하면 Firestore에서 색인을 만드는 올바른 명령어와 함께 오류가 발생합니다.

자세히 알아보기

• Genkit의 색인 생성기 및 검색기에 대한 일반적인 설명은 검색 증강 생성 페이지를 참조하세요.
• 벡터 검색 기능에 대한 자세한 내용은 Cloud Firestore 문서의 벡터 임베딩으로 검색을 참조하세요.

Cloud Firestore trace 스토리지

Cloud Firestore를 사용하여 trace를 저장할 수 있습니다.

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

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

기본적으로 플러그인은 프로젝트의 기본 데이터베이스에 있는 genkit-traces라는 컬렉션에 트레이스를 저장합니다. 두 설정 중 하나를 변경하려면 다음 단계를 따르세요.

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

Firestore 기반 trace 스토리지를 사용하는 경우 trace 문서에 TTL을 사용 설정하는 것이 좋습니다. https://firebase.google.com/docs/firestore/ttl

Cloud Functions

플러그인은 Firebase용 Cloud Functions HTTPS 트리거 함수가 지원하는 흐름을 만드는 onFlow() 생성자를 제공합니다. 이러한 함수는 Firebase의 호출 가능 함수 인터페이스를 따르며 Cloud Functions 클라이언트 SDK를 사용하여 호출할 수 있습니다.

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

Firebase CLI를 사용하여 흐름을 배포합니다.

firebase deploy --only functions

onFlow() 함수에는 defineFlow()에 없는 몇 가지 옵션이 있습니다.

• httpsOptions: Cloud 함수를 구성하는 데 사용되는 HttpsOptions 객체입니다. js export const exampleFlow = onFlow( { name: "exampleFlow", httpsOptions: { cors: true, }, // ... }, async (prompt) => { // ... } );

• enforceAppCheck: true인 경우 앱 체크 토큰이 누락되거나 잘못된 요청을 거부합니다.

• consumeAppCheckToken: true인 경우 앱 체크 토큰을 확인한 후 무효화합니다.

  재생 보호를 참고하세요.

Firebase 인증

이 플러그인은 Firebase 인증에 대한 승인 정책을 만드는 도우미 함수를 제공합니다.

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

인증 정책을 정의하려면 DecodedIdToken를 유일한 매개변수로 사용하는 콜백 함수와 함께 firebaseAuth()를 제공합니다. 이 함수에서 사용자 토큰을 검사하고 사용자가 필요한 기준을 충족하지 못하면 오류를 발생시킵니다.

이 주제에 관한 자세한 내용은 승인 및 무결성을 참고하세요.