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

В этом руководстве описан перенос кода, который вызывает Claude Haiku 4.5, на Claude Haiku 5.5. Чтобы вместо этого перейти на модель 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. Если вы используете инструмент использования компьютера в Claude API или Google Cloud, перейдите с computer_20250124 на набор инструментов computer_toolset_20260801. См. Перенесите использование компьютера на набор инструментов.
8. Если вы воспроизводите сохранённые разговоры через другой аккаунт, воспроизводите каждый из них через аккаунт, который его создал. См. Воспроизводите блоки размышлений через аккаунт, который их создал.
9. Если ваш код изменяет system, tools или более ранние messages между запросами в рамках разговора и отправляет блоки размышлений обратно, сохраняйте разговор в режиме только добавления. См. Не изменяйте предыдущие ходы.
10. Обрабатывайте stop_reason: "refusal". Claude Haiku 5.5 использует классификаторы безопасности, которые могут отклонить запрос, и у неё нет серверной резервной обработки. См. Защитные отказы.

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

Используйте идентификатор модели 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.

Подсчитывайте токены в ваших подсказках, указав 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 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 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 для классификации. В Claude в Amazon Bedrock, где структурированные выходные данные не поддерживаются, используйте инструменты.
• Вступления: попросите в системной подсказке давать прямой ответ.
• Продолжения: перенесите их в сообщение пользователя, например: «Ваш предыдущий ответ был прерван и закончился на [previous_response]. Продолжите с того места, где остановились».
• Напоминания о контексте: поместите их в ход пользователя.

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

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

Чтобы перенести интеграцию, уберите бета-заголовок 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. Об изменениях, вызывающих ошибку, и о том, что делать вместо них, см. Кому нужно что-то менять.