Apple Foundation Models

Claude for Foundation Models는 Apple Foundation Models 프레임워크에서 Claude를 서버 측 언어 모델 (Server-side Language Model)로 사용할 수 있게 하는 Swift 패키지이며, LanguageModelSession API로 응답, 스트리밍, 가이드 생성, 도구 호출 (Tool Calling)을 동일하게 다룸

• 요청은 앱에서 Claude API로 직접 전송되며, Apple은 요청 경로에 없고 프롬프트나 응답을 보지 못함
• 패키지는 OS 27 베타의 Foundation Models 서버 측 언어 모델 API를 대상으로 하는 **베타 (Beta)**이며, 일반 제공 전 API가 바뀔 수 있음
• 개발 중에는 API 키를 직접 전달할 수 있지만, 출시 앱에 키를 포함하면 추출될 수 있어 프로덕션에서는 **프록시 (Proxy)**를 통해 요청해야 함
• Apple 온디바이스 모델 (On-device Model)은 빠르고 비공개이며 오프라인에서 작동하고, Claude는 더 큰 컨텍스트 (Context), 프런티어 추론 (Frontier Reasoning), 웹 검색·코드 실행 같은 서버 측 도구가 필요할 때 쓰임

개요

• Claude for Foundation Models는 Apple의 Foundation Models 프레임워크에서 Claude를 서버 측 언어 모델로 사용할 수 있게 하는 Swift 패키지임

• 패키지는 Claude를 프레임워크의 LanguageModel 프로토콜에 맞추며, Apple 온디바이스 모델에 쓰는 LanguageModelSession API를 그대로 사용함. respond(to:), 스트리밍, 가이드 생성, 도구 호출이 같은 방식으로 작동함

• 요청은 앱에서 Claude API로 직접 이동하며, Apple은 요청 경로에 없고 프롬프트나 응답을 보지 못함

• 사용량은 Anthropic 계정에 표준 API 가격으로 청구되며, 앱은 Claude와 Apple 온디바이스 모델 중 어떤 모델을 각 세션에 넘길지 결정함

• 이 패키지는 범용 Messages API 클라이언트가 아니며, 공개 표면은 Foundation Models 제공자 적합성과 관련 설정 타입인 ClaudeLanguageModel, ClaudeModel, AuthMode, ClaudeServerTool임

베타 및 요구 사항

• 패키지는 OS 27 베타에서 도입된 Foundation Models 서버 측 언어 모델 API를 대상으로 하며, 일반 제공 전 API 변경이 가능함
• 실행 대상은 iOS 27, macOS 27, visionOS 27, watchOS 27이며 모두 베타 상태임
• 개발 환경에는 Xcode 27 베타가 필요함
• 개발용으로 Claude Console에서 발급한 Claude API 키가 필요하며, 프로덕션 옵션은 인증 방식에 따라 달라짐

설치와 기본 사용

Package.swift에 ClaudeForFoundationModels 패키지를 추가함

dependencies: [
.package(url: "https://github.com/anthropics/ClaudeForFoundationModels.git";, from: "0.1.0")
]

• Xcode에서는 File > Add Package Dependencies… 메뉴에서 저장소 URL을 입력할 수 있음
• 타깃 의존성에 ClaudeForFoundationModels를 추가한 뒤 FoundationModels와 함께 임포트함

import FoundationModels
import ClaudeForFoundationModels

ClaudeLanguageModel이 진입점이며, 이를 LanguageModelSession에 넘겨 다른 Foundation Models 제공자처럼 사용함

import FoundationModels
import ClaudeForFoundationModels
let model = ClaudeLanguageModel(
...

모델과 기능

• 모델 식별자는 ClaudeModel 값이며, 컴파일된 상수를 쓰거나 아직 패키지에 들어 있지 않은 ID를 명시적 기능과 함께 구성함

ClaudeLanguageModel(name: .opus4_8, auth: auth)

• 상수는 API 모델 ID를 반영하며, .opus4_8은 claude-opus-4-8에 해당하고 각 모델의 기능 정보를 함께 가짐
• 새 모델은 패키지 릴리스에서 새 상수로 제공되며, 현재 목록은 Xcode의 ClaudeModel과 Models overview에서 확인함
• 각 ClaudeModel은 샘플링 파라미터 (sampling parameters), 노력 수준 (effort levels), 적응형 사고 (adaptive reasoning), 구조화 출력 (structured output), 이미지 입력 (image input) 등 **허용 기능 (capabilities)**을 선언함
• 패키지는 모델이 거부하는 필드를 보내면 하드 오류가 발생하기 때문에, 선언된 기능을 기준으로 요청 필드를 결정함
• 아직 컴파일되지 않은 ID에는 모델이 허용하는 기능을 직접 선언해야 하며, 기능을 추측하는 축약 방식은 의도적으로 없음

let model = ClaudeModel(
id: "claude-experimental-x",
capabilities: .init(samplingParams: false, effortLevels: [.low, .high])
...

인증 (Authentication)

• 자격 증명은 auth: 파라미터로 설정함

• 개발용 API 키

• 개발 중에는 API 키를 직접 전달할 수 있음

ClaudeLanguageModel(name: .sonnet4_6, auth: .apiKey("YOUR_API_KEY"))

• 앱에 포함된 키는 배포 바이너리에서 추출될 수 있으며, 키를 추출한 사용자는 해당 계정으로 과금되는 요청을 만들 수 있음. .apiKey는 개발 전용으로 쓰고, 출시 전에는 **프록시 (proxy)**로 전환해야 함

• 프로덕션 프록시

• 프로덕션에서는 .proxied로 자체 백엔드를 통해 요청을 라우팅함. baseURL의 릴레이가 서버 측에서 Claude API 자격 증명을 추가하므로 앱에는 키가 포함되지 않음

• 제공한 headers는 모든 요청에 전송되며, 프록시가 호출자를 인증하는 데 사용할 수 있음

• 프록시에 별도 헤더가 필요 없으면 [:]를 전달함

ClaudeLanguageModel(
name: .sonnet4_6,
auth: .proxied(headers: ["X-App-Token": "..."]),
...

응답 처리 (Response Handling)

• 스트리밍 (Streaming)

streamResponse(to:)는 응답을 점진적으로 반환함

• 각 요소는 델타 (delta)가 아니라 지금까지의 응답을 누적한 **스냅샷 (snapshot)**임

let stream = session.streamResponse(to: "Summarize today's top science stories.")
for try await partial in stream {
print(partial.content)
...

• 구조화 출력 (Structured Output)

• 타입에 @Generable을 붙이고 generating:으로 요청하면, 모델이 구조화 출력으로 해당 타입의 값을 반환함

@Generable
struct Trip {
@Guide(description: "Destination city") var destination: String
...

• 구조화 출력에는 해당 기능을 가진 모델이 필요하며, 컴파일된 모든 상수는 이를 지원함
• 선택한 모델이 구조화 출력을 지원하지 않으면 패키지는 조용히 성능을 낮추지 않고 LanguageModelError.unsupportedGenerationGuide를 던짐

도구와 멀티모달 (Tools and Multimodal)

• 클라이언트 측 도구 (Client-side Tools)

• 프레임워크의 tools: 배열은 그대로 작동함

• 타입을 Tool에 맞추고 LanguageModelSession

에 넘기면, Claude가 도구를 호출할 때 프레임워크가 기기에서 해당 도구를 실행함

let session = LanguageModelSession(model: model, tools: [FindRestaurantsTool()])

서버 측 도구 (Server-side Tools)

• 서버 도구인 웹 검색 (Web Search), 웹 가져오기 (Web Fetch), 코드 실행 (Code Execution)은 Anthropic 인프라에서 단일 왕복 (Round-trip) 안에 실행되며, 기기에서 프레임워크가 호출할 작업이 없음
• 서버 도구는 serverTools:로 모델별 설정함

let model = ClaudeLanguageModel(
name: .sonnet4_6,
auth: auth,
...

.webSearch와 .webFetch는 선택적으로 allowedDomains, blockedDomains, maxUses를 받음

• 서버 도구 활동은 트랜스크립트 (Transcript)에서 ClaudeServerToolSegment 커스텀 세그먼트로 드러남

• serverTools는 LanguageModelSession이 아니라 ClaudeLanguageModel에 설정되며, 세션 타입이 Apple 소유이기 때문임

• 대화별로 다른 서버 도구 구성이 필요하면 여러 ClaudeLanguageModel 인스턴스를 만들어야 함

이미지 입력 (Image Input)

• 이미지 입력 기능을 가진 모델은 프레임워크의 비전 (Vision) 기능을 선언함
• 이미지 콘텐츠는 프레임워크의 표준 세션 API로 전달하며, 패키지가 이를 Claude API의 이미지 형식으로 변환함
• 이미지 요구 사항은 Vision 문서를 따름

오류 처리와 제한 사항 (Error Handling and Limitations)

오류 매핑 (Error Mapping)

• 패키지는 맞는 항목이 있을 때 Claude API 오류를 Apple의 LanguageModelError 사례 (Case)로 매핑함
• 컨텍스트 창 (Context Window) 초과는 .contextSizeExceeded, HTTP 429는 .rateLimited, 설정된 제한 시간 (Timeout)을 넘긴 요청은 .timeout으로 드러남
• 프레임워크에 대응 항목이 없는 제공자 (Provider) 오류는 ClaudeError로 드러남
• 제품 흐름 제어에는 패턴 매칭 (Pattern Matching)을 사용할 수 있음

do {
let response = try await session.respond(to: prompt)
print(response.content)
...

• 일반적인 패턴은 .rateLimited를 잡아 해당 턴을 SystemLanguageModel로 폴백 (Fallback)하거나, 요청을 큐 (Queue)에 넣거나, 재시도 수단을 표시하는 방식임

Foundation Models 프로토콜 밖 기능 (Features Outside Foundation Models Protocol)

• 패키지는 Foundation Models 제공자 프로토콜이 표현할 수 있는 Messages API 기능만 노출함
• Apple 프로토콜에 표현 방식이 없는 기능은 이 패키지를 통해 사용할 수 없음
• 프롬프트 캐싱 (Prompt Caching) 제어는 불가능하며, 패키지가 프롬프트 캐싱을 자동 적용하지만 캐시 TTL과 중단점 위치는 설정할 수 없음
• 중지 시퀀스 (Stop Sequences)는 사용할 수 없음
• 배치 처리 (Batch Processing)는 사용할 수 없음
• Files API는 사용할 수 없음
• 토큰 카운팅 (Token Counting)은 사용할 수 없음
• 베타 헤더 (Beta Headers)는 사용할 수 없음

라이선스와 기여 (Licensing and Contributions)

• 패키지는 Apache 2.0 라이선스를 따름
• 버그 리포트는 GitHub 이슈로 받을 수 있음
• 베타 기간에는 외부 풀 리퀘스트 (Pull Request)를 받지 않음