Chuyển đến nội dung chính
Hướng dẫn AI

Theo dõi mức sử dụng và chi phí token AI cục bộ với tokentab

Tìm hiểu cách cài đặt tokentab, phân tích mức sử dụng token AI và chi phí ước tính từ nhật ký phiên cục bộ, lọc báo cáo theo ngày hoặc dự án, mở bảng điều khiển web riêng tư, diễn giải kết quả và mở rộng dự án với một nhà cung cấp khác.

Thời gian đọc khoảng 18 phút
Theo dõi token và chi phí AI cục bộ với tokentab

tokentab làm gì

tokentab là công cụ báo cáo cục bộ giúp hiểu cách các trợ lý lập trình sử dụng token và tích lũy chi phí ước tính. Công cụ đọc các nhật ký phiên mà những công cụ được hỗ trợ đã lưu trên máy tính của bạn, sau đó nhóm mức sử dụng theo mô hình, nhà cung cấp, dự án, ngày và loại hoạt động được suy luận.

Không cần tài khoản hoặc khóa API. Quá trình xử lý diễn ra trên máy của bạn, và tokentab không tải thông tin phiên lên hoặc liên hệ với các dịch vụ định giá.

bảng điều khiển web tokentab

Công cụ được hỗ trợ và vị trí nhật ký

Hiện tokentab có các bộ phân tích đang hoạt động cho ba công cụ:

  • Claude Code: ~/.claude/projects/**/*.jsonl
  • Codex: ~/.codex/sessions/**/rollout-*.jsonl
  • Gemini CLI: ~/.gemini/tmp/**/session-*.json

Hiện có một vị trí nhà cung cấp dành cho Cursor, nhưng bộ phân tích vẫn chưa hoàn thiện. Nếu một trong các công cụ được hỗ trợ chưa được cài đặt, tokentab sẽ bỏ qua công cụ đó. Do đó, báo cáo chỉ bao gồm những công cụ có nhật ký sẵn trên máy của bạn.

Tính năng chính

  • Đọc trực tiếp số lượng token từ các nhật ký phiên cục bộ hiện có.
  • Ước tính chi phí bằng bảng giá cục bộ được duy trì thủ công.
  • Nhóm dữ liệu theo nhà cung cấp, mô hình, dự án, ngày và hoạt động.
  • Hỗ trợ phạm vi ngày hằng ngày, hằng tháng, toàn bộ thời gian và tùy chỉnh.
  • Xuất bảng trong terminal hoặc JSON mà máy có thể đọc.
  • Cung cấp bảng điều khiển trên trình duyệt, chỉ liên kết với localhost.
  • Tự động loại bỏ màu terminal khi đầu ra được chuyển qua pipe.
  • Không sử dụng framework web; bảng điều khiển chạy trên máy chủ HTTP thuộc thư viện chuẩn của Python.

Phụ thuộc bên thứ ba duy nhất là Rich, dùng để hiển thị các bảng trong terminal. Việc phân tích, xử lý JSON và máy chủ web cục bộ đều sử dụng thư viện chuẩn của Python.

Cài đặt tokentab

Cài đặt tiêu chuẩn

Sao chép repository, truy cập thư mục của repository và cài đặt gói vào môi trường Python đang hoạt động:

git clone https://github.com/damejan80/tokentab
cd tokentab
pip install .
python cli.py

Quá trình cài đặt thêm lệnh tokentab vào đường dẫn của bạn. Sau đó, bạn có thể chạy trực tiếp lệnh đã cài đặt:

tokentab

Cài đặt mã nguồn ở chế độ editable

Nếu dự định kiểm tra hoặc chỉnh sửa mã, hãy cài đặt ở chế độ editable:

git clone https://github.com/damejan80/tokentab
cd tokentab
pip install -e .
tokentab

Cài đặt editable giữ cho lệnh được kết nối với bản sao làm việc của bạn, vì vậy các thay đổi mã cục bộ có hiệu lực mà không cần cài đặt lại gói.

Chạy báo cáo đầu tiên

Từ thư mục repository, chạy CLI không có tùy chọn:

python cli.py

Báo cáo mặc định bao phủ bảy ngày gần nhất trên mọi nhà cung cấp và dự án được phát hiện. Nếu đã cài đặt lệnh, cách gọi tương đương là:

tokentab

Vì tokentab đọc các thư mục nhật ký hiện có của nhà cung cấp, bạn không cần thiết lập tài khoản hoặc cấu hình thông tin xác thực. Nếu không có nhật ký được hỗ trợ, sẽ không có dữ liệu sử dụng tương ứng để đưa vào.

Lọc mức sử dụng theo thời gian

Hoạt động hôm nay

python cli.py -today

Tháng dương lịch hiện tại

python cli.py -month

Toàn bộ lịch sử hiện có

python cli.py -p all

Một khoảng ngày cụ thể

python cli.py --from 2026-06-01 --to 2026-06-15

Các khoảng thời gian tùy chỉnh hữu ích khi bạn muốn đối chiếu mức sử dụng với một sprint, kỳ thanh toán, thử nghiệm hoặc khoảng thời gian xác định khác.

Lọc theo nhà cung cấp hoặc dự án

Để chỉ hiển thị mức sử dụng Claude, hãy truyền bộ lọc nhà cung cấp:

python cli.py --provider claude

Để tập trung vào một dự án, hãy sử dụng tên dự án:

python cli.py --project myapp

Các bộ lọc này giúp tách chi phí của một codebase hoặc công cụ cụ thể khỏi toàn bộ hoạt động của bạn.

Xuất JSON mà máy có thể đọc

Sử dụng --json khi một chương trình khác cần tiếp nhận báo cáo:

python cli.py --json

Ví dụ, nếu đã cài đặt jq, hãy chuyển JSON qua công cụ này để định dạng hoặc xử lý thêm:

python cli.py --json | jq .

tokentab tự động loại bỏ màu terminal khi đầu ra thông thường được chuyển qua pipe, giúp bạn dễ dàng dán báo cáo vào pull request, tin nhắn trò chuyện, tệp hoặc lệnh khác mà không có mã thoát ANSI.

Sử dụng bảng điều khiển web cục bộ

Khởi động giao diện trình duyệt bằng:

python cli.py -web

tokentab mở http://localhost:4747 và trình bày dữ liệu như một bảng kê hằng tháng, với tổng số ở trên cùng và thông tin chi tiết theo từng mục bên dưới.

Bảng điều khiển đọc nhật ký từ ổ đĩa trong mỗi yêu cầu thay vì lưu kết quả vào bộ nhớ đệm, vì vậy các phiên mới được ghi nhận có thể xuất hiện mà không cần duy trì cơ sở dữ liệu riêng. Bảng điều khiển chỉ liên kết với localhost và không tải dữ liệu lên. Công cụ cũng không sử dụng dịch vụ phông chữ bên ngoài, cho phép giao diện hoạt động khi mạng bị ngắt kết nối.

Để chọn cổng khác, hãy sử dụng --port. Để khởi động máy chủ mà không tự động mở trình duyệt, hãy thêm --no-open:

python cli.py -web --port 8080 --no-open

Tìm hiểu cách tính token và chi phí

Số lượng token

Tổng số token được lấy trực tiếp từ nhật ký của các công cụ được hỗ trợ thay vì ước tính từ văn bản. tokentab cũng tính đến sự khác biệt trong cách báo cáo bộ nhớ đệm. Claude ghi nhận lượt đọc và ghi bộ nhớ đệm riêng biệt, trong khi Gemini báo cáo dữ liệu đầu vào bao gồm các token đã được lưu trong bộ nhớ đệm. tokentab loại phần đã lưu trong bộ nhớ đệm khi cần để tránh tính phí cùng một token hai lần.

Định giá mô hình

Giá được lưu cục bộ trong tokentab/pricing/prices.py dưới dạng đô la trên mỗi triệu token. Công cụ này chủ ý sử dụng bảng tĩnh thay vì yêu cầu giá trực tiếp từ mạng.

Việc đối sánh mô hình sử dụng phương pháp gần đúng, vì vậy một mã nhận dạng mô hình có ngày tháng như claude-opus-4-6-20260514 có thể khớp với mục tổng quát hơn là claude-opus-4-6. Nếu một mô hình xuất hiện với chi phí $0.00, có thể tên của mô hình không khớp với bảng. CLI báo cáo tình trạng này thay vì ngầm giả định rằng mô hình đó miễn phí.

Giá được cung cấp theo nguyên tắc nỗ lực tốt nhất. Hãy cập nhật bảng cục bộ khi nhà cung cấp thay đổi giá hoặc ra mắt các tên mô hình chưa được nhận diện.

Danh mục hoạt động

Các nhãn hoạt động như lập trình, gỡ lỗi, tái cấu trúc, kiểm thử, trò chuyện và khám phá được suy ra từ các công cụ được sử dụng cùng cách diễn đạt trong tin nhắn đầu tiên của một phiên. Việc phân loại này mang tính xác định và không gọi đến một mô hình AI khác.

Hãy xem các nhãn hoạt động là những gợi ý hữu ích thay vì nhận định mang tính kết luận. Các nhãn giúp cho thấy những xu hướng lớn, nhưng chỉ bạn mới biết đầy đủ bối cảnh của công việc.

Diễn giải báo cáo

  • Tỷ lệ truy cập bộ nhớ đệm ổn định dưới khoảng 80%: Ngữ cảnh của bạn có thể đang thay đổi thường xuyên hoặc tính năng bộ nhớ đệm chưa được bật. Một phiên bất thường đơn lẻ ít có ý nghĩa hơn một xu hướng kéo dài vài tuần.
  • Một mô hình đắt tiền chiếm ưu thế trong nhiều lệnh gọi nhỏ: Báo cáo có thể cho thấy một mô hình lớn đang xử lý các tác vụ thường xuyên nhưng giới hạn. tokentab hiển thị xu hướng này để bạn kiểm tra xem cách sử dụng đó có đúng chủ ý hay không.
  • Các danh mục trò chuyện hoặc khám phá có quy mô lớn: Phần lớn hoạt động được ghi nhận liên quan đến thảo luận hoặc đọc thay vì chỉnh sửa. Điều này có thể phù hợp, nhưng cũng có thể làm nổi bật những phiên bị lan man.

Những xu hướng này là điểm khởi đầu để điều tra, không phải kết luận. Hãy đối chiếu báo cáo với những gì bạn thực sự đã làm trong các phiên liên quan.

Mẹo nâng cao: thêm nhà cung cấp khác

Mỗi nhà cung cấp được triển khai dưới dạng một mô-đun trong tokentab/providers/. Một nhà cung cấp cung cấp hàm collect() trả về danh sách phẳng các đối tượng UsageRecord. Cấu trúc bản ghi dùng chung được định nghĩa trong tokentab/types.py.

  1. Tạo mô-đun nhà cung cấp trong tokentab/providers/.
  2. Đọc và phân tích các tệp phiên cục bộ của nhà cung cấp.
  3. Chuyển đổi từng mục sử dụng liên quan sang cấu trúc UsageRecord dùng chung.
  4. Trả về các bản ghi từ collect().
  5. Thêm nhà cung cấp vào tokentab/providers/__init__.py.

Khi các bản ghi sử dụng cùng một cấu trúc, hệ thống định giá, tính năng nhóm, đầu ra CLI và bảng điều khiển hiện có có thể xử lý chúng. README khuyến nghị sử dụng bộ phân tích Claude làm mẫu đơn giản nhất và tham khảo các bộ phân tích đang hoạt động khác để xem thêm ví dụ.

Mẹo sử dụng thực tế

  • Thường xuyên chạy báo cáo bảy ngày mặc định để phát hiện các thay đổi gần đây.
  • Sử dụng chế độ xem theo tháng khi xem xét các xu hướng chi tiêu tổng quát hơn.
  • Lọc theo dự án trước khi điều tra một cơ sở mã cụ thể.
  • Xuất JSON khi xây dựng tập lệnh hoặc báo cáo tùy chỉnh từ dữ liệu tokentab.
  • Kiểm tra bảng giá mỗi khi một mô hình được báo cáo ở mức $0.00.
  • Sử dụng bảng điều khiển để xem xét trực quan và CLI để tự động hóa hoặc chia sẻ.

Kết luận

tokentab biến nhật ký cục bộ của Claude Code, Codex và Gemini CLI thành các báo cáo token và chi phí thiết thực mà không yêu cầu thông tin xác thực hoặc gửi dữ liệu ra khỏi máy tính của bạn. Hãy bắt đầu với chế độ xem CLI bảy ngày mặc định, thu hẹp kết quả bằng các bộ lọc thời gian, nhà cung cấp và dự án, sau đó sử dụng JSON hoặc bảng điều khiển localhost khi cần một cách trình bày khác. Dự án được cung cấp theo giấy phép MIT.