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 konformiert Claude zum LanguageModel-Protokoll des Frameworks, sodass du es mit derselben LanguageModelSession-API steuerst, die du für Apples On-Device-Modell verwendest: respond(to:), Streaming, Guided Generation und Tool-Aufrufe funktionieren alle auf die gleiche 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 jeder Session das Modell, das du verwenden möchtest.



Anforderungen

• 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.



Installation des Pakets

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 Foundation-Models-Provider tun würdest:

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)

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 den Turn aktiviert. Die Ausführung erfordert einen macOS-27-Host.



Auswahl eines Modells

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: .opus5, auth: auth)

Die Konstanten spiegeln API-Modell-IDs wider (.opus5 ist claude-opus-5) und tragen die Capabilities des jeweiligen Modells. Neue Modelle erscheinen als neue Konstanten in Paket-Releases; 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 bestimmen, welche Request-Felder gesendet werden, denn das Senden eines Feldes, das ein Modell ablehnt, ist ein harter 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 Reasoning-Hinweisen des Frameworks pro Anfrage. Die benannten Reasoning-Level des Frameworks enden bei high; um stattdessen für eine einzelne Anfrage mehr Effort anzufordern, übergib ein benutzerdefiniertes Reasoning-Level, das das Claude-Effort benennt (.custom("xhigh") oder .custom("max")), was direkt abgebildet wird. Die API verwendet standardmäßig high, wenn kein Effort gesendet wird:

ClaudeLanguageModel(name: .opus5, 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 statt des On-Device-Modells verwenden

Apples On-Device-Modell ist schnell, privat und offline verfügbar, aber es ist für leichtgewichtige Aufgaben dimensioniert. Eskaliere zu Claude, wenn du einen größeren Kontext, Frontier-Reasoning oder serverseitige Tools wie Websuche und Code-Ausführung benötigst. Da beide dieselbe LanguageModelSession-API verwenden, kannst du durch Austauschen des model:-Arguments wechseln.



Authentifizierung

Setze die Anmeldedaten mit dem auth:-Parameter.



API-Key (Entwicklung)

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

ClaudeLanguageModel(name: .sonnet5, 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 gesendet, damit dein Proxy den Aufrufer autorisieren kann. Übergib [:], wenn keine benötigt werden:

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

Dein Proxy empfängt standardmäßige 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 Schnappschuss 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 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 sie einschließen (alle einkompilierten Konstanten tun dies). Wenn das gewählte Modell dies nicht tut, wirft das Paket LanguageModelError.unsupportedGenerationGuide, anstatt stillschweigend zu degradieren.



Tool-Nutzung



Clientseitige Tools

Das tools:-Array des Frameworks funktioniert unverändert. Konformiere deine Typen zu Tool, ü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 für jedes Modell mit serverTools::

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

.webSearch und .webFetch akzeptieren optional allowedDomains, blockedDomains und maxUses. Server-Tool-Aktivität erscheint im Transkript 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. Verwende Pattern-Matching, um Produktabläufe zu steuern:

do {
  let response = try await session.respond(to: prompt)
  print(response.content)
} catch ClaudeError.missingCredential {
  // Frage nach einem API-Key.
} catch let error as LanguageModelError {
  // Framework-spezifische Fehler (Ratenlimits, Guardrails, Kontextlänge, Dekodierung).
} 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 Wiederholungsmöglichkeit anzubieten.



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.