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

В этом руководстве описан перенос кода, который вызывает Claude Haiku 4.5, на Claude Haiku 5.5. Если ваш код вызывает Claude Haiku 3.5 или Claude Haiku 3, также внесите изменения из раздела Миграция на Claude Haiku 5.5 с Claude Haiku 3.5 и более ранних моделей Haiku. Чтобы вместо этого перейти на модель Sonnet или Opus, см. Обновление между версиями моделей. О том, как долго Claude Haiku 4.5 остаётся доступной, см. Устаревание моделей.

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

Проходите группы сверху вниз и остановитесь после той, в которой указана ваша текущая модель. Если вы используете Claude Haiku 4.5, первая группа — это весь список. Каждый пункт — одно изменение, которое нужно внести в ваш код.

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

1. Замените идентификатор модели на идентификатор Claude Haiku 5.5 для вашей платформы. См. Используйте идентификатор модели Claude Haiku 5.5.
2. Пересчитайте токены в ваших подсказках и пересмотрите ограничения max_tokens и оценки стоимости, поскольку тот же текст даёт больше токенов, а большие изображения — больше визуальных токенов. См. Пересчитайте токены.
3. Если ваши запросы отправляют thinking: {"type": "enabled", "budget_tokens": N}, измените thinking на {"type": "adaptive"}. См. Настройте размышления.
4. Если ваш код считывает первый блок содержимого как ответ, выбирайте блоки по type. См. Настройте размышления.
5. Удалите temperature, top_p и top_k из ваших запросов. См. Удалите параметры сэмплирования.
6. Если ваши запросы завершают messages ходом ассистента, который модель должна продолжить, завершайте их ходом пользователя. См. Замените предзаполнение ответа ассистента.
7. Если вы используете инструмент использования компьютера, замените computer_20250124: в Claude API и Google Cloud — на набор инструментов computer_toolset_20260801; в Amazon Bedrock — на computer_20251124 с бета-заголовком computer-use-2025-11-24. См. Перенесите использование компьютера на набор инструментов.
8. Если вы воспроизводите сохранённые разговоры через другой аккаунт, воспроизводите каждый из них через аккаунт, который его создал. См. Воспроизводите блоки размышлений через аккаунт, который их создал.
9. Если ваш код изменяет system, tools или более ранние messages между запросами в рамках разговора и отправляет блоки размышлений обратно, сохраняйте разговор в режиме только добавления. См. Не изменяйте предыдущие ходы.
10. Обрабатывайте stop_reason: "refusal". Claude Haiku 5.5 использует классификаторы безопасности, которые могут отклонить запрос, и у неё нет серверной резервной обработки. См. Защитные отказы.
11. Если вы используете структурированные выходные данные (output_config.format или инструменты с strict: true) в Amazon Bedrock, опишите формат в подсказке или используйте инструмент без strict и проверяйте выходные данные в своём коде. Структурированные выходные данные недоступны для Claude Haiku 5.5 в Amazon Bedrock.

Если у вашей организации есть обязательство Priority Tier для Claude Haiku 4.5, планируйте мощности отдельно: Priority Tier не поддерживается для Claude Haiku 5.5.

Claude Haiku 3.5 или более ранние

1. Замените идентификатор модели Claude Haiku 3.5 или Claude Haiku 3 на идентификатор Claude Haiku 5.5 для вашей платформы. См. Миграция на Claude Haiku 5.5 с Claude Haiku 3.5 и более ранних моделей Haiku.
2. Если вы используете устаревший инструмент code_execution_20250522, перейдите на code_execution_20250825 или более позднюю версию.
3. Если вы используете инструмент текстового редактора, перейдите на text_editor_20250728.
4. Обрабатывайте причины остановки refusal и model_context_window_exceeded.
5. Если ваш код проверяет строковые параметры вызовов инструментов на точное совпадение, учитывайте завершающие символы новой строки.
6. Пересмотрите ваши подсказки.

Используйте идентификатор модели Claude Haiku 5.5

Замените идентификатор модели Claude Haiku 4.5 на идентификатор Claude Haiku 5.5 для вашей платформы.

claude-haiku-5-5 — это фиксированный идентификатор модели без суффикса даты и без отдельного псевдонима.

Пересчитайте токены

Claude Haiku 5.5 использует тот же более новый «tokenizer» (токенизатор), что и Claude 4.7 и более поздние модели. Как и у всех моделей, использующих этот токенизатор, один и тот же входной текст даёт в Claude Haiku 5.5 примерно на 30% больше токенов, чем в Claude Haiku 4.5. Точное увеличение зависит от содержимого. Запросы, ответы и события «streaming» (потоковой передачи) сохраняют ту же структуру. Меняется всё, что вы измеряете или планируете в токенах:

• Поля usage и результаты подсчёта токенов выше для того же текста.
• Заданное количество токенов вмещает меньше текста.
• Ограничение max_tokens, настроенное для Claude Haiku 4.5, может обрезать эквивалентный вывод.
• Оценки стоимости, сделанные по количеству токенов Claude Haiku 4.5, нужно пересчитать с учётом количества токенов Claude Haiku 5.5 и её цен, включая более высокие цены для длинных подсказок. См. Цены на длинный контекст.

Большие изображения также могут стоить больше токенов. Claude Haiku 5.5 использует уровень изображений высокого разрешения, который уменьшает изображения больше 2 576 пикселей по длинной стороне или 4 784 визуальных токенов. Claude Haiku 4.5 и более ранние модели Haiku используют стандартный уровень, который уменьшает изображения больше 1 568 пикселей по длинной стороне или 1 568 визуальных токенов. Изображение размером 2 000 на 1 500 пикселей стоит на Claude Haiku 5.5 примерно в 2,5 раза больше визуальных токенов, чем на Claude Haiku 4.5. См. Разрешение и стоимость в токенах.

Подсчитывайте токены в ваших подсказках, указав model равным claude-haiku-5-5, а не используйте повторно значения, измеренные на Claude Haiku 4.5.

Настройте размышления

Claude Haiku 5.5 настраивает «thinking» (размышления) иначе, чем Claude Haiku 4.5. Значение thinking, равное {"type": "enabled", "budget_tokens": N}, возвращает ошибку 400, поэтому запросу, который его отправляет, нужно новое значение thinking.

Раньше запрос к Claude Haiku 4.5 устанавливал thinking в enabled с бюджетом токенов:

{
  "model": "claude-haiku-4-5",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{ "role": "user", "content": "..." }]
}

Теперь тот же запрос к Claude Haiku 5.5 использует «adaptive thinking» (адаптивные размышления). Значение thinking меняется, а output_config.effort задаёт, насколько много модель размышляет:

{
  "model": "claude-haiku-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

Адаптивные размышления включены по умолчанию, поэтому ответ может начинаться с одного или нескольких блоков thinking, даже если запрос не задаёт thinking. Оставьте thinking незаданным или установите его в {"type": "adaptive"} и используйте effort (уровень усилий) в качестве рычага управления: там, где Claude Haiku 4.5 работала без размышлений или с небольшим бюджетом для экономии токенов, выберите более низкий уровень усилий. На более низком уровне модель размышляет меньше и может полностью пропускать размышления для более простых запросов. Рекомендации по составлению подсказок см. в разделе Используйте effort для управления размышлениями. Выбирайте блоки содержимого по их полю type, а не по позиции, и передавайте блоки thinking обратно без изменений вместе с результатами инструментов.

Токены размышлений учитываются в max_tokens, поэтому запрос с небольшим max_tokens может остановиться с stop_reason: "max_tokens" после блока thinking и до какого-либо текста. Если вы задавали небольшое значение max_tokens для Claude Haiku 4.5, увеличьте его, чтобы оставить место для размышлений, или выберите более низкий уровень effort.

Блоки размышлений из предыдущих ходов ассистента остаются в контексте и учитываются как входные токены, тогда как Claude Haiku 4.5 сохраняла только блоки последнего хода. Поэтому многоходовые разговоры содержат больше входных токенов, чем объясняется одним лишь изменением токенизатора. Чтобы удалить старые блоки, используйте очистку блоков размышлений. См. Сохранение блоков размышлений по моделям.

По умолчанию Claude Haiku 5.5 возвращает каждый блок thinking с пустым полем thinking и только с signature, тогда как Claude Haiku 4.5 возвращала сводку размышлений. Чтобы получать сводку размышлений, установите thinking: {"type": "adaptive", "display": "summarized"}.

Claude Haiku 5.5 принимает принудительный tool_choice (any или инструмент, указанный по имени), но ответ начинается с вызова инструмента и не содержит блока thinking. Чтобы позволить модели поразмышлять перед вызовом инструмента, используйте tool_choice: {"type": "auto"} и укажите в подсказке, когда следует использовать инструмент.

Claude Haiku 5.5 читает блоки размышлений от Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 и более ранних моделей, поэтому разговор, который вы переключаете с Claude Haiku 4.5 на Claude Haiku 5.5, сохраняет свои рассуждения. Она не читает блоки от Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5 или любой модели Claude Fable или Claude Mythos; API отбрасывает их без ошибки. В Claude API и Google Cloud модели Claude Opus 5.5 и Claude Sonnet 5.5 читают блоки Claude Haiku 5.5. См. Переключение моделей посреди разговора.

Удалите параметры сэмплирования

Claude Haiku 4.5 принимает temperature, top_p и top_k. В Claude Haiku 5.5 не указывайте ни один из этих трёх параметров и вместо этого управляйте поведением модели с помощью подсказок. Если запрос включает temperature, его значение должно быть 1. Если он включает top_p, его значение должно быть 0.99 — значение по умолчанию. Любое другое значение temperature или top_p возвращает ошибку 400, включая top_p, равное 1. То же самое происходит при любом значении top_k, а также для запроса, который включает одновременно temperature и top_p.

Замените предзаполнение ответа ассистента

«Prefill» (предзаполнение) — это завершающий ход ассистента в messages, который модель продолжает. Claude Haiku 4.5 принимает его, когда размышления отключены. Claude Haiku 5.5 отклоняет его с ошибкой 400, даже если размышления отключены. Завершайте messages ходом пользователя и заменяйте каждое предзаполнение в зависимости от его назначения:

• Формат вывода: используйте структурированные выходные данные или инструменты с полями enum для классификации. В Amazon Bedrock структурированные выходные данные недоступны для Claude Haiku 5.5. Там опишите формат в подсказке или используйте инструмент без strict и проверяйте выходные данные в своём коде.
• Вступления: попросите в системной подсказке давать прямой ответ.
• Продолжения: перенесите их в сообщение пользователя, например: «Ваш предыдущий ответ был прерван и закончился на [previous_response]. Продолжите с того места, где остановились».
• Напоминания о контексте: поместите их в ход пользователя.

Перенесите использование компьютера на набор инструментов

Claude Haiku 4.5 поддерживает «computer use» (использование компьютера) через инструмент computer_20250124 с бета-заголовком computer-use-2025-01-24. В Claude API и Google Cloud Claude Haiku 5.5 поддерживает использование компьютера только через набор инструментов computer_toolset_20260801, а запрос, объявляющий computer_20250124, возвращает ошибку 400. В Amazon Bedrock Claude Haiku 5.5 также не принимает computer_20250124; используйте версию инструмента computer_20251124 с бета-заголовком computer-use-2025-11-24.

Чтобы перенести интеграцию на набор инструментов, уберите бета-заголовок computer-use-2025-01-24 и замените запись в tools на {"type": "computer_toolset_20260801"}. Затем внесите остальные изменения в запрос и цикл агента, описанные в разделе Миграция с computer_20251124: выполняйте диспетчеризацию по name и toolset_name каждого блока tool_use участника набора, а не по input.action, обрабатывайте каждый такой блок в ходе и возвращайте toolset_name в результатах. Масштабирование в наборе инструментов включено по умолчанию; если ваша среда его не реализует, добавьте "configs": {"zoom": {"enabled": false}}. Если вы отправляете бета-заголовок fine-grained-tool-streaming-2025-05-14, удалите его. Вместе с записью набора инструментов он возвращает ошибку 400. Сведения о других платформах см. в разделе Совместимость инструмента использования компьютера.

В Claude API и Google Cloud Claude Haiku 5.5 также поддерживает инструмент использования браузера (browser_toolset_20260801) для задач внутри веб-страниц. Claude Haiku 4.5 его не поддерживает.

Воспроизводите блоки размышлений через аккаунт, который их создал

Блоки размышлений от Claude Haiku 5.5 работают только в аккаунте, который их создал, или в связанном с ним аккаунте. Когда другой аккаунт отправляет один из таких блоков, API отбрасывает блок до того, как его увидит модель, и запрос выполняется успешно без этих рассуждений. Это затрагивает код, который сохраняет разговоры и воспроизводит их через другой аккаунт, например сервис, обслуживающий нескольких клиентов из одного хранилища разговоров. Воспроизводите каждый разговор через аккаунт, который его создал. См. Блоки размышлений остаются в аккаунте, который их создал.

Не изменяйте предыдущие ходы

Блок размышлений Claude Haiku 5.5 остаётся действительным только до тех пор, пока всё, что было отправлено до него, остаётся неизменным: запрос, который отправляет блок размышлений обратно после изменения system, tools или более ранних messages, возвращает ошибку 400. Claude Haiku 4.5 такую проверку не выполняет. Сохраняйте разговоры в режиме только добавления. Для аккаунтов, созданных до 31 августа 2026 года, 00:00 UTC, ошибка возникает только в запросах, которые задают thinking.block_binding.prefix_mismatch_behavior. Об изменениях, вызывающих ошибку, и о том, что делать вместо них, см. Кому нужно что-то менять.

Миграция на Claude Haiku 5.5 с Claude Haiku 3.5 и более ранних моделей Haiku

Claude Haiku 3.5 выведена из эксплуатации в Claude API и Amazon Bedrock, а Claude Haiku 3 — в Claude API и Google Cloud. Запросы к выведенной из эксплуатации модели завершаются ошибкой. Google Cloud указывает Claude Haiku 3.5 как устаревшую и доступную только существующим клиентам. См. Устаревание моделей.

С любой из этих моделей сначала примените все предыдущие разделы, а затем следующие изменения:

• Идентификатор модели: замените claude-3-5-haiku-20241022, его псевдоним claude-3-5-haiku-latest или claude-3-haiku-20240307 на claude-haiku-5-5. В Google Cloud замените claude-3-5-haiku@20241022 на claude-haiku-5-5. В Amazon Bedrock используйте идентификатор Claude Haiku 5.5 из раздела Используйте идентификатор модели Claude Haiku 5.5.
• Выполнение кода: Claude Haiku 5.5 принимает code_execution_20250825 и более поздние версии. Если вы используете устаревший code_execution_20250522, поддерживающий только Python, перейдите на одну из них. См. Обновление до последней версии инструмента.
• Текстовый редактор: если вы используете инструмент текстового редактора, перейдите на text_editor_20250728 (имя инструмента str_replace_based_edit_tool), в котором нет команды undo_edit. См. Инструмент текстового редактора.
• Причины остановки: обрабатывайте refusal и model_context_window_exceeded. См. Обработка причин остановки.
• Завершающие символы новой строки: Claude 4.5 и более поздние модели сохраняют завершающие символы новой строки в строковых параметрах вызовов инструментов. Если ваш код проверяет эти строки на точное совпадение, учитывайте их.
• Подсказки: Claude 4 и более поздние модели имеют более лаконичный и прямой стиль общения и нуждаются в явных указаниях. Пересмотрите ваши подсказки с учётом материалов Составление подсказок для Claude Haiku 5.5 и лучших практик составления подсказок.