ปลั๊กอิน Firebase

ปลั๊กอิน Firebase มีการผสานรวมกับบริการ Firebase หลายรายการ ดังนี้

  • ตัวจัดทําดัชนีและเครื่องมือดึงข้อมูลที่ใช้ที่เก็บเวกเตอร์ของ Cloud Firestore
  • ติดตามพื้นที่เก็บข้อมูลโดยใช้ Cloud Firestore
  • การใช้ Cloud Functions เพื่อทำให้โฟลว์ใช้งานได้
  • นโยบายการให้สิทธิ์สําหรับผู้ใช้การตรวจสอบสิทธิ์ Firebase
  • การส่งออกข้อมูลการวัดไปยังชุดเครื่องมือการดำเนินการของ Google Cloud

การติดตั้ง

npm i --save @genkit-ai/firebase

ข้อกำหนดเบื้องต้น

  • ผลิตภัณฑ์ Firebase ทั้งหมดต้องใช้โปรเจ็กต์ Firebase คุณสร้างโปรเจ็กต์ใหม่หรือเปิดใช้ Firebase ในโปรเจ็กต์ Google Cloud ที่มีอยู่ได้โดยใช้คอนโซล Firebase
  • นอกจากนี้ หากต้องการทำให้โฟลว์ใช้งานได้ใน Cloud Functions คุณต้องอัปเกรดโปรเจ็กต์เป็นแพ็กเกจแบบชําระเงินเมื่อใช้ของ Blaze
  • หากต้องการเรียกใช้โค้ดในเครื่องซึ่งส่งออกข้อมูลการวัดผล คุณต้องติดตั้งเครื่องมือ Google Cloud CLI

การกำหนดค่า

รหัสโปรเจ็กต์

หากต้องการใช้ปลั๊กอินนี้ ให้ระบุเมื่อเริ่มต้น Genkit

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

const ai = genkit({
  plugins: [firebase({ projectId: "your-firebase-project" })],
});

ปลั๊กอินกำหนดให้คุณระบุรหัสโปรเจ็กต์ Firebase คุณสามารถระบุรหัสโปรเจ็กต์ Firebase ได้ด้วยวิธีใดวิธีหนึ่งต่อไปนี้

  • ตั้งค่า projectId ในออบเจ็กต์การกําหนดค่า firebase()

  • ตั้งค่าตัวแปรสภาพแวดล้อม GCLOUD_PROJECT หากคุณเรียกใช้โฟลว์จากสภาพแวดล้อม Google Cloud (Cloud Functions, Cloud Run และอื่นๆ) ระบบจะตั้งค่า GCLOUD_PROJECT เป็นรหัสโปรเจ็กต์ของสภาพแวดล้อมโดยอัตโนมัติ

    หากตั้งค่าเป็น GCLOUD_PROJECT คุณจะละเว้นพารามิเตอร์การกําหนดค่าได้ ดังนี้ firebase()

ข้อมูลเข้าสู่ระบบ

หากต้องการระบุข้อมูลเข้าสู่ระบบ Firebase คุณจะต้องตั้งค่าข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชัน Google Cloud ด้วย วิธีระบุข้อมูลเข้าสู่ระบบ

  • หากคุณเรียกใช้โฟลว์จากสภาพแวดล้อม Google Cloud (Cloud Functions, Cloud Run และอื่นๆ) ระบบจะตั้งค่านี้โดยอัตโนมัติ

  • สำหรับสภาพแวดล้อมอื่นๆ ให้ทำดังนี้

    1. สร้างข้อมูลเข้าสู่ระบบของบัญชีบริการสําหรับโปรเจ็กต์ Firebase และดาวน์โหลดไฟล์คีย์ JSON ซึ่งทำได้ในหน้าบัญชีบริการของคอนโซล Firebase
    2. ตั้งค่าตัวแปรสภาพแวดล้อม GOOGLE_APPLICATION_CREDENTIALS เป็นเส้นทางไฟล์ของไฟล์ JSON ที่มีคีย์บัญชีบริการ หรือจะตั้งค่าตัวแปรสภาพแวดล้อม GCLOUD_SERVICE_ACCOUNT_CREDS เป็นเนื้อหาของไฟล์ JSON ก็ได้

การส่งข้อมูลทางไกล

เนื่องจากการพึ่งพา Google Cloud Plugin โดยตรง จึงมีการระบุไว้ให้เปิดใช้การส่งออกข้อมูลการวัดไปยังชุดเครื่องมือการดําเนินการของ Google Cloud วิธีเปิดใช้การเรียกใช้การส่งออกข้อมูลการวัดและส่งข้อมูลทางไกล enableFirebaseTelemetry()

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

enableFirebaseTelemetry();

โปรดดูเอกสารประกอบของปลั๊กอิน Google Cloud เพื่อดูตัวเลือกการกำหนดค่าทั้งหมดและ API ที่จำเป็นซึ่งต้องเปิดใช้ในโปรเจ็กต์

การใช้งาน

ปลั๊กอินนี้มีการผสานรวมหลายรายการกับบริการ Firebase ซึ่งคุณใช้ร่วมกันหรือแยกกันได้

ที่เก็บเวกเตอร์ของ Cloud Firestore

คุณสามารถใช้ Cloud Firestore เป็นพื้นที่เก็บข้อมูลเวกเตอร์สําหรับการจัดทําดัชนีและการดึงข้อมูล RAG

ส่วนนี้ประกอบด้วยข้อมูลเฉพาะเกี่ยวกับปลั๊กอิน firebase และฟีเจอร์การค้นหาเวกเตอร์ของ Cloud Firestore ดูรายละเอียดเพิ่มเติมเกี่ยวกับการนำ RAG ไปใช้โดยใช้ Genkit ได้ในหน้าการสร้างที่เพิ่มการดึงข้อมูล

การใช้ GCLOUD_SERVICE_ACCOUNT_CREDS และ Firestore

หากคุณใช้ข้อมูลเข้าสู่ระบบของบัญชีบริการโดยการส่งข้อมูลเข้าสู่ระบบผ่าน GCLOUD_SERVICE_ACCOUNT_CREDS โดยตรงและใช้ Firestore เป็นพื้นที่เก็บข้อมูลเวกเตอร์ด้วย คุณจะต้องส่งข้อมูลเข้าสู่ระบบไปยังอินสแตนซ์ Firestore โดยตรงระหว่างการเริ่มต้น หรือระบบอาจเริ่มต้นใช้งาน Singleton ด้วยข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชัน ทั้งนี้ขึ้นอยู่กับลําดับการเริ่มต้นใช้งานของปลั๊กอิน

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 เพื่อให้ทำงานได้ วิธีสร้างดัชนี

  • เรียกใช้คําสั่ง gcloud ที่อธิบายไว้ในส่วนสร้างดัชนีเวกเตอร์แบบช่องเดียวของเอกสาร Firestore

    คำสั่งจะมีลักษณะดังต่อไปนี้

    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

ปลั๊กอินจะมีตัวสร้าง onFlow() ซึ่งสร้างโฟลว์ที่รองรับโดย Cloud Functions สำหรับฟังก์ชันที่ทริกเกอร์ HTTPS ของ Firebase ฟังก์ชันเหล่านี้เป็นไปตามอินเทอร์เฟซฟังก์ชันที่เรียกใช้ได้ของ Firebase และคุณใช้ SDK ของไคลเอ็นต์ Cloud Functions เพื่อเรียกใช้ฟังก์ชันเหล่านี้ได้

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: ออบเจ็กต์ HttpsOptions ใช้เพื่อกําหนดค่า Cloud Function

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

  • enforceAppCheck: เมื่อ true ให้ปฏิเสธคำขอที่ไม่มีหรือมีโทเค็น App Check ที่ใช้งานไม่ได้

  • consumeAppCheckToken: when true, invalidate the App Check token after verifying it.

    โปรดดูการป้องกันการเล่นซ้ำ

Firebase Auth

ปลั๊กอินนี้มีฟังก์ชันตัวช่วยในการสร้างนโยบายการให้สิทธิ์เกี่ยวกับ Firebase Auth

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

หากต้องการกำหนดนโยบายการตรวจสอบสิทธิ์ ให้ระบุฟังก์ชัน Callback ให้กับ firebaseAuth() ซึ่งใช้พารามิเตอร์เดียวเป็น DecodedIdToken ในฟังก์ชันนี้ ให้ตรวจสอบโทเค็นผู้ใช้และแสดงข้อผิดพลาดหากผู้ใช้ไม่มีคุณสมบัติตรงตามเกณฑ์ใดๆ ที่คุณกำหนด

ดูการอภิปรายหัวข้อนี้อย่างละเอียดได้ที่การให้สิทธิ์และความสมบูรณ์