Разработка с Claude API

Введение: Оптимизация запросов с помощью кэширования промптов в Claude API

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

Именно здесь на помощь приходит Prompt caching — мощная функция оптимизации, разработанная для ускорения и удешевления ваших API-запросов при повторной отправке идентичного контента. Она позволяет избежать повторной обработки уже знакомых данных, значительно повышая производительность и снижая расходы. Ключевая идея заключается в том, что кэширование эффективно только в том случае, если вы многократно отправляете идентичный контент, но во многих реальных приложениях это происходит чрезвычайно часто.

Как работает кэширование промптов

Когда вы включаете кэширование промптов, первый запрос, содержащий кэшируемый контент, записывает его в специальный кэш. Этот кэш является "эпизодическим" (ephemeral) и живет в течение одного часа. Все последующие запросы, которые отправляют точно такой же контент в течение этого часа, могут читать данные из кэша вместо того, чтобы Claude обрабатывал их заново. Это особенно ценно, когда вы отправляете:

• Крупные системные промпты (например, промпт для помощника по кодированию объемом в 6K token'ов).
• Сложные схемы инструментов (около 1.7K token'ов для нескольких инструментов).
• Повторяющийся контент сообщений, который не меняется между запросами.

Механизм кэширования работает на уровне компонентов запроса, позволяя вам выборочно кэшировать части, которые остаются неизменными.

Настройка кэширования для схем инструментов (Tool Schemas)

Схемы инструментов (tool schemas) часто бывают сложными и объемными, но при этом стабильными в рамках одной сессии или функции приложения. Кэширование этих схем может значительно сократить количество обрабатываемых token'ов. Чтобы кэшировать ваши схемы инструментов, вам необходимо добавить поле cache_control к последнему инструменту в вашем списке. Важно сделать это таким образом, чтобы не модифицировать исходные определения инструментов, особенно если они используются в других частях вашего кода.

Вот рекомендуемый способ реализации:

if tools:
    tools_clone = tools.copy()
    last_tool = tools_clone[-1].copy()
    last_tool["cache_control"] = {"type": "ephemeral"}
    tools_clone[-1] = last_tool
    params["tools"] = tools_clone

Этот подход создает копии как самого списка инструментов (tools_clone), так и последнего инструмента в этом списке (last_tool) перед добавлением поля cache_control. Хотя технически вы могли бы напрямую изменить tools[-1]["cache_control"], копирование предотвращает потенциальные проблемы, если вы позже измените порядок инструментов или используете исходный список в другом контексте. Таким образом, вы обеспечиваете чистоту и предсказуемость вашего кода.

Кэширование системных промптов (System Prompts)

Системные промпты (system prompts) часто содержат инструкции, контекст или персону, которые остаются неизменными на протяжении множества взаимодействий. Кэширование системного промпта работает аналогично кэшированию схем инструментов. Вместо того чтобы передавать системный промпт как простую строку, его необходимо структурировать как текстовый блок с полем cache_control.

Пример того, как это сделать:

if system:
    params["system"] = [
        {
            "type": "text",
            "text": system,
            "cache_control": {"type": "ephemeral"}
        }
    ]

Этот код преобразует ваш системный промпт из обычной строки в структурированный формат, который поддерживает функциональность кэширования. Это позволяет Claude API распознавать и кэшировать этот конкретный системный промпт, если он не меняется между запросами.

Понимание поведения кэша и метрик

Когда вы выполняете запросы с включенным кэшированием, вы увидите различные паттерны использования token'ов в ответе API, которые помогут вам понять, как работает кэш. Эти метрики предоставляют прозрачность и позволяют убедиться, что кэширование работает так, как ожидалось:

• Если Claude впервые записывает контент в кэш, вы увидите метрику, похожую на cache_creation_input_tokens=1772. Это указывает на количество token'ов, которые были обработаны и записаны в кэш.
• При последующих запросах, если Claude успешно читает контент из кэша, вы увидите метрику cache_read_input_tokens=1772. Это означает, что эти token'ы были прочитаны из кэша и не потребовали повторной обработки, что экономит время и деньги.
• Если вы измените контент, который ранее был кэширован, даже на один символ, кэш для этого компонента будет считаться недействительным. В этом случае вы снова увидите метрику cache_creation_input_tokens, так как Claude будет создавать новый кэш для измененного контента.

Важно помнить, что кэш чрезвычайно чувствителен: изменение даже одного символа в ваших инструментах или системном промпте аннулирует весь кэш для этого конкретного компонента. Это гарантирует, что Claude всегда работает с актуальной информацией.

Порядок кэширования и точки останова

Вы можете установить несколько точек останова кэша в одном запросе, что позволяет кэшировать различные компоненты независимо. Порядок, в котором Claude обрабатывает эти компоненты для кэширования, имеет значение:

1. Инструменты (tools), если они предоставлены.
2. Системный промпт (system prompt), если он предоставлен.

Эта гранулярность кэширования означает, что вы платите только за обработку тех частей запроса, которые фактически изменились. Например, если вы меняете свой системный промпт, но сохраняете те же самые инструменты, вы увидите частичное чтение из кэша для инструментов (cache_read_input_tokens) и новую запись в кэш для системного промпта (cache_creation_input_tokens). Это позволяет максимально эффективно использовать ресурсы и оптимизировать затраты.

Практические рекомендации по использованию кэширования

Чтобы максимально эффективно использовать кэширование промптов, учитывайте следующие практические соображения:

• Последовательные схемы инструментов: Кэширование наиболее эффективно, когда ваши схемы инструментов остаются неизменными на протяжении множества запросов. Если схемы часто меняются, вы не получите значительной выгоды от кэширования.
• Стабильные системные промпты: Аналогично, системные промпты, которые не меняются между запросами, являются идеальными кандидатами для кэширования.
• Приложения с множественными запросами и схожим контекстом: Кэширование идеально подходит для приложений, которые делают много запросов с повторяющимся или очень похожим контекстом, например, чат-боты, которые поддерживают одну и ту же "персону" или набор инструментов на протяжении всей сессии пользователя.

Помните, что кэш живет всего один час. Это означает, что он разработан для приложений с относительно частым использованием API, а не для долгосрочного хранения данных. Он служит для оптимизации текущих рабочих процессов и снижения накладных расходов на повторяющиеся операции, а не для постоянного хранения информации. Интегрируя кэширование промптов в свою стратегию разработки, вы можете значительно улучшить производительность и экономичность ваших приложений, работающих с Claude API.