//! LLM 用量统计:按**账号**与按**账号 × 上游**两个维度计数。 //! //! 数据全部躺在共享内存里(`ust:` / `ums:` 两个键前缀),没有新文件、 //! 没有新进程——这是项目「单容器零依赖」红线下的必然选择。 //! //! ```text //! ust: → <日窗id>:<今日数>:<累计数>:<最近调用时间戳> //! ums:: → 同 上 //! ``` //! //! 本模块是**业务解读层**:键前缀(`ust:` / `ums:` / `utt:` / `utms:` / //! `ud:` / `udu:` / `uds:`)在这里与内核记账原语(`ipass_core::usage`)组合。 //! 原语本身无任何业务语义——「去掉 LLM 还要(趋势图要给 apix 用)、 //! 去掉 apix 还要(趋势图要给 LLM 用)」⇒ 原语放内核,口径与聚合放本 crate。 //! //! ## 口径:只统计"真的转发出去"的请求 //! //! 计数点在 `LlmHandler` 的**鉴权 / 白名单 / 限流全部通过之后**, //! 所以 401 / 403 / 404 / 429 都不计入。这与配额计数 `st:` 刻意不同—— //! 后者是"先增后判"(含被拒),要的是"超限后计数继续涨"的执行语义; //! 而用量统计是给人看的,把被拒的请求算进"用量"只会让人误解。 //! //! ## token 级计量(2026-09-12 起) //! //! token 数来自上游响应体里的 `usage` 字段:`usage_filter` 模块在 **body filter 链** //! 旁路扫描响应(SSE 尾部 / 非 stream JSON 尾部),零缓冲、不影响透传; //! log 阶段统一入账到 `utt:` / `utms:` 两个键前缀,编码与本文件同款格式。 //! 抓不到 usage(如 OpenAI 流式客户端没带 `include_usage`)= 记 0,不补估。 //! 计数口径与请求数一致:**只算真的转发出去且上游给了 usage 的**。 use std::collections::BTreeMap; use serde_json::{Value, json}; use crate::config::{ KEY_UDAY_PREFIX, KEY_UDAY_SLOT_PREFIX, KEY_UDAY_USER_PREFIX, KEY_UMS_PREFIX, KEY_UTMS_PREFIX, KEY_UST_PREFIX, KEY_UTT_PREFIX, TREND_DAYS_DEFAULT, TREND_DAYS_MAX, TREND_KEEP_SECS, }; use ipass_core::{state, usage, util}; // 内核记账类型与读数结构(re-export 方便 gateway / api 组合使用) pub use ipass_core::usage::{TokenUsage, Usage}; /// 一个账号的用量 + 其下每个上游的明细 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)>, } // =========================================================================== // 写 // =========================================================================== /// 记录一次已放行的 LLM 请求。**在鉴权/白名单/限流全通过之后调用**。 pub fn record(username: &str, slot: &str, now: i64) { if username.is_empty() || slot.is_empty() { return; } let day = util::day_id(now); usage::bump(KEY_UST_PREFIX, username, day, now); usage::bump(KEY_UMS_PREFIX, &format!("{username}:{slot}"), day, now); // 日桶:趋势图数据源(请求维度)。三个维度各写一次,键名带日窗 id let delta = usage::DayBucket { requests: 1, ..Default::default() }; usage::bump_day(KEY_UDAY_PREFIX, &day.to_string(), &delta, TREND_KEEP_SECS); usage::bump_day(KEY_UDAY_USER_PREFIX, &format!("{username}:{day}"), &delta, TREND_KEEP_SECS); usage::bump_day(KEY_UDAY_SLOT_PREFIX, &format!("{slot}:{day}"), &delta, TREND_KEEP_SECS); } /// 累加一次真实 token 消耗(来源:body filter 从上游响应抓到的 usage)。 /// 口径:只有抓到 usage 才记账;抓不到不补估。 pub fn add_tokens(username: &str, slot: &str, tin: u64, tout: u64, now: i64) { if username.is_empty() || slot.is_empty() || (tin == 0 && tout == 0) { return; } let day = util::day_id(now); usage::bump_t(KEY_UTT_PREFIX, username, tin, tout, day, now); usage::bump_t(KEY_UTMS_PREFIX, &format!("{username}:{slot}"), tin, tout, day, now); // 日桶:趋势图数据源(token 维度)。与 record 写的是同一批键,字段互补 let delta = usage::DayBucket { tin: tin as i64, tout: tout as i64, ..Default::default() }; usage::bump_day(KEY_UDAY_PREFIX, &day.to_string(), &delta, TREND_KEEP_SECS); usage::bump_day(KEY_UDAY_USER_PREFIX, &format!("{username}:{day}"), &delta, TREND_KEEP_SECS); usage::bump_day(KEY_UDAY_SLOT_PREFIX, &format!("{slot}:{day}"), &delta, TREND_KEEP_SECS); } /// 删除账号时清理其全部用量键(`ust:` 与 `ums::*`)。 /// /// 用量键是**按前缀扫出来**做报表的(`all_users` / `all_models`),不清就会让 /// 已删除的账号继续挂在用量榜上。这与「删账号必须摘 `ukey:` 索引」是同类的 /// 正确性问题(只是影响面在报表而非鉴权,因此更容易被漏掉)。 pub fn forget(username: &str) { if username.is_empty() { return; } // 先物化键名再删,避免"遍历中改表"(四个键前缀同一套路) let prefix = format!("{username}:"); for p in [KEY_UST_PREFIX, KEY_UTT_PREFIX] { state::remove(p, username.as_bytes()); } // 日桶两个维度也要清:`udu::` 是按前缀扫不到的(键里还带日窗 id), // 靠 TTL 自然淘汰也能收敛,但删账号后趋势图仍会挂着幽灵账号 90 天 for p in [KEY_UMS_PREFIX, KEY_UTMS_PREFIX, KEY_UDAY_USER_PREFIX] { let keys: Vec = state::iter_prefix(p) .into_iter() .map(|(name, _)| name) .filter(|name| name.starts_with(&prefix)) .collect(); for name in keys { state::remove(p, name.as_bytes()); } } } // =========================================================================== // 读 // =========================================================================== /// 单账号读数(不含模型明细) pub fn user(username: &str, now: i64) -> Usage { let day = util::day_id(now); usage::read(KEY_UST_PREFIX, username, day) } /// 单账号 × 上游明细,按 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, _)| { let slot = name.strip_prefix(&prefix)?.to_owned(); Some((slot, usage::read(KEY_UMS_PREFIX, &name, 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, _) 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(), usage::read(KEY_UMS_PREFIX, &name, 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, _)| { let usage = usage::read(KEY_UST_PREFIX, &username, 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, _) in state::iter_prefix(KEY_UMS_PREFIX) { let Some((username, slot)) = name.split_once(':') else { continue; }; let u = usage::read(KEY_UMS_PREFIX, &name, 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 (name, _) in state::iter_prefix(KEY_UST_PREFIX) { sum.merge(&usage::read(KEY_UST_PREFIX, &name, day)); } sum } /// 单账号 token 读数 pub fn tokens_user(username: &str, now: i64) -> TokenUsage { let day = util::day_id(now); usage::read_t(KEY_UTT_PREFIX, username, day) } /// token 全表一次扫齐:`(按账号, 按上游, 按 账号→上游)`。 /// utt/utms 各扫一遍,避免报表页多次遍历共享内存。 fn tokens_scan( now: i64, ) -> ( BTreeMap, BTreeMap, BTreeMap>, ) { let day = util::day_id(now); let mut by_user: BTreeMap = BTreeMap::new(); for (name, _) in state::iter_prefix(KEY_UTT_PREFIX) { let t = usage::read_t(KEY_UTT_PREFIX, &name, day); by_user.insert(name, t); } let mut by_slot: BTreeMap = BTreeMap::new(); let mut by_pair: BTreeMap> = BTreeMap::new(); for (name, _) in state::iter_prefix(KEY_UTMS_PREFIX) { let Some((username, slot)) = name.split_once(':') else { continue; }; let t = usage::read_t(KEY_UTMS_PREFIX, &name, day); by_slot.entry(slot.to_owned()).or_default().merge(&t); by_pair.entry(username.to_owned()).or_default().insert(slot.to_owned(), t); } (by_user, by_slot, by_pair) } /// 管理台用量页的完整投影 pub fn overview(now: i64) -> Value { let (t_by_user, t_by_slot, t_by_pair) = tokens_scan(now); let users: Vec = all_users(now) .into_iter() .map(|u| { let tin = t_by_pair.get(&u.username); 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() }, "tokens": t_by_user.get(&u.username).cloned().unwrap_or_default().json(), "models": u.models.iter().map(|(slot, usage)| { json!({ "slot": slot, "today": usage.today, "total": usage.total, "tokens": tin.and_then(|m| m.get(slot)).cloned().unwrap_or_default().json() }) }).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() }, "tokens": t_by_slot.get(&m.slot).cloned().unwrap_or_default().json(), "users": m.users.iter().map(|(name, usage)| { json!({ "username": name, "today": usage.today, "total": usage.total }) }).collect::>(), }) }) .collect(); let sum = totals(now); let mut tsum = TokenUsage::default(); for t in t_by_user.values() { tsum.merge(t); } json!({ "total": sum.json(), "tokens": tsum.json(), "users": users, "models": models, }) } // =========================================================================== // 趋势(图表数据源) // =========================================================================== /// 把一串日桶摊成图表直接能吃的三条等长数组 fn buckets_json(v: &[usage::DayBucket]) -> Value { json!({ "requests": v.iter().map(|b| b.requests).collect::>(), "in": v.iter().map(|b| b.tin).collect::>(), "out": v.iter().map(|b| b.tout).collect::>(), }) } /// 最近 `days_req` 天的趋势序列(全局 / 按账号 / 按上游)。 /// /// `days_req` 会被夹到 `[1, TREND_DAYS_MAX]`——URL 里塞个 99999 也不会把 /// 共享内存扫爆。三个维度都是**按键精确取**(键名带日窗 id), /// 成本 = 天数 × (1 + 账号数 + 上游数) 次查表,且不随历史增长。 /// /// 注意:调用方(gateway 的 `/api/admin/trend`)要先给名册——日桶键里 /// 带日窗 id,**扫不出来**,账号/上游名单由 users / upstreams / apix 提供。 pub fn trend(now: i64, days_req: i64, users: &[String], slots: &[String]) -> Value { let days = days_req.clamp(1, TREND_DAYS_MAX); // 往前推 N 天:每个采样点一个时间戳,日窗 id 现算(本地自然日,不用 UTC) let stamps: Vec = (0..days).rev().map(|i| now - i * 86400).collect(); let labels: Vec = stamps.iter().map(|t| util::fmt_day(*t)).collect(); let ids: Vec = stamps.iter().map(|t| util::day_id(*t)).collect(); let total: Vec = ids.iter().map(|d| usage::day_bucket(KEY_UDAY_PREFIX, &d.to_string())).collect(); let by_user: Vec = users .iter() .map(|u| { let series: Vec = ids .iter() .map(|d| usage::day_bucket(KEY_UDAY_USER_PREFIX, &format!("{u}:{d}"))) .collect(); let mut o = buckets_json(&series); // 全 0 的账号不回传:趋势图里一堆积零的线只会把图例挤爆 let empty = series.iter().all(|b| b.requests == 0 && b.tin == 0 && b.tout == 0); if let Value::Object(ref mut m) = o { m.insert("username".to_owned(), json!(u)); m.insert("empty".to_owned(), json!(empty)); } o }) .collect(); let by_slot: Vec = slots .iter() .map(|s| { let series: Vec = ids .iter() .map(|d| usage::day_bucket(KEY_UDAY_SLOT_PREFIX, &format!("{s}:{d}"))) .collect(); let empty = series.iter().all(|b| b.requests == 0 && b.tin == 0 && b.tout == 0); let mut o = buckets_json(&series); if let Value::Object(ref mut m) = o { m.insert("slot".to_owned(), json!(s)); m.insert("empty".to_owned(), json!(empty)); } o }) .collect(); json!({ "days": days, "labels": labels, "total": buckets_json(&total), "users": by_user, "slots": by_slot, }) } /// 趋势接口的默认天数(URL 没给 `days` 时用) pub fn trend_default_days() -> i64 { TREND_DAYS_DEFAULT }