Opções de configuração para experiências híbridas em apps da Apple


Nesta página, descrevemos as seguintes opções de configuração para experiências híbridas e no dispositivo:

Confira se você concluiu o guia para iniciantes sobre como criar experiências híbridas.

Definir um "modo de inferência"

Os exemplos no guia de início rápido mostram como implementar a tentativa de inferência no dispositivo primeiro e, em seguida, fazer fallback para o modelo hospedado na nuvem. Esse é apenas um dos "modos de inferência" disponíveis que você pode implementar.

Inferência híbrida

  • Preferir inferência no dispositivo: defina primary como um modelo "system" e secondary como um modelo na nuvem.

    Tente usar o modelo no dispositivo se ele estiver disponível e for compatível com o tipo de solicitação. Caso contrário, registre um erro no dispositivo e reverta automaticamente para o modelo hospedado na nuvem.

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

  • Preferir inferência na nuvem: defina primary como um modelo de nuvem e secondary como um modelo "system".

    Tente usar o modelo hospedado na nuvem se o dispositivo estiver on-line e se o modelo estiver disponível. Se o dispositivo estiver off-line, use o modelo no dispositivo. Em todos os outros casos de falha, gere uma exceção.

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

Inferência apenas no dispositivo ou apenas na nuvem

O SDK permite definir apenas um único model, o que significa que ele só tentará fazer inferência no dispositivo ou na nuvem. Além disso, não é necessário criar um HybridModel para esse caso de uso. No entanto, para uma experiência híbrida, é necessário criar um HybridModel e definir os modelos primary e secondary (conforme descrito acima).

  • Somente inferência no dispositivo: defina model como um modelo "system". Não crie um HybridModel para esse caso de uso.

    Tente usar o modelo no dispositivo se ele estiver disponível e for compatível com o tipo de solicitação. Caso contrário, gere uma exceção.

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

  • Somente inferência na nuvem: defina model como um modelo de nuvem. Não é necessário criar um HybridModel para esse caso de uso.

    Tente usar o modelo hospedado na nuvem se o dispositivo estiver on-line e se o modelo estiver disponível. Caso contrário, gere uma exceção.

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

Verificar se o modelo no dispositivo está disponível

As verificações manuais de disponibilidade no dispositivo só são necessárias se você quiser mostrar essas informações ao usuário ou pedir que os usuários finais façam o download do modelo no dispositivo. Se o modelo no dispositivo não estiver disponível e você tiver definido primary como um modelo no dispositivo e secondary como um modelo na nuvem, o SDK vai usar automaticamente o modelo hospedado na nuvem.

Para verificar manualmente se o modelo no dispositivo pode ser usado, inspecione a propriedade isAvailable:

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

Para verificar motivos específicos de disponibilidade do modelo no dispositivo, inspecione a propriedade 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
}

Determinar se a inferência no dispositivo ou na nuvem foi usada

Se você usar um HybridModel (e definir os modelos primary e secondary), pode ser útil saber qual modelo foi usado para uma determinada solicitação. Essas informações são fornecidas pela propriedade modelVersion de rawResponse em cada resposta.

Quando você acessa essa propriedade, o valor retornado é um dos seguintes:

  • Modelo hospedado na nuvem usado: o nome do modelo, por exemplo, gemini-3.1-flash-lite
  • Modelo no dispositivo usado: apple-foundation-models-system-language-model
// let response = try await session.respond(to: ...

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

print(response.content)

Usar a configuração do modelo para controlar as respostas

Em cada solicitação a um modelo, você pode enviar uma configuração para controlar como ele gera uma resposta. Os modelos hospedados na nuvem e no dispositivo oferecem diferentes opções de configuração (parâmetros cloud x on-device).

Essas opções são configuradas para cada solicitação ao modelo.

Confira um exemplo que define as configurações para os modelos hospedados na nuvem e no dispositivo para inferência híbrida:

// ...

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

// ...


Enviar feedback sobre sua experiência com Firebase AI Logic