Prompt caching on the Claude API: up to 90% off repeated input

Ứng dụng chatbot của bạn có system prompt 3.000 token, bộ định nghĩa tool 2.000 token và tài liệu sản phẩm 20.000 token. Mỗi câu hỏi của người dùng chỉ vài chục token, nhưng bạn trả tiền cho cả 25.000 token phía trước ở mọi request. Prompt caching của Claude API giải quyết đúng việc này: phần đầu prompt lặp lại được lưu lại, các lần sau chỉ trả khoảng 10% giá input cho phần đó (với một số model mới còn thấp hơn). Bài này tóm tắt cách bật, cách tính tiền và các lỗi khiến cache "không bao giờ trúng".

Hai cách bật

Tự động: thêm cache_control ở cấp cao nhất của request; hệ thống tự đặt điểm cache ở block cuối và dời theo khi hội thoại dài thêm. Hợp với chat nhiều lượt.

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": "Bạn là trợ lý hỗ trợ khách hàng...",
  "messages": [ ... ]
}

Thủ công (explicit breakpoint): đặt cache_control lên từng block để kiểm soát chính xác. Hợp khi các phần thay đổi với tần suất khác nhau.

"system": [
  {
    "type": "text",
    "text": "...system prompt dài + tài liệu sản phẩm...",
    "cache_control": {"type": "ephemeral"}
  }
]

Quy tắc cốt lõi

• Thứ tự prefix: tools → system → messages. Cache bao toàn bộ phần đứng trước và gồm cả block có cache_control.
• Tối đa 4 breakpoint mỗi request (cache tự động chiếm 1 slot).
• Ngưỡng tối thiểu: prompt ngắn hơn ngưỡng của model (từ 512 đến 4.096 token tuỳ model) sẽ không được cache và không báo lỗi.
• Khớp 100%: chỉ cần khác một ký tự trước breakpoint là miss.

Giá và thời gian sống

Phép tính nhanh: ghi một lần tốn thêm 25%, nhưng chỉ cần đọc lại một lần đã hoà vốn. Hệ số cache cộng dồn với giảm giá của Batch API. Ngoài tiền, với hầu hết model, token đọc từ cache không tính vào rate limit ITPM, nên throughput hiệu dụng tăng đáng kể.

Điều gì làm mất cache?

Lỗi kinh điển: cache không bao giờ trúng

• Breakpoint đặt trên nội dung thay đổi: ví dụ block có timestamp "Hôm nay là 10:32:15" hoặc tin nhắn người dùng. Hash không bao giờ khớp: bạn trả phí ghi 1,25× mỗi lần mà không bao giờ được đọc. Đặt breakpoint lên block tĩnh cuối cùng, đưa phần động xuống sau.
• Thứ tự key JSON không ổn định: một số ngôn ngữ (Swift, Go) có thể xáo thứ tự key trong tool_use input, gây miss.
• Request song song quá sớm: cache chỉ sẵn sàng sau khi response đầu tiên bắt đầu. Gửi 50 request đồng thời ngay từ đầu thì không request nào được hưởng cache; hãy đợi request đầu.
• Hội thoại thêm quá nhiều block một lượt: hệ thống chỉ lùi tối đa 20 block để tìm entry cũ. Thêm breakpoint gần đó nếu một lượt sinh nhiều block.

Kiểm tra trong response

"usage": {
  "input_tokens": 50,                  // sau breakpoint cuối, không cache
  "cache_creation_input_tokens": 0,    // vừa ghi vào cache
  "cache_read_input_tokens": 25000,    // đọc từ cache
  "output_tokens": 310
}

Tổng input = cache_read + cache_creation + input_tokens. Nếu cả hai trường cache luôn bằng 0, prompt chưa đạt ngưỡng hoặc breakpoint đặt sai.

Áp dụng thế nào?

• Dev: Sắp xếp prompt theo độ ổn định: tool → system → tài liệu → lịch sử → câu hỏi mới. Log tỉ lệ cache_read/tổng input cho mỗi request.
• Tech Lead: Cấm đưa timestamp, request ID vào system prompt. Giữ cố định tham số thinking/effort trong một hội thoại.
• PM: Với chatbot có tài liệu cố định, caching thường là cách giảm chi phí lớn nhất mà không đổi model. Đưa "cache hit rate" vào dashboard chi phí.