offline-token-counter

offline-token-counter 是一个轻量级 Python 库，专为需要完全离线、精确计数大语言模型 Token 的场景而设计。将所有主流模型的 tokenizer 数据直接打包在安装包内，无需联网、无需额外下载，开箱即用。支持对字符串（str）、对话消息（messages）和工具调用（tools）三种输入格式进行精确 Token 计数，全面覆盖大模型应用开发中的各类使用场景。

特性

• 完全离线 — tokenizer 文件随包分发，无需联网下载
• 多模型支持 — 支持 429 个模型别名，覆盖 47 个独立 tokenizer（含 DeepSeek、Qwen、GLM、MiniMax、JiuTian、Janus 等系列）
• 多种输入格式 — 纯文本、对话消息、工具调用
• 智能解析 — 支持组织前缀剥离、大小写容错、模糊拼写纠错
• 无 transformers 依赖 — 仅依赖轻量 tokenizers、jinja2、sentencepiece

支持的模型

DeepSeek 系列

Qwen 系列

GLM 系列

MiniMax 系列

JiuTian 系列

Janus 系列

SynLogic 系列

快速别名参考

安装

pip install offline-token-counter

本地开发：

pip install -e ".[test]"

用法

from offline_token_counter import count_tokens

# 纯文本计数
count_tokens("Hello, world!")
# => 4 (deepseek-v4)

# 指定模型
count_tokens("你好", model="qwen-2.5")

# 对话消息
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the capital of France?"},
]
count_tokens(messages, model="glm-4")

# 带工具定义
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"},
                },
                "required": ["location"],
            },
        },
    },
]
count_tokens(messages, tools=tools, model="deepseek-r1")

API

count_tokens(messages, tools=None, model="deepseek-v4")

返回： int — Token 数量。

异常： 不抛异常。失败时自动降级为启发式估算。

版本记录

v0.1.1

• 修复：30 个模型的 chat_template.jinja 文件内容为 "Entry not found"（下载工具错误），删除后改用 tokenizer_config.json 中的合法模板
• 修复：qwen2.5-72b-instruct-awq 的 tokenizer.json 与 qwen-2.5 完全一致，删除重复文件
• 修复：jiutian-139moe-chat SentencePiece 模型从未被用于 token 计数（回落 heuristic），现转换为独立 tokenizer.json.zip（Unigram, 69120 vocab）
• 修复：synlogic / qwen2.5-vl 系列模型映射错误（指向 jt-math-8b-instruct → 修正为 qwen-2.5）
• 修复：count_tokens() 中 _get_tokenizer 与 _render_messages 调用顺序错误，导致 chat_template/bos_token 加载时机不确定
• 新增：多模态图像 token 计数支持（Qwen2.5-VL、GLM-4V、DeepSeek-VL2 等视觉模型）
• 新增：全模型回归测试用例（strings / messages / tools / vision），锁定每个 canonical 模型的精确 token 计数
• 修复：qwen2-vl-2b 和 qwen2-vl-2b-instruct-awq 的 tokenizer_config.json 中 chat_template 损坏（仅处理视觉 content 数组，不支持标准消息格式），删除后回落 fallback 格式

v0.1.0

• 首个正式发布版本
• 支持 DeepSeek、Qwen、GLM、MiniMax、JiuTian、Janus 六大系列共 47 个独立 tokenizer（429 个模型别名）
• 支持纯文本、对话消息、工具调用三种输入格式
• 支持组织前缀剥离、大小写容错、模糊拼写纠错
• 失败时自动降级为启发式估算

许可证

MIT