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 que vous utilisez pour le modèle sur appareil 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 vers 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 sur appareil 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 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: .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)

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 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 ID qui n'est pas encore compilé (voir Capacités) :

ClaudeLanguageModel(name: .opus5, auth: auth)

Les constantes reflètent les ID de modèle de l'API (.opus5 correspond à claude-opus-5) 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'images. Le package s'en sert pour déterminer quels champs de requête envoyer, car envoyer un champ qu'un modèle rejette est une erreur bloquante. Les constantes portent les bonnes capacités. Pour un ID 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. Les niveaux de raisonnement nommés du framework s'arrêtent à high ; pour demander plus d'effort pour une seule requête à la place, passez un niveau de raisonnement personnalisé nommant l'effort Claude (.custom("xhigh") ou .custom("max")), qui correspond directement. L'API utilise high par défaut lorsqu'aucun effort n'est envoyé :

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

Le niveau doit être un niveau 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 d'effort du tout.



Quand utiliser Claude plutôt que le modèle sur appareil

Le modèle sur appareil d'Apple est rapide, privé et disponible hors ligne, mais il est dimensionné pour des tâches légères. Passez à Claude lorsque vous avez besoin d'un contexte plus grand, 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 remplaçant l'argument model:.



Authentification

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



Clé API (développement)

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

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



Proxy (production)

Pour la production, acheminez les requêtes via votre propre back-end avec .proxied. Le relais à baseURL ajoute l'identifiant de l'API Claude côté serveur, de sorte que l'application n'embarque 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 besoin d'aucun :

ClaudeLanguageModel(
  name: .sonnet5,
  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, 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, pas 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 (toutes les constantes compilées le font). Si le modèle choisi ne le fait pas, 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 rien que le framework doive invoquer sur l'appareil. Configurez-les pour chaque modèle avec serverTools: :

let model = ClaudeLanguageModel(
  name: .sonnet5,
  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'images déclarent la capacité de vision du framework. Passez le contenu d'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 mappe les erreurs de l'API Claude sur les cas LanguageModelError d'Apple lorsqu'il en existe un qui convient : 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 d'attente configuré comme .timeout. Les erreurs du fournisseur sans équivalent dans le framework apparaissent comme ClaudeError. Utilisez le filtrage par motif pour piloter les flux produit :

do {
  let response = try await session.respond(to: prompt)
  print(response.content)
} catch ClaudeError.missingCredential {
  // Demande la saisie d'une clé API.
} catch let error as LanguageModelError {
  // Erreurs propres au framework (limites de débit, garde-fous, longueur de 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 à afficher 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 via celui-ci, notamment :

• Les contrôles de mise en cache des prompts (le package applique la mise en cache des prompts automatiquement ; le TTL du cache et le placement des points de rupture 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 bogues sont les bienvenus via les issues GitHub. Les pull requests externes ne sont pas acceptées pendant la période bêta.