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 per la creazione di esperienze ibride.

Imposta una "modalità di inferenza"

Gli esempi nella guida introduttiva mostrano come implementare il tentativo di inferenza sul dispositivo e poi eseguire il fallback al modello ospitato sul cloud. Questa è solo una delle "modalità 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.

    Prova a utilizzare il modello sul dispositivo se è disponibile e supporta il tipo di richiesta. In caso contrario, registra un errore sul dispositivo e poi esegui automaticamente il fallback al 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".

    Prova a utilizzare il modello ospitato sul cloud se il dispositivo è online e se il modello è disponibile. Se il dispositivo è offline, esegui il fallback 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)
)

Inferenza solo sul dispositivo o solo nel cloud

L'SDK supporta l'impostazione solo di un singolo model, il che significa che l'SDK tenterà solo 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 crei un HybridModel per questo caso d'uso.

    Prova a 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 crei un HybridModel per questo caso d'uso.

    Prova a 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
)

Verifica 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 intraprendere un'azione per 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
}

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

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

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

  • Modello ospitato sul 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)

Utilizza 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 i modelli sul dispositivo offrono opzioni di configurazione diverse (parametri cloud e sul dispositivo ).

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

// ...


Dai un feedback sulla tua esperienza con Firebase AI Logic