# token meter

**Repository Path**: cxunmz/token-meter

## Basic Information

- **Project Name**: token meter
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-04-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Token Meter

<div align="center">

**一个智能、高效、易用的 AI 模型 API 代理调度工具**

Token Meter 是一个轻量级的 HTTP 代理服务器，专为多 AI 模型场景设计。它能够智能地将聊天完成请求分发到多个后端模型，提供灵活的调度策略、完善的统计功能和美观的管理界面，让你轻松管理和优化 AI API 的使用。

![运行效果](imgs/running.jpg)

</div>

---

## 🎯 核心场景

Token Meter 能帮你解决什么问题？

- **💰 成本优化** - 你有多个免费/低价额度的 API，希望充分利用每个配额
- **🔄 负载均衡** - 避免单点故障，通过轮询机制分散请求压力
- **📊 统一入口** - 为不同平台的模型提供统一的 API 接口，简化客户端配置
- **📈 使用监控** - 实时追踪每个模型的调用次数和 Token 消耗，避免超额
- **⚡ 智能调度** - 根据模型质量（权重）自动选择最优服务，保障响应质量
- **🛡️ 容错重试** - 请求失败自动切换其他模型，提升服务可用性

无论你是个人开发者还是小团队，Token Meter 都能帮助你更高效、更经济地使用 AI 模型服务。

## ✨ 功能特性

- 🔄 **轮流模式** - 所有启用的模型按顺序轮流使用，均匀分配请求
- ⭐ **专一模式** - 始终使用 score 权重最高的启用模型，优先保障高质量
- 🥇 **高分轮流 A** - 分数最高的 2 个可用模型轮流调用，更集中
- 🏆 **高分轮流 B** - 分数最高的 3 个可用模型轮流调用，更均衡
- 📊 **调用统计** - 实时记录每个模型的调用次数和 Token 消耗（prompt/completion/total）
- 📈 **错误统计** - 记录每个模型的错误次数（非 200 状态码和异常）
- 🎯 **调用限制** - 支持按 **调用次数** 或 **Token 消耗** 设置每日上限
- 🔔 **上限触发词** - 当响应包含指定关键词时，自动设置次数上限为当前已用次数
- 🚀 **Web 管理后台** - 美观的管理界面，实时查看和切换模型状态、日志开关
- ✏️ **模型管理** - 支持在线添加、编辑、删除、复制模型配置，无需手动修改配置文件
- 🧪 **模型测试** - 内置模型测试功能，可直接在管理界面测试模型响应
- 🔐 **双重认证** - API 访问使用 `auth_keys`，管理后台使用独立的 `admin_key`
- 📝 **交互日志** - 可开关的日志功能，记录所有请求和响应的详细信息
- 📋 **平台管理** - 支持为模型添加平台标签（如 OpenRouter、SiliconFlow 等）
- 🔀 **多线程处理** - 使用 ThreadingHTTPServer，支持并发处理多个请求
- ⏱️ **耗时统计** - 自动记录并输出每次请求的响应时间
- 🛡️ **错误重试** - 请求失败自动重试 3 次，并将原始错误信息透传给客户端
- 🖥️ **后台模式** - 支持后台运行（`-d` 参数），日志始终保存到 `log.log`
- 🌐 **网络绑定** - 支持绑定到指定地址（`--host` 参数），允许外部访问
- 🔄 **防重复启动** - 自动检测端口占用，防止重复启动

## 📦 快速开始

### 环境要求

- Python 3.6+
- 无需额外依赖（仅使用标准库）

### 安装与运行

1. 克隆项目
```bash
git clone <your-repo-url>
cd token-meter
```

2. 编辑配置文件 `config.json`

3. 启动服务

```bash
# 前台运行（默认绑定 127.0.0.1）
python main_web.py

# 前台运行，允许外部访问
python main_web.py --host

# 后台运行（日志保存到 log.log）
python main_web.py -d

# 后台运行，允许外部访问
python main_web.py -d --host

# 停止后台服务
python main_web.py -s
```

**命令行参数说明：**

| 参数 | 说明 |
|------|------|
| `-d`, `--daemon` | 后台模式运行，日志保存到 `log.log` |
| `-s`, `--stop` | 停止后台服务 |
| `--host` | 绑定到 `0.0.0.0`（允许外部访问），默认绑定 `127.0.0.1` |

![启动服务](imgs/start.jpg)

4. 访问管理后台
```
http://localhost:9999/admin
```

如果使用了 `--host` 参数，可通过本机 IP 访问：
```
http://<本机 IP>:9999/admin
```

## ⚙️ 配置说明

### config.json 结构

```json
{
  "models": [
    {
      "name": "模型名称",
      "platform": "平台名称（可选）",
      "url": "API 端点 URL",
      "key": "API 密钥",
      "model": "模型标识",
      "limit_count": 500,
      "limit_token": 0,
      "limit_trigger": "quota exceeded",
      "score": 100,
      "switchon": true
    }
  ],
  "listen_port": 9999,
  "auth_keys": ["your-auth-token"],
  "admin_key": "your-admin-password",
  "model": "all",
  "log_enabled": false,
  "mode": "round"
}
```

### 客户端配置

启动服务后，将以下信息配置到你的 AI 客户端（如 OpenClaw）：

- **url**: `http://<你的IP>:9999/v1`
- **key**: `cc-1234567890`（与 config.json 中的 auth_keys 一致）
- **model**: `all`

![客户端配置](imgs/config1.jpg)

![配置示例](imgs/config2.jpg)

### 配置项说明

| 字段 | 说明 |
|------|------|
| `models` | 模型配置列表 |
| `name` | 模型自定义名称 |
| `platform` | 模型所属平台（可选，如 OpenRouter、SiliconFlow） |
| `url` | 模型 API 端点地址 |
| `key` | API 认证密钥 |
| `model` | 具体模型标识 |
| `limit_count` | 每日调用次数上限（可选，0 表示不限制） |
| `limit_token` | 每日 Token 消耗上限（可选，0 表示不限制） |
| `limit_trigger` | 上限触发词（可选），当响应包含此词时自动设置 limit_count 为当前已用次数 |
| `score` | 模型权重，用于专一模式/高分轮流模式排序 |
| `switchon` | 模型是否启用（true/false） |
| `listen_port` | 服务监听端口 |
| `auth_keys` | API 访问授权的 Bearer Token 列表（用于 /v1/* 接口） |
| `admin_key` | 管理后台登录密码（用于 /admin/* 接口） |
| `model` | 客户端请求的模型标识（通常为 "all"） |
| `log_enabled` | 是否启用交互日志（true/false） |
| `mode` | 调度模式："round"（轮流）、"priority"（专一）、"top2_round"（高分轮流 A）、"top3_round"（高分轮流 B） |

## 🎮 使用方式

### API 请求

将你的聊天请求发送到代理服务器：

```bash
curl -X POST http://localhost:9999/v1/chat/completions \
  -H "Authorization: Bearer cc-1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "any-model",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

### 管理 API

![管理后台](imgs/manage.jpg)

| 端点 | 方法 | 说明 |
|------|------|------|
| `/admin` | GET | 访问 Web 管理界面 |
| `/admin/status` | GET | 获取所有模型状态 |
| `/admin/models` | POST | 批量更新模型启用状态 |
| `/admin/model/{name}` | POST | 切换单个模型状态 |
| `/admin/model_config/{name}` | GET | 获取单个模型完整配置（含 API Key） |
| `/admin/add_model` | POST | 添加新模型 |
| `/admin/edit_model` | POST | 编辑现有模型 |
| `/admin/delete_model` | POST | 删除模型 |
| `/admin/mode` | POST | 切换调度模式 |
| `/admin/log` | POST | 切换交互日志开关 |

### Web 管理界面功能

- **模型列表** - 表格展示，显示所有模型的名称、平台、模型标识、权重、调用统计等信息
- **排序功能** - 点击表头可按名称、平台、权重、调用次数等字段排序
- **启用/禁用** - 通过切换开关快速启用或禁用模型
- **编辑模型** - 点击 ✏️ 按钮修改模型配置（名称、平台、URL、Key、权重等）
- **复制模型** - 编辑界面点击"复制模型"按钮可快速复制配置（自动添加 _copy1 后缀）
- **删除模型** - 点击 🗑️ 按钮删除模型（需二次确认）
- **添加模型** - 点击 ➕ 按钮添加新模型配置
- **刷新数据** - 点击 🔄 按钮手动刷新模型状态
- **模式切换** - 在轮流模式和专一模式之间切换
- **日志开关** - 控制是否记录交互日志
- **模型测试** - 点击 🧪 按钮打开测试窗口，可测试模型响应（流式输出）

## 📁 项目结构

```
token-meter/
├── main_web.py          # 主程序入口
├── config.json          # 配置文件（包含模型状态、模式、日志开关等）
├── interaction_log.jsonl # 交互日志（当 log_enabled 启用时）
├── log.log              # 后台模式运行时的日志文件
├── src/                 # 核心模块目录
│   ├── __init__.py      # 包初始化
│   ├── config.py        # 配置管理模块
│   ├── stats.py         # 统计管理模块
│   ├── admin.py         # 管理 API 处理模块
│   ├── admin.html       # 管理界面 HTML 模板
│   └── handler.py       # HTTP 请求处理模块
├── stats/               # 每日统计目录
│   └── stats_2026-03-21.json  # 包含 count、prompt_tokens、completion_tokens、total_tokens
└── imgs/                # 文档图片目录
```

## 🔒 安全提示

1. **请勿提交真实 API 密钥** - 开源前请确保 `config.json` 中的敏感信息已移除
2. 建议将 `config.json` 添加到 `.gitignore`
3. 使用强密码作为 `auth_keys` 和 `admin_key`
4. `auth_keys` 用于 API 访问认证，`admin_key` 用于管理后台登录认证，两者独立

## 📊 统计文件说明

### 每日统计 (stats/stats_YYYY-MM-DD.json)

记录每个模型当日的调用统计：

```json
{
  "Qwen3.5-27B": {
    "count": 100,
    "prompt_tokens": 5000,
    "completion_tokens": 10000,
    "total_tokens": 15000,
    "error_count": 2,
    "exception_count": 1
  }
}
```

| 字段 | 说明 |
|------|------|
| `count` | 成功调用次数 |
| `prompt_tokens` | 累计输入 token 数 |
| `completion_tokens` | 累计输出 token 数 |
| `total_tokens` | 累计总 token 数 |
| `error_count` | 非 200 状态码错误次数 |
| `exception_count` | 请求异常次数 |

### 交互日志 (interaction_log.jsonl)

当 `log_enabled: true` 时，记录每次请求的详细信息（JSONL 格式）。

### 运行日志 (log.log)

服务运行日志，前台和后台模式均会保存。

## 📄 License

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

**Made with ❤️ for AI developers**