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)

모델 구성을 사용하여 응답 제어

모델에 대한 각 요청에서 모델 구성을 함께 전송하여 모델의 응답 생성 방식을 제어할 수 있습니다. 클라우드 호스팅 모델과 온디바이스 모델은 서로 다른 구성 옵션(클라우드 vs 온디바이스 매개변수)을 제공합니다.

이러한 옵션은 모델에 대한 각 요청에 대해 구성됩니다.

다음은 하이브리드 추론을 위한 클라우드 호스팅 모델과 온디바이스 모델의 구성을 설정하는 예입니다.

// ...

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 사용 경험에 관한