Trong ngành kỹ thuật, người ta thường nói "Cache là quy tắc chi phối mọi thứ", và quy tắc tương tự cũng áp dụng cho các tác tử (agent).
Các sản phẩm tác tử chạy lâu dài như Claude Code trở nên khả thi nhờ prompt caching (bộ nhớ đệm lời nhắc), cho phép tái sử dụng các tính toán từ các lượt trao đổi trước đó, từ đó giảm đáng kể độ trễ và chi phí.
Prompt caching là gì, nó hoạt động như thế nào và bạn triển khai nó về mặt kỹ thuật ra sao? Đọc thêm trong bài viết của @RLanceMartin về prompt caching và bản phát hành auto-caching mới của chúng tôi.
Tại Claude Code, chúng tôi xây dựng toàn bộ hệ thống xung quanh prompt caching. Tỷ lệ cache hit cao giúp giảm chi phí và cho phép chúng tôi tạo ra các giới hạn tỷ lệ (rate limits) hào phóng hơn cho các gói đăng ký của mình, vì vậy chúng tôi theo dõi tỷ lệ cache hit và tạo cảnh báo SEV nếu tỷ lệ này quá thấp.
Đây là những bài học (thường không trực quan) mà chúng tôi đã học được từ việc tối ưu hóa prompt caching ở quy mô lớn.
Sắp xếp Prompt của bạn để Caching
Prompt caching hoạt động bằng cách so khớp tiền tố (prefix matching) – API lưu cache mọi thứ từ đầu request cho đến mỗi breakpoint cache_control. Điều này có nghĩa là thứ tự bạn sắp xếp các thành phần có ảnh hưởng rất lớn; bạn muốn càng nhiều request chia sẻ cùng một tiền tố càng tốt.
Cách tốt nhất là đặt nội dung tĩnh trước, nội dung động sau. Đối với Claude Code, cách này trông như sau:
- System prompt tĩnh & Công cụ (được cache toàn cục)
- Claude.MD (được cache trong phạm vi dự án)
- Bối cảnh phiên làm việc (được cache trong phiên đó)
- Tin nhắn hội thoại
Bằng cách này, chúng tôi tối đa hóa số phiên làm việc có thể dùng chung các cache hit.
Nhưng điều này có thể dễ vỡ một cách đáng ngạc nhiên! Các ví dụ về lý do chúng tôi từng phá vỡ thứ tự này bao gồm: đặt timestamp chi tiết trong system prompt tĩnh, xáo trộn thứ tự định nghĩa công cụ một cách không xác định, cập nhật tham số của các công cụ (ví dụ: các tác tử mà AgentTool có thể gọi), v.v.
Sử dụng Messages để Cập nhật
Có thể có những lúc thông tin bạn đưa vào prompt trở nên lỗi thời, ví dụ như nếu có thời gian hoặc người dùng thay đổi một tệp. Bạn có thể muốn cập nhật prompt, nhưng điều đó sẽ dẫn đến cache miss và có thể trở nên khá đắt đỏ cho người dùng.
Hãy cân nhắc xem bạn có thể truyền thông tin này qua messages trong lượt tiếp theo không. Trong Claude Code, chúng tôi thêm một thẻ <system-reminder> vào tin nhắn người dùng tiếp theo hoặc kết quả công cụ với thông tin cập nhật cho mô hình (ví dụ: bây giờ là thứ Tư), giúp bảo toàn cache.
Không Thay đổi Mô hình Giữa Phiên Làm Việc
Prompt cache là duy nhất cho mỗi mô hình, và điều này có thể khiến việc tính toán prompt caching trở nên khá không trực quan.
Nếu bạn đã dùng 100k token trong một cuộc hội thoại với Opus và muốn hỏi một câu khá dễ trả lời, thực tế sẽ tốn kém hơn khi chuyển sang Haiku so với để Opus trả lời, vì chúng tôi cần xây dựng lại prompt cache cho Haiku.
Nếu bạn cần chuyển đổi mô hình, cách tốt nhất là sử dụng các subagent, nơi Opus sẽ chuẩn bị một thông báo "bàn giao" cho mô hình khác về nhiệm vụ cần thực hiện. Chúng tôi thường làm điều này với các tác tử Explore trong Claude Code sử dụng Haiku.
Không bao giờ Thêm hoặc Xóa Công cụ Giữa Phiên
Thay đổi bộ công cụ ở giữa cuộc hội thoại là một trong những cách phổ biến nhất mà mọi người phá vỡ prompt caching. Điều này có vẻ trực quan – bạn chỉ nên cung cấp cho mô hình những công cụ mà bạn nghĩ nó cần ngay lúc đó. Nhưng vì các công cụ là một phần của tiền tố được cache, việc thêm hoặc xóa một công cụ sẽ làm mất hiệu lực cache cho toàn bộ cuộc hội thoại.
Plan Mode — Thiết kế Xoay Quanh Cache
Plan mode là một ví dụ tuyệt vời về việc thiết kế các tính năng xung quanh các ràng buộc caching. Cách tiếp cận trực quan là: khi người dùng vào Plan Mode, hãy chuyển đổi bộ công cụ chỉ bao gồm các công cụ chỉ-đọc. Nhưng điều đó sẽ làm hỏng cache.
Thay vào đó, chúng tôi giữ tất cả các công cụ trong request mọi lúc và sử dụng EnterPlanMode và ExitPlanMode như những công cụ riêng. Khi người dùng bật Plan Mode, agent nhận được một system message giải thích rằng nó đang ở chế độ Plan Mode và hướng dẫn là gì – khám phá codebase, không chỉnh sửa tệp, gọi ExitPlanMode khi hoàn thành kế hoạch. Định nghĩa công cụ không bao giờ thay đổi.
Điều này có một lợi ích bổ sung: vì EnterPlanMode là một công cụ mà mô hình có thể tự gọi, nó có thể tự động vào Plan Mode khi phát hiện một vấn đề khó, mà không làm vỡ cache.
Tìm kiếm Công cụ — Hoãn thay vì Xóa
Nguyên tắc tương tự áp dụng cho tính năng tìm kiếm công cụ của chúng tôi. Claude Code có thể tải hàng tá công cụ MCP, và bao gồm tất cả chúng trong mọi request sẽ rất tốn kém. Nhưng xóa chúng giữa cuộc hội thoại sẽ làm hỏng cache.
Giải pháp của chúng tôi: defer_loading. Thay vì xóa các công cụ, chúng tôi gửi các stub nhẹ – chỉ tên công cụ, với defer_loading: true – mà mô hình có thể "khám phá" thông qua một công cụ ToolSearch khi cần. Các lược đồ công cụ đầy đủ chỉ được tải khi mô hình chọn chúng. Điều này giữ cho tiền tố cache ổn định: các stub tương tự luôn hiện diện theo cùng một thứ tự.
May mắn thay, bạn có thể sử dụng công cụ tìm kiếm công cụ thông qua API của chúng tôi để đơn giản hóa việc này.
Fork Context — Nén (Compaction)
Nén (Compaction) là quá trình xảy ra khi bạn hết dung lượng context window. Chúng tôi tóm tắt cuộc hội thoại cho đến thời điểm đó và tiếp tục một phiên mới với bản tóm tắt đó.
Đáng ngạc nhiên, nén có nhiều trường hợp ngoại lệ với prompt caching có thể gây khó hiểu.
Cụ thể, khi nén, chúng tôi cần gửi toàn bộ cuộc hội thoại đến mô hình để tạo ra một bản tóm tắt. Nếu đây là một API call riêng với một system prompt khác và không có công cụ (đây là cách triển khai đơn giản), thì tiền tố cache từ cuộc hội thoại chính không khớp chút nào. Bạn phải trả toàn bộ giá cho tất cả các token đầu vào đó, làm tăng đáng kể chi phí cho người dùng.
Giải pháp — Fork An toàn Cache
Khi chạy nén, chúng tôi sử dụng chính xác cùng một system prompt, user context, system context và định nghĩa công cụ như cuộc hội thoại gốc. Chúng tôi thêm các tin nhắn hội thoại của gốc vào trước, sau đó thêm prompt nén như một tin nhắn người dùng mới ở cuối.
Từ góc nhìn của API, request này trông gần như giống với request cuối cùng của gốc – cùng tiền tố, cùng công cụ, cùng lịch sử – do đó tiền tố cache được tái sử dụng. Các token mới duy nhất là bản thân prompt nén.
Điều này có nghĩa là chúng tôi cần lưu một "bộ đệm nén" để có đủ dung lượng trong context window bao gồm cả message nén và các token đầu ra của bản tóm tắt.
Nén rất phức tạp, nhưng may mắn thay, bạn không cần phải tự mình học những bài học này – dựa trên những gì học được từ Claude Code, chúng tôi đã xây dựng chức năng nén trực tiếp vào API, vì vậy bạn có thể áp dụng các mẫu này trong ứng dụng của riêng mình.
Bài học Kinh nghiệm
- Prompt caching là so khớp tiền tố. Bất kỳ thay đổi nào ở bất cứ đâu trong tiền tố đều làm mất hiệu lực mọi thứ sau nó. Thiết kế toàn bộ hệ thống của bạn xoay quanh ràng buộc này. Sắp xếp đúng thứ tự và hầu hết việc caching sẽ hoạt động tự động.
- Sử dụng messages thay vì thay đổi system prompt. Bạn có thể muốn chỉnh sửa system prompt để thực hiện những việc như vào Plan Mode, thay đổi ngày tháng, v.v., nhưng thực tế sẽ tốt hơn nếu bạn chèn những thông tin này vào messages trong quá trình hội thoại.
- Không thay đổi công cụ hoặc mô hình giữa cuộc hội thoại. Sử dụng công cụ để mô hình hóa các chuyển đổi trạng thái (như Plan Mode) thay vì thay đổi bộ công cụ. Hoãn tải công cụ thay vì xóa chúng.
- Theo dõi tỷ lệ cache hit giống như bạn theo dõi thời gian hoạt động (uptime). Chúng tôi cảnh báo về sự cố cache và coi chúng như sự cố. Chỉ vài phần trăm tỷ lệ cache miss có thể ảnh hưởng đáng kể đến chi phí và độ trễ.
- Các thao tác fork cần chia sẻ tiền tố của gốc. Nếu bạn cần chạy một tính toán phụ (nén, tóm tắt, thực thi kỹ năng), hãy sử dụng các tham số an toàn cache giống hệt nhau để có thể đạt cache hit trên tiền tố của gốc.
Claude Code được xây dựng xoay quanh prompt caching ngay từ ngày đầu, bạn cũng nên làm như vậy nếu đang xây dựng một agent.
