Prompt Caching — Tối ưu chi phí Claude API

Prompt Caching là gì?

Prompt Caching là tính năng của Claude API cho phép lưu trữ các phần tĩnh của prompt vào bộ nhớ cache, để các request tiếp theo không cần xử lý lại phần đó. Khi một phần prompt đã được cache, chi phí đọc từ cache chỉ bằng 10% so với xử lý từ đầu — đồng thời giảm đáng kể latency.

Đây là tính năng đặc biệt hữu ích khi bạn có system prompt dài, nhiều tài liệu tham chiếu, hoặc few-shot examples lặp đi lặp lại trong mỗi request.

Cách hoạt động

Bạn đánh dấu các phần prompt cần cache bằng cache_control: { type: "ephemeral" }. Claude sẽ tạo một "breakpoint" tại vị trí đó và cache tất cả nội dung từ đầu đến breakpoint.

Cơ chế cache breakpoints

• Cache được tạo tại điểm cache_control cuối cùng trong chuỗi prefix
• Mỗi request có thể có tối đa 4 cache breakpoints
• Cache có giá trị trong 5 phút kể từ lần đọc cuối cùng (TTL sliding window)
• Kích thước tối thiểu để cache: 1024 tokens (Haiku 3.5) hoặc 2048 tokens (Sonnet 4, Opus 4)

Pricing — Cache vs No Cache

Lần đầu cache sẽ tốn thêm 25% so với không cache. Từ lần thứ hai trở đi, bạn tiết kiệm 90%. Vì vậy cache có lợi khi nội dung được tái sử dụng ít nhất 2 lần trong vòng 5 phút.

Những gì có thể cache

1. System prompt dài

Trường hợp phổ biến nhất — system prompt chứa hướng dẫn chi tiết, persona, hoặc background context:

import anthropic

client = anthropic.Anthropic()

# System prompt 3000+ token — được cache
system_prompt = """
[Toàn bộ hướng dẫn chi tiết cho AI assistant, quy tắc ứng xử,
kiến thức domain cụ thể, cách xử lý các tình huống đặc biệt...
— nội dung dài 2000-5000 tokens]
"""

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": system_prompt,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": user_question}]
)

2. Tool definitions

Khi có nhiều tools với descriptions dài, cache tool definitions tiết kiệm đáng kể:

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=[
        {
            "name": "search_database",
            "description": "...",  # Mô tả dài
            "input_schema": {...}
        },
        # ... nhiều tools khác
    ],
    # Tool definitions được tự động cache nếu đủ dài
    # Hoặc dùng cache_control trong tool definition
    messages=[...]
)

3. Long context / tài liệu tham chiếu

Cache tài liệu dài để hỏi nhiều câu hỏi về cùng một tài liệu:

with open("legal_document.txt", "r") as f:
    document = f.read()

def ask_about_document(question):
    return client.messages.create(
        model="claude-opus-4",
        max_tokens=2048,
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "text",
                        "text": f"Tài liệu:

{document}",
                        "cache_control": {"type": "ephemeral"}
                    },
                    {
                        "type": "text",
                        "text": f"
Câu hỏi: {question}"
                    }
                ]
            }
        ]
    )

# Câu hỏi 1: cache write (tốn thêm 25%)
r1 = ask_about_document("Điều khoản thanh toán là gì?")
# Câu hỏi 2: cache read (tiết kiệm 90%)
r2 = ask_about_document("Thời hạn hợp đồng bao lâu?")

4. Few-shot examples

Cache các ví dụ mẫu trong conversation history:

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": few_shot_examples,  # 10-20 ví dụ dài
                "cache_control": {"type": "ephemeral"}
            }
        ]
    },
    {"role": "assistant", "content": "Đã hiểu format. Sẵn sàng giúp bạn."},
    {"role": "user", "content": actual_user_request}
]

Cache Hit/Miss Headers

Kiểm tra trạng thái cache qua usage object trong response:

response = client.messages.create(...)

usage = response.usage
print(f"Input tokens: {usage.input_tokens}")
print(f"Cache creation tokens: {usage.cache_creation_input_tokens}")
print(f"Cache read tokens: {usage.cache_read_input_tokens}")

# Tính chi phí thực tế
if usage.cache_read_input_tokens > 0:
    print("Cache HIT — đang đọc từ cache")
elif usage.cache_creation_input_tokens > 0:
    print("Cache WRITE — đang tạo cache mới")

Mô hình tính toán chi phí tiết kiệm

Ví dụ minh họa cho ứng dụng customer support với system prompt 5000 tokens và trung bình 100 requests/giờ (Sonnet 4):

Không cache: 100 requests × 5000 tokens × $3/M = $1.50/giờ

Có cache (1 cache write + 99 cache reads):

• Cache write: 5000 × $3.75/M = $0.019
• Cache reads: 99 × 5000 × $0.30/M = $0.149
• Tổng: ~$0.17/giờ

Tiết kiệm hơn 88% chi phí input tokens cho system prompt.

Best Practices

Đặt cache breakpoint đúng vị trí

Cache breakpoint nên đặt ở cuối phần nội dung ổn định (không thay đổi). Nội dung thay đổi (user message, dynamic context) phải đặt SAU breakpoint:

# ĐÚNG: Static content trước, dynamic content sau
messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": STATIC_DOC, "cache_control": {"type": "ephemeral"}},
            {"type": "text", "text": dynamic_user_question}  # Không cache
        ]
    }
]

# SAI: Dynamic content trước breakpoint sẽ làm vô hiệu hóa cache
# (cache key bao gồm tất cả content trước breakpoint)

TTL và warm-up

• Cache hết hạn sau 5 phút không được đọc
• Với traffic thấp, cân nhắc gửi "warm-up request" định kỳ để giữ cache sống
• Cache không được persist qua API restarts — plan cho cache misses

Kết hợp với Tool Use

Cache system prompt + tool definitions, để user message và dynamic context không cache:

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=[
        {"type": "text", "text": static_instructions, "cache_control": {"type": "ephemeral"}}
    ],
    tools=large_tool_set,  # Cũng được cache tự động
    messages=[{"role": "user", "content": user_input}]
)

Limitations

• TTL chỉ 5 phút — không phù hợp cho cache giữa các phiên làm việc cách xa nhau
• Minimum token threshold: 1024 (Haiku) hoặc 2048 (Sonnet/Opus)
• Cache không share giữa các API key khác nhau
• Tối đa 4 breakpoints per request
• Cache content bị xóa hoàn toàn khi Anthropic deploy model updates

Kết luận

Prompt Caching là một trong những tính năng tối ưu chi phí hiệu quả nhất của Claude API. Đối với bất kỳ ứng dụng nào có system prompt trên 2000 tokens hoặc dùng nhiều tài liệu tham chiếu, việc bật caching là gần như bắt buộc trong môi trường production. Chi phí lần đầu (cache write) tăng 25%, nhưng từ lần thứ hai trở đi tiết kiệm 90% — với traffic thực tế, ROI thường đạt được chỉ sau vài request đầu tiên.