--- title: Apple Foundation Models url: https://platform.claude.com/docs/it/cli-sdks-libraries/libraries/apple-foundation-models description: Usa Claude sulle piattaforme Apple tramite il framework Foundation Models con il pacchetto Swift Claude for Foundation Models. --- [Claude for Foundation Models](https://github.com/anthropics/ClaudeForFoundationModels) è un pacchetto Swift che rende Claude disponibile come modello linguistico lato server nel framework [Foundation Models](https://developer.apple.com/documentation/foundationmodels) 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](https://platform.claude.com/docs/it/about-claude/pricing), 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. **Beta.** Questo pacchetto è destinato all'API per modelli linguistici lato server di Foundation Models introdotta nelle beta di OS 27. Le API potrebbero cambiare durante la beta. Claude for Foundation Models **non** è un client generico per la Messages API. La sua superficie pubblica è costituita dalla conformità al provider Foundation Models più i tipi di configurazione che la raggiungono (`ClaudeLanguageModel`, `ClaudeModel`, `AuthMode`, `ClaudeServerTool`). Per l'accesso diretto alla Messages API in un altro linguaggio, consulta i [Client SDK](https://platform.claude.com/docs/it/cli-sdks-libraries/overview#client-sdks). ## 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](https://platform.claude.com/) per lo sviluppo. Consulta [Autenticazione](https://platform.claude.com/docs/it/cli-sdks-libraries/libraries/apple-foundation-models#authentication) per le opzioni di produzione. ## Installa il pacchetto Aggiungi il pacchetto al tuo `Package.swift`: ```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`: ```swift 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: ```swift 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](https://platform.claude.com/docs/it/cli-sdks-libraries/libraries/apple-foundation-models#server-side-tools)). Per un programma completo e funzionante, il repository include [`Examples/ClaudeExample`](https://github.com/anthropics/ClaudeForFoundationModels/tree/main/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 già compilata nel pacchetto. Per un ID non ancora compilato, costruiscine una con capacità esplicite (consulta [Capacità](https://platform.claude.com/docs/it/cli-sdks-libraries/libraries/apple-foundation-models#capabilities)): ```swift ClaudeLanguageModel(name: .opus5_5, auth: auth) ``` Le costanti rispecchiano gli ID dei modelli dell'API (`.opus5` corrisponde a `claude-opus-5`) e includono le capacità di ciascun modello. I nuovi modelli vengono rilasciati come nuove costanti nelle release del pacchetto. Controlla `ClaudeModel` in Xcode per l'elenco aggiornato e consulta la [Panoramica dei modelli](https://platform.claude.com/docs/it/models/overview) per confrontarli. ### Capacità Ogni `ClaudeModel` dichiara ciò che accetta: parametri di campionamento, livelli di effort, ragionamento 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): ```swift 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](https://platform.claude.com/docs/it/build-with-claude/effort) di Claude per ogni richiesta con `fixedEffort:`. Ha la precedenza sui suggerimenti di ragionamento per singola richiesta del framework. I livelli di ragionamento con nome 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. Quando non viene inviato alcun effort, l'API usa il livello predefinito del modello, che varia da modello a modello (consulta [Livelli di effort](https://platform.claude.com/docs/it/build-with-claude/effort#effort-levels)): ```swift ClaudeLanguageModel(name: .opus5_5, auth: auth, fixedEffort: .xhigh) ``` Il livello deve essere tra 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](https://developer.apple.com/documentation/devicecheck/establishing-your-app-s-integrity) 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`: ```swift ClaudeLanguageModel( name: .sonnet5, auth: .appAttest(clientID: "clid_...") ) ``` App Attest richiede un dispositivo fisico. Il Simulatore, e l'hardware privo di Secure Enclave, non possono eseguire App Attest. Usa `.apiKey` mentre iteri nel Simulatore e `.appAttest` quando esegui su un dispositivo. 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](https://platform.claude.com/): 1. In Xcode, aggiungi la capability **App Attest** al target della tua app in **Signing & Capabilities**. 2. Nella Claude Console, vai alla pagina [App integrations](https://platform.claude.com/settings/workspaces/default/app-integrations) (`platform.claude.com/settings/workspaces/default/app-integrations`). Ogni integrazione app appartiene a un workspace. Seleziona il workspace desiderato nel selettore dei workspace nella barra laterale. 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](https://platform.claude.com/docs/it/api/messages/create). 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 bloccare un'app compromessa o dismessa, revoca la sua integrazione. Nella Claude Console, vai alla pagina [App integrations](https://platform.claude.com/settings/workspaces/default/app-integrations) (`platform.claude.com/settings/workspaces/default/app-integrations`). Ogni integrazione app appartiene a un solo workspace. Nel selettore dei workspace nella barra laterale, seleziona il workspace che contiene l'integrazione. 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: ```swift 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](https://platform.claude.com/docs/it/api/messages/create), 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: ```swift ClaudeLanguageModel(name: .sonnet5, auth: .apiKey("YOUR_API_KEY")) ``` Una chiave inclusa in un'app è estraibile dal binario distribuito, e chiunque la estragga può effettuare richieste fatturate sul tuo account. Usa `.apiKey` solo per lo sviluppo e passa ad App Attest o a un proxy prima del rilascio. ## Streaming `streamResponse(to:)` restituisce la risposta in modo incrementale. Ogni elemento è un'istantanea cumulativa della risposta fino a quel momento, non un delta: ```swift 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](https://platform.claude.com/docs/it/build-with-claude/structured-outputs): ```swift @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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/overview). ```swift let session = LanguageModelSession(model: model, tools: [FindRestaurantsTool()]) ``` ### Strumenti lato server Gli [strumenti server](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools) (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:`: ```swift 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`. `serverTools` è configurato su `ClaudeLanguageModel` anziché su `LanguageModelSession` perché il tipo della sessione è di Apple. Per usare insiemi di strumenti server diversi per ciascuna conversazione, costruisci più istanze di `ClaudeLanguageModel`. ## 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](https://platform.claude.com/docs/it/build-with-claude/vision) 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: ```swift 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 | Riferimento | Copre | | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | [Documentazione Apple Foundation Models](https://developer.apple.com/documentation/foundationmodels) | `LanguageModelSession`, `@Generable`, `Transcript`, `Tool` e il resto della superficie del framework | | [`ClaudeForFoundationModels` su GitHub](https://github.com/anthropics/ClaudeForFoundationModels) | Codice sorgente, l'esempio eseguibile e l'issue tracker | | [Riferimento della Claude API](https://platform.claude.com/docs/it/api/overview) | La Messages API sottostante | 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.