Apple Intelligence 개발자 API 가이드 — Core ML, App Intents, Writing Tools 통합

Apple Intelligence는 Apple이 iOS 18.1, iPadOS 18.1, macOS Sequoia 15.1부터 단계적으로 공개한 온디바이스 AI 플랫폼이다. 핵심 원칙은 두 가지다. 첫째, 가능한 모든 추론을 기기 내부(Neural Engine)에서 처리한다. 둘째, 클라우드 처리가 필요한 경우에도 Private Cloud Compute(PCC)를 통해 서버가 요청 데이터를 저장하거나 Apple이 열람할 수 없도록 설계한다.

개발자 관점에서 Apple Intelligence가 의미하는 것은 "새로운 API 레이어가 생겼다"는 점이다. 서드파티 앱은 System Intelligence, Writing Tools, Image Playground, Genmoji, App Intents를 통해 Apple의 온디바이스 모델과 상호작용할 수 있다. 다만 Apple의 기반 모델(Foundation Model) 자체에 직접 접근하는 API는 2026년 3월 현재 공개되지 않았다. 개발자는 Apple이 노출한 고수준 API를 사용하거나, Core ML로 자체 모델을 배포하는 두 가지 경로 중 하나를 선택해야 한다.

Apple Intelligence API를 사용할 수 있는 범위는 다음과 같다.

지원 기기는 A17 Pro 칩 이상의 iPhone(iPhone 15 Pro, 16 시리즈)과 M1 이상의 iPad, Mac으로 제한된다. 앱이 이 기기들만 타깃으로 하지 않는다면 반드시 폴백 처리가 필요하다.

Core ML 8(Xcode 16 번들)은 Transformer 아키텍처 모델에 대한 최적화가 핵심이다. 이전 버전에서 Transformer를 CoreML로 변환하면 발생하던 성능 저하가 대폭 개선됐고, Stateful Prediction API를 통해 KV-Cache를 앱 레벨에서 직접 관리할 수 있게 됐다.

coremltools 8.x로 PyTorch/Hugging Face 모델 변환하기:

import coremltools as ct
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

# 1. 모델 로드 (float16으로 추론 후 변환)
model = AutoModelForCausalLM.from_pretrained("your-model-id", torch_dtype=torch.float16)
model.eval()

# 2. Trace (추론 시 입력 형태와 동일하게)
example_input = torch.randint(0, 32000, (1, 128))
traced_model = torch.jit.trace(model, example_input)

# 3. Core ML 변환
mlmodel = ct.convert(
    traced_model,
    inputs=[ct.TensorType(name="input_ids", shape=example_input.shape)],
    compute_precision=ct.precision.FLOAT16,
    compute_units=ct.ComputeUnit.ALL,  # CPU + GPU + Neural Engine
    minimum_deployment_target=ct.target.iOS18
)

# 4. 저장
mlmodel.save("YourModel.mlpackage")

변환 시 compute_units=ct.ComputeUnit.ALL을 설정하면 Core ML이 런타임에 CPU, GPU, Neural Engine 중 가장 효율적인 조합을 자동 선택한다. iOS 18 타깃이라면 Stateful Prediction을 활성화해 자동회귀 생성에서의 추론 속도를 크게 높일 수 있다.

Xcode에서 Core ML 모델 사용하기 (Swift):

import CoreML
import Vision

// .mlpackage를 Xcode 프로젝트에 추가하면 자동 클래스 생성
let config = MLModelConfiguration()
config.computeUnits = .all

guard let model = try? YourModel(configuration: config) else {
    // 폴백 처리: 서버 API 또는 기능 비활성화
    return
}

// 입력 생성 및 예측
let input = YourModelInput(input_ids: inputTensor)
if let output = try? model.prediction(input: input) {
    let result = output.logits
    // 결과 처리
}

Create ML은 Xcode 16 기준으로 Fine-tuning 워크플로우가 개선됐다. LoRA 방식의 경량 파인튜닝을 지원하며, Create ML 앱의 GUI에서 데이터셋을 드래그 앤 드롭으로 추가해 텍스트 분류, 감정 분석, 엔티티 인식 모델을 빠르게 학습할 수 있다. 학습된 모델은 곧바로 .mlpackage로 내보낸다.

주의할 점은 Core ML 모델의 용량이다. Transformer 기반 모델은 수백 MB에서 수 GB에 달하는 경우가 많다. App Store에 배포할 때는 On-Demand Resources(ODR) 또는 Background Assets 프레임워크를 사용해 앱 초기 다운로드 크기와 모델 파일을 분리해야 한다.

App Intents는 iOS 16에서 도입됐지만, iOS 18의 Apple Intelligence와 결합하면서 실질적인 Siri 통합의 핵심이 됐다. 이전 SiriKit은 특정 도메인(메시지, 결제, 운동 등)으로 기능이 제한됐고, 인텐트 파라미터 처리도 복잡했다. App Intents는 프로토콜 기반의 Swift-native 설계로, 어떤 앱 기능이든 Siri, Spotlight, 단축어 앱에 노출할 수 있다.

기본 App Intent 구현 예시:

import AppIntents

// 1. Intent 정의
struct CreateNoteIntent: AppIntent {
    static var title: LocalizedStringResource = "새 노트 만들기"
    static var description = IntentDescription("제목과 내용으로 새 노트를 생성합니다.")

    @Parameter(title: "제목")
    var title: String

    @Parameter(title: "내용", default: "")
    var content: String

    func perform() async throws -> some IntentResult & ProvidesDialog {
        // 앱 비즈니스 로직 호출
        let note = try await NoteStore.shared.create(title: title, content: content)
        return .result(dialog: "'\(note.title)' 노트를 만들었습니다.")
    }
}

// 2. App Shortcuts로 Siri 구문 등록
struct NoteAppShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: CreateNoteIntent(),
            phrases: [
                "\(.applicationName)에 노트 만들어",
                "\(.applicationName)로 \(\.$title) 메모해"
            ],
            shortTitle: "노트 만들기",
            systemImageName: "note.text.badge.plus"
        )
    }
}

iOS 18에서 추가된 핵심 기능은 Parameterized Phrases다. \(\.$title) 구문을 사용하면 "메모에 회의록 저장해"처럼 파라미터를 발화에 포함한 Siri 명령을 바로 처리할 수 있다. 이전에는 Siri가 파라미터를 묻는 대화를 별도로 진행해야 했다.

SiriKit과의 결정적 차이는 도메인 제한이다. SiriKit은 Apple이 정의한 12개 도메인(메시지, 결제, 음악, 운동 등) 외에는 사용할 수 없었다. App Intents는 도메인 제약 없이 모든 기능을 노출 가능하다. 다만 Apple Intelligence의 "앱 동작 이해" 기능(Siri가 앱 화면 맥락을 파악하는 것)은 App Intents를 구현한 앱에서만 제대로 동작한다.

실전 구현 시 주의사항은 두 가지다. 첫째, perform()은 백그라운드에서 호출될 수 있으므로 UI 업데이트는 @MainActor로 격리해야 한다. 둘째, Intent의 파라미터가 복잡한 커스텀 타입이라면 AppEntity 프로토콜을 구현해 Siri가 해당 타입의 값을 이해할 수 있도록 해야 한다.

Writing Tools는 iOS 18 / macOS Sequoia 15부터 시스템 레벨에서 제공하는 텍스트 처리 기능이다. 교정(Proofread), 재작성(Rewrite), 요약(Summarize), 목록화(Create List), 표 변환(Create Table) 등의 기능을 포함한다. 핵심은 UITextView나 NSTextView를 사용하는 앱은 별도 코드 없이 자동으로 Writing Tools를 지원한다는 점이다.

UITextView에서 텍스트를 선택하면 컨텍스트 메뉴에 Writing Tools 항목이 자동으로 나타난다. 대부분의 텍스트 편집 앱은 추가 구현 없이 이 기능을 무료로 얻는다. 단, 특정 시나리오에서는 동작을 커스터마이징해야 한다.

Writing Tools 동작 제어 (Swift/UIKit):

import UIKit

class MyTextViewController: UIViewController, UITextViewDelegate {

    lazy var textView: UITextView = {
        let tv = UITextView()
        // Writing Tools 완전 비활성화 (코드 편집기 등에서 필요)
        tv.writingToolsBehavior = .none

        // 또는 일부 기능만 제한
        // tv.writingToolsBehavior = .limited  // 교정만 허용
        // tv.writingToolsBehavior = .complete  // 기본값 (모든 기능)
        return tv
    }()

    // Writing Tools 세션 시작/종료 시 UI 조정
    func textViewWritingToolsWillBegin(_ textView: UITextView) {
        // 편집 버튼 비활성화, 저장 버튼 숨기기 등
        saveButton.isEnabled = false
    }

    func textViewWritingToolsDidEnd(_ textView: UITextView) {
        saveButton.isEnabled = true
    }
}

SwiftUI에서는 .writingToolsBehavior() modifier로 제어한다.

TextEditor(text: $documentContent)
    .writingToolsBehavior(.complete)  // 또는 .none, .limited
    .frame(minHeight: 200)

.limited 모드는 코드 편집기처럼 요약/재작성이 부적절한 맥락에서, 교정(오탈자 수정) 기능만 허용하고 싶을 때 사용한다. .none은 Writing Tools를 완전히 차단한다.

Writing Tools는 온디바이스 모델이 텍스트를 처리하므로 앱이 텍스트를 외부로 전송하지 않는다. 다만 Apple Intelligence 지원 기기(A17 Pro+/M1+)가 아닌 경우에는 Writing Tools 자체가 표시되지 않으므로, 핵심 편집 기능이 Writing Tools에 의존하지 않도록 설계해야 한다.

Image Playground는 온디바이스 이미지 생성 기능이다. 텍스트 설명, 개념 태그, 인물 사진을 입력으로 받아 만화/일러스트/스케치 스타일의 이미지를 생성한다. iOS 18.2부터 서드파티 앱이 Image Playground ViewController를 호출해 이 기능을 통합할 수 있다.

Image Playground ViewController 통합 (Swift):

import ImagePlayground

class MyViewController: UIViewController, ImagePlaygroundViewController.Delegate {

    func openImagePlayground() {
        guard ImagePlaygroundViewController.isAvailable else {
            // A17 Pro 미만 또는 Apple Intelligence 미지원 기기
            showFallbackMessage()
            return
        }

        let vc = ImagePlaygroundViewController()
        vc.delegate = self

        // 초기 컨셉 제안 (선택사항)
        vc.concepts = [
            .text("귀여운 강아지"),
            .text("만화 스타일")
        ]

        present(vc, animated: true)
    }

    // 사용자가 이미지를 생성 완료하면 호출됨
    func imagePlaygroundViewController(
        _ vc: ImagePlaygroundViewController,
        didCreateImageAt imageURL: URL
    ) {
        // imageURL은 임시 파일 경로 — 필요시 앱 내로 복사
        if let image = UIImage(contentsOfFile: imageURL.path) {
            selectedImageView.image = image
            // 앱 영구 저장소로 복사
            let destination = FileManager.default
                .urls(for: .documentDirectory, in: .userDomainMask)[0]
                .appendingPathComponent("generated_\(UUID().uuidString).png")
            try? FileManager.default.copyItem(at: imageURL, to: destination)
        }
        vc.dismiss(animated: true)
    }

    func imagePlaygroundViewControllerDidCancel(_ vc: ImagePlaygroundViewController) {
        vc.dismiss(animated: true)
    }
}

Genmoji는 사용자가 텍스트 설명으로 커스텀 이모지를 생성하는 기능이다. iOS 18.2부터 앱이 Genmoji를 렌더링하려면 NSAttributedString의 Genmoji 어트리뷰트를 처리해야 한다. UITextView는 이를 자동 렌더링하지만, 커스텀 텍스트 렌더링 레이어를 사용하는 앱은 UIImage.SymbolConfiguration과 유사한 방식으로 Genmoji 이미지를 요청해야 한다.

Image Playground 사용 시 주의해야 할 제한사항:

• 생성 스타일 선택지가 세 가지(Animation, Illustration, Sketch)로 고정돼 있고, 사진 실사 스타일은 지원하지 않는다.
• 성인 콘텐츠 생성 차단이 시스템 레벨로 내장돼 있어 개발자가 우회할 수 없다.
• 앱이 ViewController를 커스터마이징할 수 있는 범위가 컨셉 제안 주입에 한정된다. UI 자체는 수정 불가.
• isAvailable 확인 없이 ViewController를 생성하면 런타임 크래시가 발생한다.

App Store 심사 관점에서 Image Playground를 통합한 앱은 생성 결과물의 2차 사용 조건을 명확히 해야 한다. Apple의 가이드라인에 따르면 Image Playground로 생성된 이미지는 앱 내 사용 목적으로만 제공돼야 하며, 광고/상업적 2차 판매가 금지된다.

Apple Intelligence API를 실제 앱에 통합할 때 가장 먼저 결정해야 하는 것은 "AI 기능이 핵심(Core) 경험인가, 부가(Enhancement) 경험인가"다. 핵심 경험이라면 Apple Intelligence 미지원 기기 사용자가 앱 자체를 사용할 수 없게 되므로, 현실적으로는 부가 경험으로 설계하고 폴백을 철저히 구현해야 한다.

기기 지원 범위와 폴백 패턴:

import Foundation
import CoreML

struct AIFeatureAvailability {
    // Apple Intelligence 전체 가용성
    static var isAppleIntelligenceAvailable: Bool {
        // iOS 18.1+, A17 Pro 또는 M1 이상
        if #available(iOS 18.1, macOS 15.1, *) {
            // 실제 기기 확인은 각 API의 isAvailable 속성으로
            return true
        }
        return false
    }

    // Core ML은 기기 제한 없이 사용 가능
    static func checkCoreMLModel(at url: URL) -> Bool {
        guard let _ = try? MLModel(contentsOf: url) else { return false }
        return true
    }
}

// 사용 예
func setupAIFeatures() {
    if AIFeatureAvailability.isAppleIntelligenceAvailable {
        enableWritingTools()
        enableImagePlayground()
    } else {
        // 대체 UX: 서드파티 API 호출 또는 기능 숨김
        offerAlternativeTextTools()
    }
}

프라이버시 고려사항: Apple Intelligence의 온디바이스 처리는 개인정보 보호 측면에서 강점이지만, 개발자가 Core ML 모델에 사용자 입력을 전달할 때는 App Privacy Report에 올바르게 선언해야 한다. NSPrivacyAccessedAPITypes에 Core ML 관련 데이터 사용 목적을 명시하지 않으면 App Store 심사에서 리젝될 수 있다.

App Store 심사 체크리스트:

• PrivacyInfo.xcprivacy에 사용하는 데이터 유형과 목적 명시
• Image Playground 생성 이미지의 저장 및 전송 여부를 개인정보 처리방침에 기재
• App Intents의 perform() 내에서 네트워크 요청 시 사용자 데이터 전송 최소화
• AI 기능의 결과물(생성 텍스트, 이미지)에 출처 표시 필요 여부 검토

마지막으로 성능 프로파일링이다. Core ML 모델을 처음 로드할 때 Neural Engine 컴파일이 발생해 수백 밀리초 지연이 생길 수 있다. 앱 시작 시 백그라운드 워크큐에서 모델을 미리 로드해 두고, 실제 추론 요청이 들어올 때 즉시 응답할 수 있도록 준비하는 것이 표준 패턴이다. Instruments의 Core ML profiler 템플릿으로 Neural Engine 사용률과 모델 로드 시간을 측정할 수 있다.