Tworzenie hybrydowych funkcji w aplikacjach internetowych za pomocą modeli na urządzeniu i w chmurze

Tworzenie aplikacji internetowych i funkcji opartych na AI za pomocą wnioskowania hybrydowego z użyciem Firebase AI Logic Wnioskowanie hybrydowe umożliwia wnioskowanie za pomocą modeli na urządzeniu, gdy są one dostępne, i płynne przełączanie się na modele hostowane w chmurze (i odwrotnie).

Na tej stronie dowiesz się, jak zacząć korzystać z pakietu SDK klienta. Po zakończeniu standardowej konfiguracji zapoznaj się z dodatkowymi opcjami konfiguracji i funkcjami (takimi jak uporządkowane dane wyjściowe).

Pamiętaj, że wnioskowanie na urządzeniu jest obsługiwane w przypadku aplikacji internetowych działających w Chrome na komputerze.

Przejdź do przykładów kodu

Zalecane przypadki użycia i obsługiwane funkcje

Zalecane przypadki użycia:

• Korzystanie z modelu na urządzeniu do wnioskowania zapewnia:

  • większą prywatność,
  • kontekst lokalny,
  • wnioskowanie bez opłat,
  • funkcje offline.

• Korzystanie z funkcji hybrydowych zapewnia:

  • dotarcie do 100% odbiorców niezależnie od dostępności modelu na urządzeniu lub połączenia z internetem.

Obsługiwane funkcje i możliwości wnioskowania na urządzeniu:

Wnioskowanie na urządzeniu obsługuje tylko generowanie tekstu w jednej turze (nie czat) z przesyłaniem strumieniowym lub bez niego. Obsługuje te funkcje generowania tekstu:

• generowanie tekstu na podstawie danych wejściowych zawierających tylko tekst;

• generowanie tekstu na podstawie danych wejściowych zawierających tekst i obraz, w szczególności obrazów w formatach JPEG i PNG.

Możesz też generować uporządkowane dane wyjściowe, w tym JSON i wyliczenia.

Zanim zaczniesz

Pamiętaj o tych kwestiach:

• Wnioskowanie za pomocą modelu na urządzeniu korzysta z interfejsu Prompt API w Chrome; natomiast wnioskowanie za pomocą modelu hostowanego w chmurze korzysta z wybranego Gemini API dostawcy (albo Gemini Developer API albo Agent Platform Gemini API (formerly Vertex AI)).

• Na tej stronie dowiesz się, jak zacząć tworzyć aplikacje za pomocą hosta lokalnego (więcej informacji o korzystaniu z interfejsów API na hoście lokalnym znajdziesz w dokumentacji Chrome).

  Po zakończeniu standardowej konfiguracji zapoznaj się z dodatkowymi opcjami konfiguracji i funkcjami (takimi jak uporządkowane dane wyjściowe).

Pierwsze kroki na hoście lokalnym

Te instrukcje dotyczące pierwszych kroków opisują ogólną konfigurację wymaganą w przypadku każdego obsługiwanego żądania prompta, które chcesz wysłać.

Krok 1. Skonfiguruj Chrome i Prompt API na potrzeby wnioskowania na urządzeniu

1. Upewnij się, że używasz najnowszej wersji Chrome. Zaktualizuj przeglądarkę w chrome://settings/help.
   Wnioskowanie na urządzeniu jest dostępne w Chrome w wersji 139 lub nowszej.

2. Włącz model multimodalny na urządzeniu, ustawiając tę flagę na Enabled:

   • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

3. Uruchom ponownie Chrome.

4. (Opcjonalnie) Pobierz model na urządzeniu przed pierwszym żądaniem.

   Prompt API jest wbudowany w Chrome, ale model na urządzeniu nie jest domyślnie dostępny. Jeśli nie pobierzesz modelu przed pierwszym żądaniem wnioskowania na urządzeniu, żądanie automatycznie rozpocznie pobieranie modelu w tle.

   Wyświetl instrukcje pobierania modelu na urządzeniu

   1. Otwórz Narzędzia dla deweloperów > Konsola.

   2. Wykonaj zapytanie:

      await LanguageModel.availability();
      

   3. Upewnij się, że dane wyjściowe to available, downloading lub downloadable.

   4. Jeśli dane wyjściowe to downloadable, rozpocznij pobieranie modelu, wykonując to polecenie:

      await LanguageModel.create();
      

   5. Możesz użyć tego wywołania zwrotnego monitor, aby nasłuchiwać postępów pobierania i upewnić się, że model jest available przed wysłaniem żądań:

      const session = await LanguageModel.create({
        monitor(m) {
          m.addEventListener("downloadprogress", (e) => {
            console.log(`Downloaded ${e.loaded * 100}%`);
          });
        },
      });
      

Krok 2. Skonfiguruj projekt w Firebase i połącz aplikację z Firebase

1. Zaloguj się w konsoli Firebase, i wybierz projekt w Firebase.

   Nie masz jeszcze projektu w Firebase?

   Jeśli nie masz jeszcze projektu w Firebase, kliknij przycisk, aby utworzyć nowy projekt w Firebase, a następnie użyj jednej z tych opcji:

   • Opcja 1. Utwórz całkowicie nowy projekt w Firebase (i powiązany z nim Google Cloud projekt) automatycznie, wpisując nową nazwę projektu w pierwszym kroku procesu.

   • Opcja 2: „Dodaj Firebase” do istniejącego projektu Google Cloud przez kliknięcie Dodaj Firebase do projektu Google Cloud (u dołu strony). W pierwszym kroku procesu zacznij wpisywać nazwę projektu istniejącego projektu, a następnie wybierz projekt z wyświetlonej listy.

   Wykonaj pozostałe kroki procesu wyświetlanego na ekranie, aby utworzyć projekt Firebase. Pamiętaj, że gdy pojawi się prośba, nie musisz konfigurować Google Analytics aby korzystać z Firebase AI Logic pakietów SDK.

2. W konsoli Firebase otwórz Usługi AI > AI Logic.

3. Kliknij Rozpocznij , aby uruchomić proces z przewodnikiem, który pomoże Ci skonfigurować wymagane interfejsy API i zasoby w projekcie.

4. Jeśli pojawi się taka prośba, postępuj zgodnie z instrukcjami wyświetlanymi na ekranie, aby zarejestrować aplikację i dodać do niej konfigurację Firebase.

5. Gdy pojawi się prośba o wybranie "dostawcy Gemini API", zalecamy wybranie Gemini Developer API, które umożliwia szybkie rozpoczęcie pracy bez opłat.

   W dowolnym momencie możesz zawsze skonfigurować Agent Platform Gemini API (formerly Vertex AI) i wymagane do niego płatności.

6. Kontynuuj proces, aby skonfigurować wymagane interfejsy API i powiązane usługi na potrzeby Firebase AI Logic.

   Od początku lipca 2026 r. na tym etapie procesu automatycznie wymuszane będzie Firebase App Check w przypadku AI Logic, które jest krytyczną usługą pomagającą chronić Gemini API, gdy jest ono dostępne bezpośrednio z aplikacji. W ramach pierwszych kroków (patrz dalsze instrukcje w tym przewodniku) musisz skonfigurować App Check dostawcę debugowania na potrzeby lokalnego programowania, gdy App Check jest wymuszane.

7. Aby dodać wymagane pakiety SDK do aplikacji, przejdź do następnego kroku w tym przewodniku.

Krok 3. Dodaj pakiet SDK

Biblioteka Firebase zapewnia dostęp do interfejsów API do interakcji z modelami generatywnymi. Biblioteka jest częścią pakietu Firebase JavaScript SDK na potrzeby internetu.

1. Zainstaluj pakiet Firebase JS SDK na potrzeby internetu za pomocą npm:

   npm install firebase
   

2. Zainicjuj Firebase w aplikacji:

   import { initializeApp } from "firebase/app";
   import { initializeAppCheck } from "firebase/app-check";
   
   // TODO(developer) Replace the following with your app's Firebase configuration
   // See: https://firebase.google.com/docs/web/learn-more#config-object
   const firebaseConfig = {
     // ...
   };
   
   // Initialize FirebaseApp
   const firebaseApp = initializeApp(firebaseConfig);
   

Krok 4. Skonfiguruj dostawcę debugowania App Check na potrzeby lokalnego programowania

Od początku lipca 2026 r. w ramach procesu konfiguracji z przewodnikiem dla AI Logic w konsoli automatycznie wymuszane będzie Firebase App Check, aby chronić Gemini API. Na potrzeby lokalnego programowania musisz skonfigurować App Check dostawcę debugowania, aby pominąć atest, ale nadal utrzymywać wymuszanie App Check.

Aby używać dostawcy debugowania podczas interaktywnego uruchamiania aplikacji z localhost (na przykład podczas lokalnego programowania):

1. W kompilacji do debugowania włącz tryb debugowania, ustawiając self.FIREBASE_APPCHECK_DEBUG_TOKEN na true przed zainicjowaniem App Check. Przykład:

   self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   initializeAppCheck(firebaseApp, { /* App Check options */ });
   

2. Otwórz lokalnie aplikację internetową i narzędzia dla deweloperów w przeglądarce. W konsoli debugowania zobaczysz token debugowania:

   AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
   You will need to safelist it in the Firebase console for it to work.
   

3. Zarejestruj token debugowania w App Check:

   1. W konsoli Firebase otwórz kartę Zabezpieczenia > Sprawdzanie aplikacji > Aplikacje.

   2. Znajdź swoją aplikację, kliknij rozszerzone menu (more_vert), a następnie wybierz Zarządzaj tokenami debugowania.

   3. Postępuj zgodnie z instrukcjami wyświetlanymi na ekranie, aby zarejestrować token debugowania.

Szczegółowe informacje o dostawcy debugowania (w tym o tym, jak uzyskać nowy token debugowania) znajdziesz w oficjalnej App Checkdokumentacji.

Krok 5. Zainicjuj usługę i utwórz instancję modelu

Zanim wyślesz żądanie prompta do modelu, skonfiguruj te elementy:

1. Zainicjuj usługę dla wybranego dostawcy interfejsu API.

2. Utwórz instancję GenerativeModel. Upewnij się, że mode jest ustawiony na jedną z tych wartości:

   • PREFER_ON_DEVICE: użyj modelu na urządzeniu, jeśli jest dostępny; w przeciwnym razie przejdź na model hostowany w chmurze.

   • ONLY_ON_DEVICE: użyj modelu na urządzeniu, jeśli jest dostępny; w przeciwnym razie zgłoś wyjątek.

   • PREFER_IN_CLOUD: użyj modelu hostowanego w chmurze, jeśli jest dostępny; w przeciwnym razie przejdź na model na urządzeniu.

   • ONLY_IN_CLOUD: użyj modelu hostowanego w chmurze, jeśli jest dostępny; w przeciwnym razie zgłoś wyjątek.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

Krok 6. Zainicjuj model na urządzeniu

Musisz wywołać initializeDeviceModel() po lub podczas interakcji użytkownika ze stroną (np. kliknięcia przycisku) i przed wysłaniem żądania prompta do modelu. Więcej informacji o wymaganiach dotyczących aktywacji użytkownika znajdziesz w dokumentacji Chrome.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

// `initializeDeviceModel` must be called:
// (1) after or on an end-user page interaction such as a button click
// and
// (2) before any queries to the model (such as `generateContent()`)
// You may want to `await` this promise if using `ONLY_ON_DEVICE` (see note below).
model.initializeDeviceModel((val) =>
  // Example: "Download progress: 72.62%""
  console.log(`Download progress: ${Math.round(val*10000) / 100}%`)
);

Krok 7. Wyślij żądanie prompta do modelu

W tej sekcji dowiesz się, jak wysyłać różne typy danych wejściowych, aby generować różne typy danych wyjściowych, w tym:

• generowanie tekstu na podstawie danych wejściowych zawierających tylko tekst;
• generowanie tekstu na podstawie danych wejściowych zawierających tekst i obraz (multimodalnych).

Jeśli chcesz generować uporządkowane dane wyjściowe (np. JSON lub wyliczenia), to użyj jednego z tych przykładów „generowania tekstu” i dodatkowo skonfiguruj model tak, aby odpowiadał zgodnie z podanym schematem.

Generowanie tekstu na podstawie danych wejściowych zawierających tylko tekst

Możesz użyć generateContent() aby wygenerować tekst na podstawie prompta zawierającego tekst:

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Wrap in an async function so you can use await
async function run() {
  // Provide a prompt that contains text
  const prompt = "Write a story about a magic backpack."

  // To generate text output, call `generateContent` with the text input
  const result = await model.generateContent(prompt);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

Pamiętaj, że Firebase AI Logic obsługuje też przesyłanie strumieniowe odpowiedzi tekstowych za pomocą generateContentStream (zamiast generateContent).

Generowanie tekstu na podstawie danych wejściowych zawierających tekst i obraz (multimodalnych)

Możesz użyć generateContent() aby wygenerować tekst na podstawie prompta zawierającego tekst i pliki graficzne – podając każdego pliku wejściowego mimeType i sam plik.

Obsługiwane typy obrazów wejściowych w przypadku wnioskowania na urządzeniu to PNG i JPEG.

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Converts a File object to a Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

async function run() {
  // Provide a text prompt to include with the image
  const prompt = "Write a poem about this picture:";

  const fileInputEl = document.querySelector("input[type=file]");
  const imagePart = await fileToGenerativePart(fileInputEl.files[0]);

  // To generate text output, call `generateContent` with the text and image
  const result = await model.generateContent([prompt, imagePart]);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

Pamiętaj, że Firebase AI Logic obsługuje też przesyłanie strumieniowe odpowiedzi tekstowych za pomocą generateContentStream (zamiast generateContent).

Co jeszcze możesz zrobić?

W przypadku funkcji hybrydowych możesz używać różnych dodatkowych opcji konfiguracji i funkcji:

• Ustaw tryb wnioskowania

• Zastąp domyślny model rezerwowy hostowany w chmurze

• Użyj konfiguracji modelu, aby kontrolować odpowiedzi (np. temperaturę)

• Generuj uporządkowane dane wyjściowe (np. JSON)

Funkcje, które nie są jeszcze dostępne w przypadku wnioskowania na urządzeniu

Nie wszystkie funkcje pakietu Web SDK są dostępne w przypadku wnioskowania na urządzeniu. Te funkcje nie są jeszcze obsługiwane w przypadku wnioskowania na urządzeniu (ale zwykle są dostępne w przypadku wnioskowania w chmurze).

• Generowanie tekstu na podstawie danych wejściowych w postaci plików graficznych w formatach innych niż JPEG i PNG.

  • Można przejść na model hostowany w chmurze, ale tryb ONLY_ON_DEVICE spowoduje zgłoszenie błędu.

• Generowanie tekstu na podstawie danych wejściowych w postaci plików audio, wideo i dokumentów (np. PDF).

  • Można przejść na model hostowany w chmurze, ale tryb ONLY_ON_DEVICE spowoduje zgłoszenie błędu.

• Generowanie obrazów za pomocą modeli Gemini lub Imagen.

  • Można przejść na model hostowany w chmurze, ale tryb ONLY_ON_DEVICE spowoduje zgłoszenie błędu.

• Udostępnianie plików za pomocą adresów URL w żądaniach multimodalnych. Musisz udostępniać pliki jako dane wbudowane w modelach na urządzeniu.

• Czat wieloetapowy.

  • Można przejść na model hostowany w chmurze, ale tryb ONLY_ON_DEVICE spowoduje zgłoszenie błędu.

• Dwukierunkowe przesyłanie strumieniowe za pomocą Gemini Live API.

• Udostępnianie modelowi narzędzi , które pomogą mu generować odpowiedzi (np. wywoływanie funkcji, wykonywanie kodu, kontekst adresu URL, Grounding z Google Search, i Grounding z Google Maps).

• Zliczanie tokenów.

  • Zawsze zgłasza błąd. Liczba będzie się różnić w zależności od modelu hostowanego w chmurze i modelu na urządzeniu, więc nie ma intuicyjnego przejścia.

• Monitorowanie wykorzystania AI w konsoli Firebase w przypadku wnioskowania na urządzeniu.

  • Pamiętaj, że każde wnioskowanie za pomocą modeli hostowanych w chmurze można monitorować tak samo jak inne wnioskowanie za pomocą Firebase AI Logic client SDK na potrzeby internetu.

Prześlij opinię o korzystaniu z Firebase AI Logic