Apple Foundation Models

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

요청은 앱에서 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: 파라미터로 자격 증명을 설정하세요. 백엔드 없이 출시하려면 .appAttest를, 자체 백엔드를 통해 요청을 라우팅하려면 .proxied를, 개발 중 반복 작업에는 .apiKey를 사용하세요.

App Attest

앱의 각 설치본은 Apple의 App Attest 서비스를 사용하여 해당 설치본이 여러분이 등록한 앱의 정품이며 변조되지 않은 빌드임을 증명합니다. 그러면 Anthropic은 해당 기기에 사용량을 여러분의 워크스페이스로 청구하는 단기 "access token"(액세스 토큰)을 발급합니다. 앱에는 API 키가 포함되지 않으며, 여러분이 운영해야 할 프록시도 없습니다.

App Attest 인증은 앱이 Claude API를 직접 호출하는 경우에만 사용할 수 있습니다. Amazon Bedrock, Google Cloud 또는 Microsoft Foundry를 통해서는 사용할 수 없습니다.

백엔드를 운영하지 않고 출시하려면 .appAttest를 사용하세요:

ClaudeLanguageModel(
  name: .sonnet5,
  auth: .appAttest(clientID: "clid_...")
)

App Attest를 설정하려면 Apple Developer Team ID와 조직 내 admin, owner 또는 primary owner 역할이 필요합니다. Xcode 프로젝트를 구성하고 Claude Console에 앱을 등록하세요:

1. Xcode에서 Signing & Capabilities 아래의 앱 타겟에 App Attest 기능을 추가하세요.
2. Claude Console의 워크스페이스 설정에서 App integrations를 여세요.
3. Create app integration을 클릭하고 이름, Apple Developer Team ID, 그리고 하나 이상의 번들 ID(최대 32개)를 입력하세요.
4. 통합의 Overview 탭에서 클라이언트 ID(clid_...)를 복사하여 앱의 Claude 구성에 전달하세요.

앱이 기기에서 처음으로 Claude를 사용할 때, 앱은 Anthropic에 챌린지를 요청하고, Apple의 DCAppAttestService로 기기를 증명(attest)한 다음, 검증된 증명을 액세스 토큰으로 교환합니다. Claude for Foundation Models 패키지는 이 흐름을 자동으로 실행하며 토큰이 만료되면 새 토큰을 요청합니다. 따라서 직접 작성해야 할 증명 코드는 없습니다.

토큰은 워크스페이스 범위로 한정되며, 1시간 후에 만료되고, Messages API 호출만 승인합니다. 토큰에는 최종 사용자 신원 정보가 포함되지 않습니다. App Attest는 앱을 사용하는 사람이 아니라 앱 자체를 식별하므로, 사용자별 로직은 앱 내에서 처리하세요.

침해되었거나 종료된 앱을 중지하려면 해당 통합을 취소하세요. Claude Console의 워크스페이스 설정에서 App integrations를 열고, 해당 통합을 선택한 다음 Revoke를 클릭하고 확인하세요. 통합을 취소하면 해당 통합의 미사용 토큰이 모두 취소되며, 등록된 기기는 더 이상 새 토큰을 요청할 수 없습니다. 취소는 영구적이므로, 액세스를 복원하려면 새 앱 통합을 생성하세요.

프록시(프로덕션)

프로덕션에서는 .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으로 전달합니다.

API 키(개발)

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

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

스트리밍

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 이슈를 통해 환영합니다. 베타 기간 동안에는 외부 풀 리퀘스트를 받지 않습니다.