Trình bổ trợ Firebase

Trình bổ trợ Firebase cung cấp một số tính năng tích hợp với các dịch vụ của Firebase:

  • Trình lập chỉ mục và trình truy xuất sử dụng kho vectơ Cloud Firestore
  • Lưu trữ dấu vết bằng Cloud Firestore
  • Triển khai Flow bằng Cloud Functions
  • Chính sách uỷ quyền cho người dùng Xác thực Firebase
  • Xuất dữ liệu đo từ xa sang bộ công cụ vận hành của Google Cloud

Lắp đặt

npm i --save @genkit-ai/firebase

Điều kiện tiên quyết

  • Tất cả các sản phẩm Firebase đều yêu cầu một dự án Firebase. Bạn có thể tạo dự án mới hoặc bật Firebase trong một dự án Google Cloud hiện có bằng cách sử dụng bảng điều khiển Firebase.
  • Ngoài ra, nếu muốn triển khai flow cho Cloud Functions, bạn phải nâng cấp dự án lên gói Blaze trả theo mức sử dụng.
  • Nếu muốn chạy mã cục bộ để xuất dữ liệu đo từ xa, bạn cần cài đặt công cụ Google Cloud CLI.

Cấu hình

Mã dự án

Để sử dụng trình bổ trợ này, hãy chỉ định trình bổ trợ đó khi bạn khởi chạy Genkit:

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

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

Trình bổ trợ yêu cầu bạn chỉ định mã dự án Firebase. Bạn có thể chỉ định mã dự án Firebase theo một trong hai cách sau:

  • Đặt projectId trong đối tượng cấu hình firebase().

  • Đặt biến môi trường GCLOUD_PROJECT. Nếu bạn đang chạy luồng từ một môi trường Google Cloud (Cloud Functions, Cloud Run, v.v.), thì GCLOUD_PROJECT sẽ tự động được đặt thành mã dự án của môi trường đó.

    Nếu đặt GCLOUD_PROJECT, bạn có thể bỏ qua thông số cấu hình: firebase()

Thông tin đăng nhập

Để cung cấp thông tin xác thực Firebase, bạn cũng cần thiết lập Thông tin xác thực mặc định của ứng dụng Google Cloud. Cách chỉ định thông tin xác thực:

  • Nếu bạn đang chạy flow từ môi trường Google Cloud (Cloud Functions, Cloud Run, v.v.), thì giá trị này sẽ được đặt tự động.

  • Đối với các môi trường khác:

    1. Tạo thông tin xác thực tài khoản dịch vụ cho dự án Firebase và tải tệp khoá JSON xuống. Bạn có thể thực hiện việc này trên trang Tài khoản dịch vụ của bảng điều khiển Firebase.
    2. Đặt biến môi trường GOOGLE_APPLICATION_CREDENTIALS thành đường dẫn tệp của tệp JSON chứa khoá tài khoản dịch vụ hoặc bạn có thể đặt biến môi trường GCLOUD_SERVICE_ACCOUNT_CREDS thành nội dung của tệp JSON.

Dữ liệu đo từ xa

Trình bổ trợ này có phần phụ thuộc trực tiếp vào trình bổ trợ Google Cloud, do đó có các quy định để cho phép xuất dữ liệu đo từ xa sang bộ công cụ hoạt động trên Google Cloud. Cách bật lệnh gọi xuất dữ liệu đo từ xa enableFirebaseTelemetry():

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

enableFirebaseTelemetry();

Tham khảo tài liệu về trình bổ trợ Google Cloud để biết tất cả các tuỳ chọn cấu hình và các API cần thiết cần bật trên dự án.

Cách sử dụng

Trình bổ trợ này cung cấp một số tính năng tích hợp với các dịch vụ của Firebase. Bạn có thể sử dụng các tính năng này cùng nhau hoặc riêng lẻ.

Kho vectơ Cloud Firestore

Bạn có thể sử dụng Cloud Firestore làm kho vectơ để lập chỉ mục và truy xuất RAG.

Phần này chứa thông tin dành riêng cho trình bổ trợ firebase và tính năng tìm kiếm vectơ của Cloud Firestore. Hãy xem trang Tạo dữ liệu tăng cường bằng tính năng truy xuất để thảo luận chi tiết hơn về cách triển khai RAG bằng Genkit.

Sử dụng GCLOUD_SERVICE_ACCOUNT_CREDS và Firestore

Nếu đang sử dụng thông tin xác thực tài khoản dịch vụ bằng cách truyền thông tin xác thực trực tiếp qua GCLOUD_SERVICE_ACCOUNT_CREDS và cũng đang sử dụng Firestore làm kho vectơ, thì bạn cần truyền thông tin xác thực trực tiếp đến thực thể Firestore trong quá trình khởi chạy hoặc singleton có thể được khởi chạy bằng thông tin xác thực mặc định của ứng dụng tuỳ thuộc vào thứ tự khởi chạy trình bổ trợ.

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

Chó săn mồi

Trình bổ trợ firebase cung cấp một hàm thuận tiện để xác định trình truy xuất 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)
});

Để sử dụng, hãy truyền hàm này vào hàm ai.retrieve():

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

Các tuỳ chọn truy xuất hiện có bao gồm:

  • limit: Chỉ định số lượng kết quả trùng khớp cần trả về.
  • where: Các cặp trường/giá trị cần so khớp (ví dụ: {category: 'food'}) ngoài tính năng tìm kiếm vectơ.
  • collection: Ghi đè bộ sưu tập mặc định để tìm kiếm, ví dụ: tìm kiếm bộ sưu tập con.

Lập chỉ mục và nhúng

Để điền sẵn bộ sưu tập Firestore, hãy sử dụng trình tạo nhúng cùng với SDK quản trị. Ví dụ: bạn có thể điều chỉnh tập lệnh truyền dẫn trình đơn từ trang Tạo dữ liệu tăng cường truy xuất cho Firestore theo cách sau:

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 phụ thuộc vào các chỉ mục để cung cấp khả năng truy vấn nhanh chóng và hiệu quả trên các bộ sưu tập. (Lưu ý rằng "chỉ mục" ở đây đề cập đến các chỉ mục cơ sở dữ liệu, chứ không phải trình lập chỉ mục và trình truy xuất trừu tượng của Genkit.)

Ví dụ trước yêu cầu trường embedding phải được lập chỉ mục để hoạt động. Cách tạo chỉ mục:

  • Chạy lệnh gcloud được mô tả trong phần Tạo chỉ mục vectơ một trường của tài liệu về Firestore.

    Lệnh sẽ có dạng như sau:

    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

    Tuy nhiên, cấu hình lập chỉ mục chính xác phụ thuộc vào các truy vấn mà bạn sẽ thực hiện và mô hình nhúng mà bạn đang sử dụng.

  • Ngoài ra, hãy gọi ai.retrieve() và Firestore sẽ gửi một lỗi kèm theo lệnh chính xác để tạo chỉ mục.

Tìm hiểu thêm

Cloud Functions

Trình bổ trợ cung cấp hàm khởi tạo onFlow(). Hàm này tạo một flow được hỗ trợ bởi hàm Cloud Functions cho hàm được kích hoạt bằng HTTPS của Firebase. Các hàm này tuân thủ giao diện hàm có thể gọi của Firebase và bạn có thể sử dụng SDK ứng dụng của Cloud Functions để gọi các hàm này.

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

Triển khai quy trình bằng Giao diện dòng lệnh (CLI) của Firebase:

firebase deploy --only functions

Hàm onFlow() có một số tuỳ chọn không có trong defineFlow():

  • httpsOptions: đối tượng HttpsOptions dùng để định cấu hình Hàm trên đám mây:

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

  • enforceAppCheck: khi true, hãy từ chối các yêu cầu thiếu hoặc không hợp lệ mã thông báo Kiểm tra ứng dụng.

  • consumeAppCheckToken: khi true, hãy vô hiệu hoá mã thông báo Kiểm tra ứng dụng sau khi xác minh mã đó.

    Xem phần Bảo vệ khỏi các cuộc tấn công phát lại.

Firebase Auth

Trình bổ trợ này cung cấp một hàm trợ giúp để tạo chính sách uỷ quyền liên quan đến 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) => {
    // ...
  }
);

Để xác định chính sách xác thực, hãy cung cấp cho firebaseAuth() một hàm gọi lại lấy DecodedIdToken làm tham số duy nhất. Trong hàm này, hãy kiểm tra mã thông báo người dùng và gửi lỗi nếu người dùng không đáp ứng bất kỳ tiêu chí nào mà bạn muốn yêu cầu.

Hãy xem phần Uỷ quyền và tính toàn vẹn để thảo luận kỹ hơn về chủ đề này.