basforge

Ищем по названиям, тексту и разборам «Если не работает».

    EN

    Запрос к модели по блокам: что уходит в каждом запросе

    Модель не помнит прошлых запросов: каждый раз ей уходит всё сразу — системный промпт, описания инструментов, вся переписка и новый вопрос. Это и есть контекст. Разбираем запрос к Claude API по блокам: что значит каждое поле, сколько оно стоит в токенах и что изменилось в моделях 5.5.

    Что такое контекст

    ┌──────────────── окно контекста: 1M токенов у Claude 5.5 ────────────────┐
    │ tools     описания инструментов              сотни токенов за штуку     │
    │ system    роль, правила, постоянные материалы                           │
    │ messages  user → assistant → user → … → последний вопрос                │
    │           (+ файлы, картинки, результаты инструментов)                  │
    ├─────────────────────────────────────────────────────────────────────────┤
    │ ответ     размышления + текст ≤ max_tokens                              │
    └─────────────────────────────────────────────────────────────────────────┘

    Чат в браузере делает то же самое: собирает свой системный промпт, всю переписку и файлы проекта в один запрос. Поэтому длинный чат дорожает и тупеет («Длинный разговор»).

    Запрос по блокам

    POST https://api.anthropic.com/v1/messages
    {
      "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, ответ модели — целиком, со всеми блоками.