---
title: Кэширование подсказок
url: https://platform.claude.com/docs/ru/build-with-claude/prompt-caching
description: Кэшируйте префиксы подсказок с помощью `cache_control`, чтобы снизить затраты и задержку, используя автоматическое кэширование или явные точки останова с TTL 5 минут или 1 час.
featureMetadata:
zdr:
eligibility: eligible
note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). Ваши подсказки и выходные данные Claude не хранятся. Представления KV-кэша и криптографические хеши хранятся в памяти в течение TTL кэша и оперативно удаляются после его истечения.
supportedModels:
- claude-fable-5-2
- claude-mythos-5-2
- claude-fable-5-1
- claude-mythos-5-1
- claude-fable-5
- claude-mythos-5
- claude-mythos-preview
- claude-opus-5-5
- claude-opus-5
- claude-sonnet-5-5
- claude-sonnet-5
- claude-haiku-5-5
- claude-haiku-4-5-20251001
- claude-opus-4-8
- claude-opus-4-7
- claude-opus-4-6
- claude-sonnet-4-6
- claude-opus-4-5-20251101
- claude-sonnet-4-5-20250929
supportedPlatforms:
Claude API: stable
Claude Platform on AWS: stable
Claude Models on Google Cloud (Anthropic managed): stable
Amazon Bedrock: stable
Amazon Bedrock (InvokeModel): stable
Claude Models on Google Cloud (Google managed): stable
Microsoft Foundry: stable
---
**Поддержка API**: Использование зависит от продукта.
* **Messages API**: Включается с помощью `cache_control` на верхнем уровне или в блоках.
* **Managed Agents**: Всегда включено. Записи кэша по умолчанию живут 5 минут, а чтение и запись кэша отражаются в использовании сессии.
«Prompt caching» (кэширование подсказок) оптимизирует использование API, позволяя API возобновлять обработку с определённых префиксов в ваших подсказках. Это значительно сокращает время обработки и затраты для повторяющихся задач или подсказок с неизменными элементами.
Существует два способа включить кэширование подсказок:
* **[Автоматическое кэширование](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: 2026-10-21" \
-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 <<'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 UserMessageParam { 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;
// ...
void main() {
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);
IO.println(message.usage());
}
```
```php PHP
use Anthropic\Messages\CacheControlEphemeral;
use Anthropic\Messages\Model;
// ...
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => "Analyze the major themes in 'Pride and Prejudice'."]
],
model: 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: Anthropic::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.2 | $8 / MTok | $10 / MTok | $16 / MTok | $0.20 / MTok1 | $40 / MTok |
| Claude Mythos 5.2 ([limited availability](https://support.claude.com/en/articles/14604842)) | $8 / MTok | $10 / MTok | $16 / MTok | $0.20 / MTok1 | $40 / MTok |
| 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 Claude Models on Google Cloud (Google managed) and Bedrock](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 Claude Models on Google Cloud (Google managed)](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 Claude Models on Google Cloud (Google managed) and Bedrock](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 |
*1 Cache hits and refreshes on Claude Fable 5.2, Claude Mythos 5.2, 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.*
Приведённая выше таблица отражает следующие ценовые множители для кэширования подсказок:
* Токены записи в кэш с TTL 5 минут стоят в 1,25 раза больше базовой цены входных токенов.
* Токены записи в кэш с TTL 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: 2026-10-21" \
-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 <<'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 UserMessageParam { Content = "My name is Alex. I work on machine learning." },
new AssistantMessageParam
{
Content = "Nice to meet you, Alex! How can I help with your ML work today?"
},
new UserMessageParam { 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;
// ...
void main() {
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);
IO.println(message.usage());
}
```
```php PHP
use Anthropic\Messages\CacheControlEphemeral;
use Anthropic\Messages\Model;
// ...
$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: 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: Anthropic::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 час по цене, вдвое превышающей базовую цену входных токенов:
```json
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }
```
### Сочетание с кэшированием на уровне блоков
Автоматическое кэширование совместимо с [явными точками останова кэша](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#explicit-cache-breakpoints). При совместном использовании автоматическая точка останова кэша занимает один из 4 доступных слотов точек останова.
Это позволяет сочетать оба подхода. Например, используйте явную точку останова для кэширования вашей системной подсказки, а автоматическое кэширование пусть обрабатывает разговор:
```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?" }]
}
```
### Что остаётся неизменным
Автоматическое кэширование использует ту же базовую инфраструктуру кэширования. Цены, минимальные пороги токенов, требования к порядку контекста и окно ретроспективного просмотра в 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. Попадание в кэш на блоке 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 процентов от базовой цены входных токенов, с [исключениями для отдельных моделей](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#pricing))
* **Обычные входные токены:** за любой некэшированный контент
Добавление дополнительных точек останова `cache_control` не увеличивает ваши затраты; вы по-прежнему платите ту же сумму в зависимости от того, какой контент фактически кэшируется и читается. Точки останова дают вам контроль над тем, какие разделы могут кэшироваться независимо.
***
## Стратегии кэширования и соображения
### Ограничения кэша
В Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ru/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/ru/build-with-claude/claude-models-on-google-cloud/google-managed) и [Microsoft Foundry](https://platform.claude.com/docs/ru/build-with-claude/claude-in-microsoft-foundry) минимальная длина кэшируемой подсказки составляет:
* 512 токенов для Claude Fable 5.2, [Claude Mythos 5.2](https://platform.claude.com/docs/ru/models/mythos-5-2/overview), 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
* 2 048 токенов для [Claude Mythos Preview](https://anthropic.com/glasswing) и Claude Opus 4.7
* 4 096 токенов для Claude Opus 4.6 и Claude Opus 4.5
* 1 024 токена для 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 ([выведена из эксплуатации, кроме Claude Models on Google Cloud (Google managed) и Bedrock](https://platform.claude.com/docs/ru/about-claude/model-deprecations)), Claude Opus 4 ([выведена из эксплуатации, кроме Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/ru/about-claude/model-deprecations)) и Claude Sonnet 4 ([выведена из эксплуатации, кроме Claude Models on Google Cloud (Google managed) и Bedrock](https://platform.claude.com/docs/ru/about-claude/model-deprecations))
* 4 096 токенов для Claude Haiku 4.5
Эти минимальные значения действуют на каждой платформе, где доступна соответствующая модель.
Более короткие подсказки не могут быть закэшированы, даже если они помечены `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` в ходах пользователя
* Использование инструментов и результаты инструментов: блоки контента в массиве `messages.content` как в ходах пользователя, так и в ходах ассистента
Каждый из этих элементов можно кэшировать либо автоматически, либо пометив его с помощью `cache_control`.
### Что нельзя кэшировать
Хотя большинство блоков запроса можно кэшировать, есть некоторые исключения:
* Блоки размышлений нельзя кэшировать напрямую с помощью `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 отбрасывает блок размышлений, который не [сохраняется](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.2, [Claude Mythos 5.2](https://platform.claude.com/docs/ru/models/mythos-5-2/overview), 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; Claude Models on Google Cloud (Google managed) и Bedrock поддерживают изоляцию кэша на уровне организации. Если вы используете несколько рабочих пространств, пересмотрите свою стратегию кэширования с учётом этого различия.
* **Изоляция организаций и рабочих пространств:** кэши изолированы между организациями. Разные организации никогда не используют кэши совместно, даже если применяют идентичные подсказки. В Claude API, Claude Platform on AWS и Microsoft Foundry кэши также изолированы по рабочим пространствам внутри организации; Claude Models on Google Cloud (Google managed) и Bedrock используют только изоляцию на уровне организации.
* **Точное совпадение:** для попадания в кэш требуются на 100 процентов идентичные сегменты подсказки, включая весь текст и изображения вплоть до блока с управлением кэшем включительно.
* **Генерация выходных токенов:** кэширование подсказок никак не влияет на генерацию выходных токенов. Полученный ответ идентичен тому, который вы получили бы без использования кэширования подсказок.
### Лучшие практики эффективного кэширования
Чтобы оптимизировать производительность кэширования подсказок:
* Начните с [автоматического кэширования](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), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/ru/build-with-claude/claude-models-on-google-cloud/google-managed) и [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-минутный и часовой кэши ведут себя одинаково с точки зрения задержки. Как правило, для длинных документов вы увидите сокращение времени до первого токена.
### Смешивание разных TTL
Вы можете использовать в одном запросе элементы управления кэшем как на 1 час, так и на 5 минут, но с важным ограничением: записи кэша с более длинным TTL должны располагаться перед записями с более коротким TTL (то есть запись кэша на 1 час должна располагаться перед любыми записями кэша на 5 минут).
При смешивании TTL Claude API определяет в вашей подсказке три позиции для выставления счёта:
1. Позиция `A`: количество токенов на последнем в вашей подсказке попадании в кэш (или 0, если попаданий нет).
* Попадание в запись, закэшированную с TTL 5 минут, не засчитывается, если блок `cache_control` с TTL 1 час, расположенный в подсказке дальше этой записи, является промахом кэша.
* Запрос, который читает запись, закэшированную с TTL 5 минут, заново начинает отсчёт её 5-минутного времени жизни, даже если на этот раз запрос задаёт `"ttl": "1h"`.
2. Позиция `B`: количество токенов на последнем после `A` блоке `cache_control` с TTL 1 час (или равно `A`, если таких нет).
3. Позиция `C`: количество токенов на последнем блоке `cache_control`.
Если `B` или `C` больше `A`, это обязательно промах кэша.
С вас взимается плата за:
1. Токены чтения из кэша для `A`.
2. Токены записи в кэш на 1 час для `(B - A)`.
3. Токены записи в кэш на 5 минут для `(C - B)`.
Ниже приведены три примера запросов, у каждого из которых разные попадания и промахи кэша. У каждого получается разная расчётная стоимость, показанная в блоках.
***
## Предварительный прогрев кэша
«Cache pre-warming» (предварительный прогрев кэша) позволяет загрузить вашу системную подсказку или определения инструментов в кэш подсказок до того, как пользователь инициирует реальный запрос. Это может уменьшить штраф к «latency» (задержке) из-за промаха кэша при первом взаимодействии пользователя, снижая «time-to-first-token» (время до первого токена), или TTFT, для приложений, чувствительных к задержке.
### Как это работает
Установите `max_tokens: 0` в вашем запросе. API считывает вашу подсказку в модель и записывает кэш в каждой точке останова `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: 2026-10-21" \
-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 <<'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 UserMessageParam { 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: 2026-10-21" \
-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: 2026-10-21" \
-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 <<'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 <<'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.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 UserMessageParam { Content = "warmup" }],
}
);
// Реальный запрос пользователя; выигрывает от прогретого кэша.
async Task Respond(string userMessage) =>
await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new(systemPrompt),
Messages = [new UserMessageParam { 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 instanceof \Anthropic\Messages\TextBlock) {
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.is_a?(Anthropic::Models::TextBlock)
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`
* [Расширенные размышления](https://platform.claude.com/docs/ru/build-with-claude/extended-thinking) (`thinking.type: "enabled"`)
* [Структурированные выводы](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: 1` для прогрева кэша. Отдавайте предпочтение `max_tokens: 0`, если запрос это допускает: вывод не создаётся, поэтому не нужно отбрасывать однотокенный ответ, выходные токены не тарифицируются, а назначение запроса однозначно.
***
## Примеры кэширования подсказок
Чтобы помочь вам начать работу с кэшированием подсказок, [рецепт кэширования подсказок](https://platform.claude.com/cookbook/misc-prompt-caching) в Claude Cookbook содержит подробные примеры и лучшие практики.
Следующие фрагменты кода демонстрируют различные шаблоны кэширования подсказок. Эти примеры показывают, как реализовать кэширование в различных сценариях, помогая понять практическое применение этой функции:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-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 <<'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 UserMessageParam
{
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;
// ...
void main() {
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);
IO.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: 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: Anthropic::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: 2026-10-21" \
-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 <<'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 UserMessageParam
{
Content = new List
{
new ContentBlockParam(new TextBlockParam("Hello, can you tell me more about the solar system?")),
},
},
new AssistantMessageParam
{
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 UserMessageParam
{
Content = 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?")),
anthropic.NewUserMessage(
anthropic.NewTextBlock("Good to know."),
anthropic.ContentBlockParamUnion{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;
// ...
void main() {
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?"
)
// Второе сообщение пользователя (с управлением кэшем)
.addUserMessageOfContentBlockParams(
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);
IO.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: 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: Anthropic::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 минут без использования, следующий запрос снова добавит его в кэш.
Этот подход полезен для сохранения контекста в текущих диалогах без повторной обработки одной и той же информации.
При правильной настройке вы должны увидеть следующее в ответе об использовании каждого запроса:
* `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: 2026-10-21" \
-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 <<'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 UserMessageParam { Content = "Can you search for information about Mars rovers?" },
new AssistantMessageParam
{
Content = new List
{
new ContentBlockParam(new ToolUseBlockParam()
{
ID = "tool_1",
Name = "search_documents",
Input = new Dictionary
{
["query"] = JsonSerializer.SerializeToElement("Mars rovers"),
},
}),
},
},
new UserMessageParam
{
Content = 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 AssistantMessageParam
{
Content = "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
},
new UserMessageParam
{
Content = 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.")),
anthropic.NewUserMessage(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;
// ...
void main() {
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)
// Инструменты с управлением кэшем на последнем из них
.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()
)
// Системные подсказки с управлением кэшем отдельно для инструкций и контекста
.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?")
.addAssistantMessageOfContentBlockParams(
List.of(
ContentBlockParam.ofToolUse(
ToolUseBlockParam.builder()
.id("tool_1")
.name("search_documents")
.input(JsonValue.from(Map.of("query", "Mars rovers")))
.build()
)
)
)
.addUserMessageOfContentBlockParams(
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()
)
)
)
.addAssistantMessageOfContentBlockParams(
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()
)
)
)
.addUserMessageOfContentBlockParams(
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);
IO.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: 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: Anthropic::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): документы базы знаний кэшируются независимо, что позволяет обновлять документы 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 с большими контекстами документов
* агентных систем, использующих несколько инструментов
* длительных диалогов, в которых необходимо сохранять контекст
* приложений, которым нужно независимо оптимизировать разные части подсказки
## Хранение данных
Кэширование подсказок (как автоматическое, так и явное) соответствует требованиям ZDR. Anthropic не хранит необработанный текст ваших подсказок или ответов Claude.
Представления «KV (key-value) cache» (кэша ключ-значение) и криптографические хэши закэшированного содержимого хранятся только в памяти и не сохраняются на постоянных носителях. Закэшированные записи имеют минимальное время жизни 5 минут (стандартное) или 1 час (расширенное), после чего они удаляются оперативно, хотя и не мгновенно. Записи кэша изолированы между организациями, а в Claude API, Claude Platform on AWS и Microsoft Foundry — также между рабочими пространствами внутри организации.
***
## Часто задаваемые вопросы
**В большинстве случаев достаточно одной точки останова кэша в конце вашего статического содержимого.** Запись в кэш происходит только на помеченном вами блоке. Разместите её на последнем блоке, который остаётся идентичным между запросами, и каждый последующий запрос будет читать эту же запись. Если какой-то последующий блок меняется с каждым запросом (метка времени, входящее сообщение), оставьте точку останова перед ним, на последнем стабильном блоке.
Несколько точек останова нужны только в следующих случаях:
* Растущий диалог отодвигает вашу точку останова на 20 или более блоков от последней записи в кэш, в результате чего предыдущая запись оказывается за пределами окна обратного поиска
* Вы хотите независимо кэшировать разделы, которые обновляются с разной частотой
* Вам нужен явный контроль над тем, что кэшируется, для оптимизации затрат
Пример: если у вас есть системные инструкции (меняются редко) и контекст RAG (меняется ежедневно), вы можете использовать две точки останова, чтобы кэшировать их по отдельности.
Нет, сами точки останова кэша бесплатны. Вы платите только за:
* Запись содержимого в кэш (на 25 процентов дороже базовых входных токенов для TTL 5 минут)
* Чтение из кэша ([долю от базовой цены входных токенов](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#pricing))
* Обычные входные токены для некэшированного содержимого
Количество точек останова не влияет на цену; значение имеет только объём закэшированного и прочитанного содержимого.
Ответ об использовании включает три отдельных поля входных токенов, которые вместе составляют ваш общий ввод:
```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 токенов
Эта разбивка критически важна для понимания как ваших затрат, так и использования ограничения скорости. Подробнее см. в разделе [Отслеживание производительности кэша](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).
Изменение параметров размышлений (переключение режимов или изменение бюджета в расширенном режиме) делает недействительными закэшированные префиксы сообщений, а также может сделать недействительными закэшированные системные подсказки и инструменты, поскольку конфигурация размышлений встраивается в подсказку. Значение [`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).
Подробнее о размышлениях, включая их взаимодействие с использованием инструментов и кэшированием подсказок, см. в разделе [Размышления и кэширование подсказок](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 час стоит 2x от базовых входных токенов, а попадания в кэш стоят [долю от базовой цены входных токенов](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 кэши изолированы по рабочим пространствам внутри организации. В Claude Models on Google Cloud (Google managed) и Bedrock кэши изолированы по организациям. В любом случае кэши никогда не используются совместно разными организациями, даже для идентичных подсказок. Подробнее см. в разделе [Хранение и совместное использование кэша](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#cache-storage-and-sharing).
3. Механизм кэширования разработан для сохранения целостности и конфиденциальности каждого уникального диалога или контекста.
4. Использовать `cache_control` в любом месте ваших подсказок безопасно. Чтобы кэширование приводило к чтениям, размещайте точку останова в конце стабильного префикса: если разместить её на блоке, который меняется при каждом запросе (например, метка времени или произвольный ввод пользователя), каждый раз будет записываться новая запись, в которую никогда не будет попаданий.
Эти меры гарантируют, что кэширование подсказок сохраняет конфиденциальность и безопасность данных, одновременно обеспечивая преимущества в производительности.
Да, вы можете использовать кэширование подсказок с вашими запросами [Message 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 или используете устаревшие примеры кода. Кэширование подсказок доступно в `client.messages`, без бета-префикса. Вместо:
```python Python
client.beta.prompt_caching.messages.create(**params)
```
Используйте:
```python Python
client.messages.create(**params)
```
Эта ошибка обычно появляется, когда вы обновили SDK или используете устаревшие примеры кода. Кэширование подсказок доступно в `client.messages`, без бета-префикса. Вместо:
```typescript TypeScript
client.beta.promptCaching.messages.create(/* ... */);
```
Используйте:
```typescript
client.messages.create(/* ... */);
```
## Доступность
Кэширование подсказок находится в доступе или в бета-версии в зависимости от API и подпадает под нулевое хранение данных и готовность к HIPAA.
### Поддержка API
#### [Messages API](https://platform.claude.com/docs/ru/build-with-claude/working-with-messages)
* Доступность: Доступно
* Использование: Включается с помощью `cache_control` на верхнем уровне или в блоках.
| Статус | Облачные платформы | Модели |
| -------- | ---------------------------- | ----------------------------------------------------------------- |
| Доступно | Все поддерживаемые платформы | [Все модели](https://platform.claude.com/docs/ru/models/overview) |
#### [Managed Agents](https://platform.claude.com/docs/ru/managed-agents/overview)
* Доступность: Всегда включено
* Использование: Записи кэша по умолчанию живут 5 минут, а чтение и запись кэша отражаются в использовании сессии.
| Статус | Облачные платформы | Модели |
| ------ | ---------------------------- | ----------------------------------------------------------------- |
| Бета | Все поддерживаемые платформы | [Все модели](https://platform.claude.com/docs/ru/models/overview) |
### Обработка данных
[Обзор обработки данных](https://platform.claude.com/docs/ru/manage-claude/api-and-data-retention#feature-eligibility)
| Элемент | Нулевое хранение данных | HIPAA |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| Статус | Допускается (кроме [Охватываемые модели](https://platform.claude.com/docs/ru/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)) | Допускается |
| Подробности | Ваши подсказки и выходные данные Claude не хранятся. Представления KV-кэша и криптографические хеши хранятся в памяти в течение TTL кэша и оперативно удаляются после его истечения. [Подробнее](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#data-retention) | — |
Применимые конечные точки:
* `/v1/messages`