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 사용 경험에 관한 의견 보내기