Genkit với Cloud Functions cho Firebase

Firebase Genkit bao gồm một trình bổ trợ giúp bạn triển khai các quy trình của mình cho Firebase Chức năng đám mây. Trang này, làm ví dụ, sẽ hướng dẫn bạn qua quy trình triển khai luồng mẫu mặc định cho Firebase.

Triển khai luồng ở dạng Hàm đám mây

  1. Cài đặt các công cụ cần thiết:

    1. Đảm bảo bạn đang sử dụng Node.js phiên bản 20 trở lên (chạy node --version để ).

    2. Cài đặt Firebase CLI.

  2. Tạo một dự án Firebase mới bằng bảng điều khiển của Firebase hoặc chọn một dự án hiện có.

    Nâng cấp dự án lên Gói linh hoạt. Đây là gói bắt buộc để triển khai Đám mây Hàm.

  3. Đăng nhập bằng Giao diện dòng lệnh (CLI) của Firebase:

    firebase login
firebase login --reauth # alternative, if necessary
firebase login --no-localhost # if running in a remote shell

  4. Tạo thư mục dự án mới:

    export PROJECT_ROOT=~/tmp/genkit-firebase-project1
mkdir -p $PROJECT_ROOT

  5. Khởi chạy dự án Firebase bằng Genkit trong thư mục:

    cd $PROJECT_ROOT
firebase init genkit
    • Chọn dự án mà bạn đã tạo trước đó.
    • Chọn nhà cung cấp mô hình bạn muốn sử dụng.

    Chấp nhận chế độ mặc định cho các câu lệnh còn lại. Công cụ genkit sẽ tạo một số tệp nguồn mẫu để giúp bạn bắt đầu phát triển các luồng AI của riêng mình. Tuy nhiên, trong phần còn lại của hướng dẫn này, bạn sẽ chỉ triển khai luồng mẫu.

  6. Cung cấp thông tin đăng nhập API cho Hàm đám mây của bạn. Thực hiện một trong sau, tuỳ thuộc vào nhà cung cấp mô hình mà bạn đã chọn:

    Gemini (AI của Google)

    1. Đảm bảo AI của Google được cung cấp ở khu vực của bạn.

    2. Tạo khoá API cho Gemini API thông qua Google AI Studio.

    3. Lưu trữ khoá API trong Cloud Secret Manager:

      firebase functions:secrets:set GOOGLE_GENAI_API_KEY

      Đây là bước quan trọng để ngăn chặn vô tình làm rò rỉ khoá API, cấp quyền truy cập vào một dịch vụ có thể có đo lượng dữ liệu.

      Xem bài viết Lưu trữ và truy cập thông tin cấu hình nhạy cảm để biết thêm thông tin về cách quản lý khoá bí mật.

    4. Chỉnh sửa src/index.ts và thêm nội dung sau đây sau các lệnh nhập hiện có:

      import {defineSecret} from "firebase-functions/params";
const googleAIapiKey = defineSecret("GOOGLE_GENAI_API_KEY");

      Sau đó, trong định nghĩa luồng, hãy khai báo rằng hàm đám mây cần quyền truy cập vào giá trị bí mật này:

      export const menuSuggestionFlow = onFlow(
  {
    name: "menuSuggestionFlow",
    // ...
    httpsOptions: {
      secrets: [googleAIapiKey],  // Add this line.
    },
  },
  async (subject) => {
    // ...
  }
);

    Giờ đây, khi bạn triển khai chức năng này, khoá API của bạn sẽ được lưu trữ trong Cloud Secret Manager và Cloud Functions môi trường.

    Gemini (AI Vertex)

    1. Trong bảng điều khiển Cloud, Bật Vertex AI API cho dự án Firebase của bạn.

    2. Trên IAM hãy đảm bảo rằng bạn đã cấp Tài khoản dịch vụ mặc định của Compute Engine vai trò Người dùng Vertex AI.

    Bí mật duy nhất bạn cần để thiết lập cho hướng dẫn này là về mô hình nhưng nhìn chung, bạn phải thực hiện điều tương tự cho từng dịch vụ mà flow của bạn sử dụng.

  7. Nếu bạn truy cập flow của mình từ một ứng dụng web (bạn sẽ thực hiện việc này trong phần tiếp theo), trong tham số httpsOptions, hãy đặt một chính sách CORS:

    export const menuSuggestionFlow = onFlow(
  {
    name: "menuSuggestionFlow",
    // ...
    httpsOptions: {
      cors: true,  // Add this line.
    },
  },
  async (subject) => {
    // ...
  }
);

    Có thể bạn muốn có một chính sách hạn chế hơn cho các ứng dụng chính thức, nhưng điều này sẽ thực hiện trong hướng dẫn này.

  8. Không bắt buộc: Hãy thử quy trình của bạn trong giao diện người dùng dành cho nhà phát triển:

    1. Cung cấp thông tin đăng nhập API trên thiết bị. Thực hiện một trong các thao tác sau: tuỳ thuộc vào nhà cung cấp mô hình mà bạn chọn:

      Gemini (AI của Google)

      Đặt biến môi trường GOOGLE_GENAI_API_KEY thành khoá của bạn:

      export GOOGLE_GENAI_API_KEY=<your API key>

      Gemini (AI Vertex)

      Thiết lập một số biến môi trường bổ sung và sử dụng Công cụ gcloud để thiết lập thông tin xác thực mặc định của ứng dụng trên máy:

      export GCLOUD_PROJECT=<your project ID>
export GCLOUD_LOCATION=us-central1
gcloud auth application-default login

    2. Khởi động giao diện người dùng:

      cd $PROJECT_ROOT/functions
genkit start

    3. Trong giao diện người dùng dành cho nhà phát triển (http://localhost:4000/), hãy chạy flow:

      1. Nhấp vào menusuggestedionFlow.

      2. Trên thẻ Input JSON, hãy cung cấp một chủ thể cho mô hình:

        "AI app developers"

      3. Trên thẻ Xác thực JSON, hãy cung cấp một đối tượng xác thực được mô phỏng:

        {
  "uid": 0,
  "email_verified": true
}

      4. Nhấp vào Run (Chạy).

  9. Nếu tính đến thời điểm hiện tại mọi thứ hoạt động như mong đợi, bạn có thể triển khai luồng:

    cd $PROJECT_ROOT
firebase deploy --only functions

Bạn hiện đã triển khai luồng dưới dạng một Hàm đám mây! Tuy nhiên, bạn sẽ không thể truy cập vào điểm cuối đã triển khai bằng curl hoặc tương tự, do luồng chính sách uỷ quyền. Chuyển đến phần tiếp theo để tìm hiểu cách truy cập vào flow.

Thử quy trình đã triển khai

Điều quan trọng là mỗi quy trình bạn triển khai đều phải đặt chính sách uỷ quyền. Không có Một là các luồng AI tạo sinh có thể rất tốn kém của bạn sẽ được gọi bằng bất kỳ ai.

Luồng mẫu mặc định có chính sách uỷ quyền như sau:

firebaseAuth((user) => {
  if (!user.email_verified) {
    throw new Error('Verified email required to run flow');
  }
});

Chính sách này sử dụng trình trợ giúp firebaseAuth() để chỉ cho phép truy cập vào những tài khoản đã đăng ký người dùng ứng dụng của bạn bằng địa chỉ email đã được xác minh. Ở phía máy khách, bạn cần đặt tiêu đề Authorization: Bearer thành mã thông báo mã nhận dạng Firebase đáp ứng chính sách của bạn. SDK ứng dụng Cloud Functions cung cấp hàm có thể gọi tự động hoá việc này.

Để dùng thử điểm cuối luồng của mình, bạn có thể triển khai phiên bản web mẫu tối thiểu sau đây ứng dụng:

  1. Trong Cài đặt dự án của bảng điều khiển của Firebase, hãy thêm một ứng dụng web mới, rồi chọn phương án cũng thiết lập Lưu trữ.

  2. Trong Xác thực trong bảng điều khiển của Firebase, hãy bật nhà cung cấp Google. Bạn có thể sẽ dùng trong ví dụ này.

  3. Trong thư mục dự án, hãy thiết lập tính năng Lưu trữ Firebase, nơi bạn sẽ triển khai ứng dụng mẫu:

    cd $PROJECT_ROOT
firebase init hosting

    Chấp nhận các chế độ mặc định cho tất cả lời nhắc.

  4. Thay thế public/index.html bằng mã sau:

    <!doctype html>
<html>
  <head>
    <title>Genkit demo</title>
  </head>
  <body>
    <div id="signin" hidden>
      <button id="signinBtn">Sign in with Google</button>
    </div>
    <div id="callGenkit" hidden>
      Subject: <input type="text" id="subject" />
      <button id="suggestMenuItem">Suggest a menu theme</button>
      <p id="menuItem"></p>
    </div>
    <script type="module">
      import { initializeApp } from 'https://www.gstatic.com/firebasejs/10.10.0/firebase-app.js';
      import {
        getAuth,
        onAuthStateChanged,
        GoogleAuthProvider,
        signInWithPopup,
      } from 'https://www.gstatic.com/firebasejs/10.10.0/firebase-auth.js';
      import {
        getFunctions,
        httpsCallable,
      } from 'https://www.gstatic.com/firebasejs/10.10.0/firebase-functions.js';

      const firebaseConfig = await fetch('/__/firebase/init.json');
      initializeApp(await firebaseConfig.json());

      async function generateMenuItem() {
        const menuSuggestionFlow = httpsCallable(
          getFunctions(),
          'menuSuggestionFlow'
        );
        const subject = document.querySelector('#subject').value;
        const response = await menuSuggestionFlow(subject);
        document.querySelector('#menuItem').innerText = response.data;
      }

      function signIn() {
        signInWithPopup(getAuth(), new GoogleAuthProvider());
      }

      document
        .querySelector('#signinBtn')
        .addEventListener('click', signIn);
      document
        .querySelector('#suggestMenuItem')
        .addEventListener('click', generateMenuItem);

      const signinEl = document.querySelector('#signin');
      const genkitEl = document.querySelector('#callGenkit');

      onAuthStateChanged(getAuth(), (user) => {
        if (!user) {
          signinEl.hidden = false;
          genkitEl.hidden = true;
        } else {
          signinEl.hidden = true;
          genkitEl.hidden = false;
        }
      });
    </script>
  </body>
</html>

  5. Triển khai ứng dụng web và Chức năng đám mây:

    cd $PROJECT_ROOT
firebase deploy

Mở ứng dụng web bằng cách truy cập URL do lệnh deploy in. Ứng dụng yêu cầu bạn đăng nhập bằng Tài khoản Google, sau đó bạn có thể bắt đầu yêu cầu thiết bị đầu cuối.

Phát triển bằng Bộ mô phỏng cục bộ của Firebase

Firebase cung cấp một bộ trình mô phỏng để phát triển cục bộ mà bạn có thể sử dụng với Genkit.

Để sử dụng Genkit với Bộ mô phỏng Firebase, hãy khởi động trình mô phỏng Firebase như sau:

GENKIT_ENV=dev firebase emulators:start --inspect-functions

Thao tác này sẽ chạy mã của bạn trong trình mô phỏng và chạy khung Genkit ở chế độ phát triển. Khung này sẽ khởi chạy và hiển thị API phản chiếu Genkit (chứ không phải Giao diện người dùng Dev).

Sau đó, hãy khởi chạy giao diện người dùng Genkit Dev với tuỳ chọn --attach để kết nối giao diện đó với mã của bạn chạy bên trong Trình mô phỏng Firebase:

genkit start --attach http://localhost:3100 --port 4001

Để xem dấu vết từ Firestore trong Dev UI, bạn có thể chuyển đến thẻ Inspect (Kiểm tra) rồi bật/tắt chế độ "Dev/Product" . Khi chuyển sang trạng thái "chính thức" nó sẽ tải dấu vết từ Firestore.