Anthropic, Apple Foundation Models에서 Claude 쓰는 Swift 패키지 공개

9bow · 6월 16, 2026, 9:30오후

Claude for Foundation Models 소개

애플은 OS 26 세대부터 기기에서 직접 도는 소형 언어 모델을 다루기 위한 Foundation Models 프레임워크를 제공해 왔습니다. 개발자는 LanguageModelSession이라는 단일 API로 프롬프트를 보내고, 응답을 스트리밍으로 받고, 타입 안전한 구조화된 출력을 요청하고, 기기 위에서 도구(tool)를 호출할 수 있습니다. 이 프레임워크의 매력은 일관성에 있습니다. 한 번 익힌 세션 API로 모든 모델 상호작용을 처리할 수 있고, 앱 코드가 특정 모델의 SDK 형태에 묶이지 않습니다.

다만 애플의 온디바이스(on-device) 모델은 빠르고, 사생활을 보호하며, 오프라인에서도 동작하지만 가벼운 작업을 위해 설계된 작은 모델입니다. 더 긴 컨텍스트, 더 강한 추론(reasoning), 또는 웹 검색이나 코드 실행 같은 서버 측 도구가 필요한 순간에는 한계가 분명합니다. 바로 이 지점을 메우기 위해 Anthropic이 Claude for Foundation Models를 공개했습니다. 이 Swift 패키지는 Claude를 애플 Foundation Models 프레임워크의 서버 측 언어 모델로 노출시킵니다.

핵심 설계는 단순하고 강력합니다. 패키지가 Claude를 프레임워크의 LanguageModel 프로토콜에 맞춰 구현(conform)하기 때문에, 애플의 온디바이스 모델을 쓸 때와 완전히 동일한 LanguageModelSession API로 Claude를 구동합니다. respond(to:), 스트리밍, 가이드 기반 생성(guided generation), 도구 호출이 모두 같은 방식으로 작동합니다. 앱 입장에서 모델을 바꾸는 일은 세션에 넘기는 model: 인자를 교체하는 것뿐입니다. 요청은 앱에서 Claude API로 직접 전달되며, 애플은 요청 경로에 끼어들지 않고 프롬프트나 응답을 보지 않습니다. 사용량은 표준 API 요금에 따라 Anthropic 계정에 청구됩니다.

이 패키지는 OS 27 베타에서 도입된 Foundation Models의 서버 측 언어 모델 API를 대상으로 하는 베타(Beta) 단계입니다. 정식 출시 전까지 API가 변경될 수 있습니다. 또한 이 패키지는 범용 Messages API 클라이언트가 아닙니다. 다른 언어에서 Messages API에 직접 접근하려면 클라이언트 SDK 목록을 참고하시기 바랍니다.

같은 세션 API로 온디바이스와 Claude를 함께 다루는 구조

이 패키지가 해결하는 문제를 한 문장으로 요약하면, "앱 코드를 거의 바꾸지 않고도 작업의 난이도에 따라 모델을 갈아끼우는 것" 입니다. 일반적으로 클라우드 LLM을 붙이려면 그 제공자의 전용 SDK를 가져와 별도의 요청/응답 처리 코드를 짜야 합니다. 그러면 앱 안에 온디바이스 경로와 클라우드 경로라는 서로 다른 두 갈래의 코드가 생깁니다.

Claude for Foundation Models는 이 두 갈래를 하나로 합칩니다. Claude가 LanguageModel 프로토콜을 따르므로, 세션을 만들 때 모델만 다르게 지정하면 나머지 호출 코드는 그대로 재사용됩니다. 덕분에 "평소에는 온디바이스 모델로 빠르고 저렴하게 처리하다가, 무거운 요청이 들어오면 같은 코드 흐름에서 Claude로 승격(escalate)한다" 는 패턴을 자연스럽게 구현할 수 있습니다.

패키지의 공개 표면(public surface)은 Foundation Models 제공자 구현과 거기에 닿는 설정 타입들로 의도적으로 좁게 유지됩니다. 핵심 타입은 진입점인 ClaudeLanguageModel, 모델 식별자와 능력을 담는 ClaudeModel, 인증 방식을 정하는 AuthMode, 그리고 서버 측 도구를 구성하는 ClaudeServerTool 네 가지입니다.

설치와 빠른 시작

이 패키지는 베타 단계이며, 다음 환경을 요구합니다. 특히 Foundation Models 프레임워크 자체는 OS 26 세대부터 온디바이스 모델용으로 제공되었지만, 이 패키지가 사용하는 서버 측 언어 모델 API 는 OS 27 베타에서 도입되었기 때문에 OS 27 이상이 필요합니다.

iOS 27, macOS 27, visionOS 27, watchOS 27 (모두 베타): Foundation Models 프레임워크가 서버 측 언어 모델을 지원하는 OS 릴리스
Xcode 27 (베타)
개발용 Claude API 키 (프로덕션 환경의 인증 방식은 아래 "인증" 섹션 참고)

먼저 Swift Package Manager를 통해 패키지를 의존성으로 추가합니다. Package.swift에 다음을 더하거나, Xcode에서 File > Add Package Dependencies… 메뉴에 저장소 URL을 입력하면 됩니다.

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

그다음 타겟 의존성에 ClaudeForFoundationModels를 추가하고, FoundationModels와 함께 임포트합니다.

import FoundationModels
import ClaudeForFoundationModels

진입점은 ClaudeLanguageModel입니다. 이를 LanguageModelSession에 넘긴 뒤, 다른 어떤 Foundation Models 제공자와도 똑같은 방식으로 세션을 사용합니다.

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)

초기화 함수는 baseURL(기본값 https://api.anthropic.com), timeout, 그리고 서버 측 도구를 위한 serverTools 인자도 받습니다. 저장소에는 한 번의 대화 턴을 LanguageModelSession으로 터미널에 스트리밍하고 마지막에 토큰 사용량까지 출력하는 실행 가능한 명령줄 예제 Examples/ClaudeExample이 포함되어 있습니다. 다만 이 예제를 실행하려면 macOS 27 호스트가 필요합니다.

ANTHROPIC_API_KEY=<key> swift run ClaudeExample "What should I see in Kyoto?"

--search 플래그를 주면 해당 턴에서 서버 측 웹 검색이 켜집니다.

ANTHROPIC_API_KEY=<key> swift run ClaudeExample --search "Top spaceflight news this week?"

모델 선택과 능력(Capabilities) 선언

모델 식별자는 ClaudeModel 타입의 값입니다. 패키지에 컴파일되어 들어 있는 상수를 쓰거나, 아직 컴파일되지 않은 ID는 능력을 명시해 직접 구성합니다.

ClaudeLanguageModel(name: .opus4_8, auth: auth)

상수는 API 모델 ID를 그대로 반영합니다. 예를 들어 .opus4_8은 claude-opus-4-8에 해당하며, 각 모델의 능력 정보를 함께 담고 있습니다. 새 모델은 패키지 릴리스마다 새로운 상수로 추가되므로, 현재 사용할 수 있는 목록은 Xcode에서 ClaudeModel을 확인하고, 모델 간 비교는 모델 개요(Models overview) 문서를 참고하면 됩니다.

여기서 한 가지 짚어둘 점이 있습니다. claude-opus-4-8처럼 날짜가 붙지 않은 모델 ID(4.6 세대 이후)는 그때그때 최신 모델을 가리키는 별칭이 아니라 고정된 스냅샷(pinned snapshot) 입니다. 즉, 같은 ID 뒤에 있는 모델이 어느 날 조용히 다른 버전으로 바뀌는 일이 없으므로, 앱이 의존하는 모델 동작이 배포 이후에도 일정하게 유지됩니다.

각 ClaudeModel은 자신이 무엇을 받아들이는지를 선언합니다. 샘플링 파라미터, 노력 수준(effort level), 적응형 사고(adaptive thinking), 구조화된 출력, 이미지 입력 등이 여기에 포함됩니다. 패키지는 이 정보를 바탕으로 어떤 요청 필드를 보낼지 결정하는데, 모델이 거부하는 필드를 보내는 것은 곧바로 오류가 되기 때문입니다. 컴파일된 상수는 올바른 능력을 이미 담고 있고, 아직 컴파일되지 않은 ID라면 모델이 받아들이는 능력을 직접 선언해야 합니다. 의도적으로 능력을 추측하는 단축 표기를 두지 않았다는 점이 특징입니다.

let model = ClaudeModel(
  id: "claude-experimental-x",
  capabilities: .init(effortLevels: [.low, .high], structuredOutput: true)
)
ClaudeLanguageModel(name: model, auth: auth)

노력 수준(Effort)을 고정하기

fixedEffort: 인자로 모든 요청에 Claude의 노력 수준(effort level)을 고정할 수 있습니다. 이 값은 프레임워크가 요청마다 주는 추론 힌트보다 우선합니다. 노력 수준을 아예 보내지 않으면 API는 기본값으로 high를 사용합니다.

ClaudeLanguageModel(name: .opus4_8, auth: auth, fixedEffort: .xhigh)

fixedEffort를 지정하지 않은 경우, 패키지는 프레임워크가 요청마다 건네는 추론 수준(reasoning level)을 다음 규칙에 따라 Claude의 노력 수준으로 변환해 보냅니다.

.light 는 low 로
.moderate 는 medium 으로
.deep 는 high 로
.custom 은 Claude의 노력 수준 이름("xhigh", "max" 등)을 직접 받습니다

즉 프레임워크가 자동으로 거는 일반 추론 수준은 high까지만 닿기 때문에, .xhigh나 .max를 쓰려면 fixedEffort로 고정하거나 .custom으로 직접 지정해야 합니다. 또한 모델이 받아들이지 않는 수준은 그대로 버려집니다. 추론 수준은 반드시 지켜지는 계약이 아니라 힌트이기 때문입니다.

지정하는 수준은 모델이 받아들이는 것이어야 합니다. 각 ClaudeModel은 다섯 단계(low, medium, high, xhigh, max) 중 자신이 어떤 것을 받는지 선언하며, 일부 모델은 노력 수준 자체를 받지 않습니다.

언제 온디바이스 모델을 쓰고 언제 Claude를 쓰는가

이 패키지의 가치는 두 모델을 상황에 맞게 나눠 쓰는 데 있습니다. 애플의 온디바이스 모델은 응답이 빠르고, 데이터가 기기를 벗어나지 않아 사생활을 보호하며, 네트워크 없이도 동작합니다. 자동 완성, 짧은 요약, 간단한 분류처럼 가벼운 작업에 적합합니다.

반면 큰 컨텍스트가 필요하거나, 프런티어급 추론이 필요하거나, 웹 검색과 코드 실행 같은 서버 측 도구가 필요한 작업에는 Claude로 승격하는 편이 낫습니다. 두 경로 모두 같은 LanguageModelSession API를 쓰므로, 전환은 model: 인자를 바꾸는 것만으로 끝납니다. 이 단순함 덕분에 "요청의 성격을 보고 런타임에 모델을 고른다" 는 라우팅 로직을 앱 안에 깔끔하게 넣을 수 있습니다.

인증: 개발용 API 키와 프로덕션 프록시

자격 증명은 auth: 파라미터로 설정합니다. 패키지는 개발 단계와 배포 단계에 각각 어울리는 두 가지 방식을 제공합니다.

API 키 (개발 단계)

개발 중에는 API 키를 직접 넘길 수 있습니다. 개발용 키는 Claude Console에서 발급받습니다.

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

앱 바이너리에 박아 넣은 키는 배포된 실행 파일에서 추출할 수 있고, 추출에 성공한 사람은 누구나 여러분의 계정으로 청구되는 요청을 보낼 수 있습니다. 따라서 .apiKey는 개발용으로만 쓰고, 출시 전에 반드시 프록시 방식으로 전환해야 합니다.

프록시 (프로덕션 단계)

프로덕션에서는 .proxied로 요청을 자체 백엔드를 거쳐 보냅니다. baseURL에 지정한 중계 서버(relay)가 Claude API 자격 증명을 서버 측에서 붙여 주므로, 앱에는 키가 전혀 실리지 않습니다. 여러분이 제공하는 headers는 모든 요청에 함께 전송되어 프록시가 호출자를 인증할 수 있게 합니다. 인증이 필요 없다면 [:]을 넘기면 됩니다.

ClaudeLanguageModel(
  name: .sonnet4_6,
  auth: .proxied(headers: ["X-App-Token": "..."]),
  baseURL: URL(string: "https://api.yourapp.com/claude")!
)

이 구성에서 프록시는 표준 Messages API 요청을 받아 x-api-key 헤더를 붙인 뒤 https://api.anthropic.com으로 전달합니다.

곧 추가될 인증 방식: 백엔드가 필요 없는 프로덕션 모드

Anthropic은 자체 백엔드를 운영하지 않고도 프로덕션에서 쓸 수 있는 세 번째 인증 방식을 준비 중이라고 밝혔습니다. 이 방식에서는 각 앱 설치본이 애플의 App Attest로 자신의 무결성을 증명하고, 사용량은 여러분의 Anthropic 워크스페이스로 직접 청구됩니다. 프록시 중계 서버를 따로 세우지 않고도 앱에 키를 싣지 않을 수 있게 되는 셈입니다. 다만 이 모드가 정식 출시되기 전까지는 개발에는 .apiKey, 프로덕션에는 위의 .proxied를 사용하면 됩니다.

스트리밍, 구조화된 출력, 이미지 입력

스트리밍

streamResponse(to:)는 응답을 점진적으로 돌려줍니다. 주의할 점은 각 요소가 변화분(delta)이 아니라 지금까지의 응답 전체에 대한 누적 스냅샷(cumulative snapshot)이라는 것입니다.

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

구조화된 출력

타입에 @Generable을 붙이고 generating:으로 요청하면, 모델은 구조화된 출력(structured outputs)을 통해 해당 타입의 값을 돌려줍니다. 자유 텍스트를 파싱할 필요 없이 곧바로 타입 안전한 값을 얻는다는 점이 강력합니다.

@Generable
struct Trip {
  @Guide(description: "Destination city") var destination: String
  @Guide(description: "Length in days") var days: Int
}

let response = try await session.respond(to: "Plan a trip to Tokyo.", generating: Trip.self)
print(response.content.destination)

구조화된 출력은 해당 능력을 가진 모델에서만 동작합니다. 컴파일된 상수는 모두 이 능력을 갖추고 있지만, 만약 선택한 모델이 지원하지 않으면 패키지는 조용히 품질을 떨어뜨리는 대신 LanguageModelError.unsupportedGenerationGuide 오류를 던집니다.

이미지 입력

이미지 입력 능력을 가진 모델은 프레임워크의 비전(vision) 능력을 선언합니다. 프레임워크의 표준 세션 API로 이미지 콘텐츠를 넘기면, 패키지가 이를 Claude API의 이미지 포맷으로 변환합니다. 이미지 요구사항은 비전(Vision) 문서를 참고하면 됩니다.

도구 사용: 클라이언트 측 도구와 서버 측 도구

클라이언트 측 도구

프레임워크의 tools: 배열은 그대로 작동합니다. 타입을 Tool 프로토콜에 맞춰 구현해 LanguageModelSession에 넘기면, Claude가 그 도구를 호출할 때 프레임워크가 기기 위에서 도구를 실행합니다. 자세한 내용은 Claude와 도구 사용(Tool use) 문서를 참고하시기 바랍니다.

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

서버 측 도구

서버 측 도구(Server tools)는 웹 검색, 웹 페치(web fetch), 코드 실행을 가리키며, Anthropic의 인프라 위에서 단일 왕복(round trip) 안에 실행됩니다. 기기에서 따로 실행할 것이 없다는 점이 클라이언트 측 도구와의 차이입니다. 서버 측 도구는 모델별로 serverTools:로 구성합니다.

let model = ClaudeLanguageModel(
  name: .sonnet4_6,
  auth: auth,
  serverTools: [
    .webSearch(maxUses: 5),
    .codeExecution,
  ]
)

.webSearch와 .webFetch는 domains: 인자로 접근 범위를 좁힐 수 있습니다. 기본값은 제한을 두지 않는 .unrestricted 이며, .allowing([...])로 허용할 도메인만 지정하거나 .blocking([...])로 특정 도메인을 차단할 수 있고, 여기에 선택적으로 maxUses로 호출 횟수 상한을 더할 수 있습니다. 서버 측 도구의 활동은 트랜스크립트에서 ClaudeServerToolSegment 커스텀 세그먼트로 드러납니다.

serverTools는 LanguageModelSession이 아니라 ClaudeLanguageModel에 구성합니다. 세션 타입은 애플이 소유하기 때문입니다. 대화별로 서로 다른 서버 측 도구 집합을 쓰려면 ClaudeLanguageModel 인스턴스를 여러 개 만들면 됩니다.

오류 처리와 지원 범위

패키지는 Claude API 오류를 맞아떨어지는 애플의 LanguageModelError 케이스로 매핑합니다. 컨텍스트 윈도우 초과는 .contextSizeExceeded로, HTTP 429는 .rateLimited로, 설정한 타임아웃을 넘긴 요청은 .timeout으로 드러납니다. 프레임워크에 대응하는 케이스가 없는 제공자 오류는 ClaudeError로 표면화됩니다. 패턴 매칭으로 제품 흐름을 분기할 수 있습니다.

do {
  let response = try await session.respond(to: prompt)
  print(response.content)
} catch ClaudeError.missingCredential {
  // Prompt for an API key.
} catch let error as LanguageModelError {
  // Framework-shaped errors (rate limits, guardrails, context length, decoding).
} catch {
  // Transport errors.
}

자주 쓰이는 패턴은 .rateLimited를 잡아 그 턴에 한해 온디바이스 모델인 SystemLanguageModel로 대체하거나, 요청을 큐에 넣거나, 사용자에게 재시도 버튼을 제공하는 것입니다.

지원하지 않는 기능

이 패키지는 Foundation Models 제공자 프로토콜이 표현할 수 있는 Messages API 능력만 노출합니다. 애플 프로토콜에 표현할 자리가 없는 기능은 패키지를 통해 사용할 수 없으며, 다음이 여기에 해당합니다.

프롬프트 캐싱(prompt caching) 제어: 패키지가 프롬프트 캐싱을 자동으로 적용하지만, 캐시 TTL이나 중단점(breakpoint) 위치는 설정할 수 없습니다.
정지 시퀀스(stop sequences)
배치 처리(batch processing)
파일 API(Files API)
토큰 카운팅(token counting)
베타 헤더(beta headers)

정리: 애플 생태계 개발자를 위한 점진적 승격 경로

Claude for Foundation Models의 의의는 애플 개발자가 이미 익숙한 도구를 그대로 두고도 클라우드 LLM의 능력을 끌어올 수 있게 한다는 데 있습니다. 새로운 SDK의 요청/응답 모델을 학습하거나 앱 안에 별도 코드 경로를 만들 필요 없이, LanguageModelSession이라는 단일 추상화 위에서 온디바이스 모델과 Claude를 같은 코드로 다룹니다. 가벼운 작업은 기기에서 빠르고 사적으로 처리하고, 무거운 작업만 Claude로 승격하는 점진적 설계가 이 패키지의 핵심 가치입니다.

다만 현재는 OS 27 베타와 Xcode 27 베타를 요구하는 베타 단계이므로, 정식 출시 전까지 API 변경 가능성을 염두에 두는 것이 좋습니다. 프로덕션을 준비한다면 출시 전에 반드시 API 키 직접 삽입에서 프록시 방식으로 전환해야 한다는 점도 잊지 말아야 합니다.

Apple Foundation Models 공식 문서

Claude for Foundation Models GitHub 저장소

더 읽어보기

Apple Foundation Models 공식 개발자 문서 - LanguageModelSession, @Generable, Transcript, Tool 등 프레임워크 전반
Claude API(Messages API) 레퍼런스 - 이 패키지가 내부적으로 사용하는 API
Apple, macOS 환경에서 Apple Intelligence의 Foundation Model에 접근할 수 있는 Python SDK 공개
Apple, 3세대 파운데이션 모델(AFM) 5종 공개, 온디바이스 희소 아키텍처로 진화한 Apple Intelligence
apple-on-device-openai: Apple의 On-Device 모델을 OpenAI 호환 API로 운영할 수 있도록 하는 프로젝트

라이선스

Claude for Foundation Models는 Apache License 2.0으로 배포되고 있어, 연구 목적은 물론 상업적 용도로도 자유롭게 사용 및 수정이 가능합니다. 다만 이 패키지는 best-effort 방식으로 있는 그대로(as is) 유지보수되며, 외부 풀 리퀘스트(pull request)는 받지 않습니다. 버그 리포트와 피드백은 GitHub 이슈로 환영하고 있습니다.

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~