tiktoken đếm thiếu token Claude: 37/418 request vỡ limit

Một job digest chạy đêm chết lúc 2 giờ 14 sáng với lỗi 400 và thông điệp prompt is too long. Packer đã đo prompt đó ở 181.874 token, nằm thoải mái dưới cửa sổ 200K. Claude báo con số thật là 207.431.

Khoảng chênh 14% đó đến từ một quyết định quen thuộc với rất nhiều pipeline LLM đang chạy production: đếm token Claude bằng tiktoken. Nó nhanh, chạy local, và đã có sẵn trong gần như mọi môi trường Python.

Vì sao tiktoken đếm thiếu

Theo tác giả bài gốc trên Dev.to: "tiktoken is OpenAI's tokenizer. Using cl100k_base to count Claude tokens gives you a different vocabulary's answer, not an approximation of Claude's." Hai tokenizer train trên dữ liệu khác nhau với merge rule khác nhau thì sẽ bất đồng, và mức bất đồng phụ thuộc vào nội dung.

Ông lấy mẫu 600 chunk từ chính input của job, đếm song song bằng cl100k_base và bằng endpoint count_tokens của Anthropic. Tỷ lệ Claude chia tiktoken theo loại nội dung:

Loại nội dung	Số chunk	Tỷ lệ trung vị	Chunk tệ nhất
Markdown docs, commit message	180	1,09	1,15
Python source	210	1,16	1,24
TypeScript source	110	1,17	1,26
JSON, lockfile, fixture	100	1,27	1,38
Tổng	600	1,14	1,38

Chi tiết đáng lo nhất không nằm ở độ lớn mà ở dấu: trên corpus này tỷ lệ chưa bao giờ xuống dưới 1,0. tiktoken không đếm thừa lần nào. Sai số một chiều thì không bao giờ tự triệt tiêu.

Vì sao chỉ một phần request gãy

Đếm thiếu 14% trên một prompt mới đầy nửa cửa sổ thì không chạm giới hạn nào cả. Trong 418 request qua 19 đêm, 357 request không bao giờ lấp đầy budget và không cái nào fail. 61 request còn lại lấp đầy budget, và 37 trong số đó nổ.

Có một khoản overhead mà packer không hề đếm: ba tool definition cộng thêm 1.180 token chưa từng đi qua bộ đếm nào. Tool schema là một phần của input, kể cả khi bạn không nghĩ về nó như text. System prompt thì cũng được đếm bằng tiktoken, nên mang đúng sai số đó.

Sai lệch còn chảy sang chi phí. Dashboard của tác giả nhân số tiktoken với đơn giá input và báo 41,20 USD cho tháng đó. Hoá đơn thật là 46,90 USD.

Cách đếm đúng

Anthropic không ship tokenizer local cho các model Claude hiện tại, nên không có thư viện offline nào cho con số chính xác. Cách còn lại là gọi endpoint messages.count_tokens với đúng model, system prompt, messages và tools sắp gửi đi. Theo bài gốc, endpoint này miễn phí (rate limit tính riêng với message creation) và trả về số token input cho toàn bộ request đã lắp ráp, bao gồm cả tool definition.

Mẫu hai pass mà tác giả mô tả: pass một dùng tiktoken nhân hệ số bi quan (ông đặt 1,2) để lấp prompt nhanh ở local; pass hai gọi count_tokens trên request đã lắp ráp và bỏ bớt file ít liên quan nhất cho tới khi vừa. Ông đặt mục tiêu 194K token thật thay vì sát 200K, để chừa headroom.

Kết quả ông báo cáo: không còn lần tràn nào trong 21 đêm và 463 request kế tiếp. Pass hai chỉ cần một lần gọi count_tokens ở 79% số request lấp đầy budget, và hai lần ở phần còn lại. Chi phí đánh đổi là độ trễ trung vị thêm 170 ms mỗi request.

Một cảnh báo quan trọng

Đừng chép hệ số 1,14 vào code của bạn. Chính tác giả nói rõ tỷ lệ này không phải hằng số: nó gắn với nội dung của ông và với model ông đo, còn tokenizer thì đổi giữa các thế hệ model, nên một hệ số hiệu chỉnh quý trước có thể trôi sau khi bạn nâng cấp.

Việc rẻ nhất nên làm ngay: thay vì ước lượng chi phí sau khi gọi, hãy log trường usage trong response. API đã nói chính xác bạn bị tính bao nhiêu token — không có lý do gì để đoán lại con số đó.