시작하기: Apple의 Foundation Models 프레임워크를 통해 Gemini API에 액세스


WWDC 2026에서 Apple은 Foundation Models 프레임워크를 서드 파티 모델 어댑터에 개방했습니다. 즉, 온디바이스 모델에 액세스하는 데 사용하는 것과 동일한 API 를 사용하여 Foundation Models 프레임워크를 통해 클라우드 호스팅 모델 (예: Gemini)에 액세스할 수 있습니다.

앱에서 모델 인스턴스를 교체하여 사용 사례에 맞게 요청을 온디바이스 또는 클라우드 추론으로 라우팅할 수 있습니다.

  • 온디바이스 모델은 최대한의 개인 정보 보호, 무료, 오프라인 지원을 제공합니다.
  • 클라우드 호스팅 Gemini 모델은 큰 컨텍스트 윈도우, 고급 기능, 더 많은 추론 기능을 제공합니다.

Apple 플랫폼용 Apple SDK(특히 Firebase AI Logic 라이브러리)를 사용하여 Apple의 Foundation Models 프레임워크를 통해 클라우드 호스팅 Gemini 모델에 액세스 할 수 있습니다.Firebase 이 가이드에서는 시작하는 방법을 보여줍니다.

Gemini 모델에 대한 액세스를 보호하기 위해 이 가이드에서는 개발 중에도 중요한 Firebase App Check를 설정하는 방법도 보여줍니다.

기본 요건

  • 최신 Xcode 27 베타를 설치합니다.

  • Apple 플랫폼 시뮬레이터 또는 실제 기기(둘 다 해당 베타 OS 버전(예: iOS 27 베타)을 실행 중임)

  • SwiftUI 인터페이스를 사용하는 Apple 플랫폼 앱의 새 Xcode 프로젝트

지원되는 Gemini 모델

Apple의 Foundation Models 프레임워크와의 통합은 다음 과 같은 Gemini 모델을 지원합니다.

  • 범용 모델

    • gemini-3.1-pro-preview
    • gemini-3.6-flash (이전 gemini-3.5-flash)
    • gemini-3.5-flash-lite (이전 gemini-3.1-flash-lite)

  • 이미지 생성 모델

    • gemini-3-pro-image (일명 'Nano Banana Pro')
    • gemini-3.1-flash-image (일명 'Nano Banana 2')
    • gemini-3.1-flash-lite-image (일명 'Nano Banana 2 Lite')

Gemini Live API 모델 및 Imagen 모델은 지원되지 않습니다. Gemini 2.5 모델은 기술적으로 지원되지만 새 프로젝트에는 권장되지 않으며 이 가이드에서 다루지 않는 특별한 구성이 필요합니다.

1단계: Firebase 프로젝트 만들기

이 통합을 살펴보려면 새 Firebase 프로젝트로 시작하는 것이 좋습니다.

  1. Firebase 콘솔에 로그인합니다.

  2. 새 Firebase 프로젝트 만들기 를 클릭합니다.

  3. 화면에 표시된 안내를 따릅니다. Google 애널리틱스를 사용 설정할 필요가 없습니다.

2단계: Firebase에 앱 연결

앱을 Firebase에 연결하려면 Firebase 프로젝트에 앱을 등록하고 구성 파일을 코드베이스에 추가해야 합니다.

  1. 프로젝트 개요 페이지 중앙에 있는 iOS+ 아이콘을 클릭하여 설정 워크플로를 시작합니다.

  2. 앱을 등록합니다.

    1. 앱의 번들 ID 를 입력합니다. Xcode에서 빌드 중인 프로젝트의 번들 ID와 일치하는지 확인합니다.

    2. 앱 등록 을 클릭합니다.

  3. Firebase 구성 파일을 추가합니다. 이 파일에는 Firebase SDK가 Firebase 프로젝트에 연결하기 위한 설정이 포함되어 있습니다.

    1. 다운로드 GoogleService-Info.plist를 클릭하여 구성 파일을 가져옵니다.

    2. GoogleService-Info.plist를 Xcode 프로젝트의 루트로 이동하고 모든 타겟에 추가합니다.

    3. Firebase 콘솔에서 다음 을 클릭합니다.

  4. 콘솔의 워크플로는 앱에 일반 안내를 제공하므로 Firebase SDK를 추가하기 위한 구체적인 안내는 이 가이드의 다음 단계로 건너뛰세요.Firebase AI Logic

3단계: 앱에 Firebase 라이브러리 추가 및 Firebase 초기화

  1. Swift Package Manager를 사용하여 필요한 Firebase 라이브러리를 추가합니다.

    1. 앱 프로젝트를 연 상태로 Xcode에서 File(파일) > Add Packages(패키지 추가)를 선택합니다.

    2. Firebase Apple SDK 저장소 URL을 입력합니다.

      https://github.com/firebase/firebase-ios-sdk

    3. 종속 항목 규칙을 Branch(브랜치)로 선택하고 wwdc26-preview 를 입력합니다.

    4. 패키지 추가 를 클릭합니다. Xcode가 종속 항목을 확인하고 다운로드합니다.

    5. 메시지가 표시되면 FirebaseAILogic 및 FirebaseAppCheck 라이브러리를 앱 타겟에 추가합니다.

  2. 앱이 시작될 때 다음 코드를 앱의 기본 진입점에 추가하여 Firebase를 초기화합니다.

    import SwiftUI
import FirebaseCore

@main
struct YourApp: App {
  init() {
    FirebaseApp.configure()
  }

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

4단계: Firebase 서비스 사용 설정 및 보안 유지

이제 앱이 Firebase를 사용하도록 구성되었으므로 Firebase AI Logic 서비스를 사용 설정하고 Firebase App Check를 사용하여 연결된 API에 대한 액세스를 보호해야 합니다.

4a단계: Firebase 프로젝트에서 Firebase AI Logic 설정

  1. Firebase 콘솔에서 AI 서비스 > AI 로직으로 이동합니다.

  2. 시작하기 를 클릭하여 안내 설정 워크플로를 시작합니다.

  3. "Gemini API 제공업체"를 선택하라는 메시지가 표시되면 Gemini Developer API를 선택하는 것이 좋습니다. 이 API를 사용하면 무료로 빠르게 시작할 수 있습니다.

    나중에 언제든지 Vertex AI Gemini API (및 결제 요구사항)를 설정할 수 있습니다.

  4. 워크플로를 계속 진행하여 필요한 API와 연결된 서비스를 설정합니다. Firebase AI Logic

    2026년 7월 초부터 이 워크플로 단계에서는 자동으로 Firebase App Check에 AI Logic가 적용됩니다. 이는 앱에서 직접 액세스할 때 Gemini API를 보호하는 데 도움이 되는 중요한 서비스입니다. 시작하기의 일부로 (이 가이드의 뒷부분에 나오는 단계 참고) App Check가 적용될 때 로컬 개발을 위해 App Check 디버그 제공업체를 구성해야 합니다.

    App Check

4b단계: 로컬 개발을 위한 App Check 디버그 제공업체 구성

로컬 개발의 경우 App Check 디버그 제공업체 를 구성하여 앱 체크를 적용하면서도 증명을 우회하도록 해야 합니다.App Check

  1. Xcode 프로젝트에서 FirebaseAppCheck를 가져오고 디버그 제공업체 팩터리를 사용하여 App Check를 전에 구성 Firebase합니다.

    import SwiftUI
import FirebaseCore
import FirebaseAppCheck

@main
struct YourApp: App {
  init() {
    let providerFactory = AppCheckDebugProviderFactory()
    AppCheck.setAppCheckProviderFactory(providerFactory)
    FirebaseApp.configure()
  }

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

  2. 디버그 토큰을 가져옵니다.

    1. 시뮬레이터 또는 테스트 기기에서 앱을 실행합니다.

    2. Xcode 콘솔을 열고 App Check 디버그 토큰을 찾습니다. 예를 들면 다음과 같습니다.

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.

    3. 토큰을 복사합니다 (예: 123a4567-b89c-12d3-e456-789012345678).

  3. App Check에 디버그 토큰을 등록합니다.

    1. Firebase Console에서 보안 > 앱 체크 > 앱 탭으로 이동합니다.

    2. 앱을 찾고 더보기 메뉴 ()를 클릭한 다음 디버그 토큰 관리를 선택합니다.

    3. 화면에 표시된 안내에 따라 디버그 토큰을 등록합니다.

새 디버그 토큰을 가져오는 방법을 비롯한 디버그 제공업체에 관한 자세한 내용은 공식 문서를 참고하세요.App Check

5단계: 앱에서 AI Logic 서비스 초기화

Gemini API 제공업체를 클릭하여 이 페이지에서 제공업체별 콘텐츠 및 코드를 확인합니다.

Firebase 및 App Check이(가) 구성되었으므로 이제 앱에서 Firebase AI Logic 서비스를 초기화할 수 있습니다.

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.6-flash")

6단계: Gemini 모델에 요청 보내기

앱에서 Firebase AI Logic이(가) 설정, 보호, 초기화되었으므로 Gemini 모델에 요청을 보낼 수 있습니다.

다음 예에서는 가장 기본적인 요청 유형인 텍스트 전용 프롬프트에서 텍스트를 생성하는 방법을 보여줍니다.

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.6-flash")


// Create a session by injecting the model into Apple's `LanguageModelSession`.
let session = LanguageModelSession(model: model)

// Generate a text response to a prompt.
let response = try await session.respond(to: "Write a story about a magic backpack.")
print(response.content)

Gemini 모델은 이미지 및 PDF 분석 , 구조화된 JSON 출력 생성 , 이미지 생성('Nano Banana' 모델 사용) 과 같은 다른 유형의 요청도 지원합니다. 이러한 유형의 요청에 관한 예는 문서 또는 샘플 앱을 참고하세요.

응답 스트리밍

모델 생성의 전체 결과를 기다리지 않고 스트리밍 을 사용하여 부분 결과를 처리하면 상호작용 속도를 높일 수 있습니다. 응답을 스트리밍하려면 respond(to:) 대신 streamResponse(to:)를 사용합니다.

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.6-flash")


// Create a session by injecting the model into Apple's `LanguageModelSession`.
let session = LanguageModelSession(model: model)

// Generate a streamed text response to a prompt.
// To stream the response, use `streamResponse(to:)` instead of `respond(to:)`
let stream = session.streamResponse(to: "Write a story about a magic backpack.")
var response = ""
for try await snapshot in stream {
  // The snapshot contains *all* content generated so far.
  response = snapshot.content
}

다음 단계


의견을 보내주세요 Apple의 Foundation Models 프레임워크를 통해 Gemini API에 액세스하는 것에 관한