Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Claude for Foundation Models es un paquete Swift que hace que Claude esté disponible como modelo de lenguaje del lado del servidor en el framework Foundation Models de Apple. El paquete hace que Claude cumpla con el protocolo LanguageModel del framework, de modo que lo controlas con la misma API LanguageModelSession que usas para el modelo en el dispositivo de Apple: respond(to:), streaming, generación guiada y llamadas a herramientas funcionan de la misma manera.
Las solicitudes van directamente desde tu app a la API de Claude; Apple no está en la ruta de la solicitud y no ve los prompts ni las respuestas. El uso se factura a tu cuenta de Anthropic según los precios estándar de la API, por lo que tu organización necesita un saldo de crédito disponible o un método de facturación activo. Tu app decide cuándo usar Claude y cuándo usar el modelo en el dispositivo de Apple: pasa el modelo que quieras a cada sesión.
Agrega el paquete a tu Package.swift:
dependencies: [
.package(url: "https://github.com/anthropics/ClaudeForFoundationModels.git", from: "0.1.0")
]O en Xcode: File > Add Package Dependencies… e ingresa la URL del repositorio.
Luego agrega ClaudeForFoundationModels a las dependencias de tu target e impórtalo junto con FoundationModels:
import FoundationModels
import ClaudeForFoundationModelsClaudeLanguageModel es el punto de entrada. Pásalo a LanguageModelSession y usa la sesión exactamente como lo harías con cualquier proveedor de 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)El inicializador también acepta baseURL (por defecto https://api.anthropic.com), timeout y serverTools (consulta Herramientas del lado del servidor).
Para un programa funcional completo, el repositorio incluye Examples/ClaudeExample, un target de línea de comandos ejecutable que transmite un turno de chat a la terminal, con una bandera --search que habilita la búsqueda web del lado del servidor para el turno. Ejecutarlo requiere un host con macOS 27.
Los identificadores de modelo son valores de ClaudeModel. Usa una constante compilada, o construye uno con capacidades explícitas para un ID que aún no esté compilado (consulta Capacidades):
ClaudeLanguageModel(name: .opus5, auth: auth)Las constantes reflejan los IDs de modelo de la API (.opus5 es claude-opus-5) y llevan las capacidades de cada modelo. Los nuevos modelos se publican como nuevas constantes en las versiones del paquete; revisa ClaudeModel en Xcode para ver la lista actual, y la descripción general de modelos para comparar modelos.
Cada ClaudeModel declara lo que acepta: parámetros de muestreo, niveles de esfuerzo, pensamiento adaptativo, salida estructurada y entrada de imágenes. El paquete usa esto para determinar qué campos de solicitud enviar, porque enviar un campo que un modelo rechaza es un error fatal. Las constantes llevan las capacidades correctas. Para un ID que no está compilado, declara lo que el modelo acepta (deliberadamente no hay un atajo que adivine):
let model = ClaudeModel(
id: "claude-experimental-x",
capabilities: .init(samplingParams: false, effortLevels: [.low, .high])
)
ClaudeLanguageModel(name: model, auth: auth)Fija un nivel de esfuerzo de Claude para cada solicitud con fixedEffort:. Tiene prioridad sobre las sugerencias de razonamiento por solicitud del framework. Los niveles de razonamiento con nombre del framework llegan hasta high; para solicitar más esfuerzo para una sola solicitud en su lugar, pasa un nivel de razonamiento personalizado que nombre el esfuerzo de Claude (.custom("xhigh") o .custom("max")), que se mapea directamente. La API usa high por defecto cuando no se envía ningún esfuerzo:
ClaudeLanguageModel(name: .opus5, auth: auth, fixedEffort: .xhigh)El nivel debe ser uno que el modelo acepte. Cada ClaudeModel declara cuáles de los cinco niveles (low, medium, high, xhigh, max) acepta su modelo, si es que acepta alguno: algunos modelos no aceptan esfuerzo en absoluto.
El modelo en el dispositivo de Apple es rápido, privado y está disponible sin conexión, pero está dimensionado para tareas ligeras. Escala a Claude cuando necesites un contexto más grande, razonamiento de frontera o herramientas del lado del servidor como búsqueda web y ejecución de código. Debido a que ambos usan la misma API LanguageModelSession, puedes cambiar intercambiando el argumento model:.
Establece la credencial con el parámetro auth:. Usa .appAttest para publicar sin un back end, .proxied para enrutar solicitudes a través de tu propio back end, o .apiKey para iterar durante el desarrollo.
Cada instalación de tu app utiliza el servicio App Attest de Apple para demostrar que es una compilación genuina y sin modificar de la app que registraste. Anthropic luego emite al dispositivo un token de acceso de corta duración que factura el uso a tu workspace. La app no incluye ninguna clave de API, y no hay ningún proxy que debas operar.
La autenticación con App Attest está disponible únicamente cuando tu app llama directamente a la API de Claude. No está disponible a través de Amazon Bedrock, Google Cloud ni Microsoft Foundry.
Para publicar sin ejecutar un back end, usa .appAttest:
ClaudeLanguageModel(
name: .sonnet5,
auth: .appAttest(clientID: "clid_...")
)Para configurar App Attest, necesitas tu Apple Developer Team ID y el rol de administrador, propietario o propietario principal en tu organización. Configura tu proyecto de Xcode y registra tu aplicación en la Claude Console:
clid_...) de la pestaña Overview de la integración y pásalo a la configuración de Claude de tu aplicación.La primera vez que tu app usa Claude en un dispositivo, la app solicita un "challenge" (desafío) a Anthropic, atesta el dispositivo con DCAppAttestService de Apple e intercambia la atestación verificada por un token de acceso. El paquete Claude for Foundation Models ejecuta este flujo automáticamente y solicita nuevos tokens a medida que expiran; no hay código de atestación que debas escribir.
Los tokens están limitados a tu workspace, expiran después de una hora y autorizan únicamente llamadas a la Messages API. No contienen ninguna identidad de usuario final: App Attest identifica tu app, no a la persona que la usa, así que gestiona cualquier lógica por usuario en tu app.
Para detener una aplicación comprometida o retirada, revoca su integración: en la configuración de tu espacio de trabajo en la Claude Console, abre App integrations, selecciona la integración y haz clic en Revoke, luego confirma. Revocar una integración revoca sus tokens pendientes, y sus dispositivos registrados ya no pueden solicitar nuevos. La revocación es permanente, así que crea una nueva integración de aplicación para restaurar el acceso.
Para producción, enruta las solicitudes a través de tu propio back end con .proxied. El relay en baseURL agrega la credencial de la API de Claude del lado del servidor, de modo que la app no incluye ninguna clave. Los headers que proporciones se envían en cada solicitud para que tu proxy pueda autorizar al llamador. Pasa [:] si no necesita ninguno:
ClaudeLanguageModel(
name: .sonnet5,
auth: .proxied(headers: ["X-App-Token": "..."]),
baseURL: URL(string: "https://api.yourapp.com/claude")!
)Tu proxy recibe solicitudes estándar de la Messages API, adjunta el encabezado x-api-key y las reenvía a https://api.anthropic.com.
Pasa una clave de API directamente mientras desarrollas:
ClaudeLanguageModel(name: .sonnet5, auth: .apiKey("YOUR_API_KEY"))streamResponse(to:) devuelve la respuesta de forma incremental. Cada elemento es una instantánea acumulativa de la respuesta hasta el momento, no un delta:
let stream = session.streamResponse(to: "Summarize today's top science stories.")
for try await partial in stream {
print(partial.content)
}Anota un tipo con @Generable y solicítalo con generating:. El modelo devuelve un valor de ese tipo a través de salidas estructuradas:
@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 salida estructurada requiere un modelo cuyas capacidades la incluyan (todas las constantes compiladas lo hacen). Si el modelo elegido no la incluye, el paquete lanza LanguageModelError.unsupportedGenerationGuide en lugar de degradarse silenciosamente.
El array tools: del framework funciona sin cambios. Haz que tus tipos cumplan con Tool, pásalos a LanguageModelSession, y el framework los invoca en el dispositivo cuando Claude los llama. Consulta Uso de herramientas con Claude.
let session = LanguageModelSession(model: model, tools: [FindRestaurantsTool()])Las herramientas de servidor (búsqueda web, obtención web y ejecución de código) se ejecutan en la infraestructura de Anthropic dentro de un solo viaje de ida y vuelta, sin nada que el framework deba invocar en el dispositivo. Configúralas para cada modelo con serverTools::
let model = ClaudeLanguageModel(
name: .sonnet5,
auth: auth,
serverTools: [
.webSearch(maxUses: 5),
.codeExecution,
]
).webSearch y .webFetch aceptan opcionalmente allowedDomains, blockedDomains y maxUses. La actividad de las herramientas de servidor aparece en la transcripción como segmentos personalizados ClaudeServerToolSegment.
Los modelos cuyas capacidades incluyen entrada de imágenes declaran la capacidad de visión del framework. Pasa contenido de imagen a través de la API de sesión estándar del framework; el paquete lo convierte al formato de imagen de la API de Claude. Consulta Visión para los requisitos de imagen.
El paquete mapea los errores de la API de Claude a los casos de LanguageModelError de Apple cuando uno encaja: el desbordamiento de la ventana de contexto aparece como .contextSizeExceeded, HTTP 429 como .rateLimited, una solicitud que supera el tiempo de espera configurado como .timeout. Los errores del proveedor sin equivalente en el framework aparecen como ClaudeError. Usa coincidencia de patrones para controlar los flujos del producto:
do {
let response = try await session.respond(to: prompt)
print(response.content)
} catch ClaudeError.missingCredential {
// Solicita una clave de API.
} catch let error as LanguageModelError {
// Errores con forma de framework (límites de velocidad, guardrails, longitud de contexto, decodificación).
} catch {
// Errores de transporte.
}Un patrón común es capturar .rateLimited y recurrir a SystemLanguageModel para ese turno, poner la solicitud en cola o mostrar una opción de reintento.
El paquete expone las capacidades de la Messages API que el protocolo de proveedor de Foundation Models puede expresar. Las funcionalidades sin representación en el protocolo de Apple no están disponibles a través de él, incluyendo:
| Referencia | Cubre |
|---|---|
| Documentación de Apple Foundation Models | LanguageModelSession, @Generable, Transcript, Tool y el resto de la superficie del framework |
ClaudeForFoundationModels en GitHub | Código fuente, el ejemplo ejecutable y el rastreador de issues |
| Referencia de la API de Claude | La Messages API subyacente |
El paquete tiene licencia Apache 2.0. Los reportes de errores son bienvenidos a través de issues de GitHub. No se aceptan pull requests externos durante el período beta.
Was this page helpful?