Inizia: accedi all'API Gemini tramite il framework Foundation Models di Apple


Al WWDC 2026, Apple ha aperto il framework Foundation Models agli adattatori di modelli di terze parti, il che significa che puoi accedere ai modelli ospitati nel cloud (come Gemini) tramite il framework Foundation Models utilizzando la stessa API che utilizzeresti per accedere ai modelli on-device.

Nella tua app, puoi scambiare l'istanza del modello per indirizzare le richieste all'inferenza on-device o nel cloud in base al tuo caso d'uso:

  • I modelli on-device offrono la massima privacy, zero costi e supporto offline.
  • I modelli Gemini ospitati nel cloud offrono finestre contestuali di grandi dimensioni, funzionalità avanzate e maggiore capacità di ragionamento.

Puoi accedere ai modelli Geminiospitati nel cloud tramite il framework Foundation Models di Apple utilizzando l'SDK Firebase per le piattaforme Apple – in particolare la libreria Firebase AI Logic. Questa guida ti mostra come iniziare.

Per proteggere l'accesso ai modelli Gemini, questa guida ti mostra anche come configurare Firebase App Check, un servizio fondamentale anche durante lo sviluppo.

Prerequisiti

  • Installa l'ultima versione beta di Xcode 27.

  • Un simulatore di piattaforma Apple o un dispositivo fisico, entrambi con la versione beta del sistema operativo corrispondente (ad esempio, iOS 27 beta).

  • Un nuovo progetto Xcode di un'app per piattaforme Apple che utilizza un'interfaccia SwiftUI.

Modelli Gemini supportati

L'integrazione con il framework Foundation Models di Apple supporta i seguenti Gemini modelli.

  • Modelli di uso generico

    • gemini-3.1-pro-preview
    • gemini-3.6-flash (e il modello precedente gemini-3.5-flash)
    • gemini-3.5-flash-lite (e il modello precedente gemini-3.1-flash-lite)

  • Modelli di generazione di immagini

    • gemini-3-pro-image (noto anche come "Nano Banana Pro")
    • gemini-3.1-flash-image (noto anche come "Nano Banana 2")
    • gemini-3.1-flash-lite-image (noto anche come "Nano Banana 2 Lite")

I modelli Gemini Live API e i modelli Imagen non sono supportati. Tieni presente che i modelli Gemini 2.5 sono tecnicamente supportati, ma non sono consigliati per i nuovi progetti e richiedono una configurazione speciale non trattata in queste guide.

Passaggio 1: crea un progetto Firebase

Ti consigliamo di iniziare con un nuovo progetto Firebase per esplorare questa integrazione.

  1. Accedi alla Firebase console.

  2. Fai clic su Crea un nuovo progetto Firebase.

  3. Segui le istruzioni sullo schermo. Non devi attivare Google Analytics.

Passaggio 2: connetti la tua app a Firebase

Per connettere la tua app a Firebase, devi registrarla nel tuo progetto Firebase e aggiungere un file di configurazione al codebase.

  1. Al centro della panoramica del progetto pagina, fai clic sull'icona iOS+ per avviare il flusso di lavoro di configurazione.

  2. Registra la tua app:

    1. Inserisci l'ID pacchetto della tua app. Assicurati che corrisponda all'ID pacchetto del progetto che stai creando in Xcode.

    2. Fai clic su Registra app.

  3. Aggiungi il file di configurazione di Firebase. Questo file contiene le impostazioni dell'SDK Firebase per la connessione al tuo progetto Firebase.

    1. Fai clic su Scarica GoogleService-Info.plist per ottenere il file di configurazione.

    2. Sposta GoogleService-Info.plist nella root del progetto Xcode e aggiungilo a tutti i target.

    3. Fai clic su Avanti nella Firebase console.

  4. Il flusso di lavoro nella console fornisce generiche istruzioni per aggiungere l' SDK Firebase alla tua app, quindi vai al passaggio successivo di questa guida per istruzioni specifiche per Firebase AI Logic.

Passaggio 3: aggiungi le librerie Firebase e inizializza Firebase nella tua app

  1. Utilizza Swift Package Manager per aggiungere le librerie Firebase richieste:

    1. In Xcode, con il progetto dell'app aperto, seleziona File > Add Packages (File > Aggiungi pacchetti).

    2. Inserisci l'URL del repository dell'SDK Firebase per Apple:

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

    3. Seleziona la regola di dipendenza come Branch e inserisci wwdc26-preview.

    4. Fai clic su Add Package (Aggiungi pacchetto). Xcode risolverà e scaricherà le dipendenze.

    5. Quando richiesto, aggiungi le librerie FirebaseAILogic e FirebaseAppCheck al target dell'app.

  2. Inizializza Firebase all'avvio dell'app aggiungendo il seguente codice al punto di ingresso principale dell'app:

    import SwiftUI
import FirebaseCore

@main
struct YourApp: App {
  init() {
    FirebaseApp.configure()
  }

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

Passaggio 4: attiva e proteggi i servizi Firebase

Ora che la tua app è configurata per utilizzare Firebase, devi attivare il Firebase AI Logic servizio e proteggere l'accesso alle API associate utilizzando Firebase App Check.

Passaggio 4a: configura Firebase AI Logic nel tuo progetto Firebase

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

  2. Fai clic su Inizia per avviare il flusso di lavoro di configurazione guidata.

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

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

  4. Continua il flusso di lavoro per configurare le API richieste e i servizi associati per Firebase AI Logic.

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

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

Per lo sviluppo locale, devi configurare il App Check provider di debug per ignorare l'attestazione mantenendo comunque l'applicazione di App Check.

  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 () 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 (incluso come ottenere un nuovo token di debug), consulta la documentazione App Checkufficiale.

Passaggio 5: inizializza il servizio AI Logic nella tua app

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

Ora che Firebase e App Check sono configurati, puoi inizializzare il Firebase AI Logic servizio nella tua app.

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.6-flash")

Passaggio 6: invia una richiesta a un modello Gemini

Ora che Firebase AI Logic è configurato, protetto e inizializzato nella tua app, puoi inviare una richiesta a un modello Gemini.

L'esempio seguente mostra il tipo di richiesta più semplice: la generazione di testo da un prompt di solo testo:

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.6-flash")


// Create a session by injecting the model into Apple's `LanguageModelSession`.
let session = LanguageModelSession(model: model)

// Generate a text response to a prompt.
let response = try await session.respond(to: "Write a story about a magic backpack.")
print(response.content)

Gemini modelli supportano anche altri tipi di richieste, come l'analisi di immagini e PDF , la generazione di output JSON strutturato e la generazione di immagini (utilizzando i modelli "Nano Banana"). Vedi esempi di questi tipi di richieste nella documentazione o nell'app di esempio.

Visualizza in streaming la risposta

Puoi ottenere interazioni più rapide senza attendere l'intero risultato della generazione del modello e utilizzando invece lo streaming per gestire i risultati parziali. Per visualizzare la risposta in streaming, utilizza streamResponse(to:) anziché respond(to:).

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.6-flash")


// Create a session by injecting the model into Apple's `LanguageModelSession`.
let session = LanguageModelSession(model: model)

// Generate a streamed text response to a prompt.
// To stream the response, use `streamResponse(to:)` instead of `respond(to:)`
let stream = session.streamResponse(to: "Write a story about a magic backpack.")
var response = ""
for try await snapshot in stream {
  // The snapshot contains *all* content generated so far.
  response = snapshot.content
}

Passaggi successivi


Fornisci feedback sull'accesso a Gemini API tramite il framework Foundation Models di Apple