RESP 用量采集器

这是一个用 Python 编写的常驻采集程序，用来从 CLIProxyAPI 暴露的 Redis RESP 队列中持续拉取最近请求的用量记录，并按天保存成 JSONL 文件。

目录结构

.
├── .env.example
├── README.md
├── pyproject.toml
├── uv.lock
├── src/
└── tests/

安装

方式一：本地开发

1. 创建项目内虚拟环境：

uv venv

2. 安装依赖：

uv sync --extra dev

3. 复制环境文件：

cp .env.example .env

方式二：便于 uv tool 安装

如果你想把它当成一个可安装工具，直接在当前项目目录执行：

uv tool install .

安装后会得到 usage-collector 命令。

如果要更新已安装版本：

uv tool upgrade resp-usage-collector

如果要卸载：

uv tool uninstall resp-usage-collector

配置

把下面这些值写入 .env：

• RESP_HOST：RESP 服务地址
• RESP_PORT：RESP 服务端口
• RESP_KEY：Management key，必填
• RESP_QUEUE：队列名称
• BATCH_SIZE：每次批量拉取的条数
• EMPTY_SLEEP：队列为空时的等待秒数
• RETRY_SLEEP：连接失败时的重试秒数
• OUTPUT_DIR：输出目录（必须是绝对路径）

示例：

RESP_HOST=127.0.0.1
RESP_PORT=14991
RESP_KEY=sk-9999
RESP_QUEUE=queue
BATCH_SIZE=50
EMPTY_SLEEP=5
RETRY_SLEEP=5
OUTPUT_DIR=/home/your-user/resp-usage-data

运行

优先使用项目脚本：

uv run usage-collector

如果你想显式带参数，也可以这样：

uv run usage-collector --host 127.0.0.1 --port 14991 --key sk-9999 --output-dir /home/your-user/resp-usage-data

也可以直接运行模块：

uv run python -m usage_collector.cli --key sk-9999 --output-dir /home/your-user/resp-usage-data

输出

程序会把记录追加写入到按天切分的文件里，例如：

/home/your-user/resp-usage-data/usage-stats-2026-05-12.jsonl

每行是一条 JSON 记录，适合后续脚本、jq、日志管道或批处理消费。

JSONL转HTML报表工具

项目附带了一个单文件工具 jsonl2html.py，可以将生成的JSONL用量文件转换成中文友好的交互式HTML报表，方便查看和分析。

功能特点

• 📊 自动生成统计概览：总请求数、成功率、Token消耗统计、延迟统计、模型统计
• 📋 响应式表格展示核心数据：时间、模型、延迟、输入/输出/总Token、缓存用量、请求状态、API Key
• 🔍 支持全局搜索、按模型筛选、按请求状态筛选
• 📂 点击表格行可展开查看完整JSON详情，支持语法高亮
• 🔑 API Key默认打码保护，点击可切换显示明文
• 📱 完全响应式设计，适配桌面和移动端屏幕
• 📦 生成的HTML是完全独立的单文件，无任何外部依赖

使用方法

直接运行脚本并指定JSONL文件所在的文件夹路径：

uv run jsonl2html.py <JSONL文件所在文件夹路径>

执行过程

1. 自动删除目标文件夹内所有已存在的.html文件
2. 查找文件夹内所有.jsonl文件
3. 逐个处理并生成同名的.html报表文件
4. 处理完成后输出结果提示

示例

uv run jsonl2html.py /home/your-user/resp-usage-data

处理完成后，会在同目录下生成对应的HTML文件：

usage-stats-2026-05-12.jsonl → usage-stats-2026-05-12.html

运行流程

1. 读取 .env 和命令行参数
2. 检查 RESP_KEY
3. 解析并规范化 OUTPUT_DIR
4. 自动创建输出目录（如果不存在）
5. 连接 RESP 队列并认证
6. 批量执行 RPOP queue 50
7. 有数据就写入当天 JSONL 文件
8. 队列为空就等待 EMPTY_SLEEP 秒
9. 出现连接或读取异常就等待 RETRY_SLEEP 秒后重试

故障排查

1. RESP_KEY 不能为空

如果没填 RESP_KEY，程序会直接报错并退出。请先确认 .env 是否存在、内容是否正确。

2. OUTPUT_DIR 必须是绝对路径

OUTPUT_DIR 现在要求填写绝对路径。程序会自动创建目录，如果路径不存在就新建。

3. 出现 IP banned

这表示 Management 端触发了失败次数限制。通常是：

• RESP_KEY 写错
• 服务端没有启用 Management
• 端口连错了

先修正配置，再重新运行。

4. 没有输出文件

请检查：

• OUTPUT_DIR 是否有写权限
• 队列里是否真的有数据
• RESP_QUEUE 是否和服务端使用的一致

说明

• 所有依赖只安装在项目自己的虚拟环境里
• 可以使用 uv tool install . 进行本地工具安装
• 不做系统级安装
• 不会修改系统路径或全局环境
• 默认按天生成新文件，旧文件会继续追加
• 这是一个采集工具，不是完整 Redis 服务