Bộ nhớ đệm prompt Claude — mức giá, đối tượng usage và lý do tỷ lệ hit giảm phía sau gateway

Bộ nhớ đệm lời nhắc là đòn bẩy đơn lẻ lớn nhất trên hóa đơn của một tác vụ, và cũng là thứ có khả năng âm thầm không hoạt động nhất. Nếu đánh dấu đúng, phần lặp lại trong yêu cầu của bạn được tính bằng một phần mười mức phí đầu vào. Nếu đánh dấu sai — hoặc định tuyến qua thứ viết lại tiền tố — phần đó bị tính cao hơn mức thông thường, vì bạn đang trả tiền để ghi các mục bộ nhớ đệm mà không ai đọc.

Cơ chế này đã được tài liệu hóa đầy đủ ở nơi khác. Điều không được tài liệu hóa ở đâu là những gì thay đổi khi yêu cầu đi qua gateway, vốn là tình huống của hầu hết người đọc trang này. Cả hai phần đều ở bên dưới.

Tài liệu tham chiếu để làm điều này trên Kunavo — các trường của yêu cầu, giá bộ nhớ đệm của từng mô hình và cách kiểm tra bằng hai yêu cầu — là tài liệu về bộ nhớ đệm prompt; trang này nói về lý do bộ nhớ đệm không còn đem lại lợi ích.

Tóm tắt cơ chế

Bạn đánh dấu một tiền tố ổn định — lời nhắc hệ thống, lược đồ công cụ, tài liệu — và nhà cung cấp lưu dạng đã xử lý của nó. Yêu cầu tiếp theo có tiền tố khớp chính xác sẽ đọc lại tiền tố đó thay vì xử lý lại.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "..." }]
}

Hai thuộc tính thực hiện toàn bộ công việc và gây ra mọi rắc rối. Việc khớp dựa trên tiền tố, nên bất cứ thay đổi nào ở phần đầu đều làm mất hiệu lực của mọi phần sau đó. Một mục cũng có thời gian tồn tại, nên cuộc trò chuyện có khoảng cách dài giữa các lượt sẽ xây dựng lại thay vì đọc lại.

Chi phí

Cột thứ ba là tỷ lệ tiêu chuẩn: một lần đọc có giá bằng một phần mười đầu vào. Cột thứ tư cũng là tiêu chuẩn — một lần ghi bộ nhớ đệm có giá 1,25× đầu vào, là hệ số Anthropic liệt kê cho mục năm phút — và vì cả hai tỷ lệ đều áp dụng cho giá đầu vào của Kunavo, mỗi tỷ lệ có cùng mức chiết khấu so với bảng giá Anthropic như đầu vào của mô hình. Điểm Kunavo khác Anthropic là mục một giờ: Anthropic liệt kê lần ghi đó ở mức 2× đầu vào, còn Kunavo tính ở mức 1,25× tương tự. Điều này đặc biệt quan trọng với khối lượng công việc thường xuyên xây dựng lại — các tác nhân chạy trong thời gian dài, cuộc trò chuyện chậm, bất kỳ thứ gì có tiền tố thay đổi liên tục — vì đó là các khối lượng công việc mà lần ghi, chứ không phải lần đọc, chiếm phần chính trên hóa đơn bộ nhớ đệm.

Cả hai con số đều được đọc từ danh mục tại thời điểm hiển thị, cùng nguồn mà bảng giá và công cụ tính Claude đọc — không có mức giá nào được nhập thủ công trên trang này.

Đọc đối tượng usage

Đừng suy luận hành vi bộ nhớ đệm từ hóa đơn; mọi phản hồi đều cho bạn biết trực tiếp, và ba số lượng token là toàn bộ chẩn đoán.

// The four numbers that tell you whether caching is working.
// Read them from every response before you tune anything.
"usage": {
  "input_tokens": 312,                     // billed at the input rate
  "cache_creation_input_tokens": 0,        // billed at the write rate
  "cache_read_input_tokens": 24106,        // billed at the read rate
  "output_tokens": 890
}

// A healthy cached agent turn looks like the above: a small
// input_tokens, a large cache_read, and a zero creation.
// If cache_creation is large on EVERY turn, the cache is being
// rebuilt each time and you are paying more, not less.

Vì sao tỷ lệ hit giảm phía sau gateway

Bộ nhớ đệm nằm tại upstream đã tạo ra nó, còn việc khớp tiền tố là chính xác. Hai sự thật đó cùng nhau tạo ra ba dạng lỗi không bao giờ xảy ra khi bạn gọi trực tiếp một nhà cung cấp:

Định tuyến đã thay đổi. Nếu các yêu cầu liên tiếp đến các upstream khác nhau, yêu cầu thứ hai không tìm thấy bộ nhớ đệm — mục mà yêu cầu thứ nhất ghi không hiển thị ở nơi yêu cầu thứ hai chạy. Điều này không xuất hiện trong nhật ký của bạn và chỉ thể hiện qua số lượng tạo bộ nhớ đệm lẽ ra phải là số lượng đọc. Đây là nguyên nhân phổ biến nhất, cũng là lý do gateway tự do định tuyến lại giữa các upstream có thể rẻ hơn theo token nhưng đắt hơn theo phiên.

Có thứ gì đó được chèn trước tiền tố của bạn. Một lớp viết lại thông báo hệ thống, chuẩn hóa định nghĩa công cụ hoặc sắp xếp lại các trường sẽ tạo ra tiền tố khác, và tiền tố khác là cache miss. Không có lỗi nào xảy ra; hóa đơn chỉ tăng lên.

Khoảng cách dài hơn thời gian tồn tại của mục. Một tác vụ suy nghĩ vài phút giữa các lượt có thể xây dựng lại mỗi lần. Đây là thuộc tính của khối lượng công việc chứ không phải gateway, nhưng nó tương tác xấu với nguyên nhân đầu tiên: một lần xây dựng lại cũng là một cơ hội định tuyến lại.

Cách chẩn đoán cả ba trường hợp là như nhau — theo dõi cache_creation_input_tokens trong suốt một phiên. Giá trị luôn cao và không thay đổi nghĩa là bạn đang xây dựng lại. Giá trị cao một lần rồi bằng 0 sau đó nghĩa là bộ nhớ đệm đang hoạt động. Trên Kunavo, chi phí cho từng yêu cầu và số token được lưu trong bộ nhớ đệm có trong trang thống kê sử dụng, còn tài liệu tham khảo về bộ nhớ đệm có thông tin chi tiết cho từng điểm cuối.

Cần làm gì

Giữ tiền tố được lưu trong bộ nhớ đệm thực sự ổn định — đặt mọi thứ thay đổi theo từng yêu cầu sau khối được đánh dấu, không bao giờ đặt trước nó. Gom các lượt của tác vụ gần nhau hơn khi có thể, vì thời gian nhàn rỗi là kẻ thù của mục có thời gian tồn tại ngắn. Và đo lường toàn bộ phiên thay vì một yêu cầu: bộ nhớ đệm là thuộc tính của một chuỗi, còn ước tính theo từng yêu cầu không thể thấy điều đó. Công cụ tính chi phí token Claude có trường token được lưu trong bộ nhớ đệm chính vì lý do này — đặt nó thành phần lời nhắc thực sự lặp lại và con số hằng tháng sẽ không còn là hư cấu.

Câu hỏi thường gặp