Cache diagnostics: tìm đúng nguyên nhân prompt cache bị trượt
Tóm tắt
Cache diagnostics so sánh hai request liên tiếp và chỉ ra điểm khác đầu tiên khiến cache trượt: model, system prompt, tools hay messages. Bật ở mọi lượt, sửa theo loại báo về, và nhớ thủ phạm hay gặp là timestamp trong system prompt.
Bạn đã bật prompt caching, hoá đơn vẫn cao, và cache_read_input_tokens cứ về 0 mà không rõ tại sao. Có thể là một timestamp chèn vào system prompt, một tool bị đổi thứ tự, hay lịch sử hội thoại bị sửa. Trước đây bạn chỉ còn cách đoán. Cache diagnostics của Claude API so sánh hai request liên tiếp và cho biết chính xác chỗ nào khác nhau, để bạn sửa đúng gốc rễ.
Bật thế nào?
- Thêm object
diagnosticsvào mọi lượt. Lượt đầu:{"previous_message_id": null}. Các lượt sau: truyềnidcủa response lượt trước. - Không còn cần beta header (header cũ vẫn được chấp nhận).
- Khi streaming, kết quả nằm trong sự kiện
message_start.
r2 = client.beta.messages.create(
model="claude-opus-5-5", max_tokens=1024,
cache_control={"type": "ephemeral"}, system=SYSTEM,
messages=[...],
diagnostics={"previous_message_id": r1.id},
)
if r2.diagnostics and r2.diagnostics.cache_miss_reason:
print(r2.diagnostics.cache_miss_reason.type)Đọc kết quả
cache_miss_reason.type | Nghĩa là | Cách sửa |
|---|---|---|
model_changed | Model khác lượt trước (router, A/B test, fallback) | Giữ nguyên model trong một hội thoại có cache |
system_changed | System prompt khác, thường do chèn timestamp hay request ID | Giữ system prompt cố định từng byte, đưa dữ liệu động vào message user sau breakpoint |
tools_changed | Thêm, bớt, đổi thứ tự tool, hoặc schema serialize không cố định | Cùng danh sách tool, cùng thứ tự, schema sắp xếp key cố định |
messages_changed | Một message cũ bị sửa, xoá, đổi thứ tự thay vì nối thêm | Coi lịch sử là chỉ nối thêm; gửi lại nguyên văn nội dung assistant và tool result |
previous_message_not_found | Không có dấu vân tay cho ID trước (lượt trước không bật diagnostics, khác workspace, quá lâu) | Bật diagnostics mọi lượt, giữ các lượt gần nhau |
unavailable | Không có thông tin, ví dụ tham số khác như tool_choice, thinking thay đổi | Giữ cố định các tham số ảnh hưởng prompt |
API chỉ báo điểm khác đầu tiên; sửa nó trước, các điểm sau có thể đang bị che. Các loại *_changed kèm cache_missed_input_tokens ước lượng lượng token bị mất cache.
Kết hợp với usage
| Diagnostics | Cache read | Diễn giải |
|---|---|---|
null | Cao | Ổn, prefix ổn định |
null | Thấp/0 | Request giống nhau nhưng cache đã hết hạn: rút ngắn khoảng nghỉ hoặc dùng TTL 1 giờ |
Loại *_changed | Thấp/0 | Request đã đổi, sửa theo loại |
Giới hạn
- Chỉ có trên Claude API trực tiếp, không có trên Bedrock hay Google Cloud (Google managed).
- Dấu vân tay chỉ lưu ngắn hạn, cùng tổ chức và workspace; chỉ gồm hash và ước lượng token, không lưu nội dung prompt.
- Hội thoại rất dài với thay đổi nằm sâu có thể trả
unavailable. - Không bao giờ làm request thất bại; chỉ là thông tin bổ sung.
Áp dụng thế nào?
- Dev: Bật diagnostics trong môi trường staging, log
cache_miss_reasonmỗi lượt để tìm lỗi phá cache. - Tech Lead: Thêm cảnh báo khi tỷ lệ
*_changedtăng sau mỗi lần deploy prompt mới. - PM: Khi chi phí API tăng bất thường, đây là công cụ đầu tiên cần dùng trước khi đổi model.
Nguồn & tham khảo
- Cache diagnostics — Claude Docs