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, così puoi utilizzarlo 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 si trova nel percorso della richiesta e non vede prompt o risposte. L'utilizzo viene fatturato sul tuo account Anthropic ai prezzi standard dell'API, quindi la tua organizzazione necessita di un saldo di credito disponibile o di un metodo di fatturazione attivo. La tua app decide quando usare Claude e quando usare il modello on-device di Apple: passa il modello che preferisci a ciascuna sessione.

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 "API key" (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.

Quindi 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 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 (vedi Strumenti lato server).

Per un programma completo e funzionante, 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 il turno. Per eseguirlo è necessario un host macOS 27.

Scegliere un modello

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

ClaudeLanguageModel(name: .opus5, auth: auth)

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

Capacità

Ogni ClaudeModel dichiara ciò che 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 riportano le capacità corrette. Per un ID non compilato, dichiara ciò che il modello accetta (deliberatamente non esiste una scorciatoia che indovini):

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 richiesta del framework. I livelli di ragionamento denominati del framework si fermano a high; per richiedere invece più effort per una singola richiesta, passa un livello di ragionamento personalizzato che indichi l'effort di Claude (.custom("xhigh") o .custom("max")), che viene mappato direttamente. L'API usa high come valore 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) accetta il suo modello, 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 attività leggere. 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 passare dall'uno all'altro sostituendo l'argomento model:.

Autenticazione

Imposta la credenziale con il parametro auth:. Usa .appAttest per distribuire senza un back end, .proxied per instradare le richieste attraverso il tuo back end, oppure .apiKey per iterare durante lo sviluppo.

App Attest

Ogni installazione della tua app utilizza il servizio App Attest di Apple per dimostrare di essere una build autentica e non modificata dell'app che hai registrato. Anthropic rilascia quindi al dispositivo un "access token" (token di accesso) di breve durata che addebita l'utilizzo al tuo workspace. L'app non include alcuna chiave API e non c'è alcun proxy da gestire da parte tua.

L'autenticazione App Attest è disponibile solo quando la tua app chiama direttamente la Claude API. Non è disponibile tramite Amazon Bedrock, Google Cloud o Microsoft Foundry.

Per distribuire senza gestire un back end, usa .appAttest:

ClaudeLanguageModel(
  name: .sonnet5,
  auth: .appAttest(clientID: "clid_...")
)

Per configurare App Attest, hai bisogno del tuo Apple Developer Team ID e del ruolo di admin, owner o primary owner nella tua organizzazione. Configura il tuo progetto Xcode e registra la tua app nella Claude Console:

1. In Xcode, aggiungi la capability App Attest al target della tua app in Signing & Capabilities.
2. Nelle impostazioni del tuo workspace nella Claude Console, apri App integrations.
3. Fai clic su Create app integration e inserisci un nome, il tuo Apple Developer Team ID e uno o più bundle ID (fino a 32).
4. Copia il client ID (clid_...) dalla scheda Overview dell'integrazione e passalo alla configurazione Claude della tua app.

La prima volta che la tua app usa Claude su un dispositivo, l'app richiede una challenge ad Anthropic, attesta il dispositivo con DCAppAttestService di Apple e scambia l'attestazione verificata con un "access token" (token di accesso). Il pacchetto Claude for Foundation Models esegue questo flusso automaticamente e richiede nuovi token man mano che scadono; non c'è alcun codice di attestazione che tu debba scrivere.

I token sono limitati al tuo workspace, scadono dopo un'ora e autorizzano solo le chiamate alla Messages API. Non contengono alcuna identità dell'utente finale: App Attest identifica la tua app, non la persona che la usa, quindi gestisci qualsiasi logica per utente all'interno della tua app.

Per arrestare un'app compromessa o ritirata, revoca la sua integrazione: nelle impostazioni del tuo workspace nella Claude Console, apri App integrations, seleziona l'integrazione e fai clic su Revoke, quindi conferma. La revoca di un'integrazione revoca i suoi token in circolazione e i suoi dispositivi registrati non possono più richiederne di nuovi. La revoca è permanente, quindi crea una nuova integrazione app per ripristinare l'accesso.

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, così l'app non distribuisce alcuna chiave. Gli headers che fornisci vengono inviati con 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, aggiunge l'header x-api-key e le inoltra a https://api.anthropic.com.

Chiave API (sviluppo)

Passa direttamente una chiave API durante lo sviluppo:

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

Streaming

streamResponse(to:) restituisce la risposta in modo incrementale. Ogni elemento è un'istantanea cumulativa 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 lo fanno). Se il modello scelto non lo include, il pacchetto lancia LanguageModelError.unsupportedGenerationGuide anziché 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 i parametri opzionali allowedDomains, blockedDomains e maxUses. L'attività degli strumenti server emerge 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 dove ne esiste uno adatto: il superamento della "context window" (finestra di contesto) emerge come .contextSizeExceeded, HTTP 429 come .rateLimited, una richiesta oltre il timeout configurato come .timeout. Gli errori del provider senza un equivalente nel framework emergono 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 consiste nell'intercettare .rateLimited e ripiegare su SystemLanguageModel per quel turno, mettere in coda la richiesta o mostrare un'opzione per riprovare.

Supporto delle funzionalità

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

• Controlli della "prompt caching" (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 è distribuito 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 di beta.