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

미리보기: Apple의 Foundation Models 프레임워크를 통해 Gemini API에 액세스하기 위해 Firebase AI Logic를 사용하는 것은 현재 공개 미리보기 상태입니다. 즉, SLA 또는 지원 중단 정책이 적용되지 않으며 이전 버전과 호환되지 않는 방식으로 변경될 수 있습니다.
또한 이 통합은 베타 API를 사용하므로 다음 Xcode 버전이 정식 버전 (GA)에 도달하고 프로덕션 제출을 지원할 때까지 이를 사용하는 앱을 App Store에 제출할 수 없습니다.

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

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

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

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

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

기본 요건

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

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

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

참고: 이번 초기 출시에서는 iOS 및 macOS와 같은 Apple 플랫폼이 지원됩니다.

지원되는 Gemini 모델

Apple의 파운데이션 모델 프레임워크와의 통합은 다음 Gemini 모델을 지원합니다.

• 범용 모델

  • gemini-3.1-pro-preview
  • gemini-3.8-flash (이전 버전인 gemini-3.7-flash, 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 모델은 지원되지 않습니다. 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 프로젝트에 연결하기 위한 Firebase SDK 설정이 포함되어 있습니다.

   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. 종속성 규칙을 브랜치로 선택하고 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를 선택하는 것이 좋습니다. 무료로 빠르게 시작할 수 있습니다.

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

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

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

   참고: 최종 사용자에게 앱의 AI 기능을 출시하려면 App Check이 적용될 때 기능을 사용할 수 있도록 프로덕션 App Check 증명 제공업체에 앱을 등록해야 합니다.

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

로컬 개발의 경우 App Check 시행을 유지하면서 증명을 우회하도록 App Check 디버그 제공자를 구성해야 합니다.

1. Xcode 프로젝트에서 FirebaseAppCheck를 가져오고 Firebase를 구성하기 전에 디버그 제공자 팩토리로 App Check를 초기화합니다.

   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 콘솔에서 보안 > App Check > 앱 탭으로 이동합니다.

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

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

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

App Check 디버그 제공자에 관한 몇 가지 중요한 사항은 다음과 같습니다.

• 디버그 토큰과 디버그 빌드를 비공개로 유지하세요. 디버그 토큰을 공개 저장소에 커밋하지 말고 앱의 프로덕션 빌드에서 디버그 토큰이나 디버그 빌드를 제공하지 마세요.
• 최종 사용자에게 출시하기 전에 프로덕션 증명 제공업체에 앱을 등록하세요. 프로덕션 App Check 증명 제공업체(예: App Attest, Play Integrity, reCAPTCHA Enterprise)에 앱을 등록 해야 합니다. 최종 사용자가 App Check가 적용된 상태로 기능을 사용할 수 있습니다.

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

Gemini API 제공업체를 클릭하여 이 페이지에서 제공업체별 콘텐츠와 코드를 확인합니다. Gemini Developer API Agent Platform 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.8-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.8-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.8-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의 파운데이션 모델 프레임워크를 통해 Gemini API에 액세스할 때 사용 가능한 기능을 살펴봅니다.
• 사고 수준 ('추론')을 설정하는 등 모델을 구성하여 응답을 제어하는 방법을 알아봅니다.
• 최신 정보를 위한 그라운딩을 비롯해 모델에 도구를 제공하는 방법을 알아보세요.
• Firebase App Check 및 리소스 보호 방법에 대해 자세히 알아보세요.

Apple의 파운데이션 모델 프레임워크를 통해 Gemini API에 액세스하는 방법에 관한 의견 보내기