Apple Foundation Models

Claude for Foundation Models est un package Swift qui rend Claude disponible en tant que modèle de langage côté serveur dans le framework Foundation Models d'Apple. Le package rend Claude conforme au protocole LanguageModel du framework, de sorte que vous le pilotez avec la même API LanguageModelSession que celle utilisée pour le modèle embarqué d'Apple : respond(to:), le streaming, la génération guidée et l'appel d'outils fonctionnent tous de la même manière.

Les requêtes vont directement de votre application à l'API Claude ; Apple n'est pas dans le chemin de la requête et ne voit ni les prompts ni les réponses. L'utilisation est facturée sur votre compte Anthropic selon la tarification standard de l'API. Votre application décide quand utiliser Claude et quand utiliser le modèle embarqué d'Apple : passez le modèle de votre choix à chaque session.

Prérequis

• iOS 27, macOS 27, visionOS 27 ou watchOS 27 (tous en bêta) : les versions d'OS dont le framework Foundation Models prend en charge les modèles de langage côté serveur
• Xcode 27 (bêta)
• Une clé API Claude obtenue depuis la Claude Console pour le développement. Consultez Authentification pour les options de production.

Installer le package

Ajoutez le package à votre Package.swift :

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

Ou dans Xcode : File > Add Package Dependencies… et saisissez l'URL du dépôt.

Ajoutez ensuite ClaudeForFoundationModels aux dépendances de votre cible et importez-le aux côtés de FoundationModels :

import FoundationModels
import ClaudeForFoundationModels

Démarrage rapide

ClaudeLanguageModel est le point d'entrée. Passez-le à LanguageModelSession et utilisez la session exactement comme vous le feriez avec n'importe quel fournisseur 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)

L'initialiseur accepte également baseURL (par défaut https://api.anthropic.com), timeout et serverTools (voir Outils côté serveur).

Pour un programme fonctionnel complet, le dépôt inclut Examples/ClaudeExample, une cible en ligne de commande exécutable qui diffuse en streaming un tour de conversation vers le terminal, avec un indicateur --search qui active la recherche web côté serveur pour ce tour. Son exécution nécessite un hôte macOS 27.

Choisir un modèle

Les identifiants de modèle sont des valeurs de ClaudeModel. Utilisez une constante compilée, ou construisez-en une avec des capacités explicites pour un identifiant qui n'est pas encore compilé (voir Capacités) :

ClaudeLanguageModel(name: .opus4_8, auth: auth)

Les constantes reflètent les identifiants de modèle de l'API (.opus4_8 correspond à claude-opus-4-8) et portent les capacités de chaque modèle. Les nouveaux modèles sont livrés sous forme de nouvelles constantes dans les versions du package ; consultez ClaudeModel dans Xcode pour la liste actuelle, et la vue d'ensemble des modèles pour comparer les modèles.

Capacités

Chaque ClaudeModel déclare ce qu'il accepte : paramètres d'échantillonnage, niveaux d'effort, réflexion adaptative, sortie structurée et entrée d'image. Le package utilise ces informations pour décider quels champs de requête envoyer, car envoyer un champ qu'un modèle rejette constitue une erreur bloquante. Les constantes portent les bonnes capacités. Pour un identifiant qui n'est pas compilé, déclarez ce que le modèle accepte (il n'existe délibérément aucun raccourci qui devine) :

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

Effort

Fixez un niveau d'effort Claude pour chaque requête avec fixedEffort:. Il prévaut sur les indications de raisonnement par requête du framework, et c'est le seul moyen de demander .xhigh ou .max, car les niveaux de raisonnement du framework s'arrêtent à high. L'API utilise high par défaut lorsqu'aucun effort n'est envoyé :

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

Le niveau doit être l'un de ceux que le modèle accepte. Chaque ClaudeModel déclare lesquels des cinq niveaux (low, medium, high, xhigh, max) son modèle accepte, le cas échéant : certains modèles n'acceptent pas du tout d'effort.

Quand utiliser Claude plutôt que le modèle embarqué

Le modèle embarqué d'Apple est rapide, privé et fonctionne hors ligne, mais il est dimensionné pour des tâches légères. Passez à Claude lorsque vous avez besoin d'un contexte plus large, d'un raisonnement de pointe ou d'outils côté serveur tels que la recherche web et l'exécution de code. Comme les deux utilisent la même API LanguageModelSession, vous pouvez basculer en changeant l'argument model:.

Authentification

Définissez l'identifiant d'authentification avec le paramètre auth:.

Clé API (développement)

Passez une clé API directement pendant le développement :

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

Proxy (production)

Pour la production, acheminez les requêtes via votre propre back-end avec .proxied. Le relais situé à baseURL ajoute l'identifiant de l'API Claude côté serveur, de sorte que l'application ne contient aucune clé. Les headers que vous fournissez sont envoyés à chaque requête afin que votre proxy puisse autoriser l'appelant. Passez [:] s'il n'en a pas besoin :

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

Votre proxy reçoit des requêtes standard de l'API Messages, y attache l'en-tête x-api-key et les transmet à https://api.anthropic.com.

Streaming

streamResponse(to:) renvoie la réponse de manière incrémentale. Chaque élément est un instantané cumulatif de la réponse jusqu'à présent, et non un delta :

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

Sortie structurée

Annotez un type avec @Generable et demandez-le avec generating:. Le modèle renvoie une valeur de ce type via les sorties structurées :

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

La sortie structurée nécessite un modèle dont les capacités l'incluent (c'est le cas de toutes les constantes compilées). Si le modèle choisi ne la prend pas en charge, le package lève LanguageModelError.unsupportedGenerationGuide plutôt que de se dégrader silencieusement.

Utilisation d'outils

Outils côté client

Le tableau tools: du framework fonctionne sans modification. Rendez vos types conformes à Tool, passez-les à LanguageModelSession, et le framework les invoque sur l'appareil lorsque Claude les appelle. Consultez Utilisation d'outils avec Claude.

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

Outils côté serveur

Les outils serveur (recherche web, récupération web et exécution de code) s'exécutent sur l'infrastructure d'Anthropic en un seul aller-retour, sans que le framework n'ait rien à invoquer sur l'appareil. Configurez-les par modèle avec serverTools: :

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

.webSearch et .webFetch acceptent les paramètres optionnels allowedDomains, blockedDomains et maxUses. L'activité des outils serveur apparaît dans la transcription sous forme de segments personnalisés ClaudeServerToolSegment.

Images

Les modèles dont les capacités incluent l'entrée d'image déclarent la capacité de vision du framework. Passez le contenu image via l'API de session standard du framework ; le package le convertit au format d'image de l'API Claude. Consultez Vision pour les exigences relatives aux images.

Gestion des erreurs

Le package fait correspondre les erreurs de l'API Claude aux cas LanguageModelError d'Apple lorsqu'une correspondance existe : le dépassement de la fenêtre de contexte apparaît comme .contextSizeExceeded, HTTP 429 comme .rateLimited, une requête dépassant le délai configuré comme .timeout. Les erreurs du fournisseur sans équivalent dans le framework apparaissent comme ClaudeError. Utilisez le pattern matching pour piloter les flux produit :

do {
  let response = try await session.respond(to: prompt)
  print(response.content)
} catch ClaudeError.missingCredential {
  // Demander une clé API.
} catch let error as LanguageModelError {
  // Erreurs liées au framework (limites de débit, garde-fous, longueur du contexte, décodage).
} catch {
  // Erreurs de transport.
}

Un schéma courant consiste à intercepter .rateLimited et à se rabattre sur SystemLanguageModel pour ce tour, à mettre la requête en file d'attente, ou à proposer une option de nouvelle tentative.

Prise en charge des fonctionnalités

Le package expose les capacités de l'API Messages que le protocole de fournisseur Foundation Models peut exprimer. Les fonctionnalités sans représentation dans le protocole d'Apple ne sont pas disponibles par son intermédiaire, notamment :

• Les contrôles de mise en cache des prompts (le package applique automatiquement la mise en cache des prompts ; la durée de vie du cache et le placement des points d'arrêt ne sont pas configurables)
• Les séquences d'arrêt
• Le traitement par lots
• L'API Files
• Le comptage de tokens
• Les en-têtes bêta

Ressources supplémentaires

Le package est sous licence Apache 2.0. Les rapports de bugs sont les bienvenus via les issues GitHub. Les pull requests externes ne sont pas acceptées pendant la période bêta.