Кэширование префиксов запросов OpenAI
Используйте автоматическое кэширование запросов OpenAI, которое снижает стоимость повторяющихся длинных префиксов системного запроса на 50 процентов, и структурируйте запросы для максимальной частоты попаданий в кэш.
«Кэширование префиксов запросов OpenAI» — бесплатный урок AI Engineering Academy на CoddyKit. Это урок 3 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения AI Engineering Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс AI Engineering Academy содержит 4 уроков всего.
Что такое кэширование префикса запроса?
Кэширование префикса запроса — это серверная оптимизация, встроенная в API OpenAI. Она автоматически применяет скидку к токенам префикса запроса, который встречался в недавнем предыдущем запросе. В отличие от кэширования на уровне приложения, при котором возвращается сохранённый ответ, кэширование префикса запроса всё равно вызывает модель, но стоимость входных токенов кэшированной части снижается на 50 процентов. Это уменьшает затраты, не отказываясь от генерации нового ответа.
Как работает кэширование префикса изнутри
Современные LLM представляют запросы в виде KV-кэшей (кэшей ключей и значений) в памяти GPU. Обработка запроса означает вычисление ключей и значений механизма внимания для каждого токена. Если первые N токенов двух последовательных запросов идентичны, OpenAI может повторно использовать KV-кэш первого запроса и пропустить ресурсоёмкие вычисления для этих токенов. API делает это автоматически и прозрачно — если условие выполняется, вы просто платите по более низкой ставке за кэшированные токены.
# No code changes needed to enable prefix caching!
# It is automatic on supported models.
# The API response shows you how many tokens were cached:
# response.usage.prompt_tokens_details.cached_tokens
# Example response usage:
# ChatCompletionUsage(
# prompt_tokens=2048,
# completion_tokens=256,
# total_tokens=2304,
# prompt_tokens_details=PromptTokensDetails(
# cached_tokens=1984, # these tokens were served from KV cache
# audio_tokens=0,
# )
# )Проверка попадания в кэш в ответе
После каждого вызова API проверяйте response.usage.prompt_tokens_details.cached_tokens, чтобы узнать, сколько входных токенов было обслужено из KV-кэша. Если cached_tokens > 0, за эти токены взимается плата со скидкой 50 процентов. Регистрация этого значения позволяет отслеживать фактическую эффективность кэша и со временем рассчитывать экономию от кэширования префикса.
from openai import OpenAI
client = OpenAI()
SYSTEM_PROMPT = 'You are an expert AI engineer assistant. ' * 100 # long system prompt
def call_with_cache_check(user_message: str):
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[
{'role': 'system', 'content': SYSTEM_PROMPT},
{'role': 'user', 'content': user_message},
],
)
usage = response.usage
cached = usage.prompt_tokens_details.cached_tokens if usage.prompt_tokens_details else 0
print(f'Total prompt tokens: {usage.prompt_tokens}')
print(f'Cached tokens: {cached} ({100*cached//usage.prompt_tokens}%)')
return response.choices[0].message.contentПрефикс должен быть полностью идентичен
Кэширование префикса применяется только тогда, когда первые N токенов побайтно идентичны токенам недавнего предыдущего запроса. Даже изменение одного символа в системном запросе делает кэш недействительным. OpenAI кэширует фрагменты по 128 токенов — кэш применяется к полным фрагментам, совпадающим в точности. Поэтому изменяющуюся от запроса к запросу часть запроса следует размещать после длинного стабильного префикса, чтобы максимизировать число кэшированных токенов.
# Optimal structure for prefix caching:
# [LONG STABLE SYSTEM PROMPT] [CACHED DOCUMENTS] [USER QUERY]
# ↑ ↑ ↑
# always same always same varies per request
# → cached at 50% → cached at 50% → not cached, full price
# BAD structure (defeats prefix caching):
# [USER QUERY] [CACHED DOCUMENTS] [LONG STABLE SYSTEM PROMPT]
# ↑ ↑
# changes every request never cached because
# so prefix never matches it comes after the queryСтруктурирование запросов для максимальной эффективности кэша
Чтобы увеличить долю попаданий в кэш, располагайте стабильные части запроса в начале. В системе RAG используйте такой порядок: (1) системный запрос с инструкциями и ролью, (2) найденные документы, изменяющиеся только при существенном изменении запроса, (3) история разговора, (4) пользовательский запрос в самом конце. Один только системный запрос — часто от 500 до 2000 токенов — обычно будет кэшироваться, что позволит сэкономить 25–50 процентов затрат на входные токены.
def build_rag_prompt_for_caching(
system_prompt: str,
retrieved_docs: list[str],
conversation_history: list[dict],
user_query: str,
) -> list[dict]:
# Order: stable → semi-stable → variable
context_block = '\n\n'.join(
f'[Document {i+1}]\n{doc}' for i, doc in enumerate(retrieved_docs)
)
return [
# 1. Stable system prompt (always cached after first request)
{'role': 'system', 'content': system_prompt},
# 2. Context injection as a user message (cached when same docs retrieved)
{'role': 'user', 'content': f'Context documents:\n{context_block}'},
{'role': 'assistant', 'content': 'I have read the documents.'},
# 3. Conversation history (semi-stable)
*conversation_history,
# 4. Current user query (always different → never cached prefix)
{'role': 'user', 'content': user_query},
]Срок хранения и вытеснение из кэша
KV-кэш OpenAI хранится в памяти GPU и использует политику вытеснения. Префиксы, которые не использовались повторно примерно 5–10 минут, вытесняются, поскольку другие запросы занимают память GPU. Поэтому кэширование префикса наиболее выгодно для приложений с высокой пропускной способностью и частыми запросами, использующими один и тот же префикс. В приложениях с небольшим трафиком попаданий в кэш может быть мало, поскольку префикс вытесняется между редко следующими друг за другом запросами.
Поддерживаемые модели и цены
По состоянию на 2025 год кэширование префикса запроса доступно для моделей GPT-4o, GPT-4o-mini, o1 и o3-mini. Стоимость кэшированных токенов для большинства моделей составляет 50 процентов от стандартной цены входных токенов. Минимальная длина префикса, для которого доступно кэширование, — 1024 токена; более короткие префиксы скидки не получают. Всегда проверяйте страницу цен OpenAI, чтобы узнать актуальные тарифы: по мере развития функции цены могут меняться.
# Rough pricing reference (verify at platform.openai.com/pricing)
PRICING = {
'gpt-4o': {
'input_per_1M': 2.50,
'cached_input_per_1M': 1.25, # 50% off
'output_per_1M': 10.00,
},
'gpt-4o-mini': {
'input_per_1M': 0.15,
'cached_input_per_1M': 0.075, # 50% off
'output_per_1M': 0.60,
},
}
def estimate_cost_with_caching(prompt_tokens, cached_tokens, output_tokens, model):
p = PRICING[model]
uncached = (prompt_tokens - cached_tokens) * p['input_per_1M'] / 1_000_000
cached_cost = cached_tokens * p['cached_input_per_1M'] / 1_000_000
output_cost = output_tokens * p['output_per_1M'] / 1_000_000
return uncached + cached_cost + output_costКэширование запросов Anthropic
Anthropic предлагает аналогичную функцию под названием кэширование запросов для моделей Claude, но для её использования необходимо явно указать точки разрыва кэша в запросе с помощью поля cache_control. В отличие от автоматического кэширования OpenAI, здесь вы явно отмечаете части запроса, которые следует кэшировать (до 4 точек разрыва кэша на запрос). Кэшированные токены стоят 10 процентов от стандартной цены входных токенов и хранятся 5 минут.
import anthropic
client = anthropic.Anthropic()
LONG_DOCUMENT = 'This is a very long reference document...' * 500 # 2000+ tokens
response = client.messages.create(
model='claude-sonnet-4-5',
max_tokens=1024,
system=[
{
'type': 'text',
'text': 'You are a helpful assistant.',
},
{
'type': 'text',
'text': LONG_DOCUMENT,
'cache_control': {'type': 'ephemeral'}, # mark for caching
}
],
messages=[{'role': 'user', 'content': 'Summarize the document.'}],
)
print(response.usage.cache_read_input_tokens) # tokens served from cache
print(response.usage.cache_creation_input_tokens) # tokens written to cacheСочетание кэширования префикса с кэшированием на уровне приложения
Кэширование префикса и кэширование на уровне приложения дополняют друг друга. Кэширование префикса снижает стоимость каждого вызова API, но вызов LLM всё равно выполняется. Точные и семантические кэши на уровне приложения полностью устраняют вызовы API для повторяющихся запросов. Используйте кэширование префикса для всех запросов, чтобы снизить стоимость каждого вызова, а поверх него добавьте кэширование на уровне приложения, чтобы полностью устранить вызовы для часто повторяющихся запросов. Вместе эти подходы могут снизить затраты на инфраструктуру ИИ на 60–80 процентов.
# Three-layer cost optimization stack
#
# Layer 1: Exact cache (Redis, hash-based)
# → Eliminates 100% of API cost for identical requests
# → Miss rate: ~60-80% (most queries are unique)
#
# Layer 2: Semantic cache (vector similarity)
# → Eliminates 100% of API cost for semantically similar requests
# → Miss rate: ~40-60% of remaining queries
#
# Layer 3: OpenAI prefix caching (automatic)
# → Reduces input token cost by 50% for long stable prefixes
# → Applies to ALL remaining API calls that escape layers 1 and 2
#
# Combined effect: 60-80% cost reduction in FAQ/support applicationsИзмерение эффективности кэша
Отслеживайте коэффициент эффективности кэша как составную метрику: общее число токенов по полной цене, делённое на общее число фактически оплаченных токенов. Это учитывает все уровни кэширования. Записывайте cached_tokens из каждого ответа API и суммируйте их еженедельно. Если 50 процентов токенов во всех вызовах API кэшируются, система фактически вдвое сокращает затраты на входные токены без каких-либо изменений в коде приложения для кэширования префикса.
from dataclasses import dataclass, field
from typing import ClassVar
@dataclass
class CachingMetrics:
total_prompt_tokens: int = 0
total_cached_tokens: int = 0
app_cache_hits: int = 0
app_cache_misses: int = 0
@property
def prefix_cache_ratio(self) -> float:
if self.total_prompt_tokens == 0:
return 0
return self.total_cached_tokens / self.total_prompt_tokens
@property
def app_cache_hit_rate(self) -> float:
total = self.app_cache_hits + self.app_cache_misses
return self.app_cache_hits / total if total > 0 else 0
def report(self):
print(f'App cache hit rate: {self.app_cache_hit_rate:.1%}')
print(f'Prefix cache ratio: {self.prefix_cache_ratio:.1%}')
savings_multiplier = (1 - self.app_cache_hit_rate) * (1 - 0.5 * self.prefix_cache_ratio)
print(f'Effective cost vs no-cache: {savings_multiplier:.1%}')Когда кэширование префикса не помогает
Кэширование префикса не приносит пользы в следующих случаях: (1) короткие запросы длиной менее 1024 токенов (минимальная длина для кэширования), (2) сильно изменяющиеся префиксы, когда системный запрос меняется для каждого пользователя или запроса, (3) приложения с небольшим трафиком, где KV-кэш вытесняется между запросами, или (4) если вы уже платите минимальную ставку за токены. В таких случаях сосредоточьте усилия по оптимизации на семантическом кэшировании на уровне приложения.
Быстрая проверка
Проверьте, насколько хорошо вы усвоили материал этого урока о кэшировании префикса запроса OpenAI.
Итоги урока
В этом уроке вы узнали, что кэширование префикса запроса OpenAI автоматически снижает стоимость кэшированных входных токенов на 50 процентов, если префикс запроса совпадает с префиксом недавнего предыдущего запроса; чтобы максимизировать число кэшированных токенов, стабильное содержимое должно находиться в начале структуры сообщений (системный запрос, документы, затем пользовательский запрос); а Anthropic требует явных маркеров cache_control для аналогичной функции в Claude. Для максимального снижения затрат сочетайте это с кэшированием на уровне приложения. Далее мы рассмотрим пакетную обработку, маршрутизацию моделей и панели мониторинга затрат, чтобы завершить набор инструментов оптимизации.
Изучай Python с ИИ-репетитором — бесплатно
Пиши и запускай код прямо в браузере, получай мгновенную помощь от ИИ-репетитора 24/7 и продолжи учиться на сайте или в приложении.
- Курсы
- 30
- Уроки
- 120
Часто задаваемые вопросы
Урок «Кэширование префиксов запросов OpenAI» бесплатный?
Да — полный текст урока «Кэширование префиксов запросов OpenAI» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс AI Engineering Academy, подпишись на CoddyKit PRO. Курс AI Engineering Academy содержит 4 уроков всего.
Чему я научусь в уроке «Кэширование префиксов запросов OpenAI»?
Используйте автоматическое кэширование запросов OpenAI, которое снижает стоимость повторяющихся длинных префиксов системного запроса на 50 процентов, и структурируйте запросы для максимальной частоты… Ты практикуешь AI Engineering Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.
Нужен ли мне опыт, чтобы начать AI Engineering Academy?
Предыдущий опыт не требуется. AI Engineering Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 3 из 4.
Сколько времени занимает урок «Кэширование префиксов запросов OpenAI»?
Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.
Можно ли писать и запускать код в этом уроке AI Engineering Academy?
Да. Каждый урок AI Engineering Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.
Все уроки этого курса
- Точное кэширование с Redis
- Семантическое кэширование с эмбеддингами
- Кэширование префиксов запросов OpenAI
- Пакетная обработка, маршрутизация моделей и панели расходов