Opzioni di configurazione per le esperienze ibride nelle app Apple


Questa pagina descrive le seguenti opzioni di configurazione per le esperienze ibride e sul dispositivo:

Assicurati di aver completato la guida introduttiva alla creazione di esperienze ibride.

Imposta una "modalità di inferenza"

Gli esempi nella guida introduttiva mostrano come implementare prima il tentativo di inferenza sul dispositivo e poi il fallback al modello ospitato sul cloud. Questo è solo uno dei "modelli di inferenza" disponibili che puoi implementare.

Inferenza ibrida

  • Preferisci l'inferenza sul dispositivo: imposta primary su un modello "di sistema" e secondary su un modello cloud.

    Tenta di utilizzare il modello sul dispositivo se è disponibile e supporta il tipo di richiesta. In caso contrario, registra un errore sul dispositivo e poi ripristina automaticamente il modello ospitato sul cloud.

    // Imports + initialization of Gemini API backend service
// ...

// 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 GenerativeModelSession with a hybrid model.
// Provide your preferred model as `primary` and your fallback model as `secondary`
// Attempt to use the on-device model; otherwise, fall back to the cloud-hosted model.
let session = ai.generativeModelSession(
  model: .hybridModel(primary: systemModel, secondary: cloudModel)
)

  • Preferisci l'inferenza nel cloud: imposta primary su un modello cloud e secondary su un modello "di sistema".

    Tenta di utilizzare il modello ospitato sul cloud se il dispositivo è online e se il modello è disponibile. Se il dispositivo è offline, torna al modello sul dispositivo. In tutti gli altri casi di errore, genera un'eccezione.

    // Imports + initialization of Gemini API backend service
// ...

// 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 GenerativeModelSession with a hybrid model.
// Provide your preferred model as `primary` and your fallback model as `secondary`
// Attempt to use the cloud-hosted model; otherwise, fall back to the on-device model.
let session = ai.generativeModelSession(
  model: .hybridModel(primary: cloudModel, secondary: systemModel)
)

Solo inferenza on-device o solo nel cloud

L'SDK supporta l'impostazione di un solo model, il che significa che l'SDK tenterà l'inferenza sul dispositivo o nel cloud. Inoltre, non crei un HybridModel per questo caso d'uso. Tuttavia, per un'esperienza ibrida, devi creare un HybridModel e impostare i modelli primary e secondary (come descritto sopra).

  • Inferenza solo sul dispositivo: imposta model su un modello "di sistema". Non creare un HybridModel per questo caso d'uso.

    Tenta di utilizzare il modello sul dispositivo se è disponibile e supporta il tipo di richiesta. In caso contrario, genera un'eccezione.

    // Imports + initialization of Gemini API backend service
// ...

// Initialize an on-device model that supports your use case
let systemModel = FirebaseAI.SystemLanguageModel.default

// Create a GenerativeModelSession with the on-device model.
let session = ai.generativeModelSession(
  model: systemModel
)

  • Inferenza solo nel cloud: imposta model su un modello cloud. Non creare un HybridModel per questo caso d'uso.

    Tenta di utilizzare il modello ospitato sul cloud se il dispositivo è online e se il modello è disponibile. In caso contrario, genera un'eccezione.

    // Imports + initialization of Gemini API backend service
// ...

// Initialize a cloud model that supports your use case
let cloudModel = ai.geminiModel(name: "GEMINI_MODEL_NAME")

// Create a GenerativeModelSession with a cloud model.
let session = ai.generativeModelSession(
  model: cloudModel
)

Controllare se il modello sul dispositivo è disponibile

I controlli manuali della disponibilità sul dispositivo sono necessari solo se vuoi mostrare queste informazioni all'utente o richiedere agli utenti finali di scaricare il modello sul dispositivo. Se il modello sul dispositivo non è disponibile e hai impostato primary su un modello sul dispositivo e secondary su un modello cloud, l'SDK eseguirà automaticamente il fallback all'utilizzo del modello ospitato sul cloud.

Per verificare manualmente se il modello sul dispositivo è effettivamente utilizzabile, esamina la proprietà isAvailable:

if FirebaseAI.SystemLanguageModel.default.isAvailable {
  // The on-device model is ready to use.
} else {
  // The on-device model is unavailable.
}

Per verificare i motivi specifici della disponibilità del modello sul dispositivo, esamina la proprietà availability:

switch FirebaseAI.SystemLanguageModel.default.availability {
case .available:
  // The on-device model is ready to use.
  break
case .unavailable(.deviceNotEligible):
  // This device does not support Apple Intelligence.
  break
case .unavailable(.appleIntelligenceNotEnabled):
  // The user has not enabled Apple Intelligence in Settings.
  break
case .unavailable(.modelNotReady):
  // The model is still being downloaded.
  break
case let .unavailable(reason):
  // The model is unavailable due to the specified `reason`.
  break
}

Determinare se è stata utilizzata l'inferenza sul dispositivo o nel cloud

Se utilizzi un HybridModel (e imposti sia i modelli primary che secondary), potrebbe essere utile sapere quale modello è stato utilizzato per una determinata richiesta. Queste informazioni vengono fornite dalla proprietà modelVersion di rawResponse in ogni risposta.

Quando accedi a questa proprietà, il valore restituito sarà uno dei seguenti:

  • Modello ospitato su cloud utilizzato: il nome del modello, ad esempio gemini-3.1-flash-lite
  • Modello sul dispositivo utilizzato: apple-foundation-models-system-language-model
// let response = try await session.respond(to: ...

print("You used: \(response.rawResponse.modelVersion)")

print(response.content)

Utilizzare la configurazione del modello per controllare le risposte

In ogni richiesta a un modello, puoi inviare una configurazione del modello per controllare il modo in cui il modello genera una risposta. I modelli ospitati sul cloud e quelli sul dispositivo offrono diverse opzioni di configurazione (parametri cloud e on-device).

Queste opzioni vengono configurate per ogni richiesta al modello.

Ecco un esempio che imposta le configurazioni per i modelli ospitati sul cloud e sul dispositivo per l'inferenza ibrida:

// ...

let response = try await session.respond(
  to: "Why is the sky blue?",
  options: .hybrid(
    // Config for cloud-hosted model
    gemini: GenerationConfig(
      temperature: 0.8,
      topP: 0.9,
      thinkingConfig: ThinkingConfig(thinkingLevel: .high)
    ),
    // Config for on-device model
    foundationModels: FirebaseAI.GenerationOptions(
      sampling: .random(probabilityThreshold: 0.9),
      temperature: 0.8
    )
  )
)

// ...


Fornisci un feedback sulla tua esperienza con Firebase AI Logic