ปลั๊กอิน Firebase

ปลั๊กอิน Firebase มีการผสานรวมกับบริการ Firebase ซึ่งช่วยให้คุณสร้างแอปพลิเคชัน AI ที่ชาญฉลาดและปรับขนาดได้ ฟีเจอร์หลักๆ มีดังนี้

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

การติดตั้ง

ติดตั้งปลั๊กอิน Firebase ด้วย npm โดยทำดังนี้

npm install @genkit-ai/firebase

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

การตั้งค่าโปรเจ็กต์ Firebase

1. ผลิตภัณฑ์ Firebase ทั้งหมดต้องใช้โปรเจ็กต์ Firebase คุณสร้างโปรเจ็กต์ใหม่หรือเปิดใช้ Firebase ในโปรเจ็กต์ 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 คุณสามารถระบุรหัสโปรเจ็กต์ Firebase ได้ด้วยวิธีใดวิธีหนึ่งต่อไปนี้

• ตั้งค่า projectId ในออบเจ็กต์การกําหนดค่า initializeApp() ตามที่แสดงในข้อมูลโค้ดด้านบน

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

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

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

หากต้องการระบุข้อมูลเข้าสู่ระบบ 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 ที่จำเป็นซึ่งต้องเปิดใช้ในโปรเจ็กต์

การค้นหาเวกเตอร์ใน 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);
}

กำหนดเครื่องมือรับข้อมูล 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
  },
});

ตัวเลือกการเรียกข้อมูลที่ใช้ได้

ตัวเลือกต่อไปนี้สามารถส่งไปยังช่อง options ใน ai.retrieve

• limit: (number)
  ระบุจำนวนเอกสารสูงสุดที่จะดึงข้อมูล ค่าเริ่มต้นคือ 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 จึงจะทำงานได้ วิธีสร้างดัชนี

• เรียกใช้คําสั่ง 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 จะแสดงข้อผิดพลาดพร้อมคำสั่งที่ถูกต้องในการสร้างดัชนี

ดูข้อมูลเพิ่มเติม

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

ทำให้โฟลว์ทํางานเป็น Cloud Functions

ปลั๊กอินมีคอนสตรัคเตอร์ onFlow() ซึ่งสร้างโฟลว์ที่รองรับโดยฟังก์ชัน Cloud Functions สำหรับ Firebase ที่ทริกเกอร์ HTTPS ฟังก์ชันเหล่านี้เป็นไปตามอินเทอร์เฟซฟังก์ชันที่เรียกใช้ได้ของ 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

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

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