Apple Foundation Models

Claude for Foundation Models는 Apple의 Foundation Models 프레임워크에서 Claude를 서버 측 언어 모델로 사용할 수 있게 해주는 Swift 패키지입니다. 이 패키지는 Claude를 프레임워크의 LanguageModel 프로토콜에 맞게 구현하므로, Apple의 온디바이스 모델에 사용하는 것과 동일한 LanguageModelSession API로 구동할 수 있습니다. respond(to:), 스트리밍, 가이드 생성, 도구 호출이 모두 동일한 방식으로 작동합니다.

요청은 앱에서 Claude API로 직접 전송됩니다. Apple은 요청 경로에 포함되지 않으며 프롬프트나 응답을 볼 수 없습니다. 사용량은 표준 API 요금에 따라 Anthropic 계정에 청구됩니다. 언제 Claude를 사용하고 언제 Apple의 온디바이스 모델을 사용할지는 앱이 결정합니다. 각 세션에 원하는 모델을 전달하면 됩니다.



요구 사항

• iOS 27, macOS 27, visionOS 27 또는 watchOS 27(모두 베타): Foundation Models 프레임워크가 서버 측 언어 모델을 지원하는 OS 릴리스
• Xcode 27(베타)
• 개발용으로 Claude Console에서 발급받은 Claude API 키. 프로덕션 옵션은 인증을 참조하세요.



패키지 설치

Package.swift에 패키지를 추가하세요:

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(
  name: .sonnet5,
  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(서버 측 도구 참조)도 받습니다.

완전한 동작 프로그램으로, 저장소에는 Examples/ClaudeExample이 포함되어 있습니다. 이는 채팅 턴을 터미널로 스트리밍하는 실행 가능한 커맨드라인 타겟이며, 해당 턴에 대해 서버 측 웹 검색을 활성화하는 --search 플래그를 제공합니다. 실행하려면 macOS 27 호스트가 필요합니다.



모델 선택

모델 식별자는 ClaudeModel의 값입니다. 컴파일된 상수를 사용하거나, 아직 컴파일되지 않은 ID에 대해서는 명시적인 기능(capabilities)을 지정하여 생성하세요(기능 참조):

ClaudeLanguageModel(name: .opus5, auth: auth)

상수는 API 모델 ID를 반영하며(.opus5는 claude-opus-5), 각 모델의 기능을 포함합니다. 새 모델은 패키지 릴리스에서 새 상수로 제공됩니다. 현재 목록은 Xcode에서 ClaudeModel을 확인하고, 모델 비교는 모델 개요를 참조하세요.



기능

각 ClaudeModel은 샘플링 파라미터, effort 수준, 적응형 사고, 구조화된 출력, 이미지 입력 등 모델이 허용하는 항목을 선언합니다. 모델이 거부하는 필드를 전송하면 하드 에러가 발생하기 때문에, 패키지는 이를 사용하여 어떤 요청 필드를 보낼지 결정합니다. 상수는 올바른 기능을 포함하고 있습니다. 컴파일되지 않은 ID의 경우, 모델이 허용하는 항목을 직접 선언하세요(의도적으로 추측하는 축약형은 제공하지 않습니다):

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



Effort

fixedEffort:를 사용하여 모든 요청에 대해 Claude effort 수준을 고정할 수 있습니다. 이는 프레임워크의 요청별 추론 힌트보다 우선합니다. 프레임워크의 명명된 추론 수준은 high까지만 지원합니다. 대신 단일 요청에 대해 더 높은 effort를 요청하려면 Claude effort를 지정하는 커스텀 추론 수준(.custom("xhigh") 또는 .custom("max"))을 전달하세요. 이는 직접 매핑됩니다. effort가 전송되지 않으면 API는 기본값으로 high를 사용합니다:

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

수준은 모델이 허용하는 것이어야 합니다. 각 ClaudeModel은 다섯 가지 수준(low, medium, high, xhigh, max) 중 해당 모델이 허용하는 수준을 선언합니다(있는 경우). 일부 모델은 effort를 전혀 허용하지 않습니다.



Claude와 온디바이스 모델 중 선택하기

Apple의 온디바이스 모델은 빠르고, 프라이빗하며, 오프라인에서도 사용할 수 있지만 가벼운 작업에 맞게 설계되었습니다. 더 큰 컨텍스트, 프론티어 수준의 추론, 또는 웹 검색 및 코드 실행과 같은 서버 측 도구가 필요할 때는 Claude로 전환하세요. 둘 다 동일한 LanguageModelSession API를 사용하므로 model: 인자만 교체하면 전환할 수 있습니다.



인증

auth: 파라미터로 자격 증명을 설정하세요.



API 키(개발)

개발 중에는 API 키를 직접 전달하세요:

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



프록시(프로덕션)

프로덕션에서는 .proxied를 사용하여 자체 백엔드를 통해 요청을 라우팅하세요. baseURL의 릴레이가 서버 측에서 Claude API 자격 증명을 추가하므로 앱에는 키가 포함되지 않습니다. 제공한 headers는 모든 요청에 전송되므로 프록시가 호출자를 인가할 수 있습니다. 필요 없는 경우 [:]를 전달하세요:

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

프록시는 표준 Messages API 요청을 받아 x-api-key 헤더를 첨부하고 https://api.anthropic.com으로 전달합니다.



스트리밍

streamResponse(to:)는 응답을 점진적으로 반환합니다. 각 요소는 델타가 아니라 지금까지의 응답에 대한 누적 스냅샷입니다:

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



구조화된 출력

타입에 @Generable을 어노테이션하고 generating:으로 요청하세요. 모델은 구조화된 출력을 통해 해당 타입의 값을 반환합니다:

@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를 던집니다.



도구 사용



클라이언트 측 도구

프레임워크의 tools: 배열은 변경 없이 작동합니다. 타입을 Tool에 맞게 구현하고 LanguageModelSession에 전달하면, Claude가 호출할 때 프레임워크가 기기에서 이를 실행합니다. Claude의 도구 사용을 참조하세요.

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



서버 측 도구

서버 도구(웹 검색, 웹 페치, 코드 실행)는 단일 왕복 내에서 Anthropic의 인프라에서 실행되며, 프레임워크가 기기에서 실행할 것이 없습니다. 각 모델에 대해 serverTools:로 구성하세요:

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

.webSearch와 .webFetch는 선택적 allowedDomains, blockedDomains, maxUses를 받습니다. 서버 도구 활동은 트랜스크립트에 ClaudeServerToolSegment 커스텀 세그먼트로 표시됩니다.



이미지

이미지 입력 기능을 포함하는 모델은 프레임워크의 비전 기능을 선언합니다. 프레임워크의 표준 세션 API를 통해 이미지 콘텐츠를 전달하면 패키지가 이를 Claude API의 이미지 형식으로 변환합니다. 이미지 요구 사항은 비전을 참조하세요.



오류 처리

패키지는 Claude API 오류를 적합한 Apple의 LanguageModelError 케이스에 매핑합니다. 컨텍스트 윈도우 초과는 .contextSizeExceeded로, HTTP 429는 .rateLimited로, 구성된 타임아웃을 초과한 요청은 .timeout으로 표시됩니다. 프레임워크에 대응되는 것이 없는 프로바이더 오류는 ClaudeError로 표시됩니다. 패턴 매칭을 사용하여 제품 흐름을 제어하세요:

do {
  let response = try await session.respond(to: prompt)
  print(response.content)
} catch ClaudeError.missingCredential {
  // API 키 입력을 요청합니다.
} catch let error as LanguageModelError {
  // 프레임워크 형태의 오류 (속도 제한, 가드레일, 컨텍스트 길이, 디코딩).
} catch {
  // 전송 오류.
}

일반적인 패턴은 .rateLimited를 잡아서 해당 턴에 대해 SystemLanguageModel로 폴백하거나, 요청을 큐에 넣거나, 재시도 UI를 표시하는 것입니다.



기능 지원

패키지는 Foundation Models 프로바이더 프로토콜이 표현할 수 있는 Messages API 기능을 제공합니다. Apple의 프로토콜에 표현이 없는 기능은 이를 통해 사용할 수 없으며, 다음이 포함됩니다:

• 프롬프트 캐싱 제어(패키지는 프롬프트 캐싱을 자동으로 적용합니다. 캐시 TTL과 브레이크포인트 배치는 구성할 수 없습니다)
• 중지 시퀀스
• 배치 처리
• Files API
• 토큰 카운팅
• 베타 헤더



추가 리소스

패키지는 Apache 2.0 라이선스로 제공됩니다. 버그 리포트는 GitHub 이슈를 통해 환영합니다. 베타 기간 동안에는 외부 풀 리퀘스트를 받지 않습니다.