--- title: Apple Foundation Models url: https://platform.claude.com/docs/ru/cli-sdks-libraries/libraries/apple-foundation-models description: Используйте Claude на платформах Apple через фреймворк Foundation Models с помощью Swift-пакета Claude for Foundation Models. --- [Claude for Foundation Models](https://github.com/anthropics/ClaudeForFoundationModels) — это Swift-пакет, который делает Claude доступным в качестве серверной языковой модели во фреймворке Apple [Foundation Models](https://developer.apple.com/documentation/foundationmodels). Пакет реализует для Claude соответствие протоколу `LanguageModel` фреймворка, поэтому вы управляете им с помощью того же API `LanguageModelSession`, который используете для модели Apple на устройстве: `respond(to:)`, «streaming» (потоковая передача), управляемая генерация и вызов инструментов работают одинаково. Запросы идут напрямую из вашего приложения в Claude API; Apple не находится на пути запроса и не видит подсказок или ответов. Использование оплачивается с вашего аккаунта Anthropic по [стандартным ценам API](https://platform.claude.com/docs/ru/about-claude/pricing), поэтому вашей организации необходим доступный кредитный баланс или активный способ оплаты. Ваше приложение решает, когда использовать Claude, а когда — модель Apple на устройстве: передавайте в каждую сессию ту модель, которая вам нужна. **Бета.** Этот пакет ориентирован на API серверных языковых моделей Foundation Models, представленный в бета-версиях OS 27. API могут измениться в течение бета-периода. Claude for Foundation Models **не** является клиентом Messages API общего назначения. Его публичная поверхность — это соответствие провайдеру Foundation Models плюс типы конфигурации, которые до него доходят (`ClaudeLanguageModel`, `ClaudeModel`, `AuthMode`, `ClaudeServerTool`). Для прямого доступа к Messages API на другом языке см. [клиентские SDK](https://platform.claude.com/docs/ru/cli-sdks-libraries/overview#client-sdks). ## Требования * iOS 27, macOS 27, visionOS 27 или watchOS 27 (все в бета-версии): выпуски ОС, в которых фреймворк Foundation Models поддерживает серверные языковые модели * Xcode 27 (бета) * «API key» (ключ API) Claude из [Claude Console](https://platform.claude.com/) для разработки. Варианты для продакшена см. в разделе [Аутентификация](https://platform.claude.com/docs/ru/cli-sdks-libraries/libraries/apple-foundation-models#authentication). ## Установка пакета Добавьте пакет в ваш `Package.swift`: ```swift dependencies: [ .package(url: "https://github.com/anthropics/ClaudeForFoundationModels.git", from: "0.1.0") ] ``` Или в Xcode: **File** > **Add Package Dependencies…** и введите URL репозитория. Затем добавьте `ClaudeForFoundationModels` в зависимости вашей цели и импортируйте его вместе с `FoundationModels`: ```swift import FoundationModels import ClaudeForFoundationModels ``` ## Быстрый старт `ClaudeLanguageModel` — это точка входа. Передайте его в `LanguageModelSession` и используйте сессию точно так же, как с любым провайдером Foundation Models: ```swift 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` (см. [Серверные инструменты](https://platform.claude.com/docs/ru/cli-sdks-libraries/libraries/apple-foundation-models#server-side-tools)). В качестве полной рабочей программы репозиторий включает [`Examples/ClaudeExample`](https://github.com/anthropics/ClaudeForFoundationModels/tree/main/Examples/ClaudeExample) — запускаемую цель командной строки, которая в потоковом режиме выводит ход чата в терминал, с флагом `--search`, включающим серверный веб-поиск для этого хода. Для запуска требуется хост с macOS 27. ## Выбор модели Идентификаторы моделей — это значения `ClaudeModel`. Используйте встроенную константу или создайте значение с явно указанными возможностями для идентификатора, который ещё не встроен (см. [Возможности](https://platform.claude.com/docs/ru/cli-sdks-libraries/libraries/apple-foundation-models#capabilities)): ```swift ClaudeLanguageModel(name: .opus5_5, auth: auth) ``` Константы отражают идентификаторы моделей API (`.opus5` — это `claude-opus-5`) и несут в себе возможности каждой модели. Новые модели поставляются как новые константы в выпусках пакета; проверьте `ClaudeModel` в Xcode для получения актуального списка, а также [обзор моделей](https://platform.claude.com/docs/ru/models/overview) для сравнения моделей. ### Возможности Каждая `ClaudeModel` объявляет, что она принимает: параметры сэмплирования, уровни усилия, адаптивные размышления, структурированный вывод и ввод изображений. Пакет использует это, чтобы определить, какие поля запроса отправлять, поскольку отправка поля, которое модель отклоняет, является жёсткой ошибкой. Константы несут правильные возможности. Для идентификатора, который не встроен, объявите, что принимает модель (сокращённой формы, которая угадывает, намеренно не существует): ```swift let model = ClaudeModel( id: "claude-experimental-x", capabilities: .init(samplingParams: false, effortLevels: [.low, .high]) ) ClaudeLanguageModel(name: model, auth: auth) ``` ### Усилие Зафиксируйте [уровень усилий](https://platform.claude.com/docs/ru/build-with-claude/effort) Claude для каждого запроса с помощью `fixedEffort:`. Он имеет приоритет над подсказками фреймворка о рассуждениях для отдельных запросов. Именованные уровни рассуждений фреймворка заканчиваются на high; чтобы вместо этого запросить больше усилий для одного запроса, передайте пользовательский уровень рассуждений с названием уровня усилий Claude (`.custom("xhigh")` или `.custom("max")`), который сопоставляется напрямую. Если уровень усилий не отправлен, API использует уровень модели по умолчанию, который различается в зависимости от модели (см. [Уровни усилий](https://platform.claude.com/docs/ru/build-with-claude/effort#effort-levels)): ```swift ClaudeLanguageModel(name: .opus5_5, 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](https://developer.apple.com/documentation/devicecheck/establishing-your-app-s-integrity), чтобы доказать, что это подлинная, немодифицированная сборка зарегистрированного вами приложения. Затем Anthropic выдаёт устройству краткосрочный «access token» (токен доступа), по которому использование тарифицируется в счёт вашего рабочего пространства. Приложение не содержит ключ API, и вам не нужно поддерживать какой-либо прокси-сервер. Аутентификация App Attest доступна только в том случае, если ваше приложение обращается к Claude API напрямую. Она недоступна через Amazon Bedrock, Google Cloud или Microsoft Foundry. Чтобы выпускать приложение без запуска бэкенда, используйте `.appAttest`: ```swift ClaudeLanguageModel( name: .sonnet5, auth: .appAttest(clientID: "clid_...") ) ``` App Attest требует физического устройства. Simulator, а также оборудование без Secure Enclave не могут выполнять App Attest. Используйте `.apiKey` при итерациях в Simulator и `.appAttest` при запуске на устройстве. Чтобы настроить App Attest, вам потребуется ваш Apple Developer Team ID и роль admin, owner или primary owner в вашей организации. Настройте ваш проект Xcode и зарегистрируйте ваше приложение в [Claude Console](https://platform.claude.com/): 1. В Xcode добавьте возможность **App Attest** к цели вашего приложения в разделе **Signing & Capabilities**. 2. В Claude Console перейдите на страницу [App integrations](https://platform.claude.com/settings/workspaces/default/app-integrations) (`platform.claude.com/settings/workspaces/default/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](https://platform.claude.com/docs/ru/api/messages/create). Они не содержат идентификационных данных конечного пользователя: App Attest идентифицирует ваше приложение, а не человека, который им пользуется, поэтому любую логику, относящуюся к отдельным пользователям, реализуйте в своём приложении. Чтобы остановить скомпрометированное или выведенное из эксплуатации приложение, отзовите его интеграцию. В Claude Console перейдите на страницу [App integrations](https://platform.claude.com/settings/workspaces/default/app-integrations) (`platform.claude.com/settings/workspaces/default/app-integrations`). Каждая интеграция приложения принадлежит одному рабочему пространству. В селекторе рабочих пространств на боковой панели выберите рабочее пространство, в котором находится интеграция. Выберите интеграцию и нажмите **Revoke**, затем подтвердите действие. Отзыв интеграции отзывает все её действующие токены, а зарегистрированные для неё устройства больше не смогут запрашивать новые. Отзыв необратим, поэтому для восстановления доступа создайте новую интеграцию приложения. ### Прокси (продакшен) Для продакшена направляйте запросы через собственный бэкенд с помощью `.proxied`. Ретранслятор по адресу `baseURL` добавляет учётные данные Claude API на стороне сервера, поэтому приложение не содержит ключа. Указанные вами `headers` отправляются с каждым запросом, чтобы ваш прокси мог авторизовать вызывающую сторону. Передайте `[:]`, если заголовки не нужны: ```swift ClaudeLanguageModel( name: .sonnet5, auth: .proxied(headers: ["X-App-Token": "..."]), baseURL: URL(string: "https://api.yourapp.com/claude")! ) ``` Ваш прокси получает стандартные запросы [Messages API](https://platform.claude.com/docs/ru/api/messages/create), добавляет заголовок `x-api-key` и пересылает их на `https://api.anthropic.com`. ### Ключ API (разработка) Передавайте ключ API напрямую во время разработки: ```swift ClaudeLanguageModel(name: .sonnet5, auth: .apiKey("YOUR_API_KEY")) ``` Ключ, встроенный в приложение, можно извлечь из выпущенного бинарного файла, и любой, кто его извлечёт, сможет делать запросы, оплачиваемые с вашего аккаунта. Используйте `.apiKey` только для разработки и переключитесь на App Attest или прокси перед выпуском. ## Потоковая передача `streamResponse(to:)` возвращает ответ постепенно. Каждый элемент — это накопительный снимок ответа на данный момент, а не дельта: ```swift let stream = session.streamResponse(to: "Summarize today's top science stories.") for try await partial in stream { print(partial.content) } ``` ## Структурированный вывод Аннотируйте тип с помощью `@Generable` и запросите его с помощью `generating:`. Модель возвращает значение этого типа через [структурированные выводы](https://platform.claude.com/docs/ru/build-with-claude/structured-outputs): ```swift @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](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/overview). ```swift let session = LanguageModelSession(model: model, tools: [FindRestaurantsTool()]) ``` ### Серверные инструменты [Серверные инструменты](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/server-tools) (веб-поиск, веб-загрузка и выполнение кода) выполняются на инфраструктуре Anthropic в рамках одного цикла запрос-ответ, и фреймворку нечего вызывать на устройстве. Настройте их для каждой модели с помощью `serverTools:`: ```swift let model = ClaudeLanguageModel( name: .sonnet5, auth: auth, serverTools: [ .webSearch(maxUses: 5), .codeExecution, ] ) ``` `.webSearch` и `.webFetch` принимают необязательные `allowedDomains`, `blockedDomains` и `maxUses`. Активность серверных инструментов отображается в транскрипте как пользовательские сегменты `ClaudeServerToolSegment`. `serverTools` настраивается на `ClaudeLanguageModel`, а не на `LanguageModelSession`, поскольку тип сессии принадлежит Apple. Чтобы использовать разные наборы серверных инструментов для каждого разговора, создайте несколько экземпляров `ClaudeLanguageModel`. ## Изображения Модели, возможности которых включают ввод изображений, объявляют возможность зрения фреймворка. Передавайте содержимое изображений через стандартный API сессии фреймворка; пакет преобразует его в формат изображений Claude API. Требования к изображениям см. в разделе [Зрение](https://platform.claude.com/docs/ru/build-with-claude/vision). ## Обработка ошибок Пакет отображает ошибки Claude API на случаи `LanguageModelError` от Apple там, где они подходят: переполнение «context window» (контекстного окна) отображается как `.contextSizeExceeded`, HTTP 429 — как `.rateLimited`, запрос, превысивший настроенный тайм-аут, — как `.timeout`. Ошибки провайдера без эквивалента во фреймворке отображаются как `ClaudeError`. Используйте сопоставление с образцом для управления продуктовыми сценариями: ```swift 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 * Подсчёт токенов * Бета-заголовки ## Дополнительные ресурсы | Справочник | Охватывает | | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | [Документация Apple Foundation Models](https://developer.apple.com/documentation/foundationmodels) | `LanguageModelSession`, `@Generable`, `Transcript`, `Tool` и остальная поверхность фреймворка | | [`ClaudeForFoundationModels` на GitHub](https://github.com/anthropics/ClaudeForFoundationModels) | Исходный код, запускаемый пример и трекер задач | | [Справочник Claude API](https://platform.claude.com/docs/ru/api/overview) | Лежащий в основе Messages API | Пакет лицензирован по Apache 2.0. Сообщения об ошибках приветствуются через GitHub issues. Внешние pull request'ы не принимаются в течение бета-периода.