# Model Tokenizer Registry & Counter CLI
目标：把「模型本体」的 tokenizer 计数策略统一到本地 JSON 注册库，并提供可直接使用的 Rust CLI。
## 2. 安装依赖并构建
```bash
cargo build --release
```
### Python tokenizer 环境（uv 管理）
```bash
./scripts/setup_uv_env.sh
```
默认会：
- 用 `uv venv` 创建项目内 `.venv`
- 安装 `tiktoken`、`transformers`、`sentencepiece`
CLI 会自动优先使用项目内 `.venv/bin/python`，无需手动 `source .venv/bin/activate`。
如果你仍想显式指定，可加：
```bash
export TOKENIZER_PYTHON="$(pwd)/.venv/bin/python"
```
## 3. 环境变量
```bash
export ANTHROPIC_COUNT_ENDPOINTS="https://api.anthropic.com/v1/messages/count_tokens"
export MODEL_INDEX_API_KEY="<模型列表接口密钥（可选，兼容旧为 AIHUBMIX_API_KEY）>"
export MODEL_COUNT_API_KEY="<Anthropic/网关计数密钥（可选，兼容旧为 AIHUBMIX_API_KEY）>"
export TOKENIZER_PYTHON="$(pwd)/.venv/bin/python"
export ANTHROPIC_API_KEY="..." # 可选（直接调用 Anthropic 时）
export GEMINI_API_KEY="..." # 可选
export COHERE_API_KEY="..." # 可选
export XAI_API_KEY="..." # 可选
export ALL_PROXY="socks5h://127.0.0.1:7890" # 需要代理时（可选）
```
> 注意：密钥请只放在环境变量，不要写进代码或提交文件。
## 4. 同步模型 + 映射
```bash
./target/release/utokenizer sync
```
参数：
- `--force-reclassify`：重新走一次模型归类 heuristics
- `--no-probe`：先快速落库，跳过 open-source tokenizer 探测（默认 false）
- `--only-text`：仅同步文本类模型（默认 true）
## 5. 计数
文本计数：
```bash
./target/release/utokenizer count --model gpt-4o-mini --text "你好，帮我写个接口"
```
通过文件：
```bash
./target/release/utokenizer count --model qwen2.5-72b-instruct --text-file /tmp/input.txt
```
通过 messages JSON（用于 message 样式输入）：
```bash
./target/release/utokenizer count --model claude-3-5-sonnet --messages-file /tmp/messages.json
```
若遇到模型计数失败（如 `python3` 里缺少依赖），先确认 uv 环境已安装且 `scripts/setup_uv_env.sh` 已成功执行，或手动执行：
```bash
TOKENIZER_PYTHON="$(pwd)/.venv/bin/python" ./target/release/utokenizer count --model gpt-4o-mini --text "测试"
```
## 6. 校验映射
```bash
./target/release/utokenizer validate
```
会输出低置信度或 `private_api/usage_only/unknown` 的模型，便于你补齐映射。
```bash
./target/release/utokenizer verify
./target/release/utokenizer verify --run-count
./target/release/utokenizer verify --all
./target/release/utokenizer verify --all --max-models 100
./target/release/utokenizer verify --all --max-models 100 --offset 100
```
说明：
- `verify` 默认只验证低置信度和 `private_api/usage_only` 条目
- `--all` 开启后会对全部文本模型逐条输出验证
- `--run-count` 会实际调用本地计数/计数 API 进行可复现性检查，并写入
- `validation_report.json`
- `validation_report.csv`
## 7. 模型/策略清单
```bash
./target/release/utokenizer list --strategy local_hf_transformers
```
本地注册文件：
- `--local-store`（默认 `./token_registry.json`）
- `--local-log`（默认 `./token_count_log.jsonl`）
> 兼容说明：如果你原来用的是 `aihubmix_token_registry.json` / `aihubmix_token_count_log.jsonl`，程序在首次启动且新默认文件不存在时会自动回退到旧文件。
如果你想改路径，可在命令里加参数：
```bash
./target/release/utokenizer --local-store /tmp/registry.json --local-log /tmp/tokens.log sync
```
### 说明
- 这个方案是工程化起步版，先覆盖“可落地可用”场景。
- 对于 `provider_api` 策略先走官方计数；若无公开计数能力则回退到 `usage_only`，后续可逐步补齐私有 API mapping。
- 你现在给的 key 仍可用于兼容路径；模型归类以 tokenizer 家族为主（如 gpt / claude / gemini / HF 风格模型），而不是按厂商平台标识绑定映射。