---
title: Кэширование подсказок
url: https://platform.claude.com/docs/ru/build-with-claude/prompt-caching
description: Кэшируйте префиксы подсказок с помощью `cache_control`, чтобы снизить затраты и задержку, используя автоматическое кэширование или явные точки останова с TTL 5 минут или 1 час.
---
«Prompt caching» (кэширование подсказок) оптимизирует использование API, позволяя возобновлять обработку с определённых префиксов ваших подсказок. Это значительно сокращает время обработки и затраты для повторяющихся задач или подсказок с неизменными элементами.
Чтобы узнать, как «zero data retention» (нулевое хранение данных), или ZDR, применяется к этой функции, см. раздел [API и хранение данных](https://platform.claude.com/docs/ru/manage-claude/api-and-data-retention).
Существует два способа включить кэширование подсказок:
* **[Автоматическое кэширование](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#automatic-caching)**: добавьте одно поле `cache_control` на верхнем уровне запроса. Система автоматически применяет «cache breakpoint» (точку останова кэша) к последнему кэшируемому блоку и перемещает её вперёд по мере роста диалога. Лучше всего подходит для многоходовых диалогов, в которых растущая история сообщений должна кэшироваться автоматически.
* **[Явные точки останова кэша](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#explicit-cache-breakpoints)**: размещайте `cache_control` непосредственно на отдельных блоках контента, чтобы точно контролировать, что именно кэшируется.
Проще всего начать с автоматического кэширования:
```bash cURL
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-opus-5-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
"messages": [
{
"role": "user",
"content": "Analyze the major themes in Pride and Prejudice."
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
cache_control:
type: ephemeral
system: >-
You are an AI assistant tasked with analyzing literary works. Your goal is
to provide insightful commentary on themes, characters, and writing style.
messages:
- role: user
content: Analyze the major themes in Pride and Prejudice.
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
messages=[
{
"role": "user",
"content": "Analyze the major themes in 'Pride and Prejudice'.",
}
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
cache_control: { type: "ephemeral" },
system:
"You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
messages: [
{
role: "user",
content: "Analyze the major themes in 'Pride and Prejudice'."
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
CacheControl = new CacheControlEphemeral(),
System = "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
Messages =
[
new()
{
Role = Role.User,
Content = "Analyze the major themes in 'Pride and Prejudice'."
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
CacheControl: anthropic.NewCacheControlEphemeralParam(),
System: []anthropic.TextBlockParam{
{Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the major themes in 'Pride and Prejudice'.")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class PromptCachingExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.cacheControl(CacheControlEphemeral.builder().build())
.system("You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.")
.addUserMessage("Analyze the major themes in 'Pride and Prejudice'.")
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
use Anthropic\Messages\CacheControlEphemeral;
// ...
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => "Analyze the major themes in 'Pride and Prejudice'."]
],
model: 'claude-opus-5-5',
cacheControl: CacheControlEphemeral::with(),
system: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
);
echo json_encode($response->usage);
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
cache_control: {type: "ephemeral"},
system: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
messages: [
{
role: "user",
content: "Analyze the major themes in 'Pride and Prejudice'."
}
]
)
puts response.usage
```
При автоматическом кэшировании система кэширует весь контент вплоть до последнего кэшируемого блока включительно. При последующих запросах с тем же префиксом кэшированный контент автоматически используется повторно.
***
## Как работает кэширование подсказок
Когда вы отправляете запрос с включённым кэшированием подсказок:
1. Система проверяет, закэширован ли уже префикс подсказки до указанной точки останова кэша после недавнего запроса.
2. Если он найден, используется кэшированная версия, что сокращает время обработки и затраты.
3. В противном случае обрабатывается полная подсказка, а префикс кэшируется, как только начинается ответ.
Это особенно полезно для:
* Подсказок с большим количеством примеров
* Больших объёмов контекста или справочной информации
* Повторяющихся задач с неизменными инструкциями
* Длинных многоходовых диалогов
По умолчанию время жизни кэша составляет 5 минут. Кэш обновляется без дополнительной платы при каждом использовании кэшированного контента.
Время жизни отсчитывается от начала запроса, который записывает или читает запись кэша, а не от окончания его ответа. Время, затраченное на генерацию ответа, входит во время жизни: если «streaming» (потоковая передача) ответа занимает 4 минуты, последующий запрос, повторно использующий тот же кэшированный префикс, должен начаться примерно в течение 1 минуты после завершения этого ответа.
Если 5 минут для вас слишком мало, Anthropic также предлагает длительность кэша 1 час [за дополнительную плату](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#pricing).
Подробнее см. в разделе [Длительность кэша 1 час](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#1-hour-cache-duration).
**Кэширование подсказок кэширует весь префикс**
Кэширование подсказок охватывает всю подсказку: `tools`, `system` и `messages` (в этом порядке), вплоть до блока, помеченного `cache_control`, включительно.
***
## Цены
Кэширование подсказок вводит новую структуру цен. В следующей таблице приведена цена за миллион токенов для каждой поддерживаемой модели:
| Model | Base input tokens | 5m cache writes | 1h cache writes | Cache hits and refreshes | Output tokens |
| :----------------------------------------------------------------------------------------------------------------------------------- | :---------------- | :-------------- | :-------------- | :----------------------- | :------------ |
| Claude Fable 5.1 | $10 / MTok | $12.50 / MTok | $20 / MTok | $0.25 / MTok1 | $50 / MTok |
| Claude Mythos 5.1 ([limited availability](https://support.claude.com/en/articles/14604842)) | $10 / MTok | $12.50 / MTok | $20 / MTok | $0.25 / MTok1 | $50 / MTok |
| Claude Fable 5 | $10 / MTok | $12.50 / MTok | $20 / MTok | $1 / MTok | $50 / MTok |
| Claude Mythos 5 ([limited availability](https://support.claude.com/en/articles/14604842)) | $10 / MTok | $12.50 / MTok | $20 / MTok | $1 / MTok | $50 / MTok |
| Claude Opus 5.5 | $4 / MTok | $5 / MTok | $8 / MTok | $0.20 / MTok2 | $20 / MTok |
| Claude Opus 5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.8 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.7 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.6 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.1 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/ru/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Opus 4 ([retired, except on Google Cloud](https://platform.claude.com/docs/ru/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Sonnet 5.5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.10 / MTok2 | $10 / MTok |
| Claude Sonnet 5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.20 / MTok | $10 / MTok |
| Claude Sonnet 4.6 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/ru/about-claude/model-deprecations)) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Haiku 5.5 (for prompts up to 100,000 tokens) | $0.10 / MTok | $0.125 / MTok | $0.20 / MTok | $0.01 / MTok | $0.50 / MTok |
| Claude Haiku 5.5 (for prompts over 100,000 tokens) | $0.50 / MTok | $0.625 / MTok | $1 / MTok | $0.05 / MTok | $2.50 / MTok |
| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / MTok |
| Claude Haiku 3.5 ([retired, except on Google Cloud](https://platform.claude.com/docs/ru/about-claude/model-deprecations)) | $0.80 / MTok | $1 / MTok | $1.60 / MTok | $0.08 / MTok | $4 / MTok |
*1 Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price.*
*2 Cache hits and refreshes on Claude Opus 5.5 and Claude Sonnet 5.5 are priced at 0.05x the base input price.*
*All other models use the standard 0.1x multiplier.*
Приведённая выше таблица отражает следующие ценовые множители для кэширования подсказок:
* Токены записи в 5-минутный кэш стоят в 1,25 раза больше базовой цены входных токенов
* Токены записи в 1-часовой кэш стоят в 2 раза больше базовой цены входных токенов
* Токены чтения из кэша стоят 0,1 от базовой цены входных токенов (исключения для отдельных моделей см. в сноске к таблице)
Эти множители суммируются с другими ценовыми модификаторами, такими как скидка Batch API, [цены на длинный контекст](https://platform.claude.com/docs/ru/about-claude/pricing#long-context-pricing) и резидентность данных. Для модели, цена которой зависит от длины подсказки, чтение из кэша и запись в кэш учитываются в длине подсказки запроса. Подробности см. на странице [цен](https://platform.claude.com/docs/ru/about-claude/pricing).
***
## Поддерживаемые модели
Кэширование подсказок (как автоматическое, так и явное) поддерживается всеми [активными моделями Claude](https://platform.claude.com/docs/ru/models/overview).
***
## Автоматическое кэширование
Автоматическое кэширование — самый простой способ включить кэширование подсказок. Вместо того чтобы размещать `cache_control` на отдельных блоках контента, добавьте одно поле `cache_control` на верхнем уровне тела запроса. Система автоматически применяет точку останова кэша к последнему кэшируемому блоку.
```bash cURL
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-opus-5-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": "You are a helpful assistant that remembers our conversation.",
"messages": [
{"role": "user", "content": "My name is Alex. I work on machine learning."},
{"role": "assistant", "content": "Nice to meet you, Alex! How can I help with your ML work today?"},
{"role": "user", "content": "What did I say I work on?"}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
cache_control:
type: ephemeral
system: You are a helpful assistant that remembers our conversation.
messages:
- role: user
content: My name is Alex. I work on machine learning.
- role: assistant
content: Nice to meet you, Alex! How can I help with your ML work today?
- role: user
content: What did I say I work on?
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="You are a helpful assistant that remembers our conversation.",
messages=[
{"role": "user", "content": "My name is Alex. I work on machine learning."},
{
"role": "assistant",
"content": "Nice to meet you, Alex! How can I help with your ML work today?",
},
{"role": "user", "content": "What did I say I work on?"},
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
cache_control: { type: "ephemeral" },
system: "You are a helpful assistant that remembers our conversation.",
messages: [
{ role: "user", content: "My name is Alex. I work on machine learning." },
{
role: "assistant",
content: "Nice to meet you, Alex! How can I help with your ML work today?"
},
{ role: "user", content: "What did I say I work on?" }
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
CacheControl = new CacheControlEphemeral(),
System = "You are a helpful assistant that remembers our conversation.",
Messages =
[
new()
{
Role = Role.User,
Content = "My name is Alex. I work on machine learning."
},
new()
{
Role = Role.Assistant,
Content = "Nice to meet you, Alex! How can I help with your ML work today?"
},
new()
{
Role = Role.User,
Content = "What did I say I work on?"
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
CacheControl: anthropic.NewCacheControlEphemeralParam(),
System: []anthropic.TextBlockParam{
{Text: "You are a helpful assistant that remembers our conversation."},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("My name is Alex. I work on machine learning.")),
anthropic.NewAssistantMessage(anthropic.NewTextBlock("Nice to meet you, Alex! How can I help with your ML work today?")),
anthropic.NewUserMessage(anthropic.NewTextBlock("What did I say I work on?")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class AutomaticCachingExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.cacheControl(CacheControlEphemeral.builder().build())
.system("You are a helpful assistant that remembers our conversation.")
.addUserMessage("My name is Alex. I work on machine learning.")
.addAssistantMessage("Nice to meet you, Alex! How can I help with your ML work today?")
.addUserMessage("What did I say I work on?")
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
use Anthropic\Messages\CacheControlEphemeral;
// ...
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => 'My name is Alex. I work on machine learning.'],
['role' => 'assistant', 'content' => 'Nice to meet you, Alex! How can I help with your ML work today?'],
['role' => 'user', 'content' => 'What did I say I work on?'],
],
model: 'claude-opus-5-5',
cacheControl: CacheControlEphemeral::with(),
system: 'You are a helpful assistant that remembers our conversation.',
);
echo json_encode($response->usage);
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
cache_control: {type: "ephemeral"},
system: "You are a helpful assistant that remembers our conversation.",
messages: [
{role: "user", content: "My name is Alex. I work on machine learning."},
{role: "assistant", content: "Nice to meet you, Alex! How can I help with your ML work today?"},
{role: "user", content: "What did I say I work on?"}
]
)
puts response.usage
```
### Как автоматическое кэширование работает в многоходовых диалогах
При автоматическом кэшировании точка кэширования автоматически перемещается вперёд по мере роста диалога. Каждый новый запрос кэширует всё вплоть до последнего кэшируемого блока, а предыдущий контент читается из кэша.
| Запрос | Содержимое | Поведение кэша |
| -------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Запрос 1 | System
+ User(1) + Asst(1)
+ **User(2)** ◀ кэш | Всё записывается в кэш |
| Запрос 2 | System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ **User(3)** ◀ кэш | Всё от System до User(2) читается из кэша;
Asst(2) + User(3) записываются в кэш |
| Запрос 3 | System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ User(3) + Asst(3)
+ **User(4)** ◀ кэш | Всё от System до User(3) читается из кэша;
Asst(3) + User(4) записываются в кэш |
Точка останова кэша автоматически перемещается к последнему кэшируемому блоку в каждом запросе, поэтому вам не нужно обновлять маркеры `cache_control` по мере роста диалога.
### Поддержка TTL
По умолчанию автоматическое кэширование использует «time to live» (время жизни), или TTL, равное 5 минутам. Вы можете указать TTL в 1 час по цене, в 2 раза превышающей базовую цену входных токенов:
```json
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }
```
### Сочетание с кэшированием на уровне блоков
Автоматическое кэширование совместимо с [явными точками останова кэша](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#explicit-cache-breakpoints). При совместном использовании автоматическая точка останова кэша занимает один из 4 доступных слотов точек останова.
Это позволяет сочетать оба подхода. Например, используйте явную точку останова для кэширования «system prompt» (системной подсказки), а диалог пусть обрабатывает автоматическое кэширование:
```json
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": { "type": "ephemeral" },
"system": [
{
"type": "text",
"text": "You are a helpful assistant.",
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What are the key terms?" }]
}
```
### Что остаётся неизменным
Автоматическое кэширование использует ту же базовую инфраструктуру кэширования. Цены, минимальные пороги токенов, требования к порядку контекста и «lookback window» (окно обратного просмотра) размером 20 блоков применяются так же, как и при явных точках останова.
### Граничные случаи
* Если у последнего блока уже есть явный `cache_control` с тем же TTL, автоматическое кэширование ничего не делает.
* Если у последнего блока есть явный `cache_control` с другим TTL, API возвращает ошибку 400.
* Если уже существуют 4 явные точки останова на уровне блоков, API возвращает ошибку 400 (не осталось слотов для автоматического кэширования).
* Если последний блок не подходит в качестве цели для автоматической точки останова кэша, система незаметно перемещается назад в поисках ближайшего подходящего блока. Если такой блок не найден, кэширование пропускается.
Автоматическое кэширование доступно на всех платформах, кроме устаревшей интеграции [Amazon Bedrock (Opus 4.6 и более ранние)](https://platform.claude.com/docs/ru/build-with-claude/claude-on-amazon-bedrock-legacy). В этой интеграции API возвращает ошибку 400 для поля `cache_control` верхнего уровня, поэтому используйте вместо этого [явные точки останова кэша](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#explicit-cache-breakpoints).
***
## Явные точки останова кэша
Для большего контроля над кэшированием вы можете размещать `cache_control` непосредственно на отдельных блоках контента. Это полезно, когда нужно кэшировать разные разделы, которые меняются с разной частотой, или требуется точный контроль над тем, что именно кэшируется.
### Структурирование подсказки
Размещайте статический контент (определения инструментов, системные инструкции, контекст, примеры) в начале подсказки. Отметьте конец повторно используемого контента для кэширования с помощью параметра `cache_control`.
Префиксы кэша создаются в следующем порядке: `tools`, `system`, затем `messages`. Этот порядок образует иерархию, в которой каждый уровень строится на предыдущих.
#### Как работает автоматическая проверка префиксов
Вы можете использовать всего одну точку останова кэша в конце статического контента, и система автоматически найдёт самый длинный префикс, который предыдущий запрос уже записал в кэш. Понимание того, как это работает, поможет вам оптимизировать стратегию кэширования.
**Три основных принципа:**
1. **Запись в кэш происходит только в точке останова.** Пометка блока с помощью `cache_control` создаёт ровно одну запись кэша: хеш префикса, заканчивающегося на этом блоке. Система не создаёт записей ни для каких более ранних позиций. Поскольку хеш кумулятивный и охватывает всё вплоть до точки останова включительно, изменение любого блока в точке останова или перед ней приводит к другому хешу при следующем запросе.
2. **Чтение из кэша ищет в обратном направлении записи, сделанные предыдущими запросами.** При каждом запросе система вычисляет хеш префикса в точке останова и проверяет наличие соответствующей записи кэша. Если её нет, система перемещается назад по одному блоку, проверяя, совпадает ли хеш префикса в каждой более ранней позиции с чем-либо, что уже есть в кэше. Она ищет предыдущие записи, а не стабильный контент.
3. **Окно обратного просмотра составляет 20 блоков.** Система проверяет не более 20 позиций на каждую точку останова, считая саму точку останова первой. Если система не находит подходящей записи в этом окне, проверка прекращается (или возобновляется со следующей явной точки останова, если она есть). В Claude API последовательность идущих подряд блоков `tool_use` считается одной позицией, как и последовательность идущих подряд блоков `tool_result`, поэтому ход с множеством параллельных вызовов инструментов сам по себе не выталкивает запись предыдущего запроса за пределы окна.
**Пример: обратный просмотр в растущем диалоге**
Вы добавляете новые блоки на каждом ходу и устанавливаете `cache_control` на последний блок каждого запроса:
* **Ход 1:** 10 блоков, точка останова на блоке 10. Предыдущих записей кэша нет. Система создаёт запись на блоке 10.
* **Ход 2:** 15 блоков, точка останова на блоке 15. У блока 15 нет записи, поэтому система возвращается к блоку 10 и находит запись хода 1. «Cache hit» (попадание в кэш) на блоке 10; система заново обрабатывает только блоки с 11 по 15 и создаёт новую запись на блоке 15.
* **Ход 3:** 35 блоков, точка останова на блоке 35. Система проверяет 20 позиций (блоки с 35 по 16) и ничего не находит. Запись хода 2 на блоке 15 находится на одну позицию за пределами окна, поэтому попадания в кэш нет. Добавление второй точки останова на блоке 15 запускает там второе окно обратного просмотра, которое находит запись хода 2.
**Распространённая ошибка: точка останова на контенте, который меняется при каждом запросе**
Ваша подсказка содержит большой статический системный контекст (блоки с 1 по 5), за которым следует уникальный для каждого запроса блок с меткой времени и сообщением пользователя (блок 6). Вы устанавливаете `cache_control` на блок 6:
* **Запрос 1:** запись в кэш на блоке 6. Хеш включает метку времени.
* **Запрос 2:** метка времени отличается, поэтому хеш префикса на блоке 6 отличается. Обратный просмотр проходит через блоки 5, 4, 3, 2 и 1, но система никогда не создавала записей ни в одной из этих позиций. Попадания в кэш нет. Вы платите за новую запись в кэш при каждом запросе и никогда не получаете чтения.
Обратный просмотр не находит стабильный контент перед вашей точкой останова и не кэширует его. Он находит записи, которые уже сделали предыдущие запросы, а запись происходит только в точках останова. Переместите `cache_control` на блок 5 — последний блок, который остаётся неизменным между запросами, — и каждый последующий запрос будет читать кэшированный префикс. [Автоматическое кэширование](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#automatic-caching) попадает в ту же ловушку: оно размещает точку останова на последнем кэшируемом блоке, который в этой структуре меняется при каждом запросе, поэтому вместо него используйте явную точку останова на блоке 5.
**Главный вывод:** размещайте `cache_control` на последнем блоке, префикс которого идентичен во всех запросах, которые должны использовать общий кэш. В растущем диалоге последний блок подходит, если каждый ход добавляет менее 20 блоков: более ранний контент никогда не меняется, поэтому обратный просмотр следующего запроса находит предыдущую запись. Для подсказки с изменяющимся суффиксом (метки времени, контекст конкретного запроса, входящее сообщение) размещайте точку останова в конце статического префикса, а не на изменяющемся блоке.
#### Когда использовать несколько точек останова
Вы можете определить до 4 точек останова кэша, если хотите:
* Кэшировать разные разделы, которые меняются с разной частотой (например, инструменты меняются редко, а контекст обновляется ежедневно)
* Иметь больше контроля над тем, что именно кэшируется
* Гарантировать попадание в кэш, когда растущий диалог отодвигает вашу точку останова на 20 или более блоков от последней записи в кэш
**Важное ограничение:** обратный просмотр может найти только записи, которые уже сделали более ранние запросы. Если растущий диалог отодвигает точку останова на 20 или более блоков от последней записи, окно обратного просмотра её не находит. С самого начала добавьте вторую точку останова ближе к этой позиции, чтобы запись накопилась там до того, как она понадобится.
### Понимание стоимости точек останова кэша
**Сами точки останова кэша не добавляют никаких затрат.** Плата взимается только за:
* **Запись в кэш:** когда новый контент записывается в кэш (на 25% больше базовой цены входных токенов для TTL 5 минут)
* **Чтение из кэша:** когда используется кэшированный контент (10% от базовой цены входных токенов, или 2,5% для Claude Fable 5.1 и Claude Mythos 5.1, и 5% для Claude Opus 5.5 и Claude Sonnet 5.5)
* **Обычные входные токены:** за любой некэшированный контент
Добавление дополнительных точек останова `cache_control` не увеличивает ваши затраты; вы по-прежнему платите ту же сумму в зависимости от того, какой контент фактически кэшируется и читается. Точки останова дают вам контроль над тем, какие разделы могут кэшироваться независимо.
***
## Стратегии и особенности кэширования
### Ограничения кэша
В Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ru/build-with-claude/claude-platform-on-aws), [Google Cloud](https://platform.claude.com/docs/ru/build-with-claude/claude-on-vertex-ai) и [Microsoft Foundry](https://platform.claude.com/docs/ru/build-with-claude/claude-in-microsoft-foundry) минимальная длина кэшируемой подсказки составляет:
* 512 токенов для Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/ru/models/mythos-5-1/overview), Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/ru/models/mythos-5/overview) и Claude Haiku 5.5
* 2048 токенов для [Claude Mythos Preview](https://anthropic.com/glasswing) и Claude Opus 4.7
* 4096 токенов для Claude Opus 4.6 и Claude Opus 4.5
* 1024 токена для Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 ([устарела](https://platform.claude.com/docs/ru/about-claude/model-deprecations)), Claude Opus 4.1 ([выведена из эксплуатации, кроме Bedrock и Google Cloud](https://platform.claude.com/docs/ru/about-claude/model-deprecations)), Claude Opus 4 ([выведена из эксплуатации, кроме Google Cloud](https://platform.claude.com/docs/ru/about-claude/model-deprecations)) и Claude Sonnet 4 ([выведена из эксплуатации, кроме Bedrock и Google Cloud](https://platform.claude.com/docs/ru/about-claude/model-deprecations))
* 4096 токенов для Claude Haiku 4.5
* 2048 токенов для Claude Haiku 3.5 ([выведена из эксплуатации, кроме Google Cloud](https://platform.claude.com/docs/ru/about-claude/model-deprecations))
Эти минимумы действуют на всех платформах, где доступна соответствующая модель.
Более короткие подсказки не могут быть закэшированы, даже если они помечены `cache_control`. Любые запросы на кэширование меньшего количества токенов будут обработаны без кэширования, и ошибка не возвращается. Чтобы проверить, была ли подсказка закэширована, проверьте [поля использования в ответе](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#tracking-cache-performance): если и `cache_creation_input_tokens`, и `cache_read_input_tokens` равны 0, подсказка не была закэширована (вероятно, потому что она не соответствовала требованию минимальной длины).
Если ваша подсказка лишь немного не дотягивает до минимума для вашей модели и платформы, часто имеет смысл расширить кэшируемый контент до достижения порога. Чтение из кэша стоит значительно дешевле некэшированных входных токенов, поэтому достижение минимума может снизить затраты для часто повторно используемых подсказок.
[Bedrock](https://platform.claude.com/docs/ru/build-with-claude/claude-in-amazon-bedrock) — это платформа, управляемая AWS. Для Bedrock см. [документацию Bedrock по кэшированию подсказок](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html), где описаны применимые минимумы для каждой модели, поведение при сбоях и названия полей использования.
Для параллельных запросов учтите, что запись кэша становится доступной только после начала первого ответа. Если вам нужны попадания в кэш для параллельных запросов, дождитесь первого ответа, прежде чем отправлять последующие запросы.
В настоящее время «ephemeral» — единственный поддерживаемый тип кэша, время жизни которого по умолчанию составляет 5 минут.
### Что можно кэшировать
Большинство блоков в запросе можно кэшировать. Сюда входят:
* Инструменты: определения инструментов в массиве `tools`
* Системные сообщения: блоки контента в массиве `system`
* Текстовые сообщения: блоки контента в массиве `messages.content` как для ходов пользователя, так и для ходов ассистента
* Изображения и документы: блоки контента в массиве `messages.content` в ходах пользователя
* «Tool use» (использование инструментов) и результаты инструментов: блоки контента в массиве `messages.content` в ходах как пользователя, так и ассистента
Каждый из этих элементов можно кэшировать — автоматически или пометив его с помощью `cache_control`.
### Что нельзя кэшировать
Хотя большинство блоков запроса можно кэшировать, есть некоторые исключения:
* Блоки «thinking» (размышлений) нельзя кэшировать напрямую с помощью `cache_control`. Однако блоки размышлений МОГУТ кэшироваться вместе с другим контентом, если они присутствуют в предыдущих ходах ассистента. При таком кэшировании они УЧИТЫВАЮТСЯ как входные токены при чтении из кэша.
* Вложенные блоки контента (например, [цитаты](https://platform.claude.com/docs/ru/build-with-claude/citations)) сами по себе нельзя кэшировать напрямую. Вместо этого кэшируйте блок верхнего уровня.
В случае цитат можно кэшировать блоки контента документов верхнего уровня, которые служат исходным материалом для цитат. Это позволяет эффективно использовать кэширование подсказок с цитатами, кэшируя документы, на которые будут ссылаться цитаты.
* Пустые текстовые блоки нельзя кэшировать.
### Что делает кэш недействительным
Изменения кэшированного контента могут сделать недействительной часть кэша или весь кэш.
Как описано в разделе [Структурирование подсказки](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#structuring-your-prompt), кэш следует иерархии: `tools` → `system` → `messages`. Изменения на каждом уровне делают недействительными этот уровень и все последующие уровни.
В следующей таблице показано, какие части кэша становятся недействительными при различных типах изменений. ✘ означает, что кэш становится недействительным, а ✓ — что кэш остаётся действительным.
| Что меняется | Кэш инструментов | Системный кэш | Кэш сообщений | Влияние |
| --------------------------------------------------------------------------------------------- | ----------------- | ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Определения инструментов** | ✘ | ✘ | ✘ | Изменение определений инструментов (имён, описаний, параметров) делает недействительным весь кэш |
| **Переключение веб-поиска** | ✓ | ✘ | ✘ | Включение/отключение веб-поиска изменяет системную подсказку |
| **Переключение цитат** | ✓ | ✘ | ✘ | Включение/отключение цитат изменяет системную подсказку |
| **Настройка скорости** | ✓ | ✘ | ✘ | Переключение между [`speed: "fast"` и стандартной скоростью](https://platform.claude.com/docs/ru/build-with-claude/fast-mode) делает недействительными системный кэш и кэш сообщений |
| **Выбор инструмента** | ✓ | ✓ | ✘ | Изменения параметра `tool_choice` влияют только на блоки сообщений |
| **Изображения** | ✓ | ✓ | ✘ | Добавление/удаление изображений в любом месте подсказки влияет на блоки сообщений |
| **Параметры размышлений** | Зависит от модели | Зависит от модели | ✘ | Конфигурация размышлений (режим и `budget_tokens` в расширенном режиме) встраивается в подсказку, поэтому её изменение всегда делает недействительными блоки сообщений; кэши инструментов и системы также становятся недействительными на моделях, которые встраивают конфигурацию перед ними. См. [Размышления и кэширование подсказок](https://platform.claude.com/docs/ru/build-with-claude/thinking#thinking-and-prompt-caching). |
| **Настройка уровня усилий** | Зависит от модели | Зависит от модели | ✘ | Изменение значения [`output_config.effort`](https://platform.claude.com/docs/ru/build-with-claude/effort) всегда делает недействительными блоки сообщений, с тем же зависящим от модели влиянием на кэши инструментов и системы, что и у параметров размышлений. Явная установка уровня усилий в значение по умолчанию для модели эквивалентна его отсутствию и не делает кэш недействительным. На моделях, поддерживающих [уровень усилий для отдельного сообщения](https://platform.claude.com/docs/ru/build-with-claude/effort#change-effort-mid-conversation-beta), изменение уровня усилий, переданное в сообщении `role: "system"` внутри `messages`, оставляет кэшированный префикс нетронутым. |
| **Результаты, не являющиеся результатами инструментов, переданные в запросы с размышлениями** | ✓ | ✓ | Зависит от модели | На Opus 4.5+, Sonnet 4.6+ и Haiku 5.5 блоки размышлений сохраняются по умолчанию, поэтому кэш остаётся действительным (✓). На более ранних моделях Opus/Sonnet и моделях Haiku вплоть до Claude Haiku 4.5 все ранее кэшированные блоки размышлений удаляются из контекста, а все сообщения, следующие за этими блоками размышлений, удаляются из кэша (✘). Подробнее см. в разделе [Кэширование с блоками размышлений](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#caching-with-thinking-blocks). |
| **Отброшенные блоки размышлений** | ✓ | ✓ | ✘ | Когда API отбрасывает блок размышлений Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 или Claude Haiku 5.5, который не [сохраняется](https://platform.claude.com/docs/ru/build-with-claude/thinking#preserved-thinking) в этом запросе (например, блок, который вы повторно передаёте модели, не способной его прочитать), кэшированный префикс в этом запросе изменяется начиная с позиции этого блока. Блоки, которые принимающая модель может прочитать и которые передаются обратно без изменений, сохраняют кэш нетронутым. |
На моделях, поддерживающих [изменения инструментов в середине разговора](https://platform.claude.com/docs/ru/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes), бета-заголовок `inline-tools-2026-09-15` позволяет добавить инструмент или изменить определение инструмента посреди диалога без редактирования `tools`. Отправьте определение в блоке `tool_addition` в системном сообщении в середине разговора и оставьте `tools` точно таким, каким вы отправили его изначально. Кэшированный префикс по-прежнему совпадает, поэтому как новый ввод обрабатывается только добавленное сообщение. Единственное исключение — массив `tools` без неотложенных инструментов: в этом случае первый инструмент, определённый таким образом, стоит одного полного промаха кэша в этом запросе. См. [Определение инструментов в сообщении](https://platform.claude.com/docs/ru/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta).
Для Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/ru/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/ru/models/mythos-5/overview), Claude Opus 5.5, Claude Opus 4.8, Claude Opus 5, Claude Sonnet 5.5 и Claude Haiku 5.5 вы можете добавить новую системную инструкцию посреди диалога, не делая недействительными системный кэш и кэш сообщений. Добавьте сообщение `{"role": "system"}` в `messages` вместо редактирования поля `system` верхнего уровня, чтобы кэшированный префикс остался неизменным. Эта функция недоступна для Claude Sonnet 5. Вместо этого используйте поле `system` верхнего уровня. См. [Системные сообщения в середине разговора](https://platform.claude.com/docs/ru/build-with-claude/mid-conversation-system-messages).
### Отслеживание производительности кэша
Отслеживайте производительность кэша с помощью следующих полей ответа API в объекте `usage` ответа (или в событии `message_start` при [потоковой передаче](https://platform.claude.com/docs/ru/build-with-claude/streaming)):
* `cache_creation_input_tokens`: количество токенов, записанных в кэш при создании новой записи.
* `cache_read_input_tokens`: количество токенов, извлечённых из кэша для этого запроса.
* `input_tokens`: количество входных токенов, которые не были прочитаны из кэша и не использовались для его создания (то есть токены после последней точки останова кэша).
**Понимание разбивки токенов**
Поле `input_tokens` представляет только токены, которые идут **после последней точки останова кэша** в вашем запросе, а не все отправленные вами входные токены.
Чтобы вычислить общее количество входных токенов:
```text wrap
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens
```
**Пространственное объяснение:**
* `cache_read_input_tokens` = токены перед точкой останова, уже находящиеся в кэше (чтение)
* `cache_creation_input_tokens` = токены перед точкой останова, кэшируемые сейчас (запись)
* `input_tokens` = токены после вашей последней точки останова (не подлежат кэшированию)
**Пример:** если у вас есть запрос со 100 000 токенов кэшированного контента (прочитанного из кэша), 0 токенов нового кэшируемого контента и 50 токенами в сообщении пользователя (после точки останова кэша):
* `cache_read_input_tokens`: 100 000
* `cache_creation_input_tokens`: 0
* `input_tokens`: 50
* **Всего обработано входных токенов:** 100 050 токенов
Это важно для понимания как затрат, так и «rate limits» (ограничений скорости), поскольку при эффективном использовании кэширования `input_tokens` обычно будет намного меньше общего объёма входных данных.
### Кэширование с блоками размышлений
При использовании [размышлений](https://platform.claude.com/docs/ru/build-with-claude/thinking) вместе с кэшированием подсказок блоки размышлений ведут себя особым образом:
**Автоматическое кэширование вместе с другим контентом:** хотя блоки размышлений нельзя явно пометить с помощью `cache_control`, они кэшируются как часть контента запроса, когда вы выполняете последующие вызовы API с результатами инструментов. Обычно это происходит при использовании инструментов, когда вы передаёте блоки размышлений обратно для продолжения диалога.
**Подсчёт входных токенов:** когда блоки размышлений читаются из кэша, они засчитываются как входные токены в ваших метриках использования. Это важно для расчёта затрат и планирования бюджета токенов.
**Закономерности инвалидации кэша:**
* Кэш остаётся действительным, когда в качестве сообщений пользователя передаются только результаты инструментов
* Для Opus 4.5+, Sonnet 4.6+ и Haiku 5.5 блоки размышлений по умолчанию сохраняются даже при добавлении пользовательского контента, не являющегося результатом инструмента, поэтому кэш остаётся действительным
* Для более ранних моделей Opus/Sonnet и моделей Haiku до Claude Haiku 4.5 включительно кэш становится недействительным при добавлении пользовательского контента, не являющегося результатом инструмента, что приводит к удалению всех предыдущих блоков размышлений из контекста
* Такое поведение кэширования проявляется даже без явных маркеров `cache_control`
Подробнее об инвалидации кэша см. в разделе [Что делает кэш недействительным](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#what-invalidates-the-cache).
**Пример с использованием инструментов:**
```text wrap
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]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)
```
Для более ранних моделей Opus/Sonnet и моделей Haiku до Claude Haiku 4.5 включительно на этом этапе все предыдущие блоки размышлений удаляются из контекста. Для Opus 4.5+, Sonnet 4.6+ и Haiku 5.5 предыдущие блоки размышлений по умолчанию сохраняются и остаются частью кэшированного префикса.
Более подробную информацию см. в разделе [Размышления и кэширование подсказок](https://platform.claude.com/docs/ru/build-with-claude/thinking#thinking-and-prompt-caching).
### Хранение кэша и совместный доступ
Кэширование подсказок использует изоляцию на уровне [рабочих пространств](https://platform.claude.com/docs/ru/manage-claude/workspaces). Кэши изолированы для каждого рабочего пространства, что обеспечивает разделение данных между рабочими пространствами в пределах одной организации. Это относится к Claude API, Claude Platform on AWS и Microsoft Foundry; Bedrock и Google Cloud поддерживают изоляцию кэша на уровне организации. Если вы используете несколько рабочих пространств, пересмотрите свою стратегию кэширования с учётом этого различия.
* **Изоляция организаций и рабочих пространств:** кэши изолированы между организациями. Разные организации никогда не используют общие кэши, даже если они используют идентичные подсказки. В Claude API, Claude Platform on AWS и Microsoft Foundry кэши также изолированы для каждого рабочего пространства внутри организации; Bedrock и Google Cloud используют только изоляцию на уровне организации.
* **Точное совпадение:** для попадания в кэш требуются на 100% идентичные сегменты подсказки, включая весь текст и изображения вплоть до блока, помеченного cache control, включительно.
* **Генерация выходных токенов:** кэширование подсказок не влияет на генерацию выходных токенов. Получаемый ответ идентичен тому, который вы получили бы без использования кэширования подсказок.
### Рекомендации по эффективному кэшированию
Чтобы оптимизировать производительность кэширования подсказок:
* Начните с [автоматического кэширования](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#automatic-caching) для многоходовых диалогов. Оно автоматически управляет точками останова.
* Используйте [явные точки останова на уровне блоков](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#explicit-cache-breakpoints), когда нужно кэшировать разные разделы с разной частотой изменений.
* Кэшируйте стабильный, повторно используемый контент, такой как системные инструкции, справочная информация, большие контексты или часто используемые определения инструментов.
* Размещайте кэшируемый контент в начале подсказки для наилучшей производительности.
* Стратегически используйте точки останова кэша для разделения различных кэшируемых секций префикса.
* Размещайте точку останова на последнем блоке, который остаётся идентичным между запросами. Для подсказки со статическим префиксом и изменяющимся суффиксом (метки времени, контекст конкретного запроса, входящее сообщение) это конец префикса, а не изменяющийся блок.
* Регулярно анализируйте частоту попаданий в кэш и при необходимости корректируйте стратегию.
### Оптимизация для различных сценариев использования
Адаптируйте стратегию кэширования подсказок к своему сценарию:
* Диалоговые агенты: снижайте затраты и «latency» (задержку) в длительных диалогах, особенно с длинными инструкциями или загруженными документами.
* Помощники по программированию: улучшайте автодополнение и ответы на вопросы по кодовой базе, сохраняя в подсказке релевантные разделы или сокращённую версию кодовой базы.
* Обработка больших документов: включайте в подсказку полные объёмные материалы, в том числе изображения, без увеличения задержки ответа.
* Подробные наборы инструкций: передавайте обширные списки инструкций, процедур и примеров для тонкой настройки ответов Claude. Разработчики часто включают в подсказку один-два примера, но с кэшированием подсказок можно добиться ещё лучшей производительности, включив более 20 разнообразных примеров высококачественных ответов.
* Агентное использование инструментов: повышайте производительность в сценариях с множественными вызовами инструментов и итеративными изменениями кода, где каждый шаг обычно требует нового вызова API.
* Общение с книгами, статьями, документацией, расшифровками подкастов и другим объёмным контентом: оживите любую базу знаний, встроив в подсказку документ(ы) целиком и позволив пользователям задавать по нему вопросы.
### Устранение распространённых проблем
При неожиданном поведении:
[Диагностика кэша](https://platform.claude.com/docs/ru/build-with-claude/cache-diagnostics) позволяет API сравнивать последовательные запросы и сообщать, где разошёлся префикс подсказки, что автоматически выполняет многие шаги из этого списка.
* Убедитесь, что кэшируемые разделы идентичны во всех вызовах. Для явных точек останова проверьте, что маркеры `cache_control` находятся в тех же местах
* Проверьте, что вызовы выполняются в пределах времени жизни кэша (по умолчанию 5 минут)
* Убедитесь, что `tool_choice`, использование изображений, конфигурация размышлений и `output_config.effort` остаются неизменными между вызовами
* Убедитесь, что вы кэшируете как минимум минимальное количество токенов для вашей модели и платформы (см. [Ограничения кэша](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#cache-limitations))
* Убедитесь, что точка останова находится на блоке, который остаётся идентичным между запросами. Запись в кэш происходит только в точке останова, и если этот блок меняется (метки времени, контекст конкретного запроса, входящее сообщение), хеш префикса никогда не совпадёт. Обратный просмотр не находит стабильный контент перед точкой останова; он находит только записи, которые более ранние запросы сделали в своих точках останова
* Убедитесь, что ключи в блоках контента `tool_use` имеют стабильный порядок, поскольку некоторые языки (например, Swift, Go) перемешивают порядок ключей при преобразовании в JSON, что нарушает работу кэша
* Используйте [диагностику кэша](https://platform.claude.com/docs/ru/build-with-claude/cache-diagnostics), чтобы API сравнил последовательные запросы и сообщил, какая часть подсказки разошлась
Изменения `tool_choice` или наличие/отсутствие изображений в любом месте подсказки сделают кэш недействительным, что потребует создания новой записи кэша. Подробнее об инвалидации кэша см. в разделе [Что делает кэш недействительным](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#what-invalidates-the-cache).
***
## Длительность кэша 1 час
Если 5 минут для вас слишком мало, Anthropic также предлагает длительность кэша 1 час [за дополнительную плату](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#pricing).
Длительность кэша 1 час доступна в Claude API, [Amazon Bedrock](https://platform.claude.com/docs/ru/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (Opus 4.6 и более ранние)](https://platform.claude.com/docs/ru/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Platform on AWS](https://platform.claude.com/docs/ru/build-with-claude/claude-platform-on-aws), [Google Cloud](https://platform.claude.com/docs/ru/build-with-claude/claude-on-vertex-ai) и [Microsoft Foundry](https://platform.claude.com/docs/ru/build-with-claude/claude-in-microsoft-foundry).
Чтобы использовать расширенный кэш, включите `ttl` в определение `cache_control` следующим образом:
```json
"cache_control": {
"type": "ephemeral",
"ttl": "1h"
}
```
Ответ содержит подробную информацию о кэше, например:
```json Output
{
"usage": {
"input_tokens": 2048,
"cache_read_input_tokens": 1800,
"cache_creation_input_tokens": 248,
"output_tokens": 503,
"cache_creation": {
"ephemeral_5m_input_tokens": 148,
"ephemeral_1h_input_tokens": 100
}
}
}
```
Обратите внимание, что текущее поле `cache_creation_input_tokens` равно сумме значений в объекте `cache_creation`.
Если при использовании серверных инструментов, таких как веб-поиск, вы видите записи `ephemeral_5m_input_tokens`, которые не запрашивали, см. [Использование инструментов с кэшированием подсказок](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-use-with-prompt-caching#server-tool-results-are-cached-automatically).
### Когда использовать 1-часовой кэш
Если у вас есть подсказки, которые используются с регулярной периодичностью (то есть системные подсказки, которые используются чаще, чем раз в 5 минут), продолжайте использовать 5-минутный кэш, поскольку он будет и дальше обновляться без дополнительной платы.
1-часовой кэш лучше всего использовать в следующих сценариях:
* Когда у вас есть подсказки, которые, вероятно, используются реже, чем раз в 5 минут, но чаще, чем раз в час. Например, когда вспомогательный агент будет работать дольше 5 минут или когда вы храните длинный чат с пользователем и обычно ожидаете, что пользователь может не ответить в ближайшие 5 минут.
* Когда важна задержка, а последующие подсказки могут отправляться более чем через 5 минут.
* Когда вы хотите эффективнее использовать ограничение скорости, поскольку попадания в кэш не учитываются в вашем ограничении скорости.
5-минутный и 1-часовой кэш ведут себя одинаково с точки зрения задержки. Как правило, вы увидите сокращение времени до первого токена для длинных документов.
### Смешивание разных TTL
Вы можете использовать элементы управления 1-часовым и 5-минутным кэшем в одном запросе, но с важным ограничением: записи кэша с более длинным TTL должны располагаться перед записями с более коротким TTL (то есть запись 1-часового кэша должна располагаться перед любыми записями 5-минутного кэша).
При смешивании TTL API определяет три позиции тарификации в вашей подсказке:
1. Позиция `A`: количество токенов в точке самого дальнего попадания в кэш (или 0, если попаданий нет).
2. Позиция `B`: количество токенов в самом дальнем блоке 1-часового `cache_control` после `A` (или равно `A`, если таких нет).
3. Позиция `C`: количество токенов в последнем блоке `cache_control`.
Если `B` или `C` больше `A`, это обязательно промах кэша, поскольку `A` — самое дальнее попадание в кэш.
С вас будет взиматься плата за:
1. Токены чтения из кэша для `A`.
2. Токены записи в 1-часовой кэш для `(B - A)`.
3. Токены записи в 5-минутный кэш для `(C - B)`.
Вот три примера. Здесь изображены входные токены 3 запросов, у каждого из которых разные попадания и промахи кэша. В результате у каждого из них разная рассчитанная стоимость, показанная в цветных блоках.
***
## Предварительный прогрев кэша
Cache pre-warming (предварительный прогрев кэша) позволяет загрузить вашу системную подсказку или определения инструментов в кэш подсказок до того, как пользователь инициирует реальный запрос. Это устраняет дополнительную latency (задержку), вызванную промахом кэша при первом взаимодействии пользователя, и сокращает «time-to-first-token» (время до первого токена), или TTFT, для приложений, чувствительных к задержке.
### Как это работает
Укажите `max_tokens: 0` в запросе. API загружает вашу подсказку в модель и записывает кэш в каждой breakpoint (точке останова) `cache_control`, после чего сразу возвращает ответ, не генерируя никакого вывода. Ответ содержит пустой массив `content`, `stop_reason: "max_tokens"` и полностью заполненный блок `usage`.
Разместите точку останова `cache_control` на последнем блоке, общем с последующим запросом (обычно это ваша системная подсказка или определения инструментов), а не на сообщении-заполнителе пользователя. В противном случае запись кэша будет привязана к заполнителю, и последующий запрос в неё не попадёт. Также используйте ту же конфигурацию размышлений и `output_config.effort`, что и в последующих запросах: эти значения встраиваются в подсказку (см. [Что делает кэш недействительным](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#what-invalidates-the-cache)), поэтому прогрев с другой конфигурацией может создать запись, в которую ваш реальный трафик никогда не попадёт. Это означает, что нужно использовать [явную точку останова кэша](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#explicit-cache-breakpoints), а не [автоматическое кэширование](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#automatic-caching), поскольку автоматическое кэширование размещает точку останова на последнем блоке, которым здесь является заполнитель. Сообщение-заполнитель пользователя может быть любой строкой с непробельным содержимым (в приведённых здесь примерах используется `"warmup"`); его содержимое загружается в модель, но ответ на него никогда не генерируется.
Запрос прогрева влечёт плату за **запись в кэш**, если префикс ещё не закэширован, так же как и любой другой запрос. Проверьте `usage.cache_creation_input_tokens` в ответе, чтобы убедиться, что запись произошла. Выходные токены не оплачиваются, так как их ноль.
```bash cURL
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-opus-5-5",
"max_tokens": 0,
"system": [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "warmup"}]
}'
```
```bash CLI
ant messages create \
--transform '{stop_reason,content,usage}' --format yaml <<'YAML'
model: claude-opus-5-5
max_tokens: 0
system:
- type: text
text: >-
You are an expert software engineer with deep knowledge of
distributed systems...
cache_control:
type: ephemeral
messages:
- role: user
content: warmup
YAML
```
```python Python
client = anthropic.Anthropic()
# Выполните этот запрос до прихода пользователей, чтобы прогреть общий кэш системной подсказки.
prewarm = client.messages.create(
model="claude-opus-5-5",
max_tokens=0,
system=[
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason) # "max_tokens"
print(prewarm.content) # []
print(prewarm.usage)
```
```typescript TypeScript
const client = new Anthropic();
// Вызовите это до прихода пользователей, чтобы прогреть общий кэш системной подсказки.
const prewarm = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 0,
system: [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: { type: "ephemeral" }
}
],
messages: [{ role: "user", content: "warmup" }]
});
console.log(prewarm.stop_reason); // "max_tokens"
console.log(prewarm.content); // []
console.log(prewarm.usage);
```
```csharp C#
AnthropicClient client = new();
var prewarm = await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 0,
System = new(
[
new TextBlockParam
{
Text = "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl = new(),
},
]
),
Messages = [new() { Role = Role.User, Content = "warmup" }],
}
);
Console.WriteLine(prewarm.StopReason?.Raw()); // "max_tokens"
Console.WriteLine(prewarm.Content.Count); // 0
Console.WriteLine(prewarm.Usage);
```
```go Go
client := anthropic.NewClient()
prewarm, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 0,
System: []anthropic.TextBlockParam{
{
Text: "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")),
},
})
if err != nil {
panic(err)
}
fmt.Println(prewarm.StopReason) // "max_tokens"
fmt.Println(prewarm.Content) // []
fmt.Println(prewarm.Usage.RawJSON())
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Message prewarm = client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(0)
.systemOfTextBlockParams(List.of(TextBlockParam.builder()
.text("You are an expert software engineer with deep knowledge of distributed systems...")
.cacheControl(CacheControlEphemeral.builder().build())
.build()))
.addUserMessage("warmup")
.build());
IO.println(prewarm.stopReason()); // Optional[max_tokens]
IO.println(prewarm.content()); // []
IO.println(prewarm.usage());
```
```php PHP
$client = new Client();
$prewarm = $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 0,
system: [
[
'type' => 'text',
'text' => 'You are an expert software engineer with deep knowledge of distributed systems...',
'cache_control' => ['type' => 'ephemeral'],
],
],
messages: [['role' => 'user', 'content' => 'warmup']],
);
echo $prewarm->stopReason, PHP_EOL; // "max_tokens"
echo json_encode($prewarm->content), PHP_EOL; // []
echo json_encode($prewarm->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
prewarm = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 0,
system_: [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: {type: "ephemeral"}
}
],
messages: [{role: "user", content: "warmup"}]
)
puts prewarm.stop_reason # :max_tokens
puts prewarm.content # []
puts prewarm.usage
```
API возвращает пустой массив `content`:
```json Output
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [],
"model": "claude-opus-5-5",
"stop_reason": "max_tokens",
"stop_sequence": null,
"usage": {
"input_tokens": 8,
"cache_creation_input_tokens": 5120,
"cache_read_input_tokens": 0,
"cache_creation": {
"ephemeral_5m_input_tokens": 5120,
"ephemeral_1h_input_tokens": 0
},
"iterations": [
{
"input_tokens": 8,
"output_tokens": 0,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 5120,
"cache_creation": {
"ephemeral_5m_input_tokens": 5120,
"ephemeral_1h_input_tokens": 0
},
"type": "message"
}
],
"output_tokens": 0,
"service_tier": "standard",
"inference_geo": "global"
}
}
```
### Типичный сценарий использования
Отправляйте запрос прогрева при запуске приложения (или по расписанию), а затем отправляйте реальные пользовательские запросы после завершения прогрева:
```bash cURL
# Прогрейте кэш при запуске приложения или по расписанию.
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-opus-5-5",
"max_tokens": 0,
"system": [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "warmup"}]
}'
# Позже, когда пользователь отправит сообщение, префикс системной подсказки уже будет в кэше.
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-opus-5-5",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "How do I implement a binary search tree?"}]
}'
```
```bash CLI
# Прогрейте кэш при запуске приложения или по расписанию.
ant messages create --transform usage <<'YAML'
model: claude-opus-5-5
max_tokens: 0
system:
- type: text
text: >-
You are an expert software engineer with deep knowledge of
distributed systems...
cache_control:
type: ephemeral
messages:
- role: user
content: warmup
YAML
# Позже, когда пользователь отправит сообщение, префикс системной подсказки уже будет в кэше.
ant messages create --transform 'content.#(type=="text").text' --raw-output <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
system:
- type: text
text: >-
You are an expert software engineer with deep knowledge of
distributed systems...
cache_control:
type: ephemeral
messages:
- role: user
content: How do I implement a binary search tree?
YAML
```
```python Python
client = anthropic.Anthropic()
SYSTEM_PROMPT = [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"},
}
]
def prewarm_cache() -> None:
"""Call this at application startup or on a scheduled interval."""
client.messages.create(
model="claude-opus-5-5",
max_tokens=0,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": "warmup"}],
)
def respond(user_message: str) -> anthropic.types.Message:
"""The real user request; benefits from a warm cache."""
return client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": user_message}],
)
# Прогрейте кэш до поступления пользовательского трафика.
prewarm_cache()
# Позже, когда пользователь отправит сообщение, префикс системной подсказки уже будет в кэше.
response = respond("How do I implement a binary search tree?")
for block in response.content:
if block.type == "text":
print(block.text)
```
```typescript TypeScript
const client = new Anthropic();
const SYSTEM_PROMPT: Anthropic.TextBlockParam[] = [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: { type: "ephemeral" }
}
];
// Вызывайте это при запуске приложения или по расписанию.
async function prewarmCache(): Promise {
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 0,
system: SYSTEM_PROMPT,
messages: [{ role: "user", content: "warmup" }]
});
}
// Реальный запрос пользователя; выигрывает от прогретого кэша.
async function respond(userMessage: string): Promise {
return client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
system: SYSTEM_PROMPT,
messages: [{ role: "user", content: userMessage }]
});
}
// Прогрейте кэш до поступления пользовательского трафика.
await prewarmCache();
// Позже, когда пользователь отправит сообщение, префикс системной подсказки уже будет в кэше.
const response = await respond("How do I implement a binary search tree?");
const textBlock = response.content.find(
(block): block is Anthropic.TextBlock => block.type === "text"
);
console.log(textBlock?.text);
```
```csharp C#
AnthropicClient client = new();
List systemPrompt =
[
new TextBlockParam
{
Text = "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl = new(),
},
];
// Вызывайте это при запуске приложения или по расписанию.
async Task PrewarmCache() =>
await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 0,
System = new(systemPrompt),
Messages = [new() { Role = Role.User, Content = "warmup" }],
}
);
// Реальный запрос пользователя; выигрывает от прогретого кэша.
async Task Respond(string userMessage) =>
await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new(systemPrompt),
Messages = [new() { Role = Role.User, Content = userMessage }],
}
);
// Прогрейте кэш до поступления пользовательского трафика.
await PrewarmCache();
// Позже, когда пользователь отправит сообщение, префикс системной подсказки уже будет в кэше.
var response = await Respond("How do I implement a binary search tree?");
foreach (var block in response.Content)
{
if (block.TryPickText(out var textBlock))
{
Console.WriteLine(textBlock.Text);
}
}
```
```go Go
var client = anthropic.NewClient()
var systemPrompt = []anthropic.TextBlockParam{
{
Text: "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
}
// Вызывайте это при запуске приложения или по расписанию.
func prewarmCache() error {
_, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 0,
System: systemPrompt,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")),
},
})
return err
}
// Реальный запрос пользователя; выигрывает от прогретого кэша.
func respond(userMessage string) (*anthropic.Message, error) {
return client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: systemPrompt,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock(userMessage)),
},
})
}
func main() {
// Прогрейте кэш до поступления пользовательского трафика.
if err := prewarmCache(); err != nil {
log.Fatal(err)
}
// Позже, когда пользователь отправит сообщение, префикс системной подсказки уже будет в кэше.
response, err := respond("How do I implement a binary search tree?")
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
fmt.Println(textBlock.Text)
}
}
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
List systemPrompt = List.of(TextBlockParam.builder()
.text("You are an expert software engineer with deep knowledge of distributed systems...")
.cacheControl(CacheControlEphemeral.builder().build())
.build());
// Вызывайте это при запуске приложения или по расписанию.
void prewarmCache() {
client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(0)
.systemOfTextBlockParams(systemPrompt)
.addUserMessage("warmup")
.build());
}
// Реальный запрос пользователя; выигрывает от прогретого кэша.
Message respond(String userMessage) {
return client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(systemPrompt)
.addUserMessage(userMessage)
.build());
}
void main() {
// Прогрейте кэш до поступления пользовательского трафика.
prewarmCache();
// Позже, когда пользователь отправит сообщение, префикс системной подсказки уже будет в кэше.
Message response = respond("How do I implement a binary search tree?");
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
$client = new Client();
$systemPrompt = [
[
'type' => 'text',
'text' => 'You are an expert software engineer with deep knowledge of distributed systems...',
'cache_control' => ['type' => 'ephemeral'],
],
];
// Вызывайте это при запуске приложения или по расписанию.
$prewarmCache = fn () => $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 0,
system: $systemPrompt,
messages: [['role' => 'user', 'content' => 'warmup']],
);
// Реальный запрос пользователя; выигрывает от прогретого кэша.
$respond = fn (string $userMessage) => $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
system: $systemPrompt,
messages: [['role' => 'user', 'content' => $userMessage]],
);
// Прогрейте кэш до поступления пользовательского трафика.
$prewarmCache();
// Позже, когда пользователь отправит сообщение, префикс системной подсказки уже будет в кэше.
$response = $respond('How do I implement a binary search tree?');
foreach ($response->content as $block) {
if ($block->type === 'text') {
echo $block->text, PHP_EOL;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
SYSTEM_PROMPT = [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: {type: "ephemeral"}
}
]
# Вызывайте это при запуске приложения или по расписанию.
def prewarm_cache(client)
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 0,
system_: SYSTEM_PROMPT,
messages: [{role: "user", content: "warmup"}]
)
end
# Реальный запрос пользователя; выигрывает от прогретого кэша.
def respond(client, user_message)
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
system_: SYSTEM_PROMPT,
messages: [{role: "user", content: user_message}]
)
end
# Прогрейте кэш до поступления пользовательского трафика.
prewarm_cache(client)
# Позже, когда пользователь отправит сообщение, префикс системной подсказки уже будет в кэше.
response = respond(client, "How do I implement a binary search tree?")
response.content.each do |block|
puts block.text if block.type == :text
end
```
Помните, что TTL кэша по-прежнему действует. Для 5-минутного кэша по умолчанию отправляйте новый запрос прогрева не реже чем раз в 5 минут, чтобы кэш оставался прогретым. При более длительных перерывах между пользовательскими запросами используйте вместо этого [1-часовую длительность кэша](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#1-hour-cache-duration).
### Ограничения
Запрос с `max_tokens: 0` отклоняется с ошибкой `invalid_request_error`, если задан любой из следующих параметров, поскольку каждый из них подразумевает вывод, который невозможно получить при нулевом бюджете токенов:
* `stream: true`
* [Extended thinking (расширенные размышления)](https://platform.claude.com/docs/ru/build-with-claude/extended-thinking) (`thinking.type: "enabled"`)
* [Structured outputs (структурированные выходные данные)](https://platform.claude.com/docs/ru/build-with-claude/structured-outputs) (`output_config.format`)
* `tool_choice` со значением `{"type": "tool", ...}` или `{"type": "any"}`
`max_tokens: 0` также отклоняется внутри запроса [Message Batches](https://platform.claude.com/docs/ru/build-with-claude/batch-processing). Прогрев нацелен на сокращение времени до первого токена, что неприменимо к пакетной обработке, а запись кэша, созданная во время пакетной обработки, скорее всего истечёт до выполнения последующего запроса.
### Замена обходного решения с max\_tokens=1
До появления `max_tokens: 0` некоторые приложения использовали прогревочные вызовы с `max_tokens: 1` для достижения того же эффекта. Подход с `max_tokens: 0` предпочтительнее: вывод не создаётся, поэтому не нужно отбрасывать ответ из одного токена, выходные токены не оплачиваются, а назначение запроса однозначно.
***
## Примеры кэширования подсказок
Чтобы помочь вам начать работу с prompt caching (кэшированием подсказок), в [руководстве по кэшированию подсказок](https://platform.claude.com/cookbook/misc-prompt-caching) приведены подробные примеры и рекомендации.
Следующие фрагменты кода демонстрируют различные шаблоны кэширования подсказок. Эти примеры показывают, как реализовать кэширование в разных сценариях, и помогают понять практическое применение этой функции:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-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?"
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-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?
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-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?",
}
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-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?"
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new MessageCreateParamsSystem(new List
{
new TextBlockParam()
{
Text = "You are an AI assistant tasked with analyzing legal documents.",
},
new TextBlockParam()
{
Text = "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new()
{
Role = Role.User,
Content = "What are the key terms and conditions in this agreement?"
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
Text: "You are an AI assistant tasked with analyzing legal documents.",
},
{
Text: "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What are the key terms and conditions in this agreement?")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class LegalDocumentAnalysisExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.text("You are an AI assistant tasked with analyzing legal documents.")
.build(),
TextBlockParam.builder()
.text(
"Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]"
)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
.addUserMessage("What are the key terms and conditions in this agreement?")
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => 'What are the key terms and conditions in this agreement?'
]
],
model: 'claude-opus-5-5',
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']
]
],
);
echo json_encode($message->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-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?"
}
]
)
puts message.usage
```
Этот пример демонстрирует базовое использование кэширования подсказок: полный текст юридического соглашения кэшируется как префикс, а инструкция пользователя остаётся некэшированной.
Для первого запроса:
* `input_tokens`: количество токенов только в сообщении пользователя
* `cache_creation_input_tokens`: количество токенов во всём системном сообщении, включая юридический документ
* `cache_read_input_tokens`: 0 (при первом запросе попадания в кэш нет)
Для последующих запросов в пределах времени жизни кэша:
* `input_tokens`: количество токенов только в сообщении пользователя
* `cache_creation_input_tokens`: 0 (новый кэш не создаётся)
* `cache_read_input_tokens`: количество токенов во всём закэшированном системном сообщении
Определения инструментов можно кэшировать, разместив `cache_control` на последнем инструменте в массиве `tools`. Все инструменты, определённые до этого инструмента включительно, кэшируются как единый префикс.
```json
{
"model": "claude-opus-5-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" } },
"required": ["location"]
}
},
{
"name": "get_time",
"description": "Get the current time in a given time zone",
"input_schema": {
"type": "object",
"properties": { "timezone": { "type": "string" } },
"required": ["timezone"]
},
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}
```
При первом запросе `cache_creation_input_tokens` отражает количество токенов всех определений инструментов. При последующих запросах в пределах времени жизни кэша эти токены отображаются в `cache_read_input_tokens`.
Подробнее о взаимодействии определений инструментов, `defer_loading` и инвалидации кэша см. в разделе [Использование инструментов с кэшированием подсказок](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-use-with-prompt-caching).
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-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"}
}
]
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-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
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-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'd 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"},
},
],
},
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-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'd 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" }
}
]
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new MessageCreateParamsSystem(new List
{
new TextBlockParam()
{
Text = "...long system prompt",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam("Hello, can you tell me more about the solar system?")),
}),
},
new()
{
Role = 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?"
},
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam("Good to know.")),
new ContentBlockParam(new TextBlockParam()
{
Text = "Tell me more about Mars.",
CacheControl = new CacheControlEphemeral(),
}),
})
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
Text: "...long system prompt",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, can you tell me more about the solar system?")),
anthropic.NewAssistantMessage(anthropic.NewTextBlock("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: anthropic.MessageParamRoleUser,
Content: []anthropic.ContentBlockParamUnion{
anthropic.NewTextBlock("Good to know."),
{OfText: &anthropic.TextBlockParam{
Text: "Tell me more about Mars.",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class ConversationWithCacheControlExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Создаём временную системную подсказку
TextBlockParam systemPrompt = TextBlockParam.builder()
.text("...long system prompt")
.cacheControl(CacheControlEphemeral.builder().build())
.build();
// Создаём параметры сообщения
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(List.of(systemPrompt))
// Первое сообщение пользователя (без управления кэшем)
.addUserMessage("Hello, can you tell me more about the solar system?")
// Ответ ассистента
.addAssistantMessage(
"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?"
)
// Второе сообщение пользователя (с управлением кэшем)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofText(TextBlockParam.builder().text("Good to know.").build()),
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("Tell me more about Mars.")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
)
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
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']
]
]
]
],
model: 'claude-opus-5-5',
system: [
[
'type' => 'text',
'text' => '...long system prompt',
'cache_control' => ['type' => 'ephemeral']
]
],
);
echo json_encode($message->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-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" }
}
]
}
]
)
puts message.usage
```
Этот пример демонстрирует, как использовать кэширование подсказок в многоходовом разговоре.
На каждом ходе последний блок последнего сообщения помечается `cache_control`, чтобы разговор можно было кэшировать инкрементально. Система автоматически находит и использует самую длинную ранее закэшированную последовательность блоков для последующих сообщений. То есть блоки, которые ранее были помечены блоком `cache_control`, позже уже не помечаются им, но всё равно будут считаться попаданием в кэш (а также обновлением кэша!), если обращение к ним произойдёт в течение 5 минут.
Кроме того, обратите внимание, что параметр `cache_control` размещён в системном сообщении. Это гарантирует, что если оно будет вытеснено из кэша (после того как не использовалось более 5 минут), то при следующем запросе оно снова будет добавлено в кэш.
Этот подход полезен для сохранения контекста в продолжающихся разговорах без повторной обработки одной и той же информации.
При правильной настройке в ответе usage каждого запроса вы должны увидеть следующее:
* `input_tokens`: количество токенов в новом сообщении пользователя (будет минимальным)
* `cache_creation_input_tokens`: количество токенов в новых ходах ассистента и пользователя
* `cache_read_input_tokens`: количество токенов в разговоре до предыдущего хода
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-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"}
}
]
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-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.
# Instructions
- Always search for relevant documents before answering
- Provide citations for your sources
- Be objective and accurate in your responses
- If multiple documents contain relevant information, synthesize them
- Acknowledge when information is not available in the knowledge base
cache_control:
type: ephemeral
- type: text
text: |-
# Knowledge Base Context
Here are the relevant documents for this conversation:
## Document 1: Solar System Overview
The solar system consists of the Sun and all objects that orbit it...
## Document 2: Planetary Characteristics
Each planet has unique features. Mercury is the smallest planet...
## Document 3: Mars Exploration
Mars has been a target of exploration for decades...
[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
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-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"},
}
],
},
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-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" }
}
]
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools =
[
new ToolUnion(new Tool()
{
Name = "search_documents",
Description = "Search through the knowledge base",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["query"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Search query" }),
},
Required = ["query"],
},
}),
new ToolUnion(new Tool()
{
Name = "get_document",
Description = "Retrieve a specific document by ID",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["doc_id"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Document ID" }),
},
Required = ["doc_id"],
},
CacheControl = new CacheControlEphemeral(),
}),
],
System = new MessageCreateParamsSystem(new List
{
new TextBlockParam()
{
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",
CacheControl = new CacheControlEphemeral(),
},
new TextBlockParam()
{
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...]",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new() { Role = Role.User, Content = "Can you search for information about Mars rovers?" },
new()
{
Role = Role.Assistant,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new ToolUseBlockParam()
{
ID = "tool_1",
Name = "search_documents",
Input = new Dictionary
{
["query"] = JsonSerializer.SerializeToElement("Mars rovers"),
},
}),
}),
},
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new ToolResultBlockParam()
{
ToolUseID = "tool_1",
Content = "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
}),
}),
},
new()
{
Role = Role.Assistant,
Content = "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
},
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam()
{
Text = "Yes, please tell me about the Perseverance rover specifically.",
CacheControl = new CacheControlEphemeral(),
}),
}),
},
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{
{OfTool: &anthropic.ToolParam{
Name: "search_documents",
Description: anthropic.String("Search through the knowledge base"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"query": map[string]any{
"type": "string",
"description": "Search query",
},
},
Required: []string{"query"},
},
}},
{OfTool: &anthropic.ToolParam{
Name: "get_document",
Description: anthropic.String("Retrieve a specific document by ID"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"doc_id": map[string]any{
"type": "string",
"description": "Document ID",
},
},
Required: []string{"doc_id"},
},
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
},
System: []anthropic.TextBlockParam{
{
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",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
{
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...]",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Can you search for information about Mars rovers?")),
anthropic.NewAssistantMessage(anthropic.NewToolUseBlock(
"tool_1",
map[string]any{"query": "Mars rovers"},
"search_documents",
)),
anthropic.NewUserMessage(anthropic.NewToolResultBlock(
"tool_1",
"Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
false,
)),
anthropic.NewAssistantMessage(anthropic.NewTextBlock("I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.")),
{
Role: anthropic.MessageParamRoleUser,
Content: []anthropic.ContentBlockParamUnion{
{OfText: &anthropic.TextBlockParam{
Text: "Yes, please tell me about the Perseverance rover specifically.",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class MultipleCacheBreakpointsExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Схема инструмента поиска
InputSchema searchSchema = InputSchema.builder()
.properties(
JsonValue.from(
Map.of("query", Map.of("type", "string", "description", "Search query"))
)
)
.putAdditionalProperty("required", JsonValue.from(List.of("query")))
.build();
// Схема инструмента получения документа
InputSchema getDocSchema = InputSchema.builder()
.properties(
JsonValue.from(
Map.of("doc_id", Map.of("type", "string", "description", "Document ID"))
)
)
.putAdditionalProperty("required", JsonValue.from(List.of("doc_id")))
.build();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
// Инструменты с cache control на последнем из них
.addTool(
Tool.builder()
.name("search_documents")
.description("Search through the knowledge base")
.inputSchema(searchSchema)
.build()
)
.addTool(
Tool.builder()
.name("get_document")
.description("Retrieve a specific document by ID")
.inputSchema(getDocSchema)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
// Системные подсказки с cache control отдельно для инструкций и контекста
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.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"
)
.cacheControl(CacheControlEphemeral.builder().build())
.build(),
TextBlockParam.builder()
.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...]"
)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
// История диалога
.addUserMessage("Can you search for information about Mars rovers?")
.addAssistantMessageOfBlockParams(
List.of(
ContentBlockParam.ofToolUse(
ToolUseBlockParam.builder()
.id("tool_1")
.name("search_documents")
.input(JsonValue.from(Map.of("query", "Mars rovers")))
.build()
)
)
)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder()
.toolUseId("tool_1")
.content(
"Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
)
.build()
)
)
)
.addAssistantMessageOfBlockParams(
List.of(
ContentBlockParam.ofText(
TextBlockParam.builder()
.text(
"I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
)
.build()
)
)
)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("Yes, please tell me about the Perseverance rover specifically.")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
)
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
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']
]
]
]
],
model: 'claude-opus-5-5',
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']
]
],
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']
]
],
);
echo json_encode($message->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-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" }
}
]
}
]
)
puts message.usage
```
Этот комплексный пример демонстрирует, как использовать все 4 доступные точки останова кэша для оптимизации разных частей вашей подсказки:
1. **Кэш инструментов** (точка останова кэша 1): параметр `cache_control` в последнем определении инструмента кэширует все определения инструментов.
2. **Кэш повторно используемых инструкций** (точка останова кэша 2): статические инструкции в системной подсказке кэшируются отдельно. Эти инструкции редко меняются между запросами.
3. **Кэш контекста RAG** (точка останова кэша 3): документы базы знаний для «retrieval-augmented generation» (генерации с дополнением результатами поиска), или RAG, кэшируются независимо, что позволяет обновлять документы RAG, не делая недействительным кэш инструментов или инструкций.
4. **Кэш истории разговора** (точка останова кэша 4): последнее сообщение пользователя помечается `cache_control`, чтобы обеспечить инкрементальное кэширование разговора по мере его развития.
Этот подход обеспечивает максимальную гибкость:
* Если вы добавляете новый ход в разговор, не изменяя предыдущее содержимое, повторно используются все четыре сегмента кэша
* Если вы обновляете документы RAG, но сохраняете те же инструменты и инструкции, повторно используются первые два сегмента кэша
* Если вы изменяете разговор, но сохраняете те же инструменты, инструкции и документы, повторно используются первые три сегмента
* Изменения в любой точке останова делают недействительным этот сегмент и всё, что следует за ним, тогда как более ранние закэшированные сегменты остаются действительными
Для первого запроса:
* `input_tokens`: минимальное значение (токены после последней точки останова кэша, в этом примере близко к 0)
* `cache_creation_input_tokens`: токены во всех кэшируемых сегментах (инструменты + инструкции + документы RAG + история разговора)
* `cache_read_input_tokens`: 0 (попаданий в кэш нет)
Для последующих запросов только с новым сообщением пользователя (и с четвёртой точкой останова, перенесённой на это новое последнее сообщение, как в примере):
* `input_tokens`: минимальное значение (токены после последней точки останова кэша, в этом примере близко к 0)
* `cache_creation_input_tokens`: токены в новом сообщении пользователя и предыдущем ходе ассистента (новый кэшируемый сегмент разговора)
* `cache_read_input_tokens`: все ранее закэшированные токены (инструменты + инструкции + документы RAG + предыдущий разговор)
Этот шаблон особенно эффективен для:
* приложений RAG с большими контекстами документов
* агентных систем, использующих несколько инструментов
* длительных разговоров, в которых необходимо сохранять контекст
* приложений, которым нужно независимо оптимизировать разные части подсказки
## Хранение данных
Кэширование подсказок (как автоматическое, так и явное) подходит для «Zero Data Retention» (нулевого хранения данных), или ZDR. Anthropic не хранит исходный текст ваших подсказок или ответов Claude.
Представления кэша KV (key-value, «ключ — значение») и криптографические хеши закэшированного содержимого хранятся только в памяти и не сохраняются на постоянных носителях. Закэшированные записи имеют минимальное время жизни 5 минут (стандартное) или 1 час (расширенное), после чего они удаляются оперативно, хотя и не мгновенно. Записи кэша изолированы между организациями, а в Claude API, Claude Platform on AWS и Microsoft Foundry — также между рабочими пространствами внутри организации.
Сведения о соответствии требованиям ZDR для всех функций см. в разделе [API и хранение данных](https://platform.claude.com/docs/ru/manage-claude/api-and-data-retention).
***
## Часто задаваемые вопросы
**В большинстве случаев достаточно одной точки останова кэша в конце вашего статического содержимого.** Запись в кэш происходит только в помеченном вами блоке. Разместите точку останова на последнем блоке, который остаётся неизменным между запросами, и каждый последующий запрос будет читать эту же запись. Если более поздний блок меняется от запроса к запросу (метка времени, входящее сообщение), размещайте точку останова перед ним, на последнем стабильном блоке.
Несколько точек останова нужны только в следующих случаях:
* растущий разговор отодвигает вашу точку останова на 20 или более блоков от последней записи в кэш, из-за чего предыдущая запись оказывается за пределами lookback window (окна обратного просмотра)
* вы хотите независимо кэшировать разделы, которые обновляются с разной частотой
* вам нужен явный контроль над тем, что кэшируется, для оптимизации затрат
Пример: если у вас есть системные инструкции (редко меняются) и контекст RAG (меняется ежедневно), вы можете использовать две точки останова, чтобы кэшировать их по отдельности.
Нет, сами точки останова кэша бесплатны. Вы платите только за:
* запись содержимого в кэш (на 25% дороже базовых входных токенов для TTL 5 минут)
* чтение из кэша (доля от базовой цены входных токенов, см. [Цены](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#pricing))
* обычные входные токены для некэшированного содержимого
Количество точек останова не влияет на цену; значение имеет только объём кэшируемого и считываемого содержимого.
Ответ usage содержит три отдельных поля входных токенов, которые вместе составляют ваш общий ввод:
```text wrap
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens
```
* `cache_read_input_tokens`: токены, извлечённые из кэша (всё до точек останова кэша, что было закэшировано)
* `cache_creation_input_tokens`: новые токены, записываемые в кэш (в точках останова кэша)
* `input_tokens`: токены **после последней точки останова кэша**, которые не кэшируются
**Важно:** `input_tokens` НЕ отражает все входные токены, а только часть после вашей последней точки останова кэша. Если у вас есть закэшированное содержимое, `input_tokens` обычно будет намного меньше общего объёма ввода.
**Пример:** при закэшированном документе на 200 тыс. токенов и вопросе пользователя на 50 токенов:
* `cache_read_input_tokens`: 200 000
* `cache_creation_input_tokens`: 0
* `input_tokens`: 50
* **Итого:** 200 050 токенов
Эта разбивка крайне важна для понимания как ваших затрат, так и использования rate limit (ограничения скорости). Подробнее см. в разделе [Отслеживание производительности кэша](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#tracking-cache-performance).
Минимальное время жизни кэша (TTL) по умолчанию составляет 5 минут. Это время обновляется при каждом использовании закэшированного содержимого.
Если 5 минут для вас слишком мало, Anthropic также предлагает [TTL кэша в 1 час](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#1-hour-cache-duration).
Время жизни отсчитывается от начала запроса, который записывает или читает запись кэша, а не от окончания его ответа. Время, затраченное на генерацию ответа, засчитывается во время жизни, поэтому окно, в течение которого последующий запрос может повторно использовать кэш, равно времени жизни за вычетом времени генерации.
Если ваши запросы генерируют длинные ответы и следующий запрос может начаться только после истечения времени жизни, используйте [TTL кэша в 1 час](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#1-hour-cache-duration).
В вашей подсказке можно определить до 4 точек останова кэша (с помощью параметров `cache_control`).
Кэширование подсказок поддерживается всеми [активными моделями Claude](https://platform.claude.com/docs/ru/models/overview).
Изменение параметров thinking (размышлений) — переключение режимов или изменение бюджета в расширенном режиме — делает недействительными закэшированные префиксы сообщений, а также может сделать недействительными закэшированные системные подсказки и инструменты, поскольку конфигурация размышлений встраивается в подсказку. Значение [`output_config.effort`](https://platform.claude.com/docs/ru/build-with-claude/effort) ведёт себя так же.
Подробнее об инвалидации кэша см. в разделе [Что делает кэш недействительным](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#what-invalidates-the-cache).
Подробнее о размышлениях, включая их взаимодействие с tool use (использованием инструментов) и кэшированием подсказок, см. в разделе [Размышления и кэширование подсказок](https://platform.claude.com/docs/ru/build-with-claude/thinking#thinking-and-prompt-caching).
Самый простой способ — добавить `"cache_control": {"type": "ephemeral"}` на верхний уровень тела запроса ([автоматическое кэширование](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#automatic-caching)). Кроме того, можно указать хотя бы одну точку останова `cache_control` в отдельных блоках содержимого ([явные точки останова кэша](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#explicit-cache-breakpoints)).
Да, кэширование подсказок можно использовать вместе с другими функциями API, такими как использование инструментов и возможности обработки изображений. Однако изменение наличия изображений в подсказке или изменение настроек использования инструментов нарушит кэш.
Подробнее об инвалидации кэша см. в разделе [Что делает кэш недействительным](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#what-invalidates-the-cache).
Кэширование подсказок вводит новую структуру цен, при которой 5-минутная запись в кэш стоит на 25% дороже базовых входных токенов, 1-часовая запись в кэш стоит в 2 раза больше базовых входных токенов, а попадания в кэш стоят долю от базовой цены входных токенов (множитель для каждой модели см. в разделе [Цены](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#pricing)).
В настоящее время очистить кэш вручную невозможно. Закэшированные префиксы автоматически истекают после как минимум 5 минут бездействия.
Вы можете отслеживать производительность кэша с помощью полей `cache_creation_input_tokens` и `cache_read_input_tokens` в ответе API.
Подробнее об инвалидации кэша, включая список изменений, требующих создания новой записи кэша, см. в разделе [Что делает кэш недействительным](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#what-invalidates-the-cache).
Кэширование подсказок разработано с надёжными мерами обеспечения конфиденциальности и разделения данных:
1. Ключи кэша генерируются с использованием криптографического хеша подсказок до точки управления кэшем. Это означает, что доступ к конкретному кэшу могут получить только запросы с идентичными подсказками.
2. В Claude API, Claude Platform on AWS и Microsoft Foundry кэши изолированы на уровне рабочего пространства внутри организации. В Bedrock и Google Cloud кэши изолированы на уровне организации. В любом случае кэши никогда не используются совместно разными организациями, даже для идентичных подсказок. Подробнее см. в разделе [Хранение и совместное использование кэша](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#cache-storage-and-sharing).
3. Механизм кэширования разработан для сохранения целостности и конфиденциальности каждого уникального разговора или контекста.
4. Использовать `cache_control` в любом месте подсказок безопасно. Чтобы кэширование приводило к чтениям, размещайте точку останова в конце стабильного префикса: если разместить её на блоке, который меняется при каждом запросе (например, на метке времени или произвольном вводе пользователя), каждый раз будет создаваться новая запись, и попаданий никогда не будет.
Эти меры гарантируют, что кэширование подсказок сохраняет конфиденциальность и безопасность данных, обеспечивая при этом преимущества в производительности.
Да, кэширование подсказок можно использовать в запросах [Batches API](https://platform.claude.com/docs/ru/build-with-claude/batch-processing). Однако, поскольку асинхронные пакетные запросы могут обрабатываться параллельно и в любом порядке, попадания в кэш обеспечиваются по принципу «best effort» (по мере возможности).
[1-часовой кэш](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#1-hour-cache-duration) может помочь увеличить число попаданий в кэш. Наиболее экономичный способ его использования следующий:
* Соберите набор запросов сообщений с общим префиксом.
* Отправьте пакетный запрос с одним запросом, содержащим этот общий префикс и блок 1-часового кэша. Это запишет префикс в 1-часовой кэш.
* Как только это завершится, отправьте остальные запросы. Вам придётся отслеживать задание, чтобы узнать, когда оно завершится.
Обычно это лучше, чем использование 5-минутного кэша, поскольку выполнение пакетных запросов часто занимает от 5 минут до 1 часа.
Эта ошибка обычно возникает, если вы обновили SDK или используете устаревшие примеры кода. Кэширование подсказок больше не требует бета-префикса. Вместо:
```python Python
client.beta.prompt_caching.messages.create(**params)
```
Используйте:
```python Python
client.messages.create(**params)
```
Эта ошибка обычно возникает, если вы обновили SDK или используете устаревшие примеры кода. Кэширование подсказок больше не требует бета-префикса. Вместо:
```typescript TypeScript
client.beta.promptCaching.messages.create(/* ... */);
```
Используйте:
```typescript
client.messages.create(/* ... */);
```