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

Możesz tworzyć oparte na AI aplikacje i funkcje Apple z wnioskowaniem hybrydowym za pomocą Firebase AI Logic. Wnioskowanie hybrydowe umożliwia przeprowadzanie wnioskowania przy użyciu modeli na urządzeniu (w szczególności platformy modeli podstawowych Apple) w przypadku ich dostępności i płynne przełączanie się na modele Google hostowane w chmurze w innych przypadkach (i odwrotnie).

Na tej stronie znajdziesz informacje o tym, jak zacząć korzystać z pakietu SDK klienta, a także dodatkowe opcje i możliwości konfiguracji, takie jak temperatura.

Pamiętaj, że wnioskowanie na urządzeniu za pomocą Firebase AI Logic jest obsługiwane w przypadku aplikacji Apple korzystających z Firebase AI Logic SDK w wersji 12.13.0 lub nowszej i działających na urządzeniach z włączoną funkcją Apple Intelligence. Podlega on wymaganiom dotyczącym dopuszczalnego użytkowania platformy modeli podstawowych Apple.

Zalecane przypadki użycia

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

    • Zwiększona prywatność
    • Wnioskowanie bez opłat
    • Funkcje offline

  • Korzystanie z funkcji hybrydowych:

    • Zapewnianie wszystkim klientom podobnych wrażeń związanych z aplikacją niezależnie od urządzenia użytkownika.
    • Zwiększanie dostępności funkcji opartych na generatywnej AI niezależnie od połączenia z internetem, limitów czy możliwości urządzenia.

Obsługiwane funkcje, interfejsy API i urządzenia

Zanim wdrożysz wnioskowanie hybrydowe i na urządzeniu za pomocą logiki AI w Firebase, zapoznaj się z tą sekcją, aby dowiedzieć się, co jest obsługiwane w przypadku aplikacji na urządzenia Apple.

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

Wnioskowanie na urządzeniu obsługuje tylko generowanie tekstu, a konkretnie te funkcje:

Na dole tej strony znajdziesz szczegółową listę nieobsługiwanych jeszcze wnioskowań hybrydowych i na urządzeniu.

Obsługiwane interfejsy API i urządzenia

Rozpocznij

Sprawdź sekcję powyżej, w której opisujemy obsługiwane funkcje, interfejsy API i urządzenia.

Te kroki wprowadzające 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 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ę monit, 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 każdej chwili możesz później skonfigurować Agent Platform Gemini API (formerly Vertex AI) (i jego wymagania dotyczące płatności).

  6. Kontynuuj przepływ pracy, aby skonfigurować wymagane interfejsy API i powiązane usługi dla Firebase AI Logic.

    Na początku lipca 2026 roku ten etap przepływu pracy będzie automatycznie wymagaćFirebase App Check w przypadku AI Logic, co jest kluczową usługą pomagającą chronić Gemini API, gdy jest on bezpośrednio dostępny z Twojej aplikacji. Aby rozpocząć (patrz kroki w dalszej części tego przewodnika), musisz skonfigurować App Check dostawcę debugowania na potrzeby lokalnego programowania, gdy App Check jest wymagany.

  7. Przejdź do kolejnego kroku tego przewodnika, aby dodać do aplikacji wymagane pakiety SDK.

Krok 2. Dodaj wymagane pakiety SDK

Do instalowania zależności Xcode i zarządzania nimi używaj Swift Package Manager (SPM). Obsługa hybrydowa jest dostępna tylko w przypadku korzystania z SPM.

Firebase AI Logic Biblioteka zapewnia dostęp do interfejsów API do interakcji z modelami generatywnymi. Biblioteka jest częścią pakietu SDK Firebase na platformy Apple (firebase-ios-sdk).

Jeśli korzystasz już z Firebase, upewnij się, że pakiet Firebase ma wersję 12.13.0 lub nowszą.

  1. W Xcode otwórz projekt aplikacji i kliknij File > Add Package Dependencies (Plik > Dodaj zależności pakietu).

  2. Gdy pojawi się odpowiedni komunikat, dodaj repozytorium pakietu SDK Firebase na platformy Apple:

    https://github.com/firebase/firebase-ios-sdk

  3. Wybierz najnowszą wersję pakietu SDK.

  4. Wybierz biblioteki FirebaseAILogic i FirebaseAppCheck.

Po zakończeniu Xcode automatycznie zacznie przetwarzać i pobierać zależności w tle.

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

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ąć atestowanie, ale nadal utrzymywać egzekwowanie App Check.

Aby użyć dostawcy debugowania podczas interaktywnego uruchamiania aplikacji w symulatorze (np. podczas lokalnego tworzenia):

  1. W projekcie Xcode zaimportuj FirebaseAppCheck i zainicjuj App Check za pomocą fabryki dostawcy debugowania przed skonfigurowaniem Firebase.

    import SwiftUI
import FirebaseCore
import FirebaseAppCheck

@main
struct YourApp: App {
  init() {
    let providerFactory = AppCheckDebugProviderFactory()
    AppCheck.setAppCheckProviderFactory(providerFactory)
    FirebaseApp.configure()
  }

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

  2. Uzyskaj token debugowania:

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

    2. Otwórz konsolę Xcode i poszukaj tokena debugowania App Check. Przykład:

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.

    3. Skopiuj token (np. 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. Zainicjuj usługę i utwórz instancję sesji 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 ustawienia.

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

  2. Utwórz instancję GenerativeModelSession z HybridModel.

  3. Ustaw modele primary i secondary zgodnie ze swoimi preferencjami. Możesz ustawić kolejność prób wnioskowania:

    • Najpierw spróbuj wywnioskować odpowiedź na urządzeniu, ale zezwól na powrót do chmury: ustaw primary na model „systemowy”, a secondary na model w chmurze.

    • Najpierw spróbuj wnioskowania w chmurze, ale zezwól na powrót do wnioskowania na urządzeniu: ustaw primary na model w chmurze, a secondary na model „systemowy”.

    Pamiętaj, że pakiet SDK obsługuje ustawienie tylko jednego parametru model, co oznacza, że pakiet SDK będzie tylko próbował wnioskowania na urządzeniu lub w chmurze. Jeśli jednak chcesz korzystać z hybrydowego środowiska, musisz utworzyć HybridModel i ustawić modele primary i secondary.

    Więcej informacji o działaniu „trybów wnioskowania” (kolejności prób wnioskowania) znajdziesz w sekcji Opcje konfiguracji.

Poniższy przykład pokazuje, jak najpierw spróbować wnioskowania na urządzeniu, ale zezwolić na powrót do modelu hostowanego w chmurze:

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Initialize a cloud model that supports your use case.
let cloudModel = ai.geminiModel(name: "GEMINI_MODEL_NAME")
// Initialize an on-device model that supports your use case.
let systemModel = FirebaseAI.SystemLanguageModel.default

// Create a Hybrid Model.
// Provide your preferred model as `primary` and your fallback model as `secondary`.
// In this example, attempt to use on-device model; otherwise, fall back to cloud.
let hybridModel = HybridModel(
  primary: systemModel,
  secondary: cloudModel
)

// Create a GenerativeModelSession with the HybridModel created earlier.
let session = firebaseAI.generativeModelSession(
  model: hybridModel,
)

Krok 5. Wyślij do modelu prośbę

W tej sekcji dowiesz się, jak:

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.

Aby wygenerować tekst na podstawie prompta, który zawiera tekst, użyj znaku respond(to:) w ten sposób:

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

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

// To generate text output, call `respond(to:)` with the text input
let response = try await session.respond(to: prompt)
print(response.content)

Przesyłanie strumieniowe tekstu z danych wejściowych zawierających tylko tekst

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

Możesz uzyskać szybsze interakcje, nie czekając na cały wynik wygenerowany przez model, i zamiast tego użyć strumieniowania do obsługi częściowych wyników. Aby przesyłać strumieniowo wygenerowany tekst z prompta zawierającego tekst, użyj streamResponse(to:) w ten sposób:

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

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

// To stream generated text output, call `streamResponse(to:)` with the text input
let stream = session.streamResponse(to: prompt)
for try await snapshot in stream {
  print(snapshot.content)
}

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 obsługiwane w przypadku wnioskowania hybrydowego lub na urządzeniu

W wersji eksperymentalnej nie wszystkie funkcje Firebase AI Logic ani modeli hostowanych w chmurze są obsługiwane.

  • W przypadku implementacji hybrydowych i na urządzeniu nie są obsługiwane te elementy: szablony promptów Gemini Live API i szablony promptów serwera. Nie należy też polegać na tokenach zliczania, ponieważ liczba będzie się różnić w przypadku modeli hostowanych w chmurze i na urządzeniu, więc nie ma intuicyjnego rozwiązania rezerwowego.

  • Te funkcje nie są jeszcze obsługiwane w przypadku wnioskowania na urządzeniu. Jeśli chcesz korzystać z tych funkcji, zalecamy używanie tylko modelu hostowanego w chmurze, aby zapewnić sobie większą spójność.

    • generowanie tekstu na podstawie danych multimodalnych, takich jak obrazy, dźwięk, filmy i dokumenty (PDF);

    • generowanie multimediów, takich jak obrazy, dźwięk lub filmy;

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

    • Udostępnianie modelu na urządzeniu wbudowanych narzędzi, które pomagają mu generować odpowiedź (np. wykonywanie kodu, kontekst adresu URL i grounding z wyszukiwarką Google).

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

Dodatkowe ograniczenia

Oprócz powyższych ograniczeń wnioskowanie na urządzeniu ma te ograniczenia:


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