Apple 應用程式中混合式體驗的設定選項


本頁面說明混合式和裝置端體驗的下列設定選項：

請務必完成建構混合式體驗的入門指南。

設定「推論模式」

入門指南中的範例說明如何先嘗試執行裝置端推論，然後改用雲端代管模型。這只是其中一種可實作的「推論模式」。

混合式推論

  • 偏好裝置端推論：將 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 只會嘗試在裝置端或雲端進行推論。此外，您也不會為這個用途建立 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 的使用體驗意見回饋