Claude for Foundation Models는 Apple의 Foundation Models 프레임워크에서 Claude API를 LanguageModel 구현체처럼 사용할 수 있게 하는 Anthropic 공식 Swift 패키지다. 앱은 같은 LanguageModelSession 인터페이스로 Apple 온디바이스 모델과 Claude 서버 모델을 바꿔 쓸 수 있다.
핵심 개념
Apple Foundation Models는 iOS/macOS 앱에서 LanguageModelSession으로 언어 모델 응답, 스트리밍, 구조화 출력, 도구 호출을 다루는 프레임워크다. Claude for Foundation Models는 Claude를 이 프레임워크의 서버 측 언어 모델 제공자로 연결한다.
중요한 점은 요청 경로다. 프롬프트와 응답은 앱에서 Claude API로 직접 전송되며 Apple이 중간에서 요청을 보지 않는다. 비용은 Anthropic 계정의 표준 API 과금으로 처리된다.
언제 Claude를 쓰나
Apple 온디바이스 모델은 빠르고, 비공개이며, 오프라인 동작이 가능하다. 반면 Claude는 더 큰 컨텍스트, 강한 추론, 웹 검색·웹 fetch·코드 실행 같은 서버 측 도구가 필요한 작업에 적합하다.
앱 설계 관점에서는 다음처럼 역할을 나누는 편이 자연스럽다.
| 작업 | 권장 모델 |
|---|---|
| 짧은 텍스트 변환, 로컬 자동완성, 민감 데이터 처리 | Apple 온디바이스 모델 |
| 긴 문서 요약, 복잡한 계획, 외부 정보 검색, 코드 실행 | Claude |
| 네트워크 실패·요금 제한 시 대체 응답 | 온디바이스 모델 fallback |
설치와 기본 사용
패키지는 Swift Package Manager로 추가한다.
dependencies: [
.package(url: "https://github.com/anthropics/ClaudeForFoundationModels.git", from: "0.1.0")
]앱에서는 FoundationModels와 ClaudeForFoundationModels를 함께 import하고, ClaudeLanguageModel을 세션에 넘긴다.
import FoundationModels
import ClaudeForFoundationModels
let model = ClaudeLanguageModel(
name: .sonnet4_6,
auth: .apiKey(ProcessInfo.processInfo.environment["ANTHROPIC_API_KEY"] ?? "")
)
let session = LanguageModelSession(model: model)
let response = try await session.respond(to: "Plan a 4-day trip to Buenos Aires.")
print(response.content)개발 중에는 .apiKey를 쓸 수 있지만, 배포 앱에 API 키를 포함하면 바이너리에서 추출될 수 있다. 프로덕션에서는 .proxied 모드로 자체 백엔드를 거쳐 Claude API 키를 서버에 보관해야 한다.
지원 기능
Claude for Foundation Models는 Apple 프레임워크가 표현할 수 있는 Claude 기능을 우선 노출한다.
respond(to:)응답 생성streamResponse(to:)스트리밍@Generable기반 구조화 출력- 클라이언트 측 도구 호출
- Claude 서버 측 도구: 웹 검색, 웹 fetch, 코드 실행
- 이미지 입력
LanguageModelError에 맞춘 오류 매핑
모델별 기능은 ClaudeModel의 capability로 선언된다. 새 Claude 모델 ID를 직접 지정할 때도 지원 기능을 명시해야 하며, 패키지가 모델이 거부할 필드를 보내지 않도록 제어한다.
제한 사항
이 패키지는 Claude Messages API의 범용 클라이언트가 아니다. Apple Foundation Models 제공자 프로토콜로 표현 가능한 기능에 맞춘 어댑터다. 따라서 다음 기능은 직접 노출되지 않는다.
- 프롬프트 캐싱 TTL·breakpoint 제어
- stop sequence
- Batch API
- Files API
- 토큰 카운팅
- 베타 헤더
직접 Messages API를 세밀하게 제어해야 한다면 Anthropic의 일반 SDK를 쓰는 편이 맞다.
누가 쓰면 좋은가
- iOS/macOS 앱에서 Apple 온디바이스 모델과 Claude를 같은 추상화로 다루려는 개발자
- 민감하거나 짧은 작업은 로컬 모델로 처리하고, 어려운 작업만 Claude로 승격하려는 앱 팀
- SwiftUI 앱에 구조화 출력과 도구 호출 기반 AI 기능을 넣고 싶은 팀
참고 자료
- Apple Foundation Models — Anthropic 공식 문서 (2026-06-16 확인)
- anthropics/ClaudeForFoundationModels — GitHub 공식 저장소