Apple Foundation Models

Claude for Foundation Models ist ein Swift-Paket, das Claude als serverseitiges Sprachmodell in Apples Foundation Models Framework verfügbar macht. Das Paket lässt Claude dem LanguageModel-Protokoll des Frameworks entsprechen, sodass du es mit derselben LanguageModelSession-API steuerst, die du auch für Apples On-Device-Modell verwendest: respond(to:), Streaming, Guided Generation und Tool Calling funktionieren alle auf dieselbe Weise.

Anfragen gehen direkt von deiner App an die Claude API; Apple befindet sich nicht im Anfragepfad und sieht weder Prompts noch Antworten. Die Nutzung wird deinem Anthropic-Konto zu den Standard-API-Preisen in Rechnung gestellt. Deine App entscheidet, wann Claude und wann Apples On-Device-Modell verwendet wird: Übergib einfach das gewünschte Modell an die jeweilige Session.

Voraussetzungen

• iOS 27, macOS 27, visionOS 27 oder watchOS 27 (alle in Beta): die OS-Versionen, deren Foundation Models Framework serverseitige Sprachmodelle unterstützt
• Xcode 27 (Beta)
• Ein Claude API-Key aus der Claude Console für die Entwicklung. Siehe Authentifizierung für Produktionsoptionen.

Paket installieren

Füge das Paket zu deiner Package.swift hinzu:

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

Oder in Xcode: File > Add Package Dependencies… und gib die Repository-URL ein.

Füge dann ClaudeForFoundationModels zu den Abhängigkeiten deines Targets hinzu und importiere es zusammen mit FoundationModels:

import FoundationModels
import ClaudeForFoundationModels

Schnellstart

ClaudeLanguageModel ist der Einstiegspunkt. Übergib es an LanguageModelSession und verwende die Session genau so, wie du es mit jedem anderen Foundation-Models-Provider tun würdest:

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)

Der Initializer akzeptiert außerdem baseURL (Standard: https://api.anthropic.com), timeout und serverTools (siehe Serverseitige Tools).

Für ein vollständiges, funktionierendes Programm enthält das Repository Examples/ClaudeExample, ein ausführbares Kommandozeilen-Target, das einen Chat-Turn ins Terminal streamt, mit einem --search-Flag, das die serverseitige Websuche für diesen Turn aktiviert. Zum Ausführen wird ein macOS-27-Host benötigt.

Ein Modell auswählen

Modell-Identifier sind Werte vom Typ ClaudeModel. Verwende eine einkompilierte Konstante oder konstruiere einen Wert mit expliziten Capabilities für eine ID, die noch nicht einkompiliert ist (siehe Capabilities):

ClaudeLanguageModel(name: .opus4_8, auth: auth)

Die Konstanten spiegeln die API-Modell-IDs wider (.opus4_8 ist claude-opus-4-8) und tragen die Capabilities des jeweiligen Modells. Neue Modelle werden als neue Konstanten in Paket-Releases ausgeliefert; prüfe ClaudeModel in Xcode für die aktuelle Liste und die Modellübersicht, um Modelle zu vergleichen.

Capabilities

Jedes ClaudeModel deklariert, was es akzeptiert: Sampling-Parameter, Effort-Level, adaptives Denken, strukturierte Ausgabe und Bildeingabe. Das Paket nutzt dies, um zu entscheiden, welche Request-Felder gesendet werden, denn das Senden eines Felds, das ein Modell ablehnt, führt zu einem harten Fehler. Die Konstanten tragen die richtigen Capabilities. Für eine ID, die nicht einkompiliert ist, deklariere, was das Modell akzeptiert (es gibt bewusst keine Kurzform, die rät):

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

Effort

Lege mit fixedEffort: ein Claude-Effort-Level für jede Anfrage fest. Es hat Vorrang vor den Per-Request-Reasoning-Hints des Frameworks und ist die einzige Möglichkeit, .xhigh oder .max anzufordern, da die Reasoning-Level des Frameworks bei „high" enden. Die API verwendet standardmäßig high, wenn kein Effort gesendet wird:

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

Das Level muss eines sein, das das Modell akzeptiert. Jedes ClaudeModel deklariert, welche der fünf Level (low, medium, high, xhigh, max) sein Modell annimmt, falls überhaupt: Manche Modelle akzeptieren gar kein Effort.

Wann Claude und wann das On-Device-Modell verwenden

Apples On-Device-Modell ist schnell, privat und funktioniert offline, ist aber für leichtgewichtige Aufgaben dimensioniert. Eskaliere zu Claude, wenn du größeren Kontext, Frontier-Reasoning oder serverseitige Tools wie Websuche und Code-Ausführung benötigst. Da beide dieselbe LanguageModelSession-API verwenden, kannst du wechseln, indem du das model:-Argument austauschst.

Authentifizierung

Setze die Anmeldedaten mit dem auth:-Parameter.

API-Key (Entwicklung)

Übergib während der Entwicklung direkt einen API-Key:

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

Proxy (Produktion)

Für die Produktion leite Anfragen mit .proxied über dein eigenes Backend. Das Relay unter baseURL fügt die Claude-API-Anmeldedaten serverseitig hinzu, sodass die App keinen Key ausliefert. Die von dir angegebenen headers werden bei jeder Anfrage mitgesendet, damit dein Proxy den Aufrufer autorisieren kann. Übergib [:], wenn er keine benötigt:

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

Dein Proxy empfängt Standard-Messages-API-Anfragen, fügt den x-api-key-Header hinzu und leitet sie an https://api.anthropic.com weiter.

Streaming

streamResponse(to:) gibt die Antwort inkrementell zurück. Jedes Element ist ein kumulativer Snapshot der bisherigen Antwort, kein Delta:

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

Strukturierte Ausgabe

Annotiere einen Typ mit @Generable und fordere ihn mit generating: an. Das Modell gibt über Structured Outputs (strukturierte Ausgaben) einen Wert dieses Typs zurück:

@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)

Strukturierte Ausgabe erfordert ein Modell, dessen Capabilities dies einschließen (alle einkompilierten Konstanten tun das). Wenn das gewählte Modell dies nicht unterstützt, wirft das Paket LanguageModelError.unsupportedGenerationGuide, anstatt stillschweigend zu degradieren.

Tool-Nutzung

Clientseitige Tools

Das tools:-Array des Frameworks funktioniert unverändert. Lass deine Typen dem Tool-Protokoll entsprechen, übergib sie an LanguageModelSession, und das Framework ruft sie auf dem Gerät auf, wenn Claude sie aufruft. Siehe Tool-Nutzung mit Claude.

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

Serverseitige Tools

Server-Tools (Websuche, Web-Fetch und Code-Ausführung) laufen auf Anthropics Infrastruktur innerhalb eines einzigen Roundtrips, ohne dass das Framework etwas auf dem Gerät aufrufen muss. Konfiguriere sie pro Modell mit serverTools::

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

.webSearch und .webFetch akzeptieren optional allowedDomains, blockedDomains und maxUses. Server-Tool-Aktivität erscheint im Transcript als benutzerdefinierte ClaudeServerToolSegment-Segmente.

Bilder

Modelle, deren Capabilities Bildeingabe einschließen, deklarieren die Vision-Capability des Frameworks. Übergib Bildinhalte über die Standard-Session-API des Frameworks; das Paket konvertiert sie in das Bildformat der Claude API. Siehe Vision für Bildanforderungen.

Fehlerbehandlung

Das Paket bildet Claude-API-Fehler auf Apples LanguageModelError-Fälle ab, wo einer passt: Ein Überlauf des Kontextfensters erscheint als .contextSizeExceeded, HTTP 429 als .rateLimited, eine Anfrage jenseits des konfigurierten Timeouts als .timeout. Provider-Fehler ohne Framework-Äquivalent erscheinen als ClaudeError. Nutze Pattern-Matching, um Produktabläufe zu steuern:

do {
  let response = try await session.respond(to: prompt)
  print(response.content)
} catch ClaudeError.missingCredential {
  // Fordere einen API-Key an.
} catch let error as LanguageModelError {
  // Framework-spezifische Fehler (Ratenlimits, Guardrails, Kontextlänge, Decoding).
} catch {
  // Transportfehler.
}

Ein gängiges Muster ist, .rateLimited abzufangen und für diesen Turn auf SystemLanguageModel zurückzufallen, die Anfrage in eine Warteschlange zu stellen oder eine Retry-Möglichkeit anzuzeigen.

Feature-Unterstützung

Das Paket stellt die Messages-API-Fähigkeiten bereit, die das Foundation-Models-Provider-Protokoll ausdrücken kann. Features ohne Repräsentation in Apples Protokoll sind darüber nicht verfügbar, darunter:

• Prompt-Caching-Steuerung (das Paket wendet Prompt-Caching automatisch an; Cache-TTL und Breakpoint-Platzierung sind nicht konfigurierbar)
• Stop-Sequenzen
• Batch-Verarbeitung
• Files API
• Token-Zählung
• Beta-Header

Zusätzliche Ressourcen

Das Paket ist unter Apache 2.0 lizenziert. Fehlerberichte sind über GitHub Issues willkommen. Externe Pull Requests werden während der Beta-Phase nicht angenommen.