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 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:.



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

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

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



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

Для продакшена направляйте запросы через ваш собственный бэкенд с помощью .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.



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

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.



Изображения

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



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

Пакет отображает ошибки 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 request'ы не принимаются в течение бета-периода.