Apple Foundation Models

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

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

Требования

• iOS 27, macOS 27, visionOS 27 или watchOS 27 (все в бета-версии): выпуски ОС, в которых фреймворк Foundation Models поддерживает серверные языковые модели
• Xcode 27 (бета)
• Ключ 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: .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)

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

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

Выбор модели

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

ClaudeLanguageModel(name: .opus4_8, auth: auth)

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

Возможности

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

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

Уровень усилия

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

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

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

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

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

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

Задайте учётные данные с помощью параметра auth:.

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

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

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

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

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

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

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

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

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: .sonnet4_6,
  auth: auth,
  serverTools: [
    .webSearch(maxUses: 5),
    .codeExecution,
  ]
)

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

Изображения

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

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

Пакет сопоставляет ошибки Claude API с вариантами LanguageModelError от Apple там, где есть подходящий: переполнение контекстного окна отображается как .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, через него недоступны, в том числе:

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

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

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