Firebase 플러그인

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

  • Cloud Firestore 벡터 저장소를 사용하는 색인 생성기 및 검색기
  • Cloud Firestore를 사용하여 스토리지 추적
  • Cloud Functions를 사용한 흐름 배포
  • Firebase 인증 사용자의 승인 정책
  • Google Cloud 운영 제품군으로 원격 분석 내보내기

설치

npm i --save @genkit-ai/firebase

기본 요건

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

구성

프로젝트 ID

이 플러그인을 사용하려면 Genkit를 초기화할 때 지정합니다.

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

const ai = genkit({
  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 파일의 파일 경로로 설정하거나 환경 변수 GCLOUD_SERVICE_ACCOUNT_CREDS를 JSON 파일의 콘텐츠로 설정할 수 있습니다.

원격 분석

이 플러그인은 Google Cloud 플러그인에 직접 종속되므로 Google Cloud 운영 제품군으로 원격 분석을 내보낼 수 있는 조항이 있습니다. 원격 분석 내보내기를 사용 설정하려면 enableFirebaseTelemetry()를 호출합니다.

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

enableFirebaseTelemetry();

모든 구성 옵션과 프로젝트에서 사용 설정해야 하는 필수 API는 Google Cloud 플러그인 문서를 참고하세요.

용도

이 플러그인은 Firebase 서비스와의 여러 통합을 제공하며, 이를 함께 사용하거나 개별적으로 사용할 수 있습니다.

Cloud Firestore 벡터 저장소

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

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

GCLOUD_SERVICE_ACCOUNT_CREDS 및 Firestore 사용

GCLOUD_SERVICE_ACCOUNT_CREDS를 통해 사용자 인증 정보를 직접 전달하여 서비스 계정 사용자 인증 정보를 사용하고 Firestore를 벡터 저장소로 사용하는 경우 초기화 중에 사용자 인증 정보를 Firestore 인스턴스에 직접 전달해야 합니다. 그러지 않으면 플러그인 초기화 순서에 따라 싱글톤이 애플리케이션 기본 사용자 인증 정보로 초기화될 수 있습니다.

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

검색기

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

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

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

사용 가능한 검색 옵션은 다음과 같습니다.

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

색인 생성 및 임베딩

Firestore 컬렉션을 채우려면 Admin SDK와 함께 삽입 생성기를 사용하세요. 예를 들어 검색 보강 생성 페이지의 메뉴 처리 스크립트를 다음과 같이 Firestore에 맞게 조정할 수 있습니다.

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는 색인을 사용하여 컬렉션에 대한 빠르고 효율적인 쿼리를 제공합니다. 여기서 '색인'은 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

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

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

자세히 알아보기

Cloud Functions

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

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

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

firebase deploy --only functions

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

  • httpsOptions: Cloud 함수를 구성하는 데 사용되는 HttpsOptions 객체입니다.

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

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

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

    재생 보호를 참고하세요.

Firebase 인증

이 플러그인은 Firebase 인증을 중심으로 권한 부여 정책을 만드는 도우미 함수를 제공합니다.

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

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

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