Что такое контекст
┌──────────────── окно контекста: 1M токенов у Claude 5.5 ────────────────┐
│ tools описания инструментов сотни токенов за штуку │
│ system роль, правила, постоянные материалы │
│ messages user → assistant → user → … → последний вопрос │
│ (+ файлы, картинки, результаты инструментов) │
├─────────────────────────────────────────────────────────────────────────┤
│ ответ размышления + текст ≤ max_tokens │
└─────────────────────────────────────────────────────────────────────────┘
Чат в браузере делает то же самое: собирает свой системный промпт, всю переписку и файлы проекта в один запрос. Поэтому длинный чат дорожает и тупеет («Длинный разговор»).
Запрос по блокам
{
"model": "claude-sonnet-5-5",
"max_tokens": 16000,Модель и потолок ответа. max_tokens обязателен: дошли до него — ответ обрывается, stop_reason будет max_tokens. Модель о потолке не знает и не подстраивается. Для ответа без потока ставим около 16 000, с потоком — до 64 000; до 128K — только потоком, иначе запрос упрётся в таймаут HTTP.
"output_config": { "effort": "medium" },Глубина размышлений. У моделей 5.5 размышление включено по умолчанию; effort от low до max решает, сколько модель думает и сколько токенов тратит. Размышления — выходные токены по цене выхода. По умолчанию текст размышлений не возвращается (display: omitted), но оплачивается.
по умолчанию:effort high у Sonnet 5.5, medium у Opus 5.5 и Haiku 5.5
"system": [
{
"type": "text",
"text": "Конфиги серверов: Ubuntu 24.04, Traefik 3.7. Команды — с откатом.",
"cache_control": { "type": "ephemeral" }
}
],Системный промпт: кто модель здесь, правила, постоянные материалы. Читается первым, и правила отсюда модель ставит выше просьб в переписке. Меняется редко — поэтому ставим метку кэша: следующие запросы с тем же началом читают его в 10 раз дешевле («Кэш промпта»). Любой изменившийся байт — дата, счётчик — сбрасывает кэш всего, что после него.
"tools": [
{
"name": "read_file",
"description": "Читает файл из репозитория конфигов",
"input_schema": {
"type": "object",
"properties": { "path": { "type": "string" } },
"required": ["path"]
}
}
],Инструменты: имя, описание и JSON-схема входа. Описание — тоже текст в контексте, за него платим на каждом запросе. Двадцать инструментов — несколько тысяч токенов ещё до вопроса. Как модель их вызывает — «Агенты и инструменты».
"messages": [
{ "role": "user", "content": "Почему 404 на memos?" },
{ "role": "assistant", "content": [
{ "type": "text", "text": "Нужны лейблы контейнера" }
] },История. API ничего не хранит: каждый запрос несёт все прошлые реплики. Роли чередуются, первая — user. Ответ модели возвращаем целиком, со всеми блоками (thinking, tool_use), а не только текст — иначе теряется размышление и вызовы инструментов.
{
"role": "user",
"content": [
{ "type": "text", "text": "<labels>…</labels>" },
{ "type": "text", "text": "Вот лейблы. Где ошибка?" }
]
}
]
}Новый вопрос. Длинный материал — сначала, вопрос — в конце: так модель отвечает точнее («Длинный документ — в начало»). Файлы и картинки — отдельными блоками того же сообщения.
"temperature": 0,
"top_p": 0.9,Случайность выбора токена. На Claude Opus 4.7 и новее эти поля убраны — запрос с ними получает 400; на Sonnet 5.5 принимается только значение по умолчанию. У других вендоров и локальных моделей живут: 0 — почти всегда самый вероятный токен, 1 — обычный разброс.
{ "role": "assistant", "content": "{" }Предзаполнение: последнее сообщение от assistant, чтобы модель продолжила с {. Старый способ получить JSON. На моделях 4.6 и новее — 400; вместо него — структурированный вывод output_config.format («JSON по схеме»).
Что приходит в ответ
{
"id": "msg_…",
"model": "claude-sonnet-5-5",
"content": [
{ "type": "thinking", "thinking": "", "signature": "…" },
{ "type": "text", "text": "У роутера нет `entrypoints`…" }
],
"stop_reason": "end_turn",
"usage": { "input_tokens": 412, "cache_read_input_tokens": 1830, "output_tokens": 690 }
}
content — список блоков, и первым часто идёт thinking с пустым текстом. Текст ответа берём фильтром
по типу, а не content[0]: jq -r '.content[] | select(.type == "text") | .text'.
stop_reason |
Что случилось | Что делаем |
|---|---|---|
end_turn |
модель закончила сама | ничего |
max_tokens |
упёрлись в потолок, ответ оборван | поднимаем max_tokens, длинное — потоком |
tool_use |
модель хочет вызвать инструмент | выполняем, результат — в следующем сообщении user («Агенты и инструменты») |
stop_sequence |
встретилась заданная строка остановки | ничего, так задумано |
pause_turn |
длинный ход на серверных инструментах прерван | отправляем запрос ещё раз, продолжит |
refusal |
отказ по правилам безопасности | смотрим stop_details.category, переформулируем или берём запасную модель |
Если не работает
400 с упоминанием temperature после перехода на новую модель
- Причина
- На Claude Opus 4.7 и новее
temperature,top_pиtop_kубраны, на Sonnet 5.5 принимается только значение по умолчанию. - Делаем
- Удаляем параметры из запроса; разброс ответов гасим форматом и проверками («Повторяемый ответ»).
400 на запросе, который заканчивается сообщением assistant
- Причина
- Предзаполнение ответа (prefill) на моделях 4.6 и новее отключено.
- Делаем
- Формат задаём структурированным выводом
output_config.format(«JSON по схеме») или инструкцией вsystem.
400 с thinking: {type: "disabled"} на Opus 5.5
- Причина
- У Opus 5.5 размышление не выключается ни на каком уровне
effort. - Делаем
- Убираем
thinkingи ставимeffort: "low"(«Размышление — под задачу»).
Модель «не видит» предыдущий ответ
- Причина
- Программа отправила только последний вопрос: API не хранит историю, её присылает клиент.
- Делаем
- Добавляем в
messagesвсе прошлые парыuserиassistant, ответ модели — целиком, со всеми блоками.