Apple Foundation Models

Claude for Foundation Models è un pacchetto Swift che rende Claude disponibile come modello linguistico lato server nel framework Foundation Models di Apple. Il pacchetto rende Claude conforme al protocollo LanguageModel del framework, quindi lo utilizzi con la stessa API LanguageModelSession che usi per il modello on-device di Apple: respond(to:), streaming, generazione guidata e chiamata di strumenti funzionano tutti allo stesso modo.

Le richieste vanno direttamente dalla tua app alla Claude API; Apple non è nel percorso della richiesta e non vede prompt o risposte. L'utilizzo viene fatturato al tuo account Anthropic secondo i prezzi standard dell'API. La tua app decide quando usare Claude e quando usare il modello on-device di Apple: passa a ciascuna sessione il modello che preferisci.



Requisiti

• iOS 27, macOS 27, visionOS 27 o watchOS 27 (tutti in beta): le versioni del sistema operativo il cui framework Foundation Models supporta i modelli linguistici lato server
• Xcode 27 (beta)
• Una chiave API di Claude dalla Claude Console per lo sviluppo. Consulta Autenticazione per le opzioni di produzione.



Installa il pacchetto

Aggiungi il pacchetto al tuo Package.swift:

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

Oppure in Xcode: File > Add Package Dependencies… e inserisci l'URL del repository.

Poi aggiungi ClaudeForFoundationModels alle dipendenze del tuo target e importalo insieme a FoundationModels:

import FoundationModels
import ClaudeForFoundationModels



Avvio rapido

ClaudeLanguageModel è il punto di ingresso. Passalo a LanguageModelSession e usa la sessione esattamente come faresti con qualsiasi provider di 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'inizializzatore accetta anche baseURL (predefinito https://api.anthropic.com), timeout e serverTools (consulta Strumenti lato server).

Per un programma funzionante completo, il repository include Examples/ClaudeExample, un target da riga di comando eseguibile che trasmette in streaming un turno di chat al terminale, con un flag --search che abilita la ricerca web lato server per quel turno. L'esecuzione richiede un host macOS 27.



Scegliere un modello

Gli identificatori dei modelli sono valori di ClaudeModel. Usa una costante compilata nel pacchetto, oppure costruiscine una con capacità esplicite per un ID non ancora compilato (consulta Capacità):

ClaudeLanguageModel(name: .opus5, auth: auth)

Le costanti rispecchiano gli ID dei modelli dell'API (.opus5 è claude-opus-5) e contengono le capacità di ciascun modello. I nuovi modelli vengono distribuiti come nuove costanti nelle release del pacchetto; controlla ClaudeModel in Xcode per l'elenco corrente, e la panoramica dei modelli per confrontare i modelli.



Capacità

Ogni ClaudeModel dichiara cosa accetta: parametri di campionamento, livelli di effort, pensiero adattivo, output strutturato e input di immagini. Il pacchetto usa queste informazioni per determinare quali campi della richiesta inviare, perché inviare un campo che un modello rifiuta è un errore bloccante. Le costanti contengono le capacità corrette. Per un ID non compilato nel pacchetto, dichiara cosa accetta il modello (deliberatamente non esiste una scorciatoia che tiri a indovinare):

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



Effort

Fissa un livello di effort di Claude per ogni richiesta con fixedEffort:. Ha la precedenza sui suggerimenti di ragionamento per singola richiesta del framework. I livelli di ragionamento nominati del framework si fermano a high; per richiedere invece più effort per una singola richiesta, passa un livello di ragionamento personalizzato che nomini l'effort di Claude (.custom("xhigh") o .custom("max")), che viene mappato direttamente. L'API usa high come predefinito quando non viene inviato alcun effort:

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

Il livello deve essere uno di quelli accettati dal modello. Ogni ClaudeModel dichiara quali dei cinque livelli (low, medium, high, xhigh, max) il suo modello accetta, se ne accetta: alcuni modelli non accettano affatto l'effort.



Quando usare Claude rispetto al modello on-device

Il modello on-device di Apple è veloce, privato e disponibile offline, ma è dimensionato per compiti leggeri. Passa a Claude quando hai bisogno di un contesto più ampio, di ragionamento di frontiera o di strumenti lato server come la ricerca web e l'esecuzione di codice. Poiché entrambi usano la stessa API LanguageModelSession, puoi cambiare semplicemente sostituendo l'argomento model:.



Autenticazione

Imposta la credenziale con il parametro auth:.



Chiave API (sviluppo)

Passa una chiave API direttamente durante lo sviluppo:

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



Proxy (produzione)

Per la produzione, instrada le richieste attraverso il tuo back end con .proxied. Il relay su baseURL aggiunge la credenziale della Claude API lato server, quindi l'app non include alcuna chiave. Gli headers che fornisci vengono inviati a ogni richiesta in modo che il tuo proxy possa autorizzare il chiamante. Passa [:] se non ne servono:

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

Il tuo proxy riceve richieste standard della Messages API, allega l'header x-api-key e le inoltra a https://api.anthropic.com.



Streaming

streamResponse(to:) restituisce la risposta in modo incrementale. Ogni elemento è uno snapshot cumulativo della risposta fino a quel momento, non un delta:

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



Output strutturato

Annota un tipo con @Generable e richiedilo con generating:. Il modello restituisce un valore di quel tipo tramite gli output strutturati:

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

L'output strutturato richiede un modello le cui capacità lo includano (tutte le costanti compilate nel pacchetto lo fanno). Se il modello scelto non lo supporta, il pacchetto genera LanguageModelError.unsupportedGenerationGuide invece di degradare silenziosamente.



Uso degli strumenti



Strumenti lato client

L'array tools: del framework funziona senza modifiche. Rendi i tuoi tipi conformi a Tool, passali a LanguageModelSession, e il framework li invoca sul dispositivo quando Claude li chiama. Consulta Uso degli strumenti con Claude.

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



Strumenti lato server

Gli strumenti server (ricerca web, recupero web ed esecuzione di codice) vengono eseguiti sull'infrastruttura di Anthropic all'interno di un singolo round trip, senza nulla che il framework debba invocare sul dispositivo. Configurali per ciascun modello con serverTools::

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

.webSearch e .webFetch accettano gli opzionali allowedDomains, blockedDomains e maxUses. L'attività degli strumenti server appare nella trascrizione come segmenti personalizzati ClaudeServerToolSegment.



Immagini

I modelli le cui capacità includono l'input di immagini dichiarano la capacità di visione del framework. Passa il contenuto delle immagini tramite l'API di sessione standard del framework; il pacchetto lo converte nel formato immagine della Claude API. Consulta Visione per i requisiti delle immagini.



Gestione degli errori

Il pacchetto mappa gli errori della Claude API sui casi di LanguageModelError di Apple quando ne esiste uno corrispondente: l'overflow della finestra di contesto appare come .contextSizeExceeded, HTTP 429 come .rateLimited, una richiesta oltre il timeout configurato come .timeout. Gli errori del provider senza un equivalente nel framework appaiono come ClaudeError. Usa il pattern matching per guidare i flussi del prodotto:

do {
  let response = try await session.respond(to: prompt)
  print(response.content)
} catch ClaudeError.missingCredential {
  // Richiedi una chiave API.
} catch let error as LanguageModelError {
  // Errori a livello di framework (limiti di velocità, guardrail, lunghezza del contesto, decodifica).
} catch {
  // Errori di trasporto.
}

Un pattern comune è intercettare .rateLimited e ripiegare su SystemLanguageModel per quel turno, mettere in coda la richiesta o mostrare un'opzione di nuovo tentativo.



Funzionalità supportate

Il pacchetto espone le capacità della Messages API che il protocollo provider di Foundation Models può esprimere. Le funzionalità senza rappresentazione nel protocollo di Apple non sono disponibili tramite esso, tra cui:

• Controlli della cache dei prompt (il pacchetto applica automaticamente la cache dei prompt; il TTL della cache e il posizionamento dei breakpoint non sono configurabili)
• Sequenze di stop
• Elaborazione batch
• Files API
• Conteggio dei token
• Header beta



Risorse aggiuntive

Il pacchetto è rilasciato con licenza Apache 2.0. Le segnalazioni di bug sono benvenute tramite le issue di GitHub. Le pull request esterne non vengono accettate durante il periodo beta.