Crea esperienze ibride nelle app Apple con modelli ospitati sul dispositivo e sul cloud

Puoi creare app e funzionalità Apple basate sull'AI con l'inferenza ibrida utilizzando Firebase AI Logic. L'inferenza ibrida consente di eseguire l'inferenza utilizzando i modelli sul dispositivo (in particolare il framework Foundation Models di Apple), se disponibili, e di eseguire automaticamente il fallback ai modelli Google ospitati sul cloud (e viceversa).

Questa pagina descrive come iniziare a utilizzare l'SDK client, oltre a mostrare opzioni e funzionalità di configurazione aggiuntive, come la temperatura.

Tieni presente che l'inferenza sul dispositivo tramite Firebase AI Logic è supportata per le app Apple che utilizzano l'SDK Firebase AI Logic v12.13.0 o versioni successive ed eseguite su dispositivi con Apple Intelligence abilitato. È regolata dai requisiti di utilizzo accettabile per il framework Foundation Models di Apple.

Casi d'uso consigliati

  • L'utilizzo di un modello sul dispositivo per l'inferenza offre:

    • Maggiore privacy
    • Inferenza senza costi
    • Funzionalità offline

  • L'utilizzo della funzionalità ibrida offre:

    • Offrire a tutti i clienti un'esperienza app simile, indipendentemente dal dispositivo dell'utente finale
    • Migliorare la disponibilità delle funzionalità di AI generativa, indipendentemente dalla connettività internet, dalle limitazioni della quota o dalle funzionalità del dispositivo

Funzionalità, API e dispositivi supportati

Prima di implementare l'inferenza ibrida e sul dispositivo utilizzando Firebase AI Logic, esamina questa sezione per capire cosa è supportato per le app Apple.

Funzionalità e funzionalità supportate per l'inferenza sul dispositivo

L'inferenza sul dispositivo supporta solo la generazione di testo, in particolare le seguenti funzionalità di generazione di testo:

Assicurati di esaminare l'elenco dettagliato dell'inferenza ibrida o sul dispositivo non ancora supportata in fondo a questa pagina.

API e dispositivi supportati

Inizia

Assicurati di aver esaminato la sezione precedente che descrive le funzionalità, le API e i dispositivi supportati.

Questi passaggi iniziali descrivono la configurazione generale richiesta per qualsiasi richiesta di prompt supportata che vuoi inviare.

Passaggio 1: configura un progetto Firebase e connetti la tua app a Firebase

  1. Accedi alla Firebase console, quindi seleziona il tuo progetto Firebase.

  2. Nella Firebase console, vai a Servizi AI > AI Logic.

  3. Fai clic su Inizia per avviare un workflow guidato che ti aiuterà a configurare le API richieste e le risorse per il tuo progetto.

  4. Se richiesto, segui le istruzioni sullo schermo per registrare la tua app e aggiungere la configurazione Firebase alla tua app.

  5. Quando ti viene chiesto di scegliere un "provider dell'API Gemini", ti consigliamo di selezionare l' API Gemini Developer, che ti consente di iniziare rapidamente senza costi.

    In qualsiasi momento successivo, puoi sempre configurare l'Vertex AI Gemini API (e il relativo requisito di fatturazione).

  6. Continua il workflow per configurare le API richieste e i servizi associati per Firebase AI Logic.

    A partire dall'inizio di luglio 2026, questa fase del workflow applicherà automaticamente Firebase App Check per AI Logic, un servizio critico per proteggere Gemini API quando viene eseguito l'accesso direttamente dalla tua app. Nell'ambito della procedura di configurazione iniziale (vedi i passaggi più avanti in questa guida), dovrai configurare il App Check provider di debug per lo sviluppo locale quando App Check è applicato.

  7. Continua con il passaggio successivo di questa guida per aggiungere gli SDK richiesti alla tua app.

Passaggio 2: aggiungi gli SDK richiesti

Utilizza Swift Package Manager (SPM) per installare e gestire le dipendenze di Xcode. Il supporto ibrido è disponibile solo quando utilizzi SPM.

La libreria Firebase AI Logic fornisce l'accesso alle API per interagire con i modelli generativi. La libreria è inclusa nell'SDK Firebase per le piattaforme Apple (firebase-ios-sdk).

Se utilizzi già Firebase, assicurati che il pacchetto Firebase sia la versione 12.13.0 o successive.

  1. In Xcode, con il progetto dell'app aperto, vai a File > Add Package Dependencies (File > Aggiungi dipendenze pacchetto).

  2. Quando richiesto, aggiungi il repository dell'SDK delle piattaforme Apple di Firebase:

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

  3. Seleziona l'ultima versione dell'SDK.

  4. Seleziona le librerie FirebaseAILogic e FirebaseAppCheck.

Al termine, Xcode inizierà automaticamente a risolvere e a scaricare le tue dipendenze in background.

Passaggio 3: configura il provider di debug App Check per lo sviluppo locale

A partire dall'inizio di luglio 2026, nell'ambito del workflow di configurazione guidata per AI Logic nella console, Firebase App Check viene applicato automaticamente per proteggere l' Gemini API. Per lo sviluppo locale, devi configurare il App Check provider di debug per ignorare l'attestazione mantenendo comunque l' applicazione di App Check.

Ecco come utilizzare il provider di debug durante l'esecuzione interattiva dell'app in un simulatore (ad esempio, durante lo sviluppo locale):

  1. Nel progetto Xcode, importa FirebaseAppCheck e inizializza App Check con la factory del provider di debug prima di configurare 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. Ottieni il token di debug:

    1. Avvia l'app nel simulatore o sul dispositivo di test.

    2. Apri la console Xcode e cerca il token di debug App Check. Ad esempio:

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

    3. Copia il token (ad esempio, 123a4567-b89c-12d3-e456-789012345678).

  3. Registra il token di debug con App Check:

    1. Nella console Firebase, vai alla scheda Sicurezza > App Check > App.

    2. Trova la tua app, fai clic sul menu extra (), quindi seleziona Gestisci token di debug.

    3. Segui le istruzioni sullo schermo per registrare il token di debug.

Per informazioni dettagliate sul provider di debug (incluso come ottenere un nuovo token di debug), consulta la documentazione App Checkufficiale.

Passaggio 4: inizializza il servizio e crea un'istanza della sessione del modello

Fai clic sul tuo provider Gemini API per visualizzare contenuti specifici del provider e codice in questa pagina.

Configura quanto segue prima di inviare una richiesta di prompt al modello.

  1. Inizializza il servizio per il provider Gemini API scelto.

  2. Crea un'istanza GenerativeModelSession con un HybridModel.

  3. Imposta i modelli primary e secondary in base alle tue preferenze. Puoi impostare l'ordine dell'inferenza tentata:

    • Tenta prima l'inferenza sul dispositivo, ma consenti il fallback al cloud: imposta primary su un modello "di sistema" e secondary su un modello cloud.

    • Tenta prima l'inferenza nel cloud, ma consenti il fallback sul dispositivo: imposta primary su un modello cloud e secondary su un modello "di sistema".

    Tieni presente che l'SDK supporta l'impostazione di un solo model, il che significa che l'SDK tenterà solo l'inferenza sul dispositivo o nel cloud. Tuttavia, per un'esperienza ibrida, devi creare un HybridModel e impostare i modelli primary e secondary.

    Scopri di più sul comportamento delle "modalità di inferenza" (l'ordine dell'inferenza tentata) in Opzioni di configurazione.

L'esempio seguente mostra come tentare prima l'inferenza sul dispositivo, ma consentire il fallback al modello ospitato sul cloud:

// 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,
)

Passaggio 5: invia una richiesta di prompt a un modello

Questa sezione mostra come:

Genera testo da input di solo testo

Prima di provare questo esempio, assicurati di aver completato la sezione Inizia di questa guida.

Per generare testo da un prompt che contiene testo, utilizza respond(to:) come segue:

// 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)

Trasmetti testo da input di solo testo

Prima di provare questo esempio, assicurati di aver completato la sezione Inizia di questa guida.

Puoi ottenere interazioni più rapide senza attendere l'intero risultato della generazione del modello e utilizzare invece lo streaming per gestire i risultati parziali. Per trasmettere il testo generato da un prompt che contiene testo, utilizza streamResponse(to:) come segue:

// 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)
}

Cos'altro sai fare?

Puoi utilizzare varie opzioni e funzionalità di configurazione aggiuntive per le tue esperienze ibride:

Funzionalità non ancora supportate per l'inferenza ibrida o sul dispositivo

Trattandosi di una release sperimentale, non tutte le funzionalità di Firebase AI Logic o dei modelli ospitati sul cloud sono supportate.

  • Le seguenti funzionalità non sono supportate per le implementazioni ibride o sul dispositivo: modelli Imagen, API Gemini Live e modelli di prompt. Inoltre, non è consigliabile fare affidamento sul conteggio dei token perché il conteggio sarà diverso tra i modelli ospitati sul cloud e quelli sul dispositivo, quindi non esiste un fallback intuitivo.

  • Le seguenti funzionalità non sono ancora supportate per l'inferenza sul dispositivo. Se vuoi utilizzare una di queste funzionalità, ti consigliamo di utilizzare solo un modello ospitato sul cloud per un'esperienza più coerente.

    • Generazione di testo da input multimodali, come immagini, audio, video e documenti (PDF)

    • Generazione di contenuti multimediali, come immagini, audio o video

    • Invio di richieste che superano i 4096 token (o circa 3000 parole in inglese).

    • Fornire al modello sul dispositivo strumenti integrati per aiutarlo a generare la risposta (come l'esecuzione del codice, il contesto dell'URL e l'ancoraggio con la Ricerca Google)

  • Il monitoraggio dell'AI nella console Firebase non mostra alcun dato per l'inferenza sul dispositivo (inclusi i log sul dispositivo). Tuttavia, qualsiasi inferenza che utilizza un modello ospitato sul cloud può essere monitorata come altre inferenze tramite Firebase AI Logic.

Ulteriori limitazioni

Oltre a quanto sopra, l'inferenza sul dispositivo presenta le seguenti limitazioni:


Fornisci un feedback sulla tua esperienza con Firebase AI Logic