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


Możesz tworzyć aplikacje i funkcje na Androida oparte na AI z wnioskowaniem hybrydowym za pomocą Firebase AI Logic. Wnioskowanie hybrydowe umożliwia przeprowadzanie wnioskowania przy użyciu modeli na urządzeniu, gdy są one dostępne, i płynne przełączanie się na modele hostowane w chmurze, gdy nie są dostępne (i na odwrót).

Na tej stronie opisujemy, jak zacząć korzystać z pakietu SDK klienta, oraz przedstawiamy 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 SDK Firebase AI Logic 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 on warunkom korzystania z ML Kit oraz 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:

    • Zwiększona prywatność
    • Kontekst lokalny
    • Bezpłatne wnioskowanie
    • Funkcje offline

  • Korzystanie z funkcji hybrydowych:

    • Docieraj do większej liczby odbiorców dzięki uwzględnianiu dostępności modelu na urządzeniu i połączenia z internetem.

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

Wnioskowanie na urządzeniu obsługuje tylko generowanie tekstu w jednej turze (nie czat) z wyjściem strumieniowym lub niestrumieniowym. Obsługuje te funkcje generowania tekstu:

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

Zanim zaczniesz

Zwróć uwagę na te kwestie:

Obsługiwane urządzenia z Androidem i 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 kroki opisują ogólną konfigurację wymaganą w przypadku każdego obsługiwanego żądania promptu, które chcesz wysłać.

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

  1. Zaloguj się w Firebasekonsoli, a potem wybierz projekt w Firebase.

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

  3. Kliknij Rozpocznij, aby uruchomić przepływ pracy z instrukcjami, 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 interfejsu Gemini API”, zalecamy wybranie Gemini Developer API, który umożliwia szybkie rozpoczęcie korzystania bezpłatnie.

    W każdej chwili możesz skonfigurować Agent Platform Gemini API (formerly Vertex AI) (i wymagane 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. ten etap przepływu pracy będzie automatycznie egzekwować Firebase App Check w przypadku AI Logic, czyli krytycznej usługi, która pomaga chronić Gemini API, gdy jest on bezpośrednio dostępny z Twojej aplikacji. Na początku (patrz kroki opisane w dalszej części tego przewodnika) musisz skonfigurować dostawcę debugowania App Check na potrzeby lokalnego programowania, gdy App Check jest egzekwowany.

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

Krok 2. Dodaj wymagane pakiety SDK.

Firebase AI Logic SDK na Androida (firebase-ai) wraz z Firebase AI Logic On-Device SDK (firebase-ai-ondevice) zapewniają dostęp do interfejsów API do interakcji z modelami generatywnymi.

W pliku Gradle na poziomie modułu (aplikacji) (np. <project>/<app-module>/build.gradle.kts) dodaj zależności dla 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 Javy 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 programowania lokalnego

Od początku lipca 2026 r. w ramach procesu konfiguracji z przewodnikiem w konsoli AI LogicFirebase App Check jest automatycznie egzekwowane, aby chronić Gemini API. W przypadku programowania lokalnego musisz skonfigurować App Check dostawcę debugowania, aby pominąć atestację, zachowując jednocześnie wymuszanie App Check.

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

    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 logach poszukaj App Check tokena debugowania. 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 (na przykład 123a4567-b89c-12d3-e456-789012345678).

  3. Zarejestruj token debugowania w usłudze App Check:

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

    2. Znajdź aplikację, kliknij rozszerzone menu (), a potem wybierz Zarządzaj tokenami debugowania.

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

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, a jeśli nie, pobierz go.

Po pobraniu AICore będzie automatycznie aktualizować model. Więcej informacji o AICore i zarządzaniu pobieraniem modelu na urządzeniu znajdziesz w uwagach pod fragmentem 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ądzenie 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 końcowi natrafią na kod w aplikacji.

  • Jeśli model na urządzeniu jest niedostępny w momencie wysłania żądania wnioskowania na urządzeniu, pakiet SDK nie uruchomi automatycznie pobierania 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 wersji, aktualizowaniem modelu itp. Pamiętaj, że na urządzeniu zostanie pobrany tylko 1 model, więc jeśli inna aplikacja na urządzeniu pobrała już 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 wywołania onDeviceExtension?.warmUp() (obecnie dostępne tylko w przypadku Kotlina). 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 Gemini API dostawcę, aby wyświetlić na tej stronie treści i kod 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 tutaj są bardzo ogólne, ale szczegółowe informacje o zachowaniu tych trybów znajdziesz w sekcji Ustawianie trybu wnioskowania.

    • PREFER_ON_DEVICE: próba użycia modelu na urządzeniu; w przeciwnym razie powrót do modelu hostowanego 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 powrót do modelu 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 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

Zanim wypróbujesz ten przykład, zapoznaj się z sekcją Pierwsze kroki w tym przewodniku.

Możesz użyć generateContent(), aby wygenerować 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ż strumieniowe przesyłanie odpowiedzi tekstowych za pomocą generateContentStream (zamiast generateContent).

Generowanie tekstu na podstawie danych wejściowych w postaci tekstu i obrazu (multimodalnych)

Zanim wypróbujesz ten przykład, zapoznaj się z sekcją Pierwsze kroki w tym przewodniku.

Możesz użyć generateContent(), aby wygenerować tekst z prompta zawierającego tekst i maksymalnie 1 plik graficzny (tylko bitmapa). W tym celu musisz podać 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ż strumieniowe przesyłanie odpowiedzi tekstowych za pomocą generateContentStream (zamiast generateContent).

Co jeszcze możesz zrobić?

W przypadku środowisk hybrydowych możesz korzystać z różnych dodatkowych opcji i funkcji konfiguracji:

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

W wersji eksperymentalnej nie wszystkie funkcje modeli w chmurze są dostępne w przypadku wnioskowania na urządzeniu. Wnioskowanie na urządzeniu nie obsługuje jeszcze tych funkcji (ale są one zwykle dostępne w przypadku wnioskowania w chmurze).

  • Generuję obrazy

    • Może wrócić do modelu hostowanego w chmurze, ale ONLY_ON_DEVICE zwróci wyjątek.

  • generowanie tekstu z plików graficznych innych niż bitmapa (obraz wczytany do pamięci);

    • Może wrócić do modelu hostowanego w chmurze, ale ONLY_ON_DEVICE zwróci wyjątek.

  • generowanie tekstu na podstawie pliku zawierającego tylko obraz; W przypadku wnioskowania na urządzeniu musisz podać tekst w ramach żądania multimodalnego.

    • Może wrócić do modelu hostowanego w chmurze, ale ONLY_ON_DEVICE zwróci wyjątek.

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

    • Można wrócić do modelu hostowanego w chmurze, ale tryb ONLY_ON_DEVICE zwróci wyjątek.

  • generowanie tekstu na podstawie danych wejściowych w postaci dźwięku, obrazu i dokumentów (np. plików PDF);

    • Może wrócić do modelu hostowanego w chmurze, ale ONLY_ON_DEVICE zwróci wyjątek.

  • podawanie plików za pomocą adresów URL w żądaniach multimodalnych; W przypadku wnioskowania na urządzeniu musisz podać pojedynczy obraz jako bitmapę.

    • Jeśli podasz adres URL pliku za pomocą fileData (FileDataPart), może on wrócić do modelu hostowanego w chmurze (tryb ONLY_ON_DEVICE spowoduje wyjątek).
    • Jeśli umieścisz adres URL bezpośrednio w prompcie tekstowym, nie zostanie on automatycznie przekierowany do modelu hostowanego w chmurze (model na urządzeniu ignoruje umieszczone adresy URL).

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

    • Może wrócić do modelu hostowanego w chmurze, ale ONLY_ON_DEVICE zwróci wyjątek.

  • Czat wieloetapowy

    • nie przełącza się automatycznie na model hostowany w chmurze (wnioskowanie na urządzeniu łączy historię promptów w jeden prompt tekstowy; ponieważ model na urządzeniu nie rozróżnia ról i widzi historię jako jedną wiadomość, nie będzie tak precyzyjny jak model hostowany w chmurze).
    • Jeśli chcesz korzystać z czatu wieloetapowego, zalecamy używanie trybu ONLY_IN_CLOUD.

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

    • Nie przełącza się automatycznie na model hostowany w chmurze. Jeśli chcesz używać narzędzi, zalecamy tryb ONLY_IN_CLOUD.

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ń wnioskowanie na urządzeniu ma te ograniczenia (więcej informacji znajdziesz w dokumentacji ML Kit):

  • Użytkownik Twojej aplikacji musi korzystać z obsługiwanego urządzenia, aby wnioskowanie mogło odbywać się na urządzeniu.

  • Aplikacja może przeprowadzać wnioskowanie na urządzeniu tylko wtedy, gdy działa na pierwszym planie.

  • W przypadku wnioskowania na urządzeniu zweryfikowano tylko język angielski i koreański.

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

  • Zalecamy unikanie przypadków użycia wnioskowania na urządzeniu, 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 wiele żądań do interfejsu API w krótkim czasie spowoduje odpowiedź ErrorCode.BUSY. Jeśli wystąpi ten błąd, rozważ ponowienie żądania ze wzrastającym czasem do ponowienia. Może też zostać zwrócony błąd ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED, jeśli aplikacja przekroczy limit długoterminowy (np. dzienny).


Prześlij opinię o korzystaniu z usługi Firebase AI Logic