Firebase 플러그인

Firebase 플러그인은 Firebase 서비스와 통합을 제공하므로 지능적이고 확장 가능한 AI 애플리케이션을 빌드할 수 있습니다. 주요 기능은 다음과 같습니다.

  • Firestore 벡터 저장소: 벡터 임베딩을 사용하여 색인 생성 및 검색에 Firestore를 사용합니다.
  • Cloud Functions: HTTPS 트리거 함수로 흐름을 배포합니다.
  • Firebase 인증: 승인 정책을 구현합니다.
  • 원격 분석: 원격 분석을 Google Cloud의 작업 제품군으로 내보내고 Firebase Console에서 전문 보기를 확인합니다.

설치

npm을 사용하여 Firebase 플러그인을 설치합니다.

npm install @genkit-ai/firebase

기본 요건

Firebase 프로젝트 설정

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

Firebase Admin SDK 초기화

애플리케이션에서 Firebase Admin SDK를 초기화해야 합니다. 이는 플러그인에서 자동으로 처리되지 않습니다.

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

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

이 플러그인에는 Firebase 프로젝트 ID를 지정해야 합니다. 다음 두 가지 방법 중 하나로 Firebase 프로젝트 ID를 지정할 수 있습니다.

  • 위 스니펫과 같이 initializeApp() 구성 객체에서 projectId를 설정합니다.

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

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

사용자 인증 정보

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 플러그인 문서를 참고하세요.

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

Firestore 검색기 정의

defineFirestoreRetriever()를 사용하여 Firestore 벡터 기반 쿼리의 검색 도구를 만듭니다.

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

문서 검색

정의된 검색 도구를 사용하여 문서를 검색하려면 검색 도구 인스턴스와 검색 옵션을 ai.retrieve에 전달합니다.

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

사용 가능한 검색 옵션

다음 옵션을 ai.retrieve의 options 필드에 전달할 수 있습니다.

  • limit: (숫자)
    검색할 최대 문서 수를 지정합니다. 기본값은 10입니다.

  • where: (Record<string, any>)
    Firestore 필드를 기반으로 필터를 추가합니다. 예:

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

  • collection: (문자열)
    검색기 구성에 지정된 기본 컬렉션을 재정의합니다. 이는 하위 컬렉션을 쿼리하거나 컬렉션 간에 동적으로 전환하는 데 유용합니다.

임베딩으로 Firestore 채우기

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를 유일한 매개변수로 사용하는 콜백 함수를 제공합니다. 이 함수에서 사용자 토큰을 검사하고 사용자가 요구하는 기준을 충족하지 않는 경우 오류를 발생시킵니다.

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