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 chiamate agli strumenti funzionano tutti allo stesso modo.

Le richieste vanno direttamente dalla tua app all'API di Claude; Apple non è nel percorso della richiesta e non vede i prompt né le risposte. L'utilizzo viene addebitato sul 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 ogni 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.

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 di 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'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 quel turno. L'esecuzione richiede un host macOS 27.

Scegliere un modello

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

ClaudeLanguageModel(name: .opus4_8, auth: auth)

Le costanti rispecchiano gli ID dei modelli dell'API (.opus4_8 è claude-opus-4-8) e includono 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 cosa accetta: parametri di campionamento, livelli di effort, adaptive thinking, output strutturato e input di immagini. Il pacchetto usa queste informazioni per decidere quali campi della richiesta inviare, perché inviare un campo che un modello rifiuta causa un errore bloccante. Le costanti includono le capacità corrette. Per un ID non compilato, dichiara cosa accetta il modello (non esiste deliberatamente alcuna 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 richiesta del framework, ed è l'unico modo per richiedere .xhigh o .max, perché i livelli di ragionamento del framework si fermano a high. L'API usa high come valore predefinito quando non viene inviato alcun effort:

ClaudeLanguageModel(name: .opus4_8, 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 funziona offline, ma è dimensionato per attività leggere. Passa a Claude quando hai bisogno di un contesto più ampio, ragionamento di frontiera o 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 cambiando l'argomento model:.

Autenticazione

Imposta la credenziale con il parametro auth:.

Chiave API (sviluppo)

Passa direttamente una chiave API durante lo sviluppo:

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

Proxy (produzione)

Per la produzione, instrada le richieste attraverso il tuo back end con .proxied. Il relay all'indirizzo baseURL aggiunge la credenziale dell'API di Claude lato server, così l'app non include 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 ha bisogno:

ClaudeLanguageModel(
  name: .sonnet4_6,
  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 lo fanno). Se il modello scelto non lo supporta, il pacchetto genera 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 in un unico round trip, senza nulla che il framework debba invocare sul dispositivo. Configurali per modello con serverTools::

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

.webSearch e .webFetch accettano opzionalmente 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 immagine tramite l'API di sessione standard del framework; il pacchetto lo converte nel formato immagine dell'API di Claude. Consulta Visione per i requisiti delle immagini.

Gestione degli errori

Il pacchetto mappa gli errori dell'API di Claude sui casi di LanguageModelError di Apple quando ne esiste uno corrispondente: il superamento della finestra di contesto appare come .contextSizeExceeded, HTTP 429 come .rateLimited, una richiesta oltre il timeout configurato come .timeout. Gli errori del provider senza 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 legati al 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 riprova.

Supporto delle funzionalità

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 arresto
• Elaborazione batch
• Files API
• Conteggio dei token
• Header beta

Risorse aggiuntive

Il pacchetto è concesso in 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.