Opzioni di configurazione per le esperienze ibride nelle app Apple


Questa pagina descrive le seguenti opzioni di configurazione per le esperienze ibride e on-device:

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 on-device e poi eseguire il fallback al modello ospitato su cloud. Questa è solo una delle "modalità di inferenza" disponibili che puoi implementare.

Inferenza ibrida

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

    Prova a utilizzare il modello on-device 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 su 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 in-cloud: imposta primary su un modello cloud e secondary su un modello "di sistema".

    Prova a utilizzare il modello ospitato su cloud se il dispositivo è online e se il modello è disponibile. Se il dispositivo è offline, esegui il fallback al modello on-device. 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 on-device o solo in-cloud

L'SDK supporta l'impostazione di un solo model, il che significa che l'SDK tenterà solo l'inferenza on-device o in-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 on-device: imposta model su un modello "di sistema". Non crei un HybridModel per questo caso d'uso.

    Prova a utilizzare il modello on-device 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 in-cloud: imposta model su un modello cloud. Non crei un HybridModel per questo caso d'uso.

    Prova a utilizzare il modello ospitato su 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 on-device è disponibile

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

Per verificare manualmente se il modello on-device è 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 on-device, 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 on-device o in-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 su cloud utilizzato: il nome del modello, ad esempio gemini-3.1-flash-lite
  • Modello on-device 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 su cloud e i modelli on-device offrono opzioni di configurazione diverse (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 su cloud e on-device 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