From budget_tokens to adaptive thinking + effort on the Claude API

Nếu code của bạn vẫn gửi thinking: {"type": "enabled", "budget_tokens": 10000} lên Claude API, đã đến lúc xem lại. Theo tài liệu Anthropic, cách "đặt ngân sách token cho suy nghĩ" (extended thinking thủ công) đã deprecated trên dòng 4.6 và bị từ chối với lỗi 400 từ Claude 4.7 trở đi. Thay vào đó là adaptive thinking: model tự quyết có cần nghĩ hay không và nghĩ bao nhiêu, còn bạn điều khiển độ "chịu khó" bằng một tham số duy nhất là effort. Bài này giải thích cơ chế, cách migrate và cách chọn mức effort.

Hai núm điều khiển: thinking và effort

Điểm quan trọng: effort ảnh hưởng mọi token output, không chỉ thinking. Effort thấp thường đồng nghĩa ít tool call hơn, ít giải thích hơn, đi thẳng vào hành động. Effort là tín hiệu hành vi, không phải trần token cứng; max_tokens mới là giới hạn cứng.

Migrate trong 3 dòng

// Trước (manual extended thinking)
{ "thinking": { "type": "enabled", "budget_tokens": 10000 } }

// Sau (adaptive thinking)
{
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "high" }
}

Khác biệt hành vi cần biết: với ngân sách cố định, Claude nghĩ ở mọi request. Với adaptive, ở effort thấp model có thể bỏ qua suy nghĩ hoàn toàn cho câu hỏi dễ. Nếu bạn dùng beta header interleaved-thinking-2025-05-14, có thể bỏ: adaptive tự xen kẽ suy nghĩ giữa các lần gọi tool.

Mặc định khác nhau theo model

• Phần lớn model hỗ trợ effort mặc định là high; Claude Opus 5.5 và Haiku 5.5 mặc định medium. Bỏ trống tham số trên Opus 5.5 nghĩa là chạy thấp hơn một bậc so với Opus 5.
• Trên nhiều model thế hệ 5.x, thinking luôn bật và không gửi được disabled (trả 400). Sonnet 5.5 có kiểu riêng between_tools để tắt suy nghĩ đầu câu trả lời; Haiku 5.5 chấp nhận disabled ở effort từ high trở xuống.
• display mặc định là omitted trên các model mới: khối thinking trả về với nội dung rỗng, chỉ còn signature mã hoá. Muốn xem tóm tắt thì đặt "display": "summarized".

Chọn mức effort

Khuyến nghị chung của Anthropic: đặt effort tường minh thay vì dựa vào mặc định, và chạy "effort sweep" trên bộ eval của bạn khi đổi model, thay vì bê nguyên cấu hình cũ sang.

Chi phí và các bẫy

• Trả tiền cho toàn bộ suy nghĩ: token thinking tính là output token, kể cả khi display: omitted hoặc bạn chỉ thấy bản tóm tắt. Số token bị tính sẽ không khớp với số token bạn nhìn thấy.
• Đặt max_tokens đủ rộng: thinking tính chung vào max_tokens. Với effort cao, đặt quá thấp dễ bị cắt giữa chừng.
• Prompt cache: đổi effort cấp request hoặc đổi chế độ thinking giữa các lượt sẽ làm mất cache. Giữ cố định trong một hội thoại dài; một số model 5.x có tính năng đổi effort theo từng message (beta) mà vẫn giữ cache.
• Tool use: phải gửi lại khối thinking/redacted_thinking nguyên vẹn. Sửa, lọc, đảo thứ tự sẽ gặp lỗi 400.
• Request dài: với effort cao và output lớn, dùng streaming hoặc Batch API để tránh timeout mạng.

Áp dụng thế nào?

• Dev: grep code tìm budget_tokens, thay bằng adaptive + effort tường minh. Ghi log usage để theo dõi phần thinking thực tế bị tính phí.
• Tech Lead: Thiết lập effort theo loại việc: low cho subagent/phân loại, medium/high cho agent chính. Chạy eval trước khi nâng model.
• PM: Effort là núm vặn chi phí–chất lượng rõ ràng nhất. Thử hạ một bậc cho tính năng ít quan trọng, đo xem người dùng có nhận ra không.