Trình bổ trợ Firebase

Trình bổ trợ Firebase cung cấp các tính năng tích hợp với các dịch vụ của Firebase, cho phép bạn xây dựng các ứng dụng AI thông minh và có thể mở rộng quy mô. Các tính năng chính bao gồm:

  • Firestore Vector Store (Kho vectơ Firestore): Sử dụng Firestore để lập chỉ mục và truy xuất bằng các vectơ nhúng.
  • Hàm trên đám mây: Triển khai luồng dưới dạng hàm được kích hoạt bằng HTTPS.
  • Xác thực Firebase: Triển khai chính sách uỷ quyền.
  • Thông tin đo từ xa: Xuất dữ liệu đo từ xa sang bộ công cụ vận hành của Google Cloud và xem các chế độ xem chuyên biệt trong bảng điều khiển Firebase

Lắp đặt

Cài đặt trình bổ trợ Firebase bằng npm:

npm install @genkit-ai/firebase

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

Thiết lập dự án Firebase

  1. 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 một dự án mới hoặc bật Firebase trong một dự án Google Cloud hiện có bằng bảng điều khiển của Firebase.
  2. Nếu triển khai flow bằng Cloud Functions, hãy nâng cấp dự án Firebase lên gói Blaze.
  3. 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.

Khởi chạy SDK quản trị Firebase

Bạn phải khởi chạy SDK quản trị Firebase trong ứng dụng của mình. Trình bổ trợ không tự động xử lý việc này.

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

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

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 initializeApp() như trong đoạn mã ở trên.

  • Đặt biến môi trường GCLOUD_PROJECT. Nếu bạn đang chạy flow từ một môi trường Google Cloud (Cloud Functions, Cloud Run, v.v.), 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 tham số cấu hình trong initializeApp().

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.

Tính năng và cách sử dụng

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

Hãy 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.

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

Xác định trình truy xuất Firestore

Sử dụng defineFirestoreRetriever() để tạo trình truy xuất cho các truy vấn dựa trên vectơ 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'
});

Truy xuất tài liệu

Để truy xuất tài liệu bằng trình truy xuất đã xác định, hãy truyền thực thể trình truy xuất và các tuỳ chọn truy vấn đến 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
  },
});

Các tuỳ chọn truy xuất có sẵn

Bạn có thể truyền các tuỳ chọn sau vào trường options trong ai.retrieve:

  • limit: (số)
    Chỉ định số lượng tài liệu tối đa cần truy xuất. Giá trị mặc định là 10.

  • where: (Record<string, any>)
    Thêm bộ lọc bổ sung dựa trên các trường Firestore. Ví dụ:

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

  • collection: (chuỗi)
    Ghi đè bộ sưu tập mặc định được chỉ định trong cấu hình trình truy xuất. Điều này rất hữu ích khi truy vấn các bộ sưu tập con hoặc tự động chuyển đổi giữa các bộ sưu tập.

Điền nội dung nhúng vào Firestore

Để đ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 bằng tính năng truy xuất bổ sung 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

Triển khai luồng dưới dạng Chức năng trên đám mây

Trình bổ trợ cung cấp hàm khởi tạo onFlow(). Hàm này tạo một luồng đượ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 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 của tính năng 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.

Xác thực Firebase

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 xung quanh 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.