Apple Foundation Models

Claude for Foundation Models — это Swift-пакет, который делает Claude доступным в качестве серверной языковой модели во фреймворке Apple Foundation Models. Пакет реализует для Claude соответствие протоколу LanguageModel фреймворка, поэтому вы управляете им с помощью того же API LanguageModelSession, который используете для модели Apple на устройстве: respond(to:), «streaming» (потоковая передача), управляемая генерация и вызов инструментов работают одинаково.

Запросы идут напрямую из вашего приложения в Claude API; Apple не находится на пути запроса и не видит подсказок или ответов. Использование оплачивается с вашего аккаунта Anthropic по стандартным ценам API, поэтому вашей организации необходим доступный кредитный баланс или активный способ оплаты. Ваше приложение решает, когда использовать Claude, а когда — модель Apple на устройстве: передавайте в каждую сессию ту модель, которая вам нужна.

Требования

• iOS 27, macOS 27, visionOS 27 или watchOS 27 (все в бета-версии): выпуски ОС, в которых фреймворк Foundation Models поддерживает серверные языковые модели
• Xcode 27 (бета)
• «API key» (ключ API) Claude из Claude Console для разработки. Варианты для продакшена см. в разделе Аутентификация.

Установка пакета

Добавьте пакет в ваш Package.swift:

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

Или в Xcode: File > Add Package Dependencies… и введите URL репозитория.

Затем добавьте ClaudeForFoundationModels в зависимости вашей цели и импортируйте его вместе с FoundationModels:

import FoundationModels
import ClaudeForFoundationModels

Быстрый старт

ClaudeLanguageModel — это точка входа. Передайте его в LanguageModelSession и используйте сессию точно так же, как с любым провайдером 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)

Инициализатор также принимает baseURL (по умолчанию https://api.anthropic.com), timeout и serverTools (см. Серверные инструменты).

В качестве полной рабочей программы репозиторий включает Examples/ClaudeExample — запускаемую цель командной строки, которая в потоковом режиме выводит ход чата в терминал, с флагом --search, включающим серверный веб-поиск для этого хода. Для запуска требуется хост с macOS 27.

Выбор модели

Идентификаторы моделей — это значения ClaudeModel. Используйте встроенную константу или создайте значение с явно указанными возможностями для идентификатора, который ещё не встроен (см. Возможности):

ClaudeLanguageModel(name: .opus5, auth: auth)

Константы отражают идентификаторы моделей API (.opus5 — это claude-opus-5) и несут в себе возможности каждой модели. Новые модели поставляются как новые константы в выпусках пакета; проверьте ClaudeModel в Xcode для получения актуального списка, а также обзор моделей для сравнения моделей.

Возможности

Каждая ClaudeModel объявляет, что она принимает: параметры сэмплирования, уровни усилия, адаптивное мышление, структурированный вывод и ввод изображений. Пакет использует это, чтобы определить, какие поля запроса отправлять, поскольку отправка поля, которое модель отклоняет, является жёсткой ошибкой. Константы несут правильные возможности. Для идентификатора, который не встроен, объявите, что принимает модель (сокращённой формы, которая угадывает, намеренно не существует):

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

Усилие

Зафиксируйте уровень усилия Claude для каждого запроса с помощью fixedEffort:. Он имеет приоритет над подсказками рассуждения фреймворка для отдельных запросов. Именованные уровни рассуждения фреймворка заканчиваются на high; чтобы вместо этого запросить больше усилия для одного запроса, передайте пользовательский уровень рассуждения с именем уровня усилия Claude (.custom("xhigh") или .custom("max")), который отображается напрямую. API по умолчанию использует high, когда усилие не отправлено:

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

Уровень должен быть одним из тех, которые принимает модель. Каждая ClaudeModel объявляет, какие из пяти уровней (low, medium, high, xhigh, max) принимает её модель, если принимает вообще: некоторые модели не принимают усилие совсем.

Когда использовать Claude, а когда модель на устройстве

Модель Apple на устройстве быстрая, приватная и доступна офлайн, но она рассчитана на лёгкие задачи. Переходите к Claude, когда вам нужен больший контекст, передовые рассуждения или серверные инструменты, такие как веб-поиск и выполнение кода. Поскольку обе используют один и тот же API LanguageModelSession, вы можете переключаться, заменяя аргумент model:.

Аутентификация

Задайте учётные данные с помощью параметра auth:. Используйте .appAttest, чтобы выпускать приложение без бэкенда, .proxied, чтобы направлять запросы через собственный бэкенд, или .apiKey для итераций во время разработки.

App Attest

Каждая установка вашего приложения использует сервис Apple App Attest, чтобы доказать, что это подлинная, немодифицированная сборка зарегистрированного вами приложения. Затем Anthropic выдаёт устройству краткосрочный «access token» (токен доступа), по которому использование тарифицируется в счёт вашего рабочего пространства. Приложение не содержит ключ API, и вам не нужно поддерживать какой-либо прокси-сервер.

Аутентификация App Attest доступна только в том случае, если ваше приложение обращается к Claude API напрямую. Она недоступна через Amazon Bedrock, Google Cloud или Microsoft Foundry.

Чтобы выпускать приложение без запуска бэкенда, используйте .appAttest:

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

Чтобы настроить App Attest, вам потребуется ваш Apple Developer Team ID и роль admin, owner или primary owner в вашей организации. Настройте ваш проект Xcode и зарегистрируйте ваше приложение в Claude Console:

1. В Xcode добавьте возможность App Attest к цели вашего приложения в разделе Signing & Capabilities.
2. В настройках вашего рабочего пространства в Claude Console откройте App integrations.
3. Нажмите Create app integration и введите название, ваш Apple Developer Team ID и один или несколько bundle ID (до 32).
4. Скопируйте client ID (clid_...) на вкладке Overview интеграции и передайте его в конфигурацию Claude вашего приложения.

Когда ваше приложение впервые использует Claude на устройстве, оно запрашивает у Anthropic challenge (проверочное значение), выполняет аттестацию устройства с помощью DCAppAttestService от Apple и обменивает подтверждённую аттестацию на «access token» (токен доступа). Пакет Claude for Foundation Models выполняет этот процесс автоматически и запрашивает новые токены по мере истечения срока их действия; вам не нужно писать никакого кода аттестации.

Токены привязаны к вашему рабочему пространству, истекают через один час и разрешают только вызовы Messages API. Они не содержат идентификационных данных конечного пользователя: App Attest идентифицирует ваше приложение, а не человека, который им пользуется, поэтому любую логику, относящуюся к отдельным пользователям, реализуйте в своём приложении.

Чтобы остановить скомпрометированное или выведенное из эксплуатации приложение, отзовите его интеграцию: в настройках вашего рабочего пространства в Claude Console откройте App integrations, выберите интеграцию и нажмите Revoke, затем подтвердите. Отзыв интеграции отзывает все её действующие токены, а её зарегистрированные устройства больше не смогут запрашивать новые. Отзыв необратим, поэтому для восстановления доступа создайте новую интеграцию приложения.

Прокси (продакшен)

Для продакшена направляйте запросы через собственный бэкенд с помощью .proxied. Ретранслятор по адресу baseURL добавляет учётные данные Claude API на стороне сервера, поэтому приложение не содержит ключа. Указанные вами headers отправляются с каждым запросом, чтобы ваш прокси мог авторизовать вызывающую сторону. Передайте [:], если заголовки не нужны:

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

Ваш прокси получает стандартные запросы Messages API, добавляет заголовок x-api-key и пересылает их на https://api.anthropic.com.

Ключ API (разработка)

Передавайте ключ API напрямую во время разработки:

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

Потоковая передача

streamResponse(to:) возвращает ответ постепенно. Каждый элемент — это накопительный снимок ответа на данный момент, а не дельта:

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

Структурированный вывод

Аннотируйте тип с помощью @Generable и запросите его с помощью generating:. Модель возвращает значение этого типа через структурированные выводы:

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

Структурированный вывод требует модели, возможности которой его включают (все встроенные константы включают). Если выбранная модель его не поддерживает, пакет выбрасывает LanguageModelError.unsupportedGenerationGuide, а не молча деградирует.

Использование инструментов

Клиентские инструменты

Массив tools: фреймворка работает без изменений. Реализуйте в ваших типах соответствие Tool, передайте их в LanguageModelSession, и фреймворк вызовет их на устройстве, когда Claude их вызовет. См. Использование инструментов с Claude.

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

Серверные инструменты

Серверные инструменты (веб-поиск, веб-загрузка и выполнение кода) выполняются на инфраструктуре Anthropic в рамках одного цикла запрос-ответ, и фреймворку нечего вызывать на устройстве. Настройте их для каждой модели с помощью serverTools::

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

.webSearch и .webFetch принимают необязательные allowedDomains, blockedDomains и maxUses. Активность серверных инструментов отображается в транскрипте как пользовательские сегменты ClaudeServerToolSegment.

Изображения

Модели, возможности которых включают ввод изображений, объявляют возможность зрения фреймворка. Передавайте содержимое изображений через стандартный API сессии фреймворка; пакет преобразует его в формат изображений Claude API. Требования к изображениям см. в разделе Зрение.

Обработка ошибок

Пакет отображает ошибки Claude API на случаи LanguageModelError от Apple там, где они подходят: переполнение «context window» (контекстного окна) отображается как .contextSizeExceeded, HTTP 429 — как .rateLimited, запрос, превысивший настроенный тайм-аут, — как .timeout. Ошибки провайдера без эквивалента во фреймворке отображаются как ClaudeError. Используйте сопоставление с образцом для управления продуктовыми сценариями:

do {
  let response = try await session.respond(to: prompt)
  print(response.content)
} catch ClaudeError.missingCredential {
  // Запросить ключ API.
} catch let error as LanguageModelError {
  // Ошибки уровня фреймворка (ограничения скорости, защитные механизмы, длина контекста, декодирование).
} catch {
  // Ошибки транспорта.
}

Распространённый шаблон — перехватить .rateLimited и переключиться на SystemLanguageModel для этого хода, поставить запрос в очередь или показать возможность повторной попытки.

Поддержка функций

Пакет предоставляет те возможности Messages API, которые может выразить протокол провайдера Foundation Models. Функции, не имеющие представления в протоколе Apple, через него недоступны, в том числе:

• Управление «prompt caching» (кэшированием подсказок) (пакет применяет кэширование подсказок автоматически; TTL кэша и размещение точек разрыва не настраиваются)
• Стоп-последовательности
• Пакетная обработка
• Files API
• Подсчёт токенов
• Бета-заголовки

Дополнительные ресурсы

Пакет лицензирован по Apache 2.0. Сообщения об ошибках приветствуются через GitHub issues. Внешние pull request'ы не принимаются в течение бета-периода.