- 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)
378 lines
15 KiB
Rust
378 lines
15 KiB
Rust
//! 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
|
||
}
|