[RFC] 113 - Client-Side Service Provider Model Usage Statistics | 客户端侧服务商模型用量统计

[cy948]

背景 (Background)

随着大语言模型技术的发展，用户可选择的模型服务商日益增多，包括 OpenAI、Anthropic、Google Gemini、Groq，以及像 DeepSeek, Qwen 这样的开源模型和各种自托管/本地部署的模型。用户通常会在客户端（如聊天界面、开发工具）中配置多个模型服务商，以便根据不同任务或成本效益进行切换。

然而，目前用户往往缺乏一个统一、便捷的方式来了解自己在客户端中对这些不同模型服务商的实际使用情况。用户可能想知道：

• 我最常使用哪个模型/服务商？
• 不同模型/服务商的调用次数和 Token 消耗分别是多少？
• 对于付费 API，我的使用量是否接近预算？
• 哪些本地或免费模型真正在我的工作流中被频繁使用？

了解这些信息有助于用户更好地管理成本、优化模型选择策略，并直观地了解自己的模型使用偏好。

注：“最常用” 是指以 Token Usage 维度的评价，与当前 Message 维度有所区分。

当前现状 (Current Situation)

目前追踪模型使用量主要有以下几种方式：

1. 服务商官方仪表盘 (Provider Dashboards)
   • 👍：提供精确的官方用量和账单信息（针对该特定服务商）。
   • 👎：数据分散在各个平台，无法提供跨服务商的统一视图。需要分别登录查看。无法统计本地模型或未接入计费系统的自定义端点。
2. 自建中转服务日志 (Self-Hosted Proxy Logs)
   • 👍：如果所有请求都通过中转，可以集中记录日志，理论上可统计所有经过中转的请求。
   • 👎：需要额外部署和维护中转服务，有运行成本。无法统计未通过中转的请求（例如直接调用本地模型或特定云服务）。日志分析和统计可能需要额外开发。
3. 客户端无统计 (No Client-Side Statistics)
   • 👍：实现简单，客户端无额外负担。
   • 👎：用户完全不了解自己在客户端内的综合使用情况，无法基于数据做出决策。

建议增加的功能 (Suggested Feature)

建议在客户端应用程序内部增加模型用量统计功能。客户端本身是所有模型请求的发起点（无论是发往云端 API 还是本地模型），因此具备记录这些请求信息的天然优势。

核心实现思路:

1. 请求拦截/记录: 在客户端发送请求到模型服务商之前或收到响应之后，记录关键信息。
2. 数据提取:
   • 识别请求对应的服务商标识（如配置名称、API Endpoint）。
   • 识别请求使用的模型名称（如 gpt-4o, claude-3-opus-20240229, llama3-70b）。
   • 从服务商的响应中提取Token 使用量（Prompt Tokens, Completion Tokens, Total Tokens）。大多数标准 API（如 OpenAI API 兼容格式）会在响应体中包含 usage 字段。对于无法提供精确 Token 数的（如部分流式响应结束时、本地模型），可以考虑仅记录请求次数，或在未来版本中进行估算。
3. 本地存储: 将统计数据（服务商、模型、请求次数、Token 数、时间戳）存储在客户端本地（例如使用 LocalStorage, IndexedDB 或本地文件数据库）。数据应按服务商和模型进行聚合。
4. 数据持久化: 确保统计数据在应用重启后仍然保留。

需要统计的关键指标:

• 服务商/模型配置名称 (Provider/Model Config Name)
• 模型名称 (Model Name)
• 请求次数 (Request Count)
• 提示 Token 数 (Prompt Tokens)
• 生成 Token 数 (Completion Tokens)
• 总 Token 数 (Total Tokens)
• 思考 Token 数 (Thoughts Tokens)

数据展示与用户界面 (Data Display and UI)

为了让用户能够方便地查看和理解用量统计，建议：

1. 专用统计页面/区域: 在客户端设置或侧边栏增加一个“用量统计”(Usage Statistics) 的入口。
2. 数据表格: 以表格形式清晰展示每个服务商/模型的各项统计指标。应支持按列排序。
3. 可视化图表: 使用图表直观展示占比和对比。
4. 时间范围选择: 提供时间筛选器，允许用户查看特定时间段（如“今天”、“过去7天”、“过去30天”、“总计”）的统计数据。
5. 重置功能: 提供一个选项，允许用户清除所有或选定时间范围的统计数据。

界面示例 (概念图):

+-------------------------------------------------------------------+
| 用量统计 (Usage Statistics)                                       |
+-------------------------------------------------------------------+
| 时间范围: [过去30天 ▼]  [重置数据]                               |
+-------------------------------------------------------------------+

请求次数分布 (按服务商/模型):

pie
    title 请求次数分布 (过去30天)
    "OpenAI (GPT-4o)" : 150
    "Anthropic (Claude 3)" : 100
    "Local Llama3" : 50
    "Groq (Mixtral)" : 30

Loading

Token 总用量对比 (按服务商/模型):
(注意: Mermaid 的 xychart 可能在所有环境中渲染效果不同，这里用 K Tokens 作为单位)

xychart-beta
    title "Token 总用量 (过去30天, 单位: K Tokens)"
    x-axis "服务商/模型" ["OpenAI (GPT-4o)", "Anthropic (Claude 3)", "Local Llama3", "Groq (Mixtral)"]
    y-axis "总 Tokens (K)" 0 --> 1300
    bar [1200, 800, 350, 250]

Loading

详细数据:

服务商/模型	请求数	Prompt Tokens	Comp. Tokens	Total Tokens
OpenAI (GPT-4o)	150	500K	700K	1.2M
Anthropic (Claude 3)	100	300K	500K	800K
Local Llama3	50	150K	200K	350K
Groq (Mixtral)	30	100K	150K	250K

潜在扩展 (Potential Extensions)

• 成本估算 (Cost Estimation): 允许用户为付费 API 输入单价（例如 $/1M prompt tokens, $/1M completion tokens），客户端根据用量估算成本。需要注意处理不同服务商复杂的计价模型。
• 按会话/标签统计 (Per-Session/Tag Statistics): 如果应用支持会话或标签功能，可以增加按会话或标签维度统计用量的能力。
• 数据导出 (Data Export): 提供将统计数据导出为 CSV 或 JSON 格式的功能，方便用户进行离线分析或备份。
• 用量预警 (Usage Alerts): 允许用户设置 Token 用量或估算成本的阈值，并在达到时进行提醒。

总结 (Summary)

在客户端增加模型用量统计功能，可以为用户提供一个统一、便捷的方式来了解和管理他们对不同模型服务商的使用情况。这有助于用户优化成本、做出更明智的模型选择，并提升对自身工作流的洞察力。该功能利用了客户端作为请求发起点的优势，实现成本相对较低，且能提供直接面向用户的价值。

Links

• [Request] Daily token count statistics by model #7557

[arvinxx]

1. 先设计 db schema 描述方案。建议参考 litellm 的 LiteLLM_SpendLogs、LiteLLM_ErrorLogs 表，在我们的使用中是非常满足需求的。然后基于统计视角可以做一些视图： LiteLLM_DailyUserSpend、LiteLLM_DailyTagSpend 、LiteLLM_DailyModelSpend 等；
2. 可能需要考虑的一个问题是现在的 ai 请求有的走的是 edge runtime，有的走的是 nodejs runtime，要落库的话就会需要考虑这部分的实现要如何改造的问题。可能的一个思路是针对 edge runtime 提供 edge 友好的 http db 请求方案。
3. 最后的可视化报表我觉得一个比较不错的参考是 openai 的 dashboard

[cy948]

如果先考虑 1,3 的话， Gemini 给了个数据库表设计的思路。统计时主要考虑了这几个指标：

• 服务商性能指标
• 费用指标
  • Usage 信息
  • 截至请求时的 provider 设定价格
• 服务商标识
• 用户标识

---

设计思路（再次精简）

1. 核心日志记录: (不变) 借鉴 LiteLLM 的 SpendLogs 和 ErrorLogs，我们需要两个核心表来分别记录成功（或已完成）的 AI 请求和失败的 AI 请求。这是数据分析的基础。
2. 丰富维度信息: (更新) 为了支持类似 OpenAI Dashboard 的多维度分析（按用户、按模型、按服务提供商、按时间、按标签等），日志表中需要包含尽可能多的上下文信息作为维度字段。我们将使用 model_provider 或类似字段来区分不同的下游 AI 服务提供商，而不是将 api_key_id 作为主要的分析维度。 api_key_id 仍会记录，主要用于审计和识别请求来源凭证，但不是聚合分析的主要视角。
3. 关键指标: (不变) 必须记录核心的量化指标，如 Token 消耗（Prompt、Completion、Total）、请求耗时、费用（Spend）等。
4. 运行时环境区分: (不变) 需要一个字段来标识请求是通过 Edge Runtime 处理还是 Node.js Runtime 处理，以便后续分析或问题排查。
5. 预聚合/统计表 (视图思路): (不变) 为了优化 Dashboard 的查询性能，特别是对于时间跨度较长或数据量大的情况，设计预聚合的统计表（或数据库视图）是必要的。这些表将按天聚合关键维度（用户、模型、服务提供商、标签）的指标。
6. 可扩展性: (不变) 字段类型选择要考虑未来可能的变化（例如，使用 TEXT 或 VARCHAR 而不是定长 CHAR，使用 JSONB 或 JSON 存储灵活的元数据）。
7. 关联性: (不变) 通过 request_id 等标识符，确保成功日志和错误日志（如果适用）可以关联。

移除字段:

• organization_id
• team_id
• ip_address

精简后的表设计描述

---

1. RequestLog (个人版)

功能: 记录每一次成功或完成的 AI API 请求的详细信息和资源消耗情况。

字段描述:

• request_id (类型: String 或 UUID):
  • 意义: 请求的唯一标识符。主键。
• start_time (类型: DateTime 或 Timestamp with Time Zone):
  • 意义: 请求处理开始的时间。
• end_time (类型: DateTime 或 Timestamp with Time Zone):
  • 意义: 请求处理完成的时间。
• latency_ms (类型: Integer):
  • 意义: 请求处理的总耗时（毫秒）。
• user_id (类型: String):
  • 意义: 用户的唯一标识符。即使是个人应用，也建议保留一个用户标识，便于未来可能的扩展或区分不同设备/场景下的使用。
• api_key_id (类型: String):
  • 意义: 用于认证的 API Key 的标识符（或其哈希值）。用于审计追踪。
• model_name (类型: String):
  • 意义: 请求使用的模型名称。
• model_provider (类型: String):
  • 意义: 提供该模型的下游服务商标识。
• call_type (类型: String, 建议使用枚举):
  • 意义: API 调用的类型 (chat, image, etc.)。
• prompt_tokens (类型: Integer):
  • 意义: Prompt Token 数量。
• completion_tokens (类型: Integer):
  • 意义: Completion Token 数量。
• total_tokens (类型: Integer):
  • 意义: 总 Token 数量。
• cost (类型: Decimal 或 Float):
  • 意义: 本次请求的预估费用。
• currency (类型: String):
  • 意义: 费用的货币单位。
• status_code (类型: Integer):
  • 意义: 请求完成时的状态码。
• runtime_environment (类型: String, 建议使用枚举: 'edge', 'nodejs'):
  • 意义: 处理请求的运行时环境。
• tags (类型: JSON 或 Array of Strings):
  • 意义: 用户为请求附加的标签。
• cache_status (类型: String, 可选, 建议枚举):
  • 意义: 缓存使用情况。
• request_details (类型: JSON, 可选):
  • 意义: 请求的关键参数（注意脱敏）。
• response_details (类型: JSON, 可选):
  • 意义: 响应的关键元数据（注意脱敏）。

---

2. ErrorLog (个人版)

功能: 记录处理失败的 AI API 请求的详细信息。

字段描述:

• error_id (类型: String 或 UUID):
  • 意义: 错误记录的唯一标识符。主键。
• request_id (类型: String 或 UUID, 可选):
  • 意义: 关联的原始请求 ID。
• timestamp (类型: DateTime 或 Timestamp with Time Zone):
  • 意义: 错误发生的时间。
• user_id (类型: String, 可选):
  • 意义: 发生错误的用户标识。
• api_key_id (类型: String, 可选):
  • 意义: 发生错误时使用的 API Key 标识。
• model_name, model_provider, call_type (类型: String, 可选):
  • 意义: 提供错误的上下文，记录尝试使用的模型和服务提供商。
• runtime_environment (类型: String, 建议使用枚举: 'edge', 'nodejs'):
  • 意义: 错误发生的运行时环境。
• error_code (类型: String 或 Integer):
  • 意义: 具体的错误代码。
• error_message (类型: Text 或 String):
  • 意义: 详细的错误信息。
• error_type (类型: String, 可选):
  • 意义: 错误的分类。
• request_details (类型: JSON, 可选):
  • 意义: 导致错误的请求参数（注意脱敏）。

---

3. DailyUsageSummary (个人版 - 视图或物化视图/统计表)

功能: 按天聚合 RequestLog 中的数据，提供快速查询日度使用情况的能力。

字段描述:

• summary_id (类型: String 或 UUID):
  • 意义: 聚合记录的唯一标识符。主键。
• date (类型: Date):
  • 意义: 统计数据的日期。
• user_id (类型: String):
  • 意义: 用户标识维度。
• model_name (类型: String):
  • 意义: 模型维度。
• model_provider (类型: String):
  • 意义: 服务提供商维度。
• call_type (类型: String):
  • 意义: API 能力维度。
• runtime_environment (类型: String):
  • 意义: 运行时环境维度。
• tag (类型: String, 注意: 处理多标签问题):
  • 意义: 标签维度。
• total_requests (类型: Integer):
  • 意义: 当天该维度组合下的总请求数。
• successful_requests (类型: Integer):
  • 意义: 当天该维度组合下的成功请求数。
• failed_requests (类型: Integer):
  • 意义: 当天该维度组合下的失败请求数。
• total_prompt_tokens (类型: BigInt):
  • 意义: 当天该维度组合下的总 Prompt Token 消耗。
• total_completion_tokens (类型: BigInt):
  • 意义: 当天该维度组合下的总 Completion Token 消耗。
• total_tokens (类型: BigInt):
  • 意义: 当天该维度组合下的总 Token 消耗。
• total_cost (类型: Decimal 或 Float):
  • 意义: 当天该维度组合下的总费用。
• currency (类型: String):
  • 意义: 费用的货币单位。
• updated_at (类型: DateTime 或 Timestamp):
  • 意义: 该聚合记录最后更新的时间。

如何满足 OpenAI Dashboard 功能 (个人版):

这个精简后的 Schema 依然可以很好地支持之前描述的 OpenAI Dashboard 功能，只是分析的上下文限定在单个用户内：

• Usage Overview: 查询 DailyUsageSummary 按 date 聚合。
• Group by (Model, Provider, Tag): DailyUsageSummary 已按这些维度聚合。
• Date Range Slider: 查询 DailyUsageSummary 时使用 WHERE date BETWEEN timestart AND timeend。
• API Capabilities: 查询 DailyUsageSummary 时按 call_type 筛选/分组。
• Spend Categories (Model, Tag, Provider): 查询 DailyUsageSummary 时按 model_name, tag, 或 model_provider 分组聚合 total_cost。
• User View: 虽然只有一个用户，但 user_id 字段仍在，可以按此过滤（如果未来需要支持多用户，结构已备好）。
• Service View (按服务提供商): 查询 DailyUsageSummary 时按 model_provider 筛选/分组。
• Error Information: 查询 ErrorLog 表。

这个版本更加轻量，符合个人应用的需求。

[arvinxx]

Team 和 organization 还是需要的，后面会用到

[cy948]

那 ip_address 要保留吗？

[arvinxx]

那 ip_address 要保留吗？

可以保留下

[cy948]

一、数据采集侧交互过程

数据采集侧的核心任务是当 AI 请求发生时，准确、完整地记录相关信息到 RequestLog 或 ErrorLog，并周期性地将 RequestLog 的数据聚合到 DailyUsageSummary 表中。

核心参与者:

• Client Application: 用户或外部系统发起的 AI 请求源。
• AI Gateway (Your System): 接收请求，进行预处理、认证、路由，并与下游 AI 服务交互。它可以是 Edge Runtime 或 Node.js Runtime。
• Downstream AI Service: 实际执行 AI 推理的服务 (如 OpenAI API, Anthropic API 等)。
• Database: 存储 RequestLog, ErrorLog, DailyUsageSummary 等表。
• Aggregation Service: 一个后台服务或定时任务，负责从 RequestLog 聚合数据到 DailyUsageSummary。

交互流程 (Mermaid Sequence Diagram):

sequenceDiagram
    participant ClientApp
    participant AIGateway as AI Gateway (Edge/Node.js)
    participant DownstreamAIService as Downstream AI Service
    participant Database
    participant AggregationService as Aggregation Service (Cron Job/Worker)

    ClientApp->>AIGateway: 1. 发起 AI 请求 (e.g., /v1/chat/completions)
    AIGateway->>AIGateway: 2. 记录请求开始时间， user_id， api_key_id， runtime_environment等初始信息
    AIGateway->>DownstreamAIService: 3. 调用下游 AI 服务
    DownstreamAIService-->>AIGateway: 4. 返回 AI 服务响应 (成功或失败)
    AIGateway->>AIGateway: 5. 计算 tokens， cost， latency； 记录 model_name， model_provider， status_code 等
    
    alt 请求成功
        AIGateway->>Database: 6a. INSERT INTO RequestLog (包含所有成功请求的字段)
        Database-->>AIGateway: 确认写入
    else 请求失败 (在AI Gateway或Downstream AI Service层面)
        AIGateway->>AIGateway: 记录错误信息 (error_code, error_message, error_type)
        AIGateway->>Database: 6b. INSERT INTO ErrorLog (包含所有错误日志的字段)
        Database-->>AIGateway: 确认写入
    end

    AIGateway-->>ClientApp: 7. 返回最终响应给客户端

    %% 数据聚合过程 (通常异步执行)
    Note over AggregationService, Database: 周期性执行 (e.g., 每小时/每天)
    AggregationService->>Database: 8. SELECT * FROM RequestLog WHERE start_time >= last_aggregation_point
    Database-->>AggregationService: 返回原始日志数据
    AggregationService->>AggregationService: 9. 按 (date, user_id，model_name， model_provider，tag 等) 分组聚合数据 (SUM(tokens), SUM(cost), COUNT(requests))
    AggregationService->>Database: 10. INSERT or UPDATE DailyUsageSummary (写入/更新聚合后的统计数据)
    Database-->>AggregationService: 确认写入/更新

Loading

流程说明:

1. 请求发起: 客户端应用向 AI Gateway 发起 AI 请求。
2. 初始记录: AI Gateway 收到请求后，立即记录一些初始信息，如请求ID、开始时间、用户信息、API Key ID、运行时环境（Edge/Node.js）等。
3. 调用下游: AI Gateway 将请求转发给相应的下游 AI 服务。
4. 下游响应: 下游 AI 服务处理请求并返回结果。
5. 数据计算与整理: AI Gateway 根据下游服务的响应，计算 Token 数量、费用、延迟，并整理模型名称、服务提供商、状态码等信息。
6. 日志写入:
   • 6a. 成功: 如果请求成功处理（即使下游返回的是业务层面可接受的“空”结果，但技术层面是成功的），则将所有相关信息（包括计算得到的指标和维度）写入 RequestLog 表。
   • 6b. 失败: 如果在 AI Gateway 处理过程中或下游 AI 服务返回明确错误，则记录错误详情到 ErrorLog 表。此时也可能在 RequestLog 中记录一条表示尝试但失败的记录，或者仅在 ErrorLog 中记录。
7. 返回客户端: AI Gateway 将最终结果（成功响应或错误响应）返回给客户端应用。
8. 读取原始日志: Aggregation Service（通常是一个后台定时任务）定期从 RequestLog 表中读取自上次聚合点以来的新数据。
9. 数据聚合: Aggregation Service 在内存中或通过数据库查询对读取到的原始日志数据进行分组聚合，计算每日、每用户、每模型、每服务提供商、每标签等的总请求数、总 Token 数、总费用等。
10. 写入统计表: 将聚合后的统计数据写入（或更新）到 DailyUsageSummary 表中。通常使用 UPSERT (Update or Insert) 逻辑，如果某一天某个维度组合的记录已存在则更新，否则插入新记录。

---

二、数据展示侧交互过程

数据展示侧的核心任务是从数据库中高效地查询数据（主要依赖 DailyUsageSummary），并将其以图表和表格的形式呈现给用户，支持用户进行筛选、分组和下钻。

核心参与者:

• User: 操作 Dashboard 的用户。
• Dashboard UI (Frontend): 用户交互界面，负责发送请求和渲染数据。
• Backend API (Your Service): 提供数据查询接口，处理前端请求，从数据库获取数据并返回。
• Database: 存储 RequestLog, ErrorLog, DailyUsageSummary 等表。

交互流程 (Mermaid Sequence Diagram):

sequenceDiagram
    participant User
    participant DashboardUI as Dashboard UI (Frontend)
    participant BackendAPI as Backend API
    participant Database

    User->>DashboardUI: 1. 打开Dashboard / 应用筛选条件 (e.g., 日期范围, Group by 'model_provider')
    DashboardUI->>DashboardUI: 2. 构建API请求参数
    DashboardUI->>BackendAPI: 3. GET /api/usage-summary?start_date=...&end_date=...&group_by=model_provider&filter_user_id=...
    
    BackendAPI->>Database: 4. SELECT date, model_provider, SUM(total_cost) as spend, SUM(total_tokens) as tokens, SUM(total_requests) as requests FROM DailyUsageSummary WHERE date BETWEEN ? AND ? [AND user_id = ?] GROUP BY date, model_provider ORDER BY date
    Database-->>BackendAPI: 5. 返回聚合后的统计数据
    
    BackendAPI->>BackendAPI: 6. (可选) 进一步处理/格式化数据
    BackendAPI-->>DashboardUI: 7. 返回JSON数据
    
    DashboardUI->>DashboardUI: 8. 渲染图表 (e.g., 消费趋势折线图) 和表格
    User->>DashboardUI: 9. (可选) 点击图表项进行下钻或查看详细日志
    
    alt 用户请求查看详细日志 (下钻)
        DashboardUI->>BackendAPI: 10a. GET /api/request-logs?request_id=... OR /api/request-logs?date=...&user_id=...&model_name=... (查询条件更细)
        BackendAPI->>Database: 11a. SELECT * FROM RequestLog WHERE ... [LIMIT N] OR SELECT * FROM ErrorLog WHERE ...
        Database-->>BackendAPI: 返回原始日志数据
        BackendAPI-->>DashboardUI: 返回JSON数据
        DashboardUI->>DashboardUI: 显示详细日志弹窗或页面
    end

Loading

流程说明:

1. 用户操作: 用户通过浏览器访问 Dashboard，并可能选择日期范围、分组方式（如按服务提供商、模型、用户）、筛选特定用户等。
2. 构建请求: Dashboard UI 根据用户的选择，构建相应的 API 请求参数。
3. API 调用: Dashboard UI向后端 API 发送获取使用情况摘要的请求。URL 中通常包含时间范围、分组依据、筛选条件等参数。
4. 数据库查询 (主要查 DailyUsageSummary):
   • Backend API 解析请求参数，并构造 SQL 查询语句。
   • 主要查询 DailyUsageSummary 表，因为它已经预聚合了数据，查询效率高。
   • 查询会根据请求中的 start_date, end_date 进行时间范围过滤，并根据 group_by 参数进行分组聚合（例如 GROUP BY date, model_provider）。
   • 其他筛选条件（如 user_id, model_name）也会加入 WHERE 子句。
5. 返回聚合数据: 数据库执行查询并将结果集返回给 Backend API。
6. 数据处理: Backend API 可能需要对从数据库获取的数据进行一些转换或格式化，使其更适合前端展示。
7. 返回 JSON: Backend API 将处理好的数据以 JSON 格式返回给 Dashboard UI。
8. 渲染界面: Dashboard UI 接收到数据后，使用图表库（如 Chart.js, ECharts, D3.js）和表格组件将数据可视化展示给用户。
9. 下钻操作 (可选):
   • 用户可能点击图表上的某个数据点或表格中的某一行，希望查看更详细的原始日志。
   • 10a. 请求详细日志: Dashboard UI 发起新的 API 请求，这次可能是查询 RequestLog 或 ErrorLog 表，并携带更具体的筛选条件（如精确到某个 request_id，或某天某个用户某个模型的具体请求）。
   • 11a. 查询原始日志: Backend API 从 RequestLog 或 ErrorLog 中查询满足条件的原始日志记录。
   • 后续步骤与之前类似，最终将详细日志展示给用户。

通过这样的设计，数据采集侧保证了数据的完整性和后续聚合的基础，数据展示侧则通过查询预聚合的 DailyUsageSummary 表来保证 Dashboard 的响应速度和用户体验，同时保留了下钻到原始日志的能力。