lanyuanxiaoyao
915b004924
实现支持 OpenAI 和 Anthropic 双协议的统一大模型 API 网关 MVP 版本，包含： - OpenAI 和 Anthropic 协议代理 - 供应商和模型管理 - 用量统计 - 前端配置界面
156 lines
4.6 KiB
Markdown
156 lines
4.6 KiB
Markdown
# 用量统计
|
||
|
||
## Purpose
|
||
|
||
TBD - 提供请求用量统计的记录和查询功能
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 记录请求统计
|
||
|
||
网关 SHALL 为每次 API 调用记录请求统计。
|
||
|
||
#### Scenario: 记录成功请求
|
||
|
||
- **WHEN** 请求成功转发到供应商
|
||
- **THEN** 网关 SHALL 增加该供应商和模型的请求计数
|
||
- **THEN** 网关 SHALL 记录当前日期的统计
|
||
|
||
#### Scenario: 记录流式请求
|
||
|
||
- **WHEN** 流式请求成功完成
|
||
- **THEN** 网关 SHALL 增加该供应商和模型的请求计数
|
||
- **THEN** 网关 SHALL 在流结束后记录统计
|
||
|
||
#### Scenario: 不记录失败请求
|
||
|
||
- **WHEN** 请求在到达供应商前失败（路由错误、验证错误）
|
||
- **THEN** 网关 SHALL NOT 增加请求计数
|
||
|
||
#### Scenario: 记录供应商错误
|
||
|
||
- **WHEN** 请求到达供应商但供应商返回错误
|
||
- **THEN** 网关 SHALL 仍然增加请求计数（请求已被处理）
|
||
|
||
### Requirement: 按供应商查询统计
|
||
|
||
网关 SHALL 允许按供应商过滤查询统计。
|
||
|
||
#### Scenario: 查询特定供应商的统计
|
||
|
||
- **WHEN** 向 `/api/stats?provider_id=<provider_id>` 发送 GET 请求
|
||
- **THEN** 网关 SHALL 仅返回指定供应商的统计
|
||
|
||
#### Scenario: 查询不存在供应商的统计
|
||
|
||
- **WHEN** 向 `/api/stats?provider_id=<non_existent_id>` 发送 GET 请求
|
||
- **THEN** 网关 SHALL 返回空结果或零计数
|
||
|
||
### Requirement: 按模型查询统计
|
||
|
||
网关 SHALL 允许按模型过滤查询统计。
|
||
|
||
#### Scenario: 查询特定模型的统计
|
||
|
||
- **WHEN** 向 `/api/stats?model_name=<model_name>` 发送 GET 请求
|
||
- **THEN** 网关 SHALL 仅返回指定模型的统计
|
||
|
||
#### Scenario: 查询不存在模型的统计
|
||
|
||
- **WHEN** 向 `/api/stats?model_name=<non_existent_name>` 发送 GET 请求
|
||
- **THEN** 网关 SHALL 返回空结果或零计数
|
||
|
||
### Requirement: 按日期范围查询统计
|
||
|
||
网关 SHALL 允许在日期范围内查询统计。
|
||
|
||
#### Scenario: 使用日期范围查询统计
|
||
|
||
- **WHEN** 向 `/api/stats?start=<start_date>&end=<end_date>` 发送 GET 请求
|
||
- **THEN** 网关 SHALL 仅返回指定范围内的日期统计
|
||
- **THEN** 日期格式 SHALL 为 YYYY-MM-DD
|
||
|
||
#### Scenario: 不使用日期范围查询统计
|
||
|
||
- **WHEN** 向 `/api/stats` 发送 GET 请求，不带 start 和 end 参数
|
||
- **THEN** 网关 SHALL 返回所有可用日期的统计
|
||
|
||
#### Scenario: 仅使用开始日期查询统计
|
||
|
||
- **WHEN** 向 `/api/stats?start=<start_date>` 发送 GET 请求
|
||
- **THEN** 网关 SHALL 返回从开始日期到当前日期的统计
|
||
|
||
#### Scenario: 仅使用结束日期查询统计
|
||
|
||
- **WHEN** 向 `/api/stats?end=<end_date>` 发送 GET 请求
|
||
- **THEN** 网关 SHALL 返回从最早可用日期到结束日期的统计
|
||
|
||
### Requirement: 聚合统计
|
||
|
||
网关 SHALL 按日期聚合统计。
|
||
|
||
#### Scenario: 同一天多次请求
|
||
|
||
- **WHEN** 同一天对同一供应商和模型发起多次请求
|
||
- **THEN** 网关 SHALL 为该天维护单条统计记录
|
||
- **THEN** 请求计数 SHALL 为所有请求的总和
|
||
|
||
#### Scenario: 跨多天请求
|
||
|
||
- **WHEN** 跨不同天发起请求
|
||
- **THEN** 网关 SHALL 为每一天维护独立的统计记录
|
||
|
||
### Requirement: 以结构化格式返回统计
|
||
|
||
网关 SHALL 以结构化 JSON 格式返回统计。
|
||
|
||
#### Scenario: 统计响应格式
|
||
|
||
- **WHEN** 查询统计
|
||
- **THEN** 响应 SHALL 为统计对象数组
|
||
- **THEN** 每个对象 SHALL 包含 provider_id, model_name, request_count 和 date
|
||
|
||
#### Scenario: 空统计
|
||
|
||
- **WHEN** 没有统计匹配查询条件
|
||
- **THEN** 网关 SHALL 返回空数组
|
||
|
||
### Requirement: 支持并发统计记录
|
||
|
||
网关 SHALL 支持并发请求统计记录而无冲突。
|
||
|
||
#### Scenario: 并发请求
|
||
|
||
- **WHEN** 同时处理多个并发请求
|
||
- **THEN** 网关 SHALL 正确为每个请求增加请求计数
|
||
- **THEN** 不 SHALL 因并发写入而丢失统计
|
||
|
||
### Requirement: 仅将统计限制为请求计数
|
||
|
||
网关 SHALL 在 MVP 中仅记录请求计数，不记录其他指标。
|
||
|
||
#### Scenario: 仅请求计数
|
||
|
||
- **WHEN** 记录统计
|
||
- **THEN** 网关 SHALL 仅跟踪请求数量
|
||
- **THEN** 网关 SHALL NOT 在 MVP 中跟踪 token 使用、成本、延迟或其他指标
|
||
|
||
### Requirement: 为新组合初始化统计
|
||
|
||
网关 SHALL 为新的供应商-模型-日期组合自动创建统计记录。
|
||
|
||
#### Scenario: 组合的首次请求
|
||
|
||
- **WHEN** 在新日期首次对供应商-模型组合发起请求
|
||
- **THEN** 网关 SHALL 创建新的统计记录，request_count = 1
|
||
|
||
### Requirement: 查询所有统计
|
||
|
||
网关 SHALL 允许不带过滤条件查询所有统计。
|
||
|
||
#### Scenario: 查询所有统计
|
||
|
||
- **WHEN** 向 `/api/stats` 发送 GET 请求，不带任何查询参数
|
||
- **THEN** 网关 SHALL 返回所有可用统计
|
||
- **THEN** 结果 SHALL 按日期排序（最近的在前）
|