Files
ipass__ipass/rust/crates/plugin-llm/src/stats.rs
T
admin 0d8e1c94d1 refactor(plugin): P3 拆 plugin-llm —— LLM 路由/配额/计量/审计/趋势迁入独立插件
- plugin-llm 新 crate:llm/upstreams/usage_filter/llm_audit/stats/handlers/api/config/models/store
- 下行契约(downstream_key/identity/check_quota/fail)与记账原语(usage::bump/read/bump_day)已下沉 ipass-core
- usage_filter 改走 loc::enabled(Switch::Llm) + core::plugin::ctx_index(解除对 gateway 私有 ModuleConfig 的依赖)
- gateway 收缩为壳:LlmHandler/LlmHealthHandler/AuditHandler 随 LlmPlugin 装配;
  /api/admin/trend 留 gateway(需 users+upstreams+apix 三方名册,组合根职责)
- 行为等价:262 项回归全绿(gateway 102 + llm 160)
2026-09-13 12:08:34 +08:00

378 lines
15 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! LLM 用量统计:按**账号**与按**账号 × 上游**两个维度计数。
//!
//! 数据全部躺在共享内存里(`ust:` / `ums:` 两个键前缀),没有新文件、
//! 没有新进程——这是项目「单容器零依赖」红线下的必然选择。
//!
//! ```text
//! ust:<username> → <日窗id>:<今日数>:<累计数>:<最近调用时间戳>
//! ums:<username>:<slot> → 同 上
//! ```
//!
//! 本模块是**业务解读层**:键前缀(`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:<user>` 与 `ums:<user>:*`)。
///
/// 用量键是**按前缀扫出来**做报表的(`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:<user>:<day>` 是按前缀扫不到的(键里还带日窗 id),
// 靠 TTL 自然淘汰也能收敛,但删账号后趋势图仍会挂着幽灵账号 90 天
for p in [KEY_UMS_PREFIX, KEY_UTMS_PREFIX, KEY_UDAY_USER_PREFIX] {
let keys: Vec<String> = 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<UserUsage> {
let day = util::day_id(now);
let mut by_user: BTreeMap<String, Vec<(String, Usage)>> = 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<ModelUsage> {
let day = util::day_id(now);
// slot → (总量, 各账号)
let mut by_slot: BTreeMap<String, (Usage, Vec<(String, Usage)>)> = 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<String, TokenUsage>,
BTreeMap<String, TokenUsage>,
BTreeMap<String, BTreeMap<String, TokenUsage>>,
) {
let day = util::day_id(now);
let mut by_user: BTreeMap<String, TokenUsage> = 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<String, TokenUsage> = BTreeMap::new();
let mut by_pair: BTreeMap<String, BTreeMap<String, TokenUsage>> = 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<Value> = 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::<Vec<_>>(),
})
})
.collect();
let models: Vec<Value> = 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::<Vec<_>>(),
})
})
.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::<Vec<_>>(),
"in": v.iter().map(|b| b.tin).collect::<Vec<_>>(),
"out": v.iter().map(|b| b.tout).collect::<Vec<_>>(),
})
}
/// 最近 `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<i64> = (0..days).rev().map(|i| now - i * 86400).collect();
let labels: Vec<String> = stamps.iter().map(|t| util::fmt_day(*t)).collect();
let ids: Vec<i64> = stamps.iter().map(|t| util::day_id(*t)).collect();
let total: Vec<usage::DayBucket> =
ids.iter().map(|d| usage::day_bucket(KEY_UDAY_PREFIX, &d.to_string())).collect();
let by_user: Vec<Value> = users
.iter()
.map(|u| {
let series: Vec<usage::DayBucket> = 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<Value> = slots
.iter()
.map(|s| {
let series: Vec<usage::DayBucket> = 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
}