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 iniciação mostram como implementar a tentativa de inferência no dispositivo primeiro e, em seguida, voltar 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 de "sistema" e secondary como um modelo de nuvem.

    Tenta 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, em seguida, recorra automaticamente ao 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 de "sistema".

    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, recorra ao 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 somente no dispositivo ou somente na nuvem

O SDK permite definir apenas um único model, o que significa que ele vai tentar apenas a 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 de "sistema". Não é necessário criar um HybridModel para esse caso de uso.

    Tenta 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ó serão necessárias se você quiser mostrar essas informações ao usuário ou solicitar que os usuários finais entrem em ação para fazer 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 foi feita no dispositivo ou na nuvem

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.

Ao acessar essa propriedade, o valor retornado será 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 para um modelo, é possível 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 de nuvem versus no dispositivo).

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

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

// ...


Envie feedback sobre sua experiência com o Firebase AI Logic