//! LLM 用量统计:按**账号**与按**账号 × 上游**两个维度计数。 //! //! 数据全部躺在共享内存里(`ust:` / `ums:` 两个键前缀),没有新文件、 //! 没有新进程——这是项目「单容器零依赖」红线下的必然选择。 //! //! ```text //! ust: → <日窗id>:<今日数>:<累计数>:<最近调用时间戳> //! ums:: → 同 上 //! ``` //! //! ## 口径:只统计"真的转发出去"的请求 //! //! 计数点在 `LlmHandler` 的**鉴权 / 白名单 / 限流全部通过之后**, //! 所以 401 / 403 / 404 / 429 都不计入。这与配额计数 `st:` 刻意不同—— //! 后者是"先增后判"(含被拒),要的是"超限后计数继续涨"的执行语义; //! 而用量统计是给人看的,把被拒的请求算进"用量"只会让人误解。 //! //! ## 为什么不做 token 级 //! //! token 数在上游响应体里,而 SSE 必须关缓冲透传(`proxy_buffering off`), //! 网关不缓冲就解析不到 `usage` 字段。要做 token 级计费得自建 upstream //! 把响应拦下来重组流,与「不引入额外常驻进程 / 不改 nginx 原生转发」冲突。 //! 因此口径统一为**请求数**,并在文档里写明。 use std::collections::BTreeMap; use serde_json::{Value, json}; use crate::config::{KEY_UMS_PREFIX, KEY_UST_PREFIX}; use crate::state; use crate::util; /// 一条统计记录的读数。`today` 已按调用方给的日窗折算过(跨天即为 0)。 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] pub struct Usage { /// 今日(本地自然日)请求数 pub today: i64, /// 累计请求数(自该计数键建立以来,不随跨天归零) pub total: i64, /// 最近一次调用时间戳;0 = 从未调用 pub last_ts: i64, } impl Usage { /// 累加(聚合用)。`last_ts` 取最大。 fn merge(&mut self, other: &Usage) { self.today += other.today; self.total += other.total; if other.last_ts > self.last_ts { self.last_ts = other.last_ts; } } pub fn json(&self) -> Value { json!({ "today": self.today, "total": self.total, "last_ts": self.last_ts, "last_ts_text": if self.last_ts > 0 { util::fmt_time(self.last_ts) } else { String::new() }, }) } } /// 一个账号的用量 + 其下每个上游的明细 pub struct UserUsage { pub username: String, pub usage: Usage, pub models: Vec<(String, Usage)>, } /// 一个上游的用量 + 用它的每个账号的明细 pub struct ModelUsage { pub slot: String, pub usage: Usage, pub users: Vec<(String, Usage)>, } // =========================================================================== // 编解码 // =========================================================================== /// `<日窗id>:<今日数>:<累计数>:<最近调用时间戳>`。 /// 字段全是数字,用 `:` 分隔不会与键名里的字符冲突(键不参与这段编码)。 fn encode(day: i64, u: &Usage) -> String { format!("{}:{}:{}:{}", day, u.today, u.total, u.last_ts) } /// 解码并把"今日数"按当前日窗折算——跨天时旧值归零,累计值保留。 fn decode(payload: &str, day: i64) -> Usage { let mut it = payload.split(':'); let stored_day = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); let today = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); let total = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); let last_ts = it.next().and_then(|s| s.parse::().ok()).unwrap_or(0); Usage { today: if stored_day == day { today } else { 0 }, total, last_ts } } fn bump(prefix: &[u8], name: &str, day: i64, now: i64) { let current = state::get(prefix, name.as_bytes()) .map(|(payload, _)| decode(&payload, day)) .unwrap_or_default(); let next = Usage { today: current.today + 1, total: current.total + 1, last_ts: now, }; // 与限流的窗口计数同款近似语义:读-增-写不加写锁(并发下偶发少计一次), // 换来的是 LLM 热路径不为统计去抢锁。统计用途下这点误差无影响。 state::put(prefix, name.as_bytes(), encode(day, &next).as_bytes(), 0); } // =========================================================================== // 写 // =========================================================================== /// 记录一次已放行的 LLM 请求。**在鉴权/白名单/限流全通过之后调用**。 pub fn record(username: &str, slot: &str, now: i64) { if username.is_empty() || slot.is_empty() { return; } let day = util::day_id(now); bump(KEY_UST_PREFIX, username, day, now); bump(KEY_UMS_PREFIX, &format!("{username}:{slot}"), day, now); } /// 删除账号时清理其全部用量键(`ust:` 与 `ums::*`)。 /// /// 用量键是**按前缀扫出来**做报表的(`all_users` / `all_models`),不清就会让 /// 已删除的账号继续挂在用量榜上。这与「删账号必须摘 `ukey:` 索引」是同类的 /// 正确性问题(只是影响面在报表而非鉴权,因此更容易被漏掉)。 pub fn forget(username: &str) { if username.is_empty() { return; } state::remove(KEY_UST_PREFIX, username.as_bytes()); // 先物化键名再删,避免"遍历中改表" let prefix = format!("{username}:"); let keys: Vec = state::iter_prefix(KEY_UMS_PREFIX) .into_iter() .map(|(name, _)| name) .filter(|name| name.starts_with(&prefix)) .collect(); for name in keys { state::remove(KEY_UMS_PREFIX, name.as_bytes()); } } // =========================================================================== // 读 // =========================================================================== /// 单账号读数(不含模型明细) pub fn user(username: &str, now: i64) -> Usage { let day = util::day_id(now); state::get(KEY_UST_PREFIX, username.as_bytes()) .map(|(payload, _)| decode(&payload, day)) .unwrap_or_default() } /// 单账号 × 上游明细,按 slot 升序 pub fn user_models(username: &str, now: i64) -> Vec<(String, Usage)> { let day = util::day_id(now); let prefix = format!("{username}:"); let mut out: Vec<(String, Usage)> = state::iter_prefix(KEY_UMS_PREFIX) .into_iter() .filter_map(|(name, payload)| { let slot = name.strip_prefix(&prefix)?.to_owned(); Some((slot, decode(&payload, day))) }) .collect(); out.sort_by(|a, b| a.0.cmp(&b.0)); out } /// 全部账号的用量(含各自的模型明细),按账号名升序。 /// /// 只扫一次 `ums:` 前缀再分组,避免"每个账号遍历一遍全表"。 pub fn all_users(now: i64) -> Vec { let day = util::day_id(now); let mut by_user: BTreeMap> = BTreeMap::new(); for (name, payload) in state::iter_prefix(KEY_UMS_PREFIX) { let Some((username, slot)) = name.split_once(':') else { continue; }; by_user .entry(username.to_owned()) .or_default() .push((slot.to_owned(), decode(&payload, day))); } for models in by_user.values_mut() { models.sort_by(|a, b| a.0.cmp(&b.0)); } state::iter_prefix(KEY_UST_PREFIX) .into_iter() .map(|(username, payload)| { let usage = decode(&payload, day); let models = by_user.remove(&username).unwrap_or_default(); UserUsage { username, usage, models } }) .collect() } /// 全部上游的用量(含用到它的账号明细),按 slot 升序。 pub fn all_models(now: i64) -> Vec { let day = util::day_id(now); // slot → (总量, 各账号) let mut by_slot: BTreeMap)> = BTreeMap::new(); for (name, payload) in state::iter_prefix(KEY_UMS_PREFIX) { let Some((username, slot)) = name.split_once(':') else { continue; }; let u = decode(&payload, day); let entry = by_slot.entry(slot.to_owned()).or_default(); entry.0.merge(&u); entry.1.push((username.to_owned(), u)); } by_slot .into_iter() .map(|(slot, (usage, mut users))| { users.sort_by(|a, b| a.0.cmp(&b.0)); ModelUsage { slot, usage, users } }) .collect() } /// 全局合计 pub fn totals(now: i64) -> Usage { let day = util::day_id(now); let mut sum = Usage::default(); for (_, payload) in state::iter_prefix(KEY_UST_PREFIX) { sum.merge(&decode(&payload, day)); } sum } /// 管理台用量页的完整投影 pub fn overview(now: i64) -> Value { let users: Vec = all_users(now) .into_iter() .map(|u| { json!({ "username": u.username, "today": u.usage.today, "total": u.usage.total, "last_ts": u.usage.last_ts, "last_ts_text": if u.usage.last_ts > 0 { util::fmt_time(u.usage.last_ts) } else { String::new() }, "models": u.models.iter().map(|(slot, usage)| { json!({ "slot": slot, "today": usage.today, "total": usage.total }) }).collect::>(), }) }) .collect(); let models: Vec = all_models(now) .into_iter() .map(|m| { json!({ "slot": m.slot, "today": m.usage.today, "total": m.usage.total, "last_ts": m.usage.last_ts, "last_ts_text": if m.usage.last_ts > 0 { util::fmt_time(m.usage.last_ts) } else { String::new() }, "users": m.users.iter().map(|(name, usage)| { json!({ "username": name, "today": usage.today, "total": usage.total }) }).collect::>(), }) }) .collect(); let sum = totals(now); json!({ "total": sum.json(), "users": users, "models": models, }) }