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


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

Conclua o guia para iniciantes sobre como criar experiências híbridas.

Definir um "modo de inferência"

Os exemplos no guia para iniciantes mostram como implementar a tentativa de inferência no dispositivo primeiro e, em seguida, fazer o 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 a inferência no dispositivo: defina primary como um modelo "de sistema" e secondary como um modelo de nuvem.

    Tente usar o modelo no dispositivo se ele estiver disponível e oferecer suporte ao tipo de solicitação. Caso contrário, registre um erro no dispositivo e faça o fallback automático 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 a 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 o modelo estiver disponível. Se o dispositivo estiver off-line, faça o fallback para 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 oferece suporte à definição de apenas um único model, o que significa que ele só tentará a inferência no dispositivo ou na nuvem. Além disso, você não cria 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).

  • Inferência apenas no dispositivo: defina model como um modelo "de sistema". Você não cria um HybridModel para esse caso de uso.

    Tente usar o modelo no dispositivo se ele estiver disponível e oferecer suporte ao 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
)

  • Inferência apenas na nuvem: defina model como um modelo de nuvem. Você não cria um HybridModel para esse caso de uso.

    Tente usar o modelo hospedado na nuvem se o dispositivo estiver on-line e 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 solicitar que os usuários finais tomem medidas 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 de nuvem, o SDK fará o fallback automático para 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 os motivos específicos da 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.

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 respostas

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

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