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


Za pomocą Firebase AI Logic możesz tworzyć aplikacje na Androida i funkcje oparte na AI, które korzystają z wnioskowania hybrydowego. Wnioskowanie hybrydowe umożliwia uruchamianie wnioskowania za pomocą modeli na urządzeniu, gdy są one dostępne, i płynne przełączanie się na modele hostowane w chmurze w przeciwnym razie (i odwrotnie).

Na tej stronie dowiesz się, jak zacząć korzystać z pakietu SDK klienta, oraz poznasz dodatkowe opcje konfiguracji i możliwości.

Pamiętaj, że wnioskowanie na urządzeniu za pomocą Firebase AI Logic jest obsługiwane w przypadku aplikacji na Androida korzystających z pakietu Firebase AI Logic SDK w wersji 17.10.0 lub nowszej (BoM w wersji 34.10.0 lub nowszej) i działających na określonych urządzeniach. Podlega ono warunkom korzystania z ML Kit, a także warunkom dotyczącym aspektów generatywnej AI w ML Kit.

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,
    • bezpłatne wnioskowanie,
    • funkcje offline.

  • Korzystanie z funkcji hybrydowych zapewnia:

    • dotarcie do większej liczby odbiorców dzięki uwzględnieniu dostępności modelu na urządzeniu i 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 jednym kroku (nie czat) z wyjściem strumieniowym lub niestrumieniowym. Obsługuje te funkcje generowania tekstu:

U dołu tej strony znajdziesz listę funkcji, które nie są jeszcze dostępne w przypadku wnioskowania na urządzeniu.

Zanim zaczniesz

Pamiętaj o tych kwestiach:

Obsługiwane urządzenia z Androidem i ich modele na urządzeniu

W przypadku wnioskowania na urządzeniu (które korzysta z Prompt API z ML Kit) listę obsługiwanych urządzeń i ich modeli na urządzeniu znajdziesz w dokumentacji ML Kit.

Rozpocznij

Te instrukcje dla początkujących opisują ogólną konfigurację wymaganą w przypadku każdego obsługiwanego żądania prompta, które chcesz wysłać.

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

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

  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ę 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 dla Firebase AI Logic.

    Od początku lipca 2026 r. na tym etapie procesu automatycznie będzie wymuszane Firebase App Check w przypadku AI Logic, co jest krytyczną usługą, która pomaga chronić Gemini API, gdy jest ono dostępne bezpośrednio z aplikacji. W ramach rozpoczęcia pracy (patrz kroki w dalszej części tego przewodnika) 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 2. Dodaj wymagane pakiety SDK

Pakiet Firebase AI Logic SDK na Androida (firebase-ai) wraz z pakietem Firebase AI Logic On-Device SDK (firebase-ai-ondevice) zapewniają dostęp do interfejsów API umożliwiających interakcję z modelami generatywnymi.

W pliku Gradle na poziomie modułu (aplikacji) (np. <project>/<app-module>/build.gradle.kts) dodaj zależności od bibliotek Firebase AI Logic i App Check na Androida:

Kotlin 

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:18.0.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta06")
  implementation("com.google.firebase:firebase-appcheck-debug:20.0.0")
}

Java

W przypadku języka Java musisz dodać 2 dodatkowe biblioteki.

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:18.0.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta06")
  implementation("com.google.firebase:firebase-appcheck-debug:20.0.0")

  // Required for one-shot operations (to use `ListenableFuture` from Guava Android)
  implementation("com.google.guava:guava:31.0.1-android")

  // Required for streaming operations (to use `Publisher` from Reactive Streams)
  implementation("org.reactivestreams:reactive-streams:1.0.4")
}

Krok 3. 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 będzie wymuszane Firebase App Check, aby chronić Gemini API. Na potrzeby lokalnego programowania musisz skonfigurować App Check dostawcę debugowania sprawdzania aplikacji, aby pominąć atest, ale nadal utrzymywać wymuszanie App Check.

  1. W kompilacji do debugowania skonfiguruj App Check tak, aby używało dostawcy debugowania fabryki:

    Kotlin

    Firebase.initialize(context = this)
Firebase.appCheck.installAppCheckProviderFactory(
    DebugAppCheckProviderFactory.getInstance(),
)

    Java

    FirebaseApp.initializeApp(/*context=*/ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance());

  2. Uzyskaj token debugowania:

    1. Uruchom aplikację w emulatorze lub na urządzeniu testowym.

    2. W dziennikach poszukaj tokena debugowania App Check. Przykład:

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. Skopiuj token (np. 123a4567-b89c-12d3-e456-789012345678).

  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 (), 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 dokumentacji.App Check

Krok 4. Sprawdź, czy model na urządzeniu jest dostępny

Za pomocą FirebaseAIOnDevice, sprawdź, czy model na urządzeniu jest dostępny, i pobierz go, jeśli nie jest dostępny.

Po pobraniu AICore będzie automatycznie aktualizować model. Więcej informacji o AICore i zarządzaniu pobieraniem modelu na urządzeniu znajdziesz w uwagach po fragmencie kodu.

Kotlin 

val status = FirebaseAIOnDevice.checkStatus()
when (status) {
  OnDeviceModelStatus.UNAVAILABLE -> {
    Log.w(TAG, "On-device model is unavailable")
  }

  OnDeviceModelStatus.DOWNLOADABLE -> {
    FirebaseAIOnDevice.download().collect { status ->
      when (status) {
        is DownloadStatus.DownloadStarted ->
          Log.w(TAG, "Starting download - ${status.bytesToDownload}")

        is DownloadStatus.DownloadInProgress ->
          Log.w(TAG, "Download in progress ${status.totalBytesDownloaded} bytes downloaded")

        is DownloadStatus.DownloadCompleted ->
          Log.w(TAG, "On-device model download complete")

        is DownloadStatus.DownloadFailed ->
          Log.e(TAG, "Download failed ${status}")
      }
    }
  }
  OnDeviceModelStatus.DOWNLOADING -> {
    Log.w(TAG, "On-device model is being downloaded")
  }

  OnDeviceModelStatus.AVAILABLE -> {
    Log.w(TAG, "On-device model is available")
  }
}

Java 

Checking for, downloading, and warming up the model is not yet available for Java.

However, all other APIs and interactions in this guide are available for Java.

Pamiętaj o tych kwestiach dotyczących pobierania modelu na urządzeniu:

  • Czas pobierania modelu na urządzeniu zależy od wielu czynników, w tym od sieci.

  • Jeśli Twój kod używa modelu na urządzeniu do wnioskowania podstawowego lub rezerwowego, upewnij się, że model jest pobierany na wczesnym etapie cyklu życia aplikacji, aby był dostępny, zanim użytkownicy napotkają kod w aplikacji.

  • Jeśli model na urządzeniu nie jest dostępny , gdy wysyłane jest żądanie wnioskowania na urządzeniu, pakiet SDK nie spowoduje automatycznie pobrania modelu na urządzeniu. Pakiet SDK przełączy się na model hostowany w chmurze lub zgłosi wyjątek (szczegółowe informacje o działaniu trybów wnioskowania).

  • AICore (usługa systemowa Androida) zarządza pobieraniem modelu i jego wersji, aktualizowaniem modelu itp. Pamiętaj, że na urządzeniu będzie pobrany tylko 1 model. Jeśli inna aplikacja na urządzeniu wcześniej pobrała model na urządzeniu, to sprawdzenie zwróci informację, że model jest dostępny.

Optymalizacja czasu oczekiwania

Aby zoptymalizować pierwsze wywołanie wnioskowania, możesz użyć w aplikacji funkcji onDeviceExtension?.warmUp() (obecnie dostępna tylko w Kotlinie). Spowoduje to wczytanie modelu na urządzeniu do pamięci i zainicjowanie komponentów środowiska wykonawczego.

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

Kliknij dostawcę Gemini API, aby wyświetlić na tej stronie treści i kod dotyczące tego dostawcy.

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

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

  2. Utwórz instancję GenerativeModel i ustaw mode na jedną z tych wartości. Opisy są bardzo ogólne, ale szczegółowe informacje o działaniu tych trybów znajdziesz w artykule Ustawianie trybu wnioskowania.

    • PREFER_ON_DEVICE: próba użycia modelu na urządzeniu; w przeciwnym razie przełącz się na model hostowany w chmurze.

    • ONLY_ON_DEVICE: próba użycia modelu na urządzeniu; w przeciwnym razie zgłoś wyjątek.

    • PREFER_IN_CLOUD: próba użycia modelu hostowanego w chmurze; w przeciwnym razie przełącz się na model na urządzeniu.

    • ONLY_IN_CLOUD: próba użycia modelu hostowanego w chmurze; w przeciwnym razie zgłoś wyjątek.

Kotlin 

// Using this SDK to access on-device inference is an Experimental release and requires opt-in
@OptIn(PublicPreviewAPI::class)

// ...

// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "CLOUD_MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.PREFER_ON_DEVICE)
    )

Java 

// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
    .generativeModel(
        "CLOUD_MODEL_NAME",
        new OnDeviceConfig(InferenceMode.PREFER_ON_DEVICE)
    );

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

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

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

Zanim wypróbujesz ten przykład, upewnij się, że masz za sobą sekcję Rozpocznij w tym przewodniku.

Za pomocą generateContent() możesz generować tekst na podstawie prompta zawierającego tekst:

Kotlin 

// Imports + initialization of Gemini API backend service + creation of model instance

// Provide a prompt that contains text
val prompt = "Write a story about a magic backpack."

// To generate text output, call generateContent with the text input
val response = model.generateContent(prompt)
print(response.text)

Java 

// Imports + initialization of Gemini API backend service + creation of model instance

// Provide a prompt that contains text
Content prompt = new Content.Builder()
    .addText("Write a story about a magic backpack.")
    .build();

// To generate text output, call generateContent with the text input
ListenableFuture<GenerateContentResponse> response = model.generateContent(prompt);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

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)

Zanim wypróbujesz ten przykład, upewnij się, że masz za sobą sekcję Rozpocznij w tym przewodniku.

Za pomocą generateContent() możesz generować tekst na podstawie prompta zawierającego tekst i maksymalnie 1 plik obrazu (tylko Bitmap) – podając mimeType każdego pliku wejściowego i sam plik.

Kotlin 

// Imports + initialization of Gemini API backend service + creation of model instance

// Loads an image from the app/res/drawable/ directory
val bitmap: Bitmap = BitmapFactory.decodeResource(resources, R.drawable.sparky)

// Provide a prompt that includes the image specified above and text
val prompt = content {
  image(bitmap)
  text("What developer tool is this mascot from?")
}

// To generate text output, call generateContent with the prompt
val response = model.generateContent(prompt)
print(response.text)

Java 

// Imports + initialization of Gemini API backend service + creation of model instance

Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.sparky);

// Provide a prompt that includes the image specified above and text
Content content = new Content.Builder()
        .addImage(bitmap)
        .addText("What developer tool is this mascot from?")
        .build();

// To generate text output, call generateContent with the prompt
ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

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 rozwiązań hybrydowych możesz używać różnych dodatkowych opcji konfiguracji i możliwości:

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

W wersji eksperymentalnej nie wszystkie możliwości modeli w chmurze są dostępne w przypadku wnioskowania na urządzeniu.

Funkcje wymienione w tej sekcji nie są jeszcze dostępne w przypadku wnioskowania na urządzeniu. Jeśli chcesz korzystać z którejś z tych funkcji, zalecamy używanie trybu wnioskowania ONLY_IN_CLOUD, aby zapewnić większą spójność.

  • Generowanie tekstu na podstawie typów plików obrazów innych niż Bitmap (obraz wczytany do pamięci).

  • Generowanie tekstu na podstawie więcej niż 1 pliku obrazu.

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

  • Generowanie obrazów za pomocą modeli Gemini.

  • Udostępnianie plików za pomocą adresów URL w żądaniach multimodalnych. Modele na urządzeniu wymagają podania plików jako danych wbudowanych.

  • Wysyłanie żądań przekraczających 4000 tokenów (czyli około 3000 słów w języku angielskim).

  • Czat wieloetapowy.

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

Monitorowanie wykorzystania AI w konsoli Firebase nie pokazuje żadnych danych dotyczących wnioskowania na urządzeniu (w tym dzienników urządzenia). Jednak każde wnioskowanie, które korzysta z modelu hostowanego w chmurze, można monitorować tak samo jak inne wnioskowanie za pomocą Firebase AI Logic.

Dodatkowe ograniczenia

Oprócz powyższych ograniczeń wnioskowaniena urządzeniu ma te ograniczenia (więcej informacji znajdziesz w dokumentacji ML Kit):

  • Użytkownik aplikacji musi korzystać z obsługiwanego urządzenia do wnioskowania na urządzeniu.

  • Aplikacja może uruchamiać wnioskowanie na urządzeniu tylko wtedy, gdy jest na pierwszym planie.

  • Wnioskowanie na urządzeniu zostało zweryfikowane tylko w języku angielskim i koreańskim.

  • Maksymalny limit tokenów dla całego żądania wnioskowania na urządzeniu wynosi 4000 tokenów. Jeśli Twoje żądania mogą przekroczyć ten limit, skonfiguruj tryb wnioskowania, który może używać modelu hostowanego w chmurze.

  • Nie zalecamy używania wnioskowania na urządzeniu w przypadkach, które wymagają długich danych wyjściowych (ponad 256 tokenów).

  • AICore (usługa systemowa Androida, która zarządza modelami na urządzeniu) wymusza limit wnioskowania na aplikację. Zbyt duża liczba żądań do interfejsu API w krótkim czasie spowoduje odpowiedź ErrorCode.BUSY. Jeśli otrzymujesz ten błąd, rozważ użycie wzrastającego czasu do ponowienia, aby ponowić żądanie. Jeśli aplikacja przekroczy limit długotrwały (np. dzienny), może też zostać zwrócony kod ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED.


Prześlij opinię o Firebase AI Logic