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 modelli on-device (in particolare il framework Foundation Models di Apple) quando disponibili e di passare senza problemi ai modelli Google ospitati nel cloud in caso contrario (e viceversa).

In questa pagina viene descritto come iniziare a utilizzare l'SDK client. Dopo aver completato questa configurazione standard, consulta le opzioni di configurazione e le funzionalità aggiuntive.

Tieni presente che l'inferenza on-device tramite Firebase AI Logic è supportata per le app Apple che utilizzano l'SDK Firebase AI Logic v12.13.0+ e vengono eseguite su dispositivi con Apple Intelligence abilitato. È regolato dai Requisiti di utilizzo accettabile per il framework dei foundation model di Apple.

Vai agli esempi di codice

Casi d'uso e funzionalità supportate

A seconda dei casi d'uso della tua app, puoi sfruttare diversi vantaggi delle esperienze on-device o ibride:

  • Vantaggi dell'utilizzo di un modello on-device per l'inferenza:

    • Privacy avanzata
    • Local Context
    • Inferenza senza costi
    • Funzionalità offline
  • Vantaggi dell'utilizzo di un approccio ibrido:

    • Offri un'esperienza con l'app simile, indipendentemente dal dispositivo dell'utente finale
    • Migliorare la disponibilità delle funzionalità di AI generativa, indipendentemente dalla connettività a internet, dalle limitazioni delle quote o dalle funzionalità del dispositivo

Funzionalità di inferenza on-device supportate

L'inferenza on-device supporta solo la generazione di testo, in particolare le seguenti funzionalità:

Assicurati di consultare l'elenco delle funzionalità non ancora supportate per l'inferenza ibrida o on-device in fondo a questa pagina.

API e dispositivi supportati

Le sezioni seguenti descrivono le API supportate, nonché i dispositivi supportati (e i relativi modelli on-device).

API supportate per l'inferenza in cloud e on-device

Dispositivi Apple supportati e relativi modelli on-device

Per l'inferenza on-device (che utilizza il framework dei modelli di base di Apple), puoi trovare un elenco di dispositivi con Apple Intelligence abilitata nella documentazione di Apple.

Inizia

Questi passaggi per iniziare 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 console Firebase, quindi seleziona il tuo progetto Firebase.

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

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

  4. Se richiesto, segui le istruzioni sullo schermo per registrare la tua app e aggiungere la configurazione di 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 Agent Platform Gemini API (formerly Vertex AI) (e il relativo requisito per la fatturazione).

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

    Questa fase del workflow applica automaticamente Firebase App Check per AI Logic, che è un servizio critico per proteggere Gemini API quando l'accesso avviene direttamente dalla tua app. Come parte dei primi passi (vedi i passaggi più avanti in questa guida), dovrai configurare il provider di debug App Check per lo sviluppo locale quando App Check viene applicato.

  7. Vai al passaggio successivo di questa guida per aggiungere gli SDK richiesti alla tua app.

Passaggio 2: aggiungi gli SDK necessari

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 successiva.

  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 Firebase per le piattaforme Apple:

    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

Nell'ambito del flusso di lavoro di configurazione guidata per AI Logic nella console, Firebase App Check viene applicato automaticamente per proteggere Gemini API. Per lo sviluppo locale, devi configurare il App Check provider di debug per bypassare 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 tuo 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 () e poi seleziona Gestisci token di debug.

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

Per informazioni dettagliate sul provider di debug (tra cui come ottenere un nuovo token di debug), consulta la documentazione ufficiale di App Check.

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

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

Prima di inviare una richiesta di prompt al modello, configura quanto segue.

  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 dei tentativi di inferenza:

    • Prova prima l'inferenza on-device, ma consenti il fallback al cloud: imposta primary su un modello "di sistema" e secondary su un modello cloud.

    • Prova prima l'inferenza nel cloud, ma consenti il fallback on-device: imposta primary su un modello cloud e secondary su un modello "system".

    Tieni presente che l'SDK supporta l'impostazione di un solo model, il che significa che l'SDK tenterà solo l'inferenza on-device 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 dei tentativi di inferenza) in Opzioni di configurazione.

L'esempio seguente mostra come provare prima l'inferenza on-device, ma consentire il fallback al modello ospitato nel 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 un 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:) in questo modo:

// 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 in streaming il testo generato da un input di solo testo

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

Puoi ottenere interazioni più rapide non aspettando l'intero risultato della generazione del modello, ma utilizzando lo streaming per gestire i risultati parziali. Per trasmettere in streaming il testo generato da un prompt che contiene testo, utilizza streamResponse(to:) in questo modo:

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

In quanto release sperimentale, non tutte le funzionalità dei modelli ospitati nel cloud o dell'SDK Firebase AI Logic sono disponibili per l'inferenza ibrida o on-device.

Funzionalità non ancora supportate per le implementazioni ibride

Le seguenti funzionalità non possono essere utilizzate con le implementazioni ibride (né on-device né tramite fallback cloud):

  • Gemini Live API: lo streaming bidirezionale in tempo reale non è supportato.

  • Template di prompt del server: i template di prompt del server gestiti non sono supportati.

  • Conteggio dei token: non fare affidamento sul conteggio dei token perché il conteggio sarà diverso tra i modelli ospitati nel cloud e quelli on-device, quindi non esiste un fallback intuitivo.

Funzionalità non ancora supportate per l'inferenza on-device

Le seguenti funzionalità non sono ancora supportate per l'inferenza on-device, ma sono disponibili per i modelli ospitati nel cloud.

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

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

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

  • Fornire al modello on-device strumenti integrati per aiutarlo a generare la sua risposta (come l'esecuzione di codice, il contesto dell'URL, il grounding con Google Search e il grounding con Google Maps). Tuttavia, è supportata la possibilità di fornire i propri strumenti utilizzando le chiamate di funzione.

  • Il monitoraggio AI nella console Firebase non mostra dati per l'inferenza on-device (inclusi i log del dispositivo on-device). Tuttavia, qualsiasi inferenza che utilizza un modello ospitato nel cloud può essere monitorata come qualsiasi altra inferenza tramite Firebase AI Logic.

Ulteriori limitazioni

Oltre a quanto sopra, l'inferenza on-device presenta le seguenti limitazioni:


Invia un feedback sulla tua esperienza con Firebase AI Logic