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

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

​

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

1. Система проверяет, кэширован ли уже префикс промпта до указанной точки разрыва кэша из недавнего запроса.
2. Если найден, она использует кэшированную версию, сокращая время обработки и затраты.
3. В противном случае она обрабатывает полный промпт и кэширует префикс после начала ответа.

• Промптов с множеством примеров
• Больших объёмов контекста или справочной информации
• Повторяющихся задач с постоянными инструкциями
• Длительных многооборотных разговоров

​

Ценообразование

​

Как реализовать кэширование промптов

​

Поддерживаемые модели

• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4.5
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Haiku 4.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3 (устарела)

​

Структурирование вашего промпта

​

Как работает автоматическая проверка префикса

• Когда вы добавляете точку разрыва cache_control, система автоматически проверяет наличие попаданий в кэш на всех предыдущих границах блоков содержимого (примерно до 20 блоков перед вашей явной точкой разрыва)
• Если какие-либо из этих предыдущих позиций совпадают с кэшированным содержимым из более ранних запросов, система использует самый длинный совпадающий префикс
• Это означает, что вам не нужны несколько точек разрыва просто для включения кэширования — одной в конце достаточно

​

Когда использовать несколько точек разрыва

• Кэшировать различные разделы, которые изменяются с разной частотой (например, инструменты редко меняются, но контекст обновляется ежедневно)
• Иметь больше контроля над тем, что именно кэшируется
• Обеспечить кэширование содержимого более чем на 20 блоков перед вашей финальной точкой разрыва

​

Ограничения кэша

• 1024 токена для Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (устарела) и Claude Opus 3 (устарела)
• 4096 токенов для Claude Haiku 4.5
• 2048 токенов для Claude Haiku 3.5 и Claude Haiku 3

​

Понимание затрат на точки разрыва кэша

• Записи в кэш: Когда новое содержимое записывается в кэш (на 25% больше, чем базовые входные токены для TTL 5 минут)
• Чтения из кэша: Когда используется кэшированное содержимое (10% от базовой цены входных токенов)
• Обычные входные токены: Для любого некэшированного содержимого

​

Что может быть кэшировано

• Инструменты: Определения инструментов в массиве tools
• Системные сообщения: Блоки содержимого в массиве system
• Текстовые сообщения: Блоки содержимого в messages.content, для обоих пользовательских и ассистентских ходов
• Изображения и документы: Блоки содержимого в messages.content, в пользовательских ходах
• Использование инструментов и результаты инструментов: Блоки содержимого в messages.content, в обоих пользовательских и ассистентских ходах

​

Что не может быть кэшировано

• Блоки мышления не могут быть кэшированы напрямую с помощью cache_control. Однако блоки мышления МОГУТ быть кэшированы вместе с другим содержимым, когда они появляются в предыдущих ассистентских ходах. При кэшировании таким образом они СЧИТАЮТСЯ входными токенами при чтении из кэша.
• Подблоки содержимого (такие как цитаты) сами по себе не могут быть кэшированы напрямую. Вместо этого кэшируйте блок верхнего уровня. В случае цитат блоки содержимого документа верхнего уровня, которые служат исходным материалом для цитат, могут быть кэшированы. Это позволяет вам эффективно использовать кэширование промптов с цитатами, кэшируя документы, на которые будут ссылаться цитаты.
• Пустые текстовые блоки не могут быть кэшированы.

​

Что делает кэш недействительным

​

Отслеживание производительности кэша

• cache_creation_input_tokens: Количество токенов, записанных в кэш при создании новой записи.
• cache_read_input_tokens: Количество токенов, полученных из кэша для этого запроса.
• input_tokens: Количество входных токенов, которые не были прочитаны из кэша или использованы для создания кэша.

​

Лучшие практики для эффективного кэширования

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

​

Оптимизация для различных вариантов использования

• Агенты диалога: Снизьте затраты и задержку для расширенных разговоров, особенно тех, которые содержат длинные инструкции или загруженные документы.
• Помощники по кодированию: Улучшите автодополнение и вопросы и ответы по кодовой базе, сохраняя релевантные разделы или сводную версию кодовой базы в промпте.
• Обработка больших документов: Включите полный долгоформатный материал, включая изображения, в ваш промпт без увеличения задержки ответа.
• Подробные наборы инструкций: Поделитесь обширными списками инструкций, процедур и примеров для точной настройки ответов Claude. Разработчики часто включают один или два примера в промпт, но с кэшированием промптов вы можете получить ещё лучшую производительность, включив 20+ разнообразных примеров высокого качества ответов.
• Использование инструментов агентом: Улучшите производительность для сценариев, включающих несколько вызовов инструментов и итеративные изменения кода, где каждый шаг обычно требует нового вызова API.
• Разговор с книгами, статьями, документацией, транскриптами подкастов и другим долгоформатным содержимым: Оживите любую базу знаний, встроив весь документ(ы) в промпт и позволив пользователям задавать ему вопросы.

​

Устранение неполадок с распространёнными проблемами

• Убедитесь, что кэшированные разделы идентичны и отмечены с помощью cache_control в одних и тех же местах во всех вызовах
• Проверьте, что вызовы выполняются в течение времени жизни кэша (5 минут по умолчанию)
• Убедитесь, что tool_choice и использование изображений остаются постоянными между вызовами
• Проверьте, что вы кэшируете по крайней мере минимальное количество токенов
• Система автоматически проверяет наличие попаданий в кэш на предыдущих границах блоков содержимого (примерно до 20 блоков перед вашей точкой разрыва). Для промптов с более чем 20 блоками содержимого вам может потребоваться дополнительные параметры cache_control ранее в промпте, чтобы обеспечить кэширование всего содержимого
• Убедитесь, что ключи в ваших блоках содержимого tool_use имеют стабильный порядок, так как некоторые языки (например, Swift, Go) рандомизируют порядок ключей при преобразовании JSON, нарушая кэши

​

Кэширование с блоками мышления

• Кэш остаётся действительным, когда в качестве пользовательских сообщений предоставляются только результаты инструментов
• Кэш становится недействительным, когда добавляется содержимое пользовательского сообщения, не связанное с результатом инструмента, что приводит к удалению всех предыдущих блоков мышления
• Это поведение кэширования происходит даже без явных маркеров cache_control

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never present

​

Хранилище кэша и совместное использование

• Изоляция организации: Кэши изолированы между организациями. Различные организации никогда не делят кэши, даже если они используют идентичные промпты.
• Точное совпадение: Попадания в кэш требуют 100% идентичных сегментов промпта, включая весь текст и изображения вплоть до и включая блок, отмеченный с помощью управления кэшем.
• Генерация выходных токенов: Кэширование промптов не влияет на генерацию выходных токенов. Ответ, который вы получите, будет идентичен тому, что вы получили бы, если бы кэширование промптов не использовалось.

​

Длительность кэша в 1 час

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,

        "cache_creation": {
            "ephemeral_5m_input_tokens": 456,
            "ephemeral_1h_input_tokens": 100,
        }
    }
}

​

Когда использовать кэш на 1 час

• Когда у вас есть промпты, которые, вероятно, используются реже, чем каждые 5 минут, но чаще, чем каждый час. Например, когда побочный агент агента будет работать дольше 5 минут, или когда вы сохраняете длительный чат с пользователем и обычно ожидаете, что пользователь может не ответить в течение следующих 5 минут.
• Когда задержка важна и ваши последующие промпты могут быть отправлены за пределами 5 минут.
• Когда вы хотите улучшить использование вашего лимита скорости, так как попадания в кэш не вычитаются из вашего лимита скорости.

​

Смешивание различных TTL

1. Позиция A: Количество токенов при самом высоком попадании в кэш (или 0, если нет попаданий).
2. Позиция B: Количество токенов при самом высоком блоке cache_control на 1 час после A (или равно A, если таких нет).
3. Позиция C: Количество токенов при последнем блоке cache_control.

1. Токены чтения из кэша для A.
2. Токены записи в кэш на 1 час для (B - A).
3. Токены записи в кэш на 5 минут для (C - B).

​

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

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing legal documents."
        },
        {
            "type": "text",
            "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What are the key terms and conditions in this agreement?"
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either celsius or fahrenheit"
                    }
                },
                "required": ["location"]
            }
        },
        # many more tools
        {
            "name": "get_time",
            "description": "Get the current time in a given time zone",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "The IANA time zone name, e.g. America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather and time in New York?"
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, can you tell me more about the solar system?",
                }
            ]
        },
        {
            "role": "assistant",
            "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Good to know."
                },
                {
                    "type": "text",
                    "text": "Tell me more about Mars.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "search_documents",
            "description": "Search through the knowledge base",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Search query"
                    }
                },
                "required": ["query"]
            }
        },
        {
            "name": "get_document",
            "description": "Retrieve a specific document by ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {
                        "type": "string",
                        "description": "Document ID"
                    }
                },
                "required": ["doc_id"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "system": [
        {
            "type": "text",
            "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
            "cache_control": {"type": "ephemeral"}
        },
        {
            "type": "text",
            "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Can you search for information about Mars rovers?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "Mars rovers"}
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Yes, please tell me about the Perseverance rover specifically.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

​

Часто задаваемые вопросы

python client.beta.prompt_caching.messages.create(...)

python client.messages.create(...)

client.beta.promptCaching.messages.create(...)

client.messages.create(...)