Руководство по миграции на Claude Sonnet 5.5
Перейдите на Claude Sonnet 5.5 с более ранних моделей Sonnet или Claude Haiku 4.5 с помощью этого руководства по миграции. Рекомендации по включению Claude Sonnet 5.5 охватывают настройки, которые возвращают ошибки, изменения в размышлениях и контрольный список для каждой исходной модели.
В этом руководстве перечислены изменения в коде, необходимые для перехода на Claude Sonnet 5.5 с Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Sonnet 4, Claude 3.7 Sonnet или Claude Haiku 4.5. Прочитайте первые два раздела, затем читайте дальше до раздела, посвящённого вашей текущей модели. В контрольном списке миграции перечислены все изменения в зависимости от исходной модели.
Claude Code
Позвольте Claude Code выполнить миграцию вашего кода за вас
/claude-api migrate этот проект на claude-sonnet-5-5Цены Claude Sonnet 5.5 такие же, как у Claude Sonnet 5, за исключением чтения из кэша подсказок, которое стоит $0,10 USD за миллион токенов — вдвое меньше тарифа Claude Sonnet 5. См. Цены. Сведения о «context window» (контекстное окно) и ограничениях на вывод см. на странице модели Claude Sonnet 5.5. Сведения о функциях и составлении подсказок см. в разделах Что нового в Claude Sonnet 5.5 и Составление подсказок для Claude Sonnet 5.5.
Отправка запроса к Claude Sonnet 5.5
Этот запрос работает на Claude Sonnet 5.5 в том виде, в котором он написан. Он задаёт уровень «effort» (усилия) и не использует пять настроек, которые возвращают ошибку 400: бюджеты размышлений, параметры сэмплирования, предзаполнение ответа ассистента, принудительный выбор инструмента и thinking: {"type": "disabled"}.
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Analyze the trade-offs between microservices and monolithic architectures",
}
],
output_config={"effort": "medium"},
)
print(f"Stop reason: {response.stop_reason}")
for block in response.content:
if block.type == "text":
print(block.text)Размышления выполняются по умолчанию
На Claude Sonnet 5.5 запрос без поля thinking выполняется с адаптивными размышлениями («adaptive thinking»), как и запрос с thinking: {"type": "adaptive"}. На Claude Sonnet 4.6 и более ранних моделях, а также на Claude Haiku 4.5 такой запрос выполнялся без размышлений. Чтобы по-прежнему работать без предварительных размышлений, см. раздел Отключение предварительных размышлений.
| Модель | Размышления без поля thinking | Допустимые значения thinking.type | display по умолчанию |
|---|---|---|---|
| Claude Sonnet 5.5 | Включены | "adaptive", "between_tools" | "omitted" |
| Claude Sonnet 5 | Включены | "adaptive", "disabled" | "omitted" |
| Claude Sonnet 4.6 | Выключены | "adaptive", "disabled", "enabled" (устарело) | "summarized" |
| Claude Sonnet 4.5 и Claude Haiku 4.5 | Выключены | "disabled", "enabled" | "summarized" |
Обработка размышлений в ответах
Коду, который работал без размышлений, нужны все три пункта. В коде для Claude Sonnet 5, скорее всего, уже есть первые два.
- Читайте блоки содержимого по
type. Ответ может начинаться с блоковthinking, поэтому код, который читаетcontent[0].text, перестаёт работать. - Передавайте блоки
thinkingобратно без изменений в циклах использования инструментов, включая пустые блоки. См. Сохранение блоков размышлений. - Пересмотрите
max_tokens. Это значение охватывает размышления и текст, а токены размышлений оплачиваются как выходные токены. См. Контроль затрат.
Текст размышлений по умолчанию опускается. Блоки thinking приходят с пустым полем thinking и полем signature. Чтобы получать читаемые сводки, задайте display: "summarized" — это значение по умолчанию на Claude Sonnet 4.6 и более ранних моделях, а также на Claude Haiku 4.5. См. Управление отображением размышлений.
Отключение предварительных размышлений
Чтобы отключить предварительные размышления на Claude Sonnet 5.5, отправьте thinking: {"type": "between_tools"}. Это самая низкая настройка размышлений. Её промежуточные сообщения о ходе работы между вызовами инструментов по-прежнему возвращаются как блоки thinking с текстом сводки. Без инструментов ответ содержит только текст. Claude Sonnet 5 вместо этого отключает размышления с помощью thinking: {"type": "disabled"}, а более ранние модели по умолчанию работают без размышлений. На Claude Sonnet 5.5 значение disabled возвращает ошибку 400 invalid_request_error:
To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.between_tools работает на всех платформах, где доступна Claude Sonnet 5.5. Эта настройка допускается при уровнях усилий low, medium и high. При xhigh или max она возвращает ошибку 400. Чтобы работать на этих уровнях, используйте адаптивные размышления: опустите поле thinking или отправьте thinking: {"type": "adaptive"}. between_tools не принимает других полей: display, budget_tokens или block_binding, отправленные вместе с ней, возвращают ошибку 400. При резервном переключении на стороне сервера запрос с between_tools, переключённый на Claude Sonnet 5, выполняется там с thinking: {"type": "disabled"}.
С between_tools уровень усилий нельзя изменить посреди разговора: значение output_config.effort для отдельного сообщения, отличающееся от действующего уровня, возвращает ошибку 400. Чтобы менять уровень усилий для каждого хода, используйте адаптивные размышления. Рекомендации по составлению подсказок см. в разделе Работа без предварительных размышлений.
До (Claude Sonnet 5):
client.messages.create(
model="claude-sonnet-5",
max_tokens=16000,
thinking={"type": "disabled"},
output_config={"effort": "xhigh"},
messages=[{"role": "user", "content": "..."}],
)После (Claude Sonnet 5.5):
client.messages.create(
model="claude-sonnet-5-5",
max_tokens=16000,
thinking={"type": "between_tools"},
output_config={"effort": "high"},
messages=[{"role": "user", "content": "..."}],
)Контрольный список миграции по исходной модели
Проходите группы сверху вниз и остановитесь после той, в которой названа ваша модель. Для Claude Haiku 4.5 примените все группы, кроме «Claude Sonnet 4 или более ранние», закончив группой «Только Claude Haiku 4.5».
Все исходные модели
- Измените идентификатор модели на
claude-sonnet-5-5. - Читайте блоки содержимого по
typeи передавайте блокиthinkingобратно без изменений. - Чтобы продолжать работу без предварительных размышлений, отправляйте самую низкую настройку размышлений при уровне «effort» (усилие)
highили ниже. - Замените принудительное использование инструментов («forced tool use») на
autoи строгие инструменты. - Ведите разговоры в режиме только добавления («append-only»).
- Перенесите «computer use» (использование компьютера) в набор инструментов («toolset») без бета-заголовка
fine-grained-tool-streaming-2025-05-14. В Amazon Bedrock также работаетcomputer_20251124. - Используйте инструмент-советник в паре с поддерживаемым советником и учитывайте, что советы будут зашифрованы.
- Читайте текст между вызовами инструментов из блоков
thinking. - Обрабатывайте отказы («refusals») и настройте резервный вариант («fallback»).
- Повторно проведите подбор уровня effort и заново определите базовый уровень стоимости.
Claude Sonnet 4.6 или более ранние
- Учитывайте, что размышления выполняются в запросах без поля
thinking, и пересмотритеmax_tokens. - Замените бюджеты размышлений уровнем усилий.
- Удалите
temperature,top_pиtop_k. - Если вы показываете текст размышлений, задайте
display: "summarized". - Пересчитайте токены и заново распределите бюджет токенов изображений.
Claude Sonnet 4.5 или более ранние
- Замените предварительное заполнение ответа ассистента («assistant prefill»).
- Разбирайте входные данные вызовов инструментов стандартным парсером JSON.
- Явно задавайте
output_config.effort. - Удалите любой бета-заголовок для контекстного окна.
- Удалите
interleaved-thinking-2025-05-14и заменитеfine-grained-tool-streaming-2025-05-14наeager_input_streaming. - Перенесите
output_formatвoutput_config.format.
Claude Sonnet 4 или более ранние
- Обновите версии инструментов до
text_editor_20250728иcode_execution_20260521. - Обрабатывайте причины остановки
refusalиmodel_context_window_exceeded. - Проверьте строковые параметры инструментов на наличие завершающих символов новой строки.
- Удалите
token-efficient-tools-2025-02-19иoutput-128k-2025-02-19. - Пересмотрите свои подсказки.
Только Claude Haiku 4.5
- Замените
claude-haiku-4-5-20251001или его псевдоним. - Заново определите базовый уровень затрат с учётом более высокой цены за токен.
- Пересмотрите подсказки, которые были слишком короткими для кэширования на Claude Haiku 4.5.
Миграция на Claude Sonnet 5.5 с Claude Sonnet 5
Изменения из этого раздела нужны для всех исходных моделей. Замените идентификатор модели на claude-sonnet-5-5, у которого нет суффикса с датой. На других платформах используйте идентификатор, указанный в разделе Доступность.
Принудительное использование инструментов не поддерживается
Все более ранние модели на этой странице принимают tool_choice типа any или tool. Claude Sonnet 5.5 отклоняет оба варианта с ошибкой 400, в том числе на эндпоинте подсчёта токенов:
tool_choice: type "tool" and "any" are not supported for this model.Отправьте tool_choice: {"type": "auto"} и пометьте инструмент как strict: true, чтобы его входные данные соответствовали схеме. В этом случае модель может ответить без вызова инструмента, поэтому укажите в подсказке, когда его использовать. Строгое использование инструментов поддерживает подмножество JSON Schema и требует additionalProperties: false для каждого объекта. См. Ограничения JSON Schema.
До (Claude Sonnet 5):
client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "tool", "name": "get_weather"},
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)После (Claude Sonnet 5.5):
client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
# строгое использование инструментов: каждый вызов соответствует input_schema инструмента
tools=[{**tool, "strict": True} for tool in tools],
tool_choice={"type": "auto"},
messages=[
{
"role": "user",
"content": "What's the weather in Paris? Use the get_weather tool.",
}
],
)В примере все инструменты в списке помечены как строгие. Запрос может содержать не более 20 строгих инструментов, а записи наборов инструментов MCP, использования компьютера и использования браузера не принимают strict. В более длинном списке инструментов помечайте только те инструменты, которым это нужно.
Блоки размышлений привязаны к модели и разговору
Claude Sonnet 5.5 читает блоки размышлений от Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 и более ранних моделей. В Claude API и Claude Models on Google Cloud (Google managed) она также читает их от Claude Haiku 5.5. Она не читает блоки от Claude Opus 5, Claude Opus 5.5 и любых моделей Claude Fable или Claude Mythos.
API отбрасывает блоки, которые модель не может прочитать. Запрос возвращает 200, а отброшенные блоки не оплачиваются. См. Переключение моделей туда и обратно.
Ведите разговоры в режиме только добавления («append-only»), чтобы блоки размышлений проходили проверку префикса. Чтобы изменить инструкции или инструменты, см. Системные сообщения и изменения инструментов в середине разговора.
Непройденная «prefix check» (проверка префикса) может привести к ошибке 400, а может и не привести. Чтобы выявлять и обрабатывать оба случая, см. Проверка префикса для блоков размышлений.
Проверка префикса выполняется в Claude API и на некоторых облачных платформах.
Блоки размышлений Claude Sonnet 5.5 работают только в аккаунте, который их создал, или в связанном с ним аккаунте. См. Сохранённые размышления.
Некоторые версии инструмента использования компьютера не поддерживаются
Claude Sonnet 5.5 поддерживает использование компьютера через набор инструментов computer_toolset_20260801. В Amazon Bedrock Claude Sonnet 5.5 также принимает инструмент computer_20251124 с бета-заголовком computer-use-2025-11-24. Claude Sonnet 5.5 возвращает ошибку 400 для любой версии инструмента использования компьютера, которую он не принимает, например computer_20251124 в Claude API. Он не принимает computer_20250124 ни на одной платформе.
Интеграции, использующие набор инструментов, не требуют изменений. Чтобы перейти на набор инструментов, замените computer_20251124 или computer_20250124 на computer_toolset_20260801 и удалите бета-заголовок этой версии. Изменения в запросах и в цикле агента см. в разделе Миграция с computer_20251124.
Если вы отправляете бета-заголовок fine-grained-tool-streaming-2025-05-14, удалите его при переходе на набор инструментов. Вместе с записью набора инструментов он возвращает ошибку 400. Вместо этого задайте eager_input_streaming: true для каждого инструмента, которому это нужно.
Инструмент-советник принимает меньше советников
При использовании инструмента-советника исполнителю Claude Sonnet 5.5 нужен один из следующих советников: Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5, Claude Fable 5.1, Claude Fable 5.2, Claude Mythos 5, Claude Mythos 5.1 или Claude Mythos 5.2. Советники Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, Claude Sonnet 4.6 и Claude Haiku 5.5 возвращают ошибку 400. Совет возвращается в зашифрованном виде как блок advisor_redacted_result, поэтому его текст в ответе прочитать нельзя. См. Совместимость моделей.
Текст между вызовами инструментов возвращается в блоках размышлений
На Claude Sonnet 5.5 заметки длиннее одного-двух предложений, которые модель пишет между вызовами инструментов, возвращаются как блоки thinking с сообщениями о ходе работы, пустые при значении display по умолчанию. Более короткие замечания остаются блоками text. На Claude Sonnet 5 и более ранних моделях весь текст между вызовами инструментов возвращается как блоки text. Ни один запрос не завершается ошибкой, но интерфейс, который показывает эти заметки, перестаёт их отображать.
При адаптивных размышлениях задайте для display значение "updates" (бета, заголовок thinking-display-updates-2026-08-18), чтобы получать только сообщения о ходе работы, или "summarized", чтобы получать их вместе с рассуждениями. Отображайте каждый непустой блок thinking перед следующим за ним блоком tool_use. При between_tools текст возвращается без display. См. Сообщения о ходе работы для пользователя.
Классификаторы безопасности и резервное переключение
Claude Sonnet 5.5 отказывает в большем числе категорий, чем Claude Sonnet 5. Отказ возвращает stop_reason: "refusal", а его stop_details может указывать одну из следующих категорий:
"cyber": Запрос может способствовать киберугрозам, например разработке вредоносного ПО или эксплойтов."bio": Запрос может способствовать биологическому вреду, например через опасные лабораторные методы."frontier_llm": Запрос может помочь в разработке конкурирующих моделей ИИ."reasoning_extraction": Запрос просит модель воспроизвести её внутренние рассуждения в тексте ответа."general_harms": Запрос относится к другой области политики использования. Эту категорию может вызвать и безобидная работа.
Резервное переключение на стороне сервера (fallbacks: "default"), доступное в бета-версии в Claude API и в Claude Models on Google Cloud (Anthropic managed), повторяет запросы с отказами "cyber" и "frontier_llm" на Claude Sonnet 5. Оно не повторяет запросы с отказами "bio", "reasoning_extraction" и "general_harms". См. Отказы и резервное переключение и Как оплачиваются отказы.
Защитные меры в области кибербезопасности в реальном времени являются новыми для кода, перешедшего с Claude Sonnet 4.6, Claude Sonnet 4.5 и Claude Haiku 4.5. Для легитимной работы в области безопасности подайте заявку в Cyber Verification Program.
Другие изменения
- Кэширование подсказок: Минимальный размер кэшируемой подсказки составляет 512 токенов вместо 1024 на Claude Sonnet 5, Claude Sonnet 4.6 и Claude Sonnet 4.5. См. Кэширование подсказок.
- Новые функции: Сведения о системных сообщениях посреди разговора, изменении инструментов посреди разговора и уровне усилий для отдельных сообщений см. в разделе Что нового в Claude Sonnet 5.5. При
between_toolsуровень усилий нельзя изменить посреди разговора.
Рекомендуемые изменения
Повторите подбор уровня усилий. У Claude Sonnet 5.5 пять уровней усилий: low, medium, high, xhigh и max. По умолчанию в Claude API используется high. Уровни откалиброваны заново, поэтому один и тот же уровень не даёт такого же объёма размышлений, как на Claude Sonnet 5. Начните с high, если ваша рабочая нагрузка не является агентной или чувствительной к «latency» (задержка). Для агентного программирования и многошагового использования инструментов начните с medium для чётко сформулированных задач и переходите на high для более сложных или длительных. Для чата и другой работы, чувствительной к задержке, начните с medium или low. Задайте уровень в output_config.effort. См. Рекомендуемые уровни усилий для Claude Sonnet 5.5. Затем заново оцените инструкции в подсказках, специфичные для модели, с учётом раздела Составление подсказок для Claude Sonnet 5.5.
Миграция на Claude Sonnet 5.5 с Claude Sonnet 4.6 и более ранних моделей Sonnet
Сначала примените все предыдущие разделы, заменив claude-sonnet-4-6. Затем внесите следующие изменения. Для Claude Sonnet 4.5 или более ранних моделей продолжите с последующими подразделами.
Критические изменения
Размышления выполняются в запросах, в которых они не были указаны. См. Размышления выполняются по умолчанию и Отключение предварительных размышлений.
Бюджеты размышлений возвращают ошибку. Claude Sonnet 4.6 принимает thinking: {"type": "enabled", "budget_tokens": N} как устаревшую настройку. Claude Sonnet 4.5 и Claude Haiku 4.5 используют её для всех размышлений. Claude Sonnet 5.5 возвращает ошибку 400:
"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.Удалите бюджет и задайте уровень усилий. Фиксированного соответствия между бюджетом и уровнем усилий нет, поэтому проведите оценку на двух-трёх уровнях.
До (Claude Sonnet 4.6):
client.messages.create(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[{"role": "user", "content": "..."}],
)После (Claude Sonnet 5.5):
client.messages.create(
model="claude-sonnet-5-5",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "high"}, # or "max", "xhigh", "medium", "low"
messages=[{"role": "user", "content": "..."}],
)Параметры сэмплирования возвращают ошибку. Удалите temperature, top_p и top_k.
Текст размышлений по умолчанию опускается. См. Обработка размышлений в ответах.
Другие изменения
- Примерно на 30 процентов больше токенов: Claude Sonnet 5.5 использует токенизатор Claude Sonnet 5. По сравнению с Claude Sonnet 4.6, Claude Sonnet 4.5 и Claude Haiku 4.5 тот же текст даёт примерно на 30 процентов больше токенов в зависимости от содержимого. Пересчитайте токены с помощью подсчёта токенов и пересмотрите
max_tokensи затраты. - Уровень усилий: Claude Sonnet 5.5 поддерживает
xhigh, а уровни откалиброваны заново. См. Рекомендуемые изменения. - Изображения: Claude Sonnet 5.5 использует уровень изображений высокого разрешения — до 2576 пикселей по длинной стороне и до 4784 визуальных токенов на изображение. Claude Sonnet 4.6, Claude Sonnet 4.5 и Claude Haiku 4.5 ограничены 1568 пикселями и 1568 токенами. Изображение размером 2000×1500 на Claude Sonnet 5.5 стоит примерно в 2,5 раза больше токенов. См. Разрешение и стоимость в токенах.
Миграция с Claude Sonnet 4.5 или более ранних моделей
Для Claude Sonnet 4.5, Claude Sonnet 4 или Claude 3.7 Sonnet сначала примените все предыдущие разделы, а затем следующие изменения.
Предзаполнение возвращает ошибку. Claude Sonnet 5.5 отклоняет предзаполненный последний ход ассистента с ошибкой 400, как и Claude Sonnet 4.6 и Claude Sonnet 5. Claude Sonnet 4.5, Claude Haiku 4.5 и более старые модели его принимают. Текст ошибки:
This model does not support assistant message prefill. The conversation must end with a user message.Замените каждое предзаполнение в зависимости от его назначения:
- Формат вывода: используйте структурированные выводы или инструменты с полями enum для классификации.
- Вступления: попросите в системной подсказке давать прямой ответ.
- Нежелательные отказы: обычно достаточно чётких инструкций в сообщении пользователя.
- Продолжения: перенесите их в сообщение пользователя, например: «Ваш предыдущий ответ был прерван и закончился на
[previous_response]. Продолжите с того места, где остановились». - Напоминания о контексте: поместите их в ход пользователя.
Экранирование входных данных инструментов. Экранирование в аргументах вызовов инструментов может отличаться. Разбирайте input стандартным парсером JSON.
Использование компьютера. Claude Sonnet 5.5 не принимает computer_20250124. См. Некоторые версии инструмента использования компьютера не поддерживаются.
Уровень усилий. У Claude Sonnet 4.5 нет параметра effort. Явно задайте уровень усилий (см. Рекомендуемые изменения).
Контекст и вывод. У Claude Sonnet 5.5 более крупное контекстное окно и более высокий предел вывода. См. страницу модели Claude Sonnet 5.5. Удалите все бета-заголовки контекстного окна.
Бета-заголовки. Удалите interleaved-thinking-2025-05-14, поскольку адаптивные размышления автоматически чередуются с вызовами инструментов. Замените fine-grained-tool-streaming-2025-05-14 на eager_input_streaming: true для каждого инструмента, которому это нужно. Этот заголовок возвращает ошибку 400 вместе с записью набора инструментов использования компьютера или браузера. См. Детализированная потоковая передача инструментов.
Структурированные выводы. Параметр output_format устарел. Чтобы всё же использовать его, добавьте бета-заголовок structured-outputs-2025-11-13. Без него API возвращает ошибку 400. Вместо этого используйте output_config.format.
Миграция с Claude Sonnet 4 или более ранних моделей
Claude Sonnet 4 выведена из эксплуатации в Claude API, но доступна в Claude Models on Google Cloud (Google managed) и Amazon Bedrock. Claude 3.7 Sonnet выведена из эксплуатации. При переходе с любой из этих моделей сначала примените все предыдущие разделы, а затем следующие изменения:
- Версии инструментов: Используйте
text_editor_20250728с именем инструментаstr_replace_based_edit_toolи без командыundo_edit. Используйтеcode_execution_20260521. См. инструмент текстового редактора и инструмент выполнения кода. - Причины остановки: Обрабатывайте
refusal. Claude 4.5 и более поздние модели также останавливаются сmodel_context_window_exceededпри достижении предела контекстного окна. См. Причины остановки и резервные модели. - Завершающие символы новой строки: Claude 4.5 и более поздние модели сохраняют их в строковых параметрах вызовов инструментов.
- Бета-заголовки: Удалите
token-efficient-tools-2025-02-19иoutput-128k-2025-02-19. - Подсказки: Пересмотрите их с учётом рекомендаций по составлению подсказок.
Миграция на Claude Sonnet 5.5 с Claude Haiku 4.5
Сначала примените все разделы вплоть до раздела Миграция с Claude Sonnet 4.5 или более ранних моделей включительно, пропустив подраздел о Claude Sonnet 4. Затем внесите следующие изменения:
- Идентификатор модели: Замените
claude-haiku-4-5-20251001или псевдонимclaude-haiku-4-5наclaude-sonnet-5-5. - Затраты: Цена за токен выше, а тот же текст даёт больше токенов. Пересчитайте токены и заново определите базовый уровень затрат. См. Цены.
- Кэширование подсказок: Минимальный размер кэшируемой подсказки снижается с 4096 токенов до минимума Claude Sonnet 5.5.
- Чередующиеся размышления: Адаптивные размышления автоматически выполняются между вызовами инструментов.
- Маршрутизация: Claude Sonnet 5.5 читает блоки размышлений Claude Haiku 4.5. Разговор, переходящий на более мощную модель, сохраняет свои рассуждения. Разговор, возвращающийся обратно на Claude Haiku 4.5, отбрасывает блоки Claude Sonnet 5.5.
Эта страница была полезной?