Apple アプリのハイブリッド エクスペリエンスの構成オプション


このページでは、ハイブリッド エクスペリエンスとオンデバイス エクスペリエンスの次の構成オプションについて説明します。

ハイブリッド エクスペリエンスの構築の スタートガイドを完了していることを確認してください。

「推論モード」を設定する

スタートガイドの例では、最初にオンデバイス推論を試行し、次にクラウド ホスト型モデルにフォールバックする方法を示しています。 これは、実装できる「推論モード」の 1 つにすぎません。

ハイブリッド推論

  • オンデバイス推論を優先する: primary を「システム」モデルに、 secondary をクラウドモデルに設定します。

    オンデバイス モデルが使用可能で、リクエストのタイプをサポートしている場合は、オンデバイス モデルを使用します。それ以外の場合は、デバイスにエラーを記録し、自動的にクラウド ホスト型モデルにフォールバックします。 

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

  • クラウド推論を優先する: primary をクラウドモデルに、 secondary を「システム」モデルに設定します。

    デバイスがオンラインで、モデルが使用可能な場合は、クラウド ホスト型モデルを使用します。デバイスがオフラインの場合は、オンデバイス モデルにフォールバックします。 その他のすべてのエラーケースでは、例外をスローします。 

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

オンデバイス推論のみまたはクラウド推論のみ

SDK は単一の model のみを設定することをサポートしています。つまり、SDK はオンデバイス推論またはクラウド推論のいずれかのみをonly 試行します。また、このユースケースでは HybridModel を作成しません。ただし、ハイブリッド エクスペリエンスの場合は、HybridModel を作成し、primary モデルと secondary モデルの両方を設定する必要があります（上記のとおり）。

  • オンデバイス推論のみ: model を「システム」モデルに設定します。このユースケースでは HybridModel を作成しません。

    オンデバイス モデルが使用可能で、リクエストのタイプをサポートしている場合は、オンデバイス モデルを使用します。それ以外の場合は、例外をスローします。 

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

  • クラウド推論のみ: model をクラウドモデルに設定します。このユースケースでは HybridModel を作成しません。

    デバイスがオンラインで、モデルが使用可能な場合は、クラウド ホスト型モデルを使用します。それ以外の場合は、例外をスローします。 

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

オンデバイス モデルが使用可能かどうかを確認する

オンデバイスの可用性を手動で確認する必要があるのは、その情報をユーザーに表示する場合や、エンドユーザーにオンデバイス モデルをダウンロードするようリクエストする場合のみです。オンデバイス モデルが使用できない場合（primary をオンデバイス モデルに、secondary をクラウドモデルに設定している場合）、SDK は自動的にクラウド ホスト型モデルの使用にフォールバックします。

オンデバイス モデルが実際に使用可能かどうかを手動で確認するには、isAvailable プロパティを調べます。

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

特定のオンデバイス モデルの可用性の理由を確認するには、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
}

オンデバイス推論とクラウド推論のどちらが使用されたかを判断する

HybridModel を使用する場合（primary モデルと secondary モデルの両方を設定する場合）、特定のリクエストにどのモデルが使用されたかを知ることが役立つことがあります。この情報は、各レスポンスの rawResponse の modelVersion プロパティで提供されます。

このプロパティにアクセスすると、次のいずれかの値が返されます。

  • 使用されたクラウド ホスト型モデル: モデル名（gemini-3.1-flash-lite など）
  • 使用されたオンデバイス モデル: apple-foundation-models-system-language-model
// let response = try await session.respond(to: ...

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

print(response.content)

モデル構成を使用してレスポンスを制御する

モデルへのリクエストごとに、モデル構成を送信して、モデルがレスポンスを生成する方法を制御できます。クラウド ホスト型モデルとオンデバイス モデル では、異なる構成オプション （クラウド パラメータと オンデバイス パラメータ）が用意されています。

これらのオプションは、モデルへのリクエストごとに構成されます。

ハイブリッド推論のクラウド ホスト型モデルとオンデバイス モデルの構成を設定する例を次に示します。

// ...

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

// ...


フィードバックを送信する Firebase AI Logicの使用に関する