Руководство по миграции на Claude Opus 5.5

На этой странице перечислены изменения кода для перехода на Claude Opus 5.5 с Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 и более ранних моделей Opus или Claude Sonnet 5. Всем читателям нужны разделы Каким требованиям должен соответствовать каждый запрос к Claude Opus 5.5 и Обработка размышлений в каждом ответе. Затем перейдите к разделу для вашей текущей модели: в его первом предложении названы другие разделы, которые к вам относятся. В контрольном списке миграции перечислены все изменения для каждой исходной модели.

Claude Opus 5.5 стоит дешевле, чем Claude Opus 5 ($4 / $20 USD за миллион входных / выходных токенов по сравнению с $5 / $25; см. цены Claude). Сведения о поддержке функций см. в разделе Что нового в Claude Opus 5.5. Различия в поведении и шаблоны подсказок для конкретной модели описаны в разделе Составление подсказок для Claude Opus 5.5.

Каким требованиям должен соответствовать каждый запрос к Claude Opus 5.5

С какой бы модели вы ни переходили, запрос к claude-opus-5-5 должен соответствовать следующим требованиям. Если в пункте сказано, что параметр отклоняется, API возвращает ошибку 400.

• Идентификатор модели: Используйте claude-opus-5-5 — фиксированный идентификатор модели без суффикса даты. В Amazon Bedrock, Claude Platform on AWS, Google Cloud и Microsoft Foundry используйте идентификатор модели соответствующей платформы; см. Доступность.
• Размышления: Не отправляйте поле thinking или отправьте thinking: {"type": "adaptive"}, что равнозначно: «adaptive thinking» (адаптивные размышления) всегда включены. thinking: {"type": "disabled"} и ручные бюджеты размышлений (thinking: {"type": "enabled", "budget_tokens": N}) отклоняются. См. пример «до и после» для размышлений.
• Effort: Управляйте глубиной размышлений с помощью параметра effort — единственного параметра запроса, который ею управляет. Поддерживаются все пять уровней (low, medium, high, xhigh, max), по умолчанию используется medium. См. Рекомендуемые уровни effort для Claude Opus 5.5.
• Выбор инструмента: Используйте tool_choice {"type": "auto"} (по умолчанию) или {"type": "none"}. Принудительный вызов инструмента с помощью {"type": "any"} или {"type": "tool", "name": "..."} отклоняется. См. пример «до и после» для выбора инструмента.
• Параметры сэмплирования: Не указывайте temperature, top_p и top_k или оставьте их значения по умолчанию: любое другое значение отклоняется. Используйте подсказки, чтобы направлять поведение модели.
• Предзаполнение: Не завершайте messages предзаполненным ходом ассистента: такой запрос отклоняется. Вместо этого используйте структурированные выходные данные или инструкции в системной подсказке. В Amazon Bedrock структурированные выходные данные недоступны для Claude Opus 5.5, поэтому там используйте инструкции в системной подсказке.
• «Computer use» (использование компьютера): В Claude API и Google Cloud объявляйте использование компьютера как набор инструментов computer_toolset_20260801; более ранний инструмент computer_20251124 там отклоняется. См. критическое изменение для использования компьютера.
• Контекстное окно: Бета-заголовок для контекстного окна не нужен. Контекстное окно на 1M токенов используется по умолчанию, а заголовок, отправляемый для старых моделей, ни на что не влияет.

Следующий запрос соответствует всем пунктам списка: effort задан, а поле thinking отсутствует. Вкладки SDK, которые выводят текст, выбирают его по типу блока, поскольку блоки thinking идут первыми.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Обработка размышлений в каждом ответе

Размышления выполняются при каждом запросе к Claude Opus 5.5, поэтому каждый ответ может начинаться с блоков thinking, а max_tokens охватывает размышления вместе с текстом. Если ваш код уже работает с включёнными размышлениями, пункты 1–3, скорее всего, уже выполнены: проверьте пункты 4 и 5. Если он работал без размышлений на любой более ранней модели, каждый пункт требует изменений.

1. max_tokens охватывает размышления и текст: В Claude Opus 4.8 и более ранних моделях Opus запросы без поля thinking выполняются без размышлений. Claude Opus 5 и Claude Sonnet 5 принимают thinking: {"type": "disabled"}. В Claude Opus 5.5 каждый запрос выполняется с адаптивными размышлениями. max_tokens остаётся жёстким ограничением на общий вывод — размышления плюс текст ответа, поэтому пересмотрите это значение для рабочих нагрузок, которые выполнялись без размышлений. Токены размышлений оплачиваются как выходные токены, даже если текст размышлений вам не возвращается, поэтому такая рабочая нагрузка может генерировать больше выходных токенов на запрос. См. Контроль затрат. Чтобы тратить меньше токенов на размышления, понизьте уровень effort. Если вы работаете с effort xhigh или max, задайте большое значение max_tokens, чтобы у модели было пространство для размышлений и действий; начните с 64k токенов и настраивайте дальше. Если ваши подсказки были настроены для работы без размышлений, см. Подсказки, написанные для отключённых размышлений.

2. Ответы начинаются с блоков размышлений: Ответ может начинаться с одного или нескольких блоков thinking перед первым блоком text. Код, который читает ответ по позиции, например content[0].text или обработчик потока, считающий первое событие content_block_start текстом, ломается на таких ответах. Вместо этого выбирайте блоки содержимого по их полю type: читайте text из блоков, у которых type равен "text", и ветвите логику по типу блока при обработке событий потока.

3. Возвращайте блоки размышлений без изменений в циклах использования инструментов: Если вы запускаете цикл «tool use» (использование инструментов), при возврате результатов инструментов передавайте блоки thinking из каждого ответа ассистента обратно в API полностью и без изменений, включая блоки с пустым полем thinking. Отправляйте сообщение ассистента обратно в том виде, в каком оно было получено, вместо того чтобы фильтровать его блоки содержимого по типу или пересобирать его: API отклоняет отредактированные, переупорядоченные или частично удалённые блоки размышлений с ошибкой 400. См. Сохранение блоков размышлений.

4. Текст размышлений по умолчанию опускается: thinking.display по умолчанию имеет значение "omitted", поэтому блоки thinking приходят с пустым полем thinking вместе со своей signature. Рассматривайте поле thinking только как текст для отображения. Чтобы вместо этого получать читаемые сводки, установите для thinking.display значение "summarized":

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   thinking = {
       "type": "adaptive",
       "display": "summarized",
   }

   Если ваш продукт передаёт рассуждения пользователям в потоковом режиме, при значении по умолчанию это выглядит как долгая пауза перед началом вывода; установите display: "summarized", чтобы вернуть видимый прогресс во время размышлений. См. Управление отображением размышлений.

5. Текст между вызовами инструментов приходит в блоках размышлений: Короткие заметки, которые модель пишет между вызовами инструментов, возвращаются как блоки thinking, которые пусты при режиме отображения по умолчанию. См. Текст между вызовами инструментов возвращается в блоках размышлений.

Контрольный список миграции по исходной модели

Проходите группы сверху вниз и остановитесь после той, в которой названа ваша текущая модель: к вам относятся все пункты до этого места. Если вы используете Claude Opus 5, первая группа — это весь список. Если вы используете Claude Sonnet 5, примените первую и последнюю группы.

Любая исходная модель

• Обновите идентификатор модели на claude-opus-5-5.
• Удалите thinking: {"type": "disabled"} и thinking: {"type": "enabled", ...}; вместо этого выберите уровень effort.
• Задайте effort явно: по умолчанию используется medium, тогда как у Claude Opus 5 — high.
• Замените типы tool_choice any и tool на auto в сочетании со строгим использованием инструментов или структурированными выходными данными либо только на auto в Amazon Bedrock.
• Если вы используете инструмент использования компьютера в Claude API или Google Cloud, объявите computer_toolset_20260801 (без бета-заголовка) вместо computer_20251124 и обновите цикл агента для набора инструментов. В Amazon Bedrock оставьте computer_20251124; для других платформ см. раздел Совместимость инструмента использования компьютера.
• Если маршрутизатор или резервный механизм может перевести разговор с Claude Opus 5.5 на другую модель, учитывайте, что эта модель будет работать без блоков размышлений Claude Opus 5.5 (исключение — Claude Fable 5.1 и Claude Mythos 5.1 в Claude API, которые их сохраняют). Сам Claude Opus 5.5 читает размышления от Claude Opus 5, от более ранних моделей Opus, Sonnet и Haiku, а в Claude API и Google Cloud — от Claude Sonnet 5.5 и Claude Haiku 5.5, но не от моделей Claude Fable или Claude Mythos.
• Читайте блоки содержимого по type и передавайте блоки thinking обратно без изменений в циклах использования инструментов.
• Если ваш интерфейс отображает текст между вызовами инструментов, задайте display: "updates" (бета) или "summarized" и отображайте непустые блоки thinking.
• Если ваш код редактирует предыдущие ходы, подсказку system или tools посреди разговора, следуйте разделу Сохранённые размышления.
• Обрабатывайте stop_reason: "refusal" и настройте резервный механизм.
• Заново определите базовые показатели стоимости и задержки на выбранном уровне effort.
• Если ваш код отключал размышления, пересмотрите max_tokens, который охватывает размышления вместе с текстом ответа; при effort xhigh или max начните с 64k. См. Обработка размышлений в каждом ответе.

Claude Opus 4.8 или более ранние модели

• Проверьте рабочие нагрузки, которые выполнялись без поля thinking: в Claude Opus 5.5 они выполняются с размышлениями, и размышления нельзя отключить. Пересмотрите max_tokens, который остаётся жёстким ограничением на общий вывод (размышления плюс текст ответа), и понизьте effort там, где вам нужно меньше размышлений. Токены размышлений оплачиваются как выходные токены, поэтому эти рабочие нагрузки могут генерировать больше выходных токенов на запрос.
• Убедитесь, что любой код, разбирающий поле thinking, рассматривает его только как текст для отображения. Установите display: "summarized", чтобы получать читаемые сводки.
• Проверьте подсказки, длина которых близка к минимуму для кэширования: подсказки длиной 512 токенов и более могут создавать записи кэша.
• Если у вашей организации есть обязательство по Priority Tier, планируйте мощности отдельно: Priority Tier не поддерживается в Claude Opus 5.5.
• Если вы работаете с effort xhigh или max, для начала увеличьте max_tokens как минимум до 64k.
• Для агентных рабочих нагрузок рассмотрите бюджеты задач (бета) и изменение инструментов посреди разговора (бета).

Claude Opus 4.7 или более ранние модели

• Заново подберите уровень effort на собственных оценках вместо того, чтобы переносить настройку, подобранную для более ранней модели.
• Удалите любой бета-заголовок для контекстного окна.
• Если вы пересобираете историю разговора для обновления инструкций, рассмотрите переход на системное сообщение посреди разговора, чтобы сохранить попадания в кэш подсказок.
• Убедитесь, что ваша обработка причин остановки читает stop_details при отказах.
• Если вам нужен быстрый режим, который Claude Opus 4.7 отклоняет, установите speed: "fast" с бета-заголовком fast-mode-2026-02-01 в Claude API.

Claude Opus 4.6 или более ранние модели

• Удалите temperature, top_p и top_k из тел запросов.
• Замените thinking: {"type": "enabled", "budget_tokens": N} на thinking: {"type": "adaptive"} вместе с параметром effort или полностью удалите поле thinking; адаптивные размышления всегда включены.
• Если ваш интерфейс отображает содержимое размышлений, явно включите суммаризацию размышлений.
• Заново измерьте сквозную стоимость и задержку с учётом обновлённой токенизации.
• Перенастройте max_tokens с учётом обновлённой токенизации, включая триггеры сжатия.
• Повторно протестируйте любые клиентские оценки количества токенов.
• Если ваше приложение отправляет изображения, пересчитайте бюджет с учётом поддержки изображений высокого разрешения (примерно до 3 раз больше токенов изображения на одно изображение в полном разрешении). Уменьшайте разрешение перед отправкой, если дополнительная детализация вам не нужна.
• Если вы используете координаты указания или ограничивающих рамок, возвращаемые моделью, удалите любое преобразование с масштабным коэффициентом; в Claude Opus 4.7 и более поздних моделях координаты соответствуют фактическим пикселям изображения 1:1.
• Ознакомьтесь с изменениями поведения, появившимися в Claude Opus 4.7.
• Если ваш продукт выполняет легитимную работу в области безопасности, подайте заявку в Cyber Verification Program, чтобы получить доступ к менее строгим ограничениям на киберконтент.

Claude Opus 4.5 или более ранние модели

• Удалите любые предзаполнения сообщений ассистента; Claude Opus 4.6 уже отклоняет их.
• Убедитесь, что для разбора JSON вызовов инструментов используется стандартный парсер JSON.
• Перейдите с client.beta.messages.create() на client.messages.create(): адаптивным размышлениям и effort не нужно бета-пространство имён.
• Удалите бета-заголовок effort-2025-11-24 (параметр effort его не требует).
• Удалите бета-заголовок fine-grained-tool-streaming-2025-05-14.
• Удалите бета-заголовок interleaved-thinking-2025-05-14 (адаптивные размышления автоматически включают чередующиеся размышления).
• Перенесите output_format в output_config.format (если применимо).

Claude 4.1 или более ранние модели

• Обновите версии инструментов (text_editor_20250728, code_execution_20260521).
• Обрабатывайте причину остановки refusal.
• Обрабатывайте причину остановки model_context_window_exceeded.
• Проверьте обработку строковых параметров инструментов на наличие завершающих символов новой строки.
• Удалите устаревшие заголовки бета-версий (token-efficient-tools-2025-02-19, output-128k-2025-02-19).
• Проверьте и обновите подсказки в соответствии с лучшими практиками составления подсказок.

Только Claude Sonnet 5

• Если вы пересобираете историю разговора для обновления инструкций, рассмотрите переход на системное сообщение посреди разговора, чтобы сохранить попадания в кэш подсказок.
• Проверьте подсказки, длина которых близка к минимуму для кэширования: подсказки длиной 512 токенов и более могут создавать записи кэша.

Миграция на Claude Opus 5.5 с Claude Opus 5

Сначала проработайте разделы Каким требованиям должен соответствовать каждый запрос к Claude Opus 5.5 и Обработка размышлений в каждом ответе. Изменения из этого раздела нужны для любой исходной модели. Это параметры запроса, которые Claude Opus 5.5 отклоняет, и связанные с ним изменения в ответах. Контрольный список для этого раздела — первая группа контрольного списка миграции.

Обновите название модели

model = "claude-opus-5"  # Before
model = "claude-opus-5-5"  # After

claude-opus-5-5 — фиксированный идентификатор модели без суффикса даты, построенный по той же схеме, что и claude-opus-5. В Amazon Bedrock, Claude Platform on AWS, Google Cloud и Microsoft Foundry используйте идентификатор модели соответствующей платформы; см. Доступность.

Критические изменения

Каждое изменение объясняется в разделе Что нового в Claude Opus 5.5; здесь для каждого из них приведено изменение кода.

Размышления нельзя отключить

thinking: {"type": "disabled"} и thinking: {"type": "enabled", "budget_tokens": N} возвращают ошибку 400 ("thinking.type.disabled" is not supported for this model. или "thinking.type.enabled" is not supported for this model.). Удалите поле thinking и выберите уровень effort; там, где вы отключали размышления для экономии токенов, используйте более низкий уровень. После этого ответы будут начинаться с блоков thinking, поэтому выбирайте блоки содержимого по type и передавайте блоки thinking обратно без изменений вместе с результатами инструментов. См. Размышления нельзя отключить.

До. Claude Opus 5 принимает этот запрос, а Claude Opus 5.5 отклоняет его с ошибкой 400:

client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "..."}],
)

После:

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    output_config={"effort": "low"},  # thinking is always on; effort is the control
    messages=[{"role": "user", "content": "..."}],
)

Принудительное использование инструментов не поддерживается

Типы tool_choice any и tool возвращают ошибку 400 (tool_choice: type "tool" and "any" are not supported for this model.), в том числе на эндпоинте подсчёта токенов. Используйте