CLI, SDK 및 라이브러리라이브러리 및 통합

Apple Foundation Models

Claude for Foundation Models Swift 패키지를 통해 Foundation Models 프레임워크로 Apple 플랫폼에서 Claude를 사용하세요.

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

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

베타. 이 패키지는 OS 27 베타에서 도입된 Foundation Models 서버 측 언어 모델 API를 대상으로 합니다. API는 정식 출시 전에 변경될 수 있습니다.

Claude for Foundation Models는 범용 Messages API 클라이언트가 아닙니다. 공개 인터페이스는 Foundation Models 프로바이더 준수와 이에 도달하는 구성 타입(ClaudeLanguageModel, ClaudeModel, AuthMode, ClaudeServerTool)입니다. 다른 언어에서 Messages API에 직접 접근하려면 클라이언트 SDK를 참조하세요.

요구 사항

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

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

모델 선택

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

ClaudeLanguageModel(name: .opus4_8, auth: auth)

상수는 API 모델 ID를 반영하며(.opus4_8은 claude-opus-4-8) 각 모델의 기능을 포함합니다. 새 모델은 패키지 릴리스에서 새 상수로 제공됩니다. 현재 목록은 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에서 끝나기 때문에 .xhigh 또는 .max를 요청하는 유일한 방법입니다. effort가 전송되지 않으면 API는 기본적으로 high를 사용합니다:

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

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

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

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

인증

auth: 매개변수로 자격 증명을 설정하세요.

API 키(개발)

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

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

앱에 번들된 키는 배포 바이너리에서 추출할 수 있으며, 이를 추출한 사람은 누구나 귀하의 계정으로 청구되는 요청을 보낼 수 있습니다. .apiKey는 개발용으로만 사용하고, 릴리스 전에 프록시로 전환하세요.

프록시(프로덕션)

프로덕션에서는 .proxied를 사용하여 자체 백엔드를 통해 요청을 라우팅하세요. baseURL의 릴레이가 서버 측에서 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으로 전달합니다.

스트리밍

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: .sonnet4_6,
  auth: auth,
  serverTools: [
    .webSearch(maxUses: 5),
    .codeExecution,
  ]
)

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

세션 타입은 Apple의 것이므로 serverTools는 LanguageModelSession이 아닌 ClaudeLanguageModel에서 구성됩니다. 대화별로 다른 서버 도구 세트를 사용하려면 여러 ClaudeLanguageModel 인스턴스를 생성하세요.

이미지

이미지 입력 기능을 포함하는 모델은 프레임워크의 비전 기능을 선언합니다. 프레임워크의 표준 세션 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
토큰 카운팅
베타 헤더

추가 리소스

참조	내용
Apple Foundation Models 문서	`LanguageModelSession`, `@Generable`, `Transcript`, `Tool` 및 나머지 프레임워크 인터페이스
GitHub의 `ClaudeForFoundationModels`	소스, 실행 가능한 예제, 이슈 트래커
Claude API 레퍼런스	기반이 되는 Messages API

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

Was this page helpful?

CLI, SDK 및 라이브러리라이브러리 및 통합

Apple Foundation Models

Claude for Foundation Models Swift 패키지를 통해 Foundation Models 프레임워크로 Apple 플랫폼에서 Claude를 사용하세요.

베타. 이 패키지는 OS 27 베타에서 도입된 Foundation Models 서버 측 언어 모델 API를 대상으로 합니다. API는 정식 출시 전에 변경될 수 있습니다.

요구 사항

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

모델 선택

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

ClaudeLanguageModel(name: .opus4_8, auth: auth)

기능

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

Effort

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

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

인증

auth: 매개변수로 자격 증명을 설정하세요.

API 키(개발)

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

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

프록시(프로덕션)

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으로 전달합니다.

스트리밍

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)

도구 사용

클라이언트 측 도구

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

서버 측 도구

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

이미지

오류 처리

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를 표시하는 것입니다.

기능 지원

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

추가 리소스

참조	내용
Apple Foundation Models 문서	`LanguageModelSession`, `@Generable`, `Transcript`, `Tool` 및 나머지 프레임워크 인터페이스
GitHub의 `ClaudeForFoundationModels`	소스, 실행 가능한 예제, 이슈 트래커
Claude API 레퍼런스	기반이 되는 Messages API

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

Was this page helpful?