From 832858dadea55b2922017caa5e62ff3fdb490e34 Mon Sep 17 00:00:00 2001 From: Zyy Date: Tue, 17 Nov 2026 17:06:55 +0800 Subject: [PATCH] feat(plugins): expose historical quota observations by window Let plugins page through retained account observations and find a prior baseline without reading raw provider documents or refreshing upstream. Reuse provider window identities and the existing completion index, preserving resets and gaps. Co-authored-by: Codex --- backend/crates/gateway-admin/src/model/mod.rs | 1 + .../gateway-admin/src/model/quota_history.rs | 87 ++++++++++ .../src/ports/plugin_accounts.rs | 6 + .../gateway-admin/src/ports/provider.rs | 5 + .../crates/gateway-admin/src/ports/store.rs | 10 ++ .../src/use_case/plugin_accounts.rs | 40 +++++ .../tests/use_case/accounts/mod.rs | 11 ++ .../gateway-admin/tests/use_case/mod.rs | 11 ++ backend/crates/gateway-api/tests/admin/mod.rs | 11 ++ .../runtime/src/callback/data.rs | 64 +++++++ .../runtime/src/callback/dispatch.rs | 1 + .../tests/adapter/command_line/execution.rs | 11 ++ .../runtime/tests/generation/data.rs | 34 +++- .../runtime/tests/rpc/dispatch.rs | 1 + backend/crates/gateway-plugin/sdk/README.md | 2 +- .../gateway-plugin/sdk/docs/capabilities.md | 11 ++ .../gateway-plugin/sdk/src/call/data.rs | 30 ++++ .../gateway-plugin/sdk/src/client/data.rs | 11 ++ .../provider_accounts/admin_adapter.rs | 25 ++- .../src/postgres/provider_accounts/mod.rs | 1 + .../provider_accounts/quota_history.rs | 72 ++++++++ .../tests/postgres/provider_accounts/mod.rs | 1 + .../provider_accounts/quota_history.rs | 162 ++++++++++++++++++ .../crates/providers/openai/src/admin/mod.rs | 32 ++-- .../providers/openai/src/admin/quota.rs | 28 ++- .../providers/openai/src/credential/mod.rs | 1 + .../openai/src/credential/quota/mod.rs | 1 + .../openai/src/credential/quota/passive.rs | 12 ++ .../openai/src/credential/quota/snapshot.rs | 27 +-- .../providers/openai/tests/admin/mod.rs | 27 +++ docs/architecture.md | 4 +- 31 files changed, 706 insertions(+), 34 deletions(-) create mode 100644 backend/crates/gateway-admin/src/model/quota_history.rs create mode 100644 backend/crates/gateway-store/src/postgres/provider_accounts/quota_history.rs create mode 100644 backend/crates/gateway-store/tests/postgres/provider_accounts/quota_history.rs diff --git a/backend/crates/gateway-admin/src/model/mod.rs b/backend/crates/gateway-admin/src/model/mod.rs index 931b747d0..ab422eb03 100644 --- a/backend/crates/gateway-admin/src/model/mod.rs +++ b/backend/crates/gateway-admin/src/model/mod.rs @@ -23,6 +23,7 @@ pub mod provider_credentials; pub mod proxies; pub mod quota_forecast; pub mod quota_forecast_sampling; +pub mod quota_history; pub mod reset_credit_automation; pub mod retention; pub mod settings; diff --git a/backend/crates/gateway-admin/src/model/quota_history.rs b/backend/crates/gateway-admin/src/model/quota_history.rs new file mode 100644 index 000000000..425a3e3eb --- /dev/null +++ b/backend/crates/gateway-admin/src/model/quota_history.rs @@ -0,0 +1,87 @@ +//! 单个额度桶的历史观测;原始文档只在宿主内交给 Provider 解释 + +use chrono::{DateTime, Utc}; +use serde::{Deserialize, Serialize}; + +use super::{observability::TimeRange, provider_credentials::ProviderDocument}; + +#[derive(Debug, Clone)] +pub struct QuotaHistoryQuery { + pub window_key: String, + pub range: TimeRange, + pub cursor: Option, +} + +impl QuotaHistoryQuery { + /// 起点基线最多回看一个查询区间 + pub fn scan_start(&self) -> DateTime { + self.range + .start + .checked_sub_signed(self.range.end - self.range.start) + .unwrap_or(DateTime::::MIN_UTC) + } +} + +/// 完成时间可能相同,继续读取时保留数据库精度和请求 ID +#[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct QuotaHistoryCursor { + pub completed_at: DateTime, + pub id: String, +} + +pub struct QuotaDocumentPage { + pub documents: Vec<(DateTime, ProviderDocument)>, + pub next_cursor: Option, +} + +#[derive(Debug, Clone, PartialEq)] +pub struct QuotaReading { + pub plan_type: Option, + pub used_percent: f64, + pub reset_at: Option>, +} + +pub type QuotaHistoryParser = fn(&ProviderDocument, &str) -> Option; + +pub struct QuotaHistoryPoint { + pub observed_at: DateTime, + pub reading: QuotaReading, +} + +#[derive(Default)] +pub struct QuotaHistoryPage { + pub samples: Vec, + pub baseline: Option, + pub next_cursor: Option, +} + +impl QuotaHistoryPage { + pub fn from_documents( + page: QuotaDocumentPage, + query: &QuotaHistoryQuery, + parse: QuotaHistoryParser, + ) -> Self { + let mut result = Self { + next_cursor: page.next_cursor, + ..Self::default() + }; + for (observed_at, document) in page.documents { + let Some(reading) = parse(&document, &query.window_key) else { + continue; + }; + let point = QuotaHistoryPoint { + observed_at, + reading, + }; + if observed_at < query.range.start { + // 倒序扫描遇到的第一个同桶读数就是最近基线,无需再向前翻页 + result.baseline = Some(point); + result.next_cursor = None; + break; + } + result.samples.push(point); + } + result + } +} diff --git a/backend/crates/gateway-admin/src/ports/plugin_accounts.rs b/backend/crates/gateway-admin/src/ports/plugin_accounts.rs index f6db87a26..20b93536f 100644 --- a/backend/crates/gateway-admin/src/ports/plugin_accounts.rs +++ b/backend/crates/gateway-admin/src/ports/plugin_accounts.rs @@ -34,6 +34,12 @@ pub trait PluginAccountAccess: Send + Sync { Err(AdminError::unavailable("插件额度事实查询暂不可用")) } + async fn quota_history( + &self, + account: &ProviderAccountId, + query: crate::model::quota_history::QuotaHistoryQuery, + ) -> Result; + /// 通过 Provider 原生管理路径刷新额度;不向插件暴露凭据或执行额度重置 async fn refresh_quota( &self, diff --git a/backend/crates/gateway-admin/src/ports/provider.rs b/backend/crates/gateway-admin/src/ports/provider.rs index a1004e8be..126decde4 100644 --- a/backend/crates/gateway-admin/src/ports/provider.rs +++ b/backend/crates/gateway-admin/src/ports/provider.rs @@ -349,6 +349,11 @@ pub trait ProviderAdmin: Send + Sync { Ok(None) } + /// 历史文档由 Provider 按稳定窗口键解释,不支持的 Provider 不扫描请求记录 + fn quota_history_parser(&self) -> Option { + None + } + /// 历史观测的协议字段仅由具体 Provider 解释;不支持时保留累计估算 fn quota_forecast_observation( &self, diff --git a/backend/crates/gateway-admin/src/ports/store.rs b/backend/crates/gateway-admin/src/ports/store.rs index 18c079dbb..748e0ce6c 100644 --- a/backend/crates/gateway-admin/src/ports/store.rs +++ b/backend/crates/gateway-admin/src/ports/store.rs @@ -180,6 +180,16 @@ pub trait AccountStore: windows: &[AccountUsageWindowQuery], ) -> AdminStoreResult>; + /// 按完成时间倒序读取一页保留的请求观测,不按本地计费结果筛选 + async fn quota_documents( + &self, + account: &gateway_core::account::ProviderAccountId, + provider: &gateway_core::routing::ProviderKind, + created_at: DateTime, + range: TimeRange, + before: Option<&crate::model::quota_history::QuotaHistoryCursor>, + ) -> AdminStoreResult; + /// 从同一数据库语句取得截止快照的累计用量和有界历史观测 async fn load_quota_forecast_history( &self, diff --git a/backend/crates/gateway-admin/src/use_case/plugin_accounts.rs b/backend/crates/gateway-admin/src/use_case/plugin_accounts.rs index 2a425b045..1d9ded3ef 100644 --- a/backend/crates/gateway-admin/src/use_case/plugin_accounts.rs +++ b/backend/crates/gateway-admin/src/use_case/plugin_accounts.rs @@ -126,6 +126,46 @@ impl PluginAccountAccess for DefaultPluginAccountAccess { self.quota(account_id, false).await } + async fn quota_history( + &self, + account_id: &ProviderAccountId, + query: crate::model::quota_history::QuotaHistoryQuery, + ) -> Result { + use crate::model::{observability::TimeRange, quota_history::QuotaHistoryPage}; + + let account = self + .accounts + .load_account_record(account_id) + .await + .map_err(|error| map_store_error(error, "plugin quota history"))? + .ok_or_else(|| AdminError::not_found("账号不存在"))?; + let Some(parse) = self + .provider(&account.provider_kind)? + .quota_history_parser() + else { + return Ok(QuotaHistoryPage::default()); + }; + let start = query.scan_start().max(account.created_at); + if start >= query.range.end { + return Ok(QuotaHistoryPage::default()); + } + let page = self + .accounts + .quota_documents( + account_id, + &account.provider_kind, + account.created_at, + TimeRange { + start, + end: query.range.end, + }, + query.cursor.as_ref(), + ) + .await + .map_err(|error| map_store_error(error, "plugin quota history"))?; + Ok(QuotaHistoryPage::from_documents(page, &query, parse)) + } + async fn refresh_quota( &self, account_id: &ProviderAccountId, diff --git a/backend/crates/gateway-admin/tests/use_case/accounts/mod.rs b/backend/crates/gateway-admin/tests/use_case/accounts/mod.rs index 077bea728..daf9ca81d 100644 --- a/backend/crates/gateway-admin/tests/use_case/accounts/mod.rs +++ b/backend/crates/gateway-admin/tests/use_case/accounts/mod.rs @@ -845,6 +845,17 @@ impl AccountStore for FakeAccountStore { .clone()) } + async fn quota_documents( + &self, + _: &gateway_core::account::ProviderAccountId, + _: &gateway_core::routing::ProviderKind, + _: chrono::DateTime, + _: gateway_admin::model::observability::TimeRange, + _: Option<&gateway_admin::model::quota_history::QuotaHistoryCursor>, + ) -> AdminStoreResult { + unreachable!("测试不读取历史额度文档") + } + async fn load_quota_forecast_history( &self, window: &AccountUsageWindowQuery, diff --git a/backend/crates/gateway-admin/tests/use_case/mod.rs b/backend/crates/gateway-admin/tests/use_case/mod.rs index 1243e7faa..cd72811b2 100644 --- a/backend/crates/gateway-admin/tests/use_case/mod.rs +++ b/backend/crates/gateway-admin/tests/use_case/mod.rs @@ -546,6 +546,17 @@ impl AccountStore for UnavailableStore { Err(unavailable("account quota window usage")) } + async fn quota_documents( + &self, + _: &gateway_core::account::ProviderAccountId, + _: &gateway_core::routing::ProviderKind, + _: chrono::DateTime, + _: gateway_admin::model::observability::TimeRange, + _: Option<&gateway_admin::model::quota_history::QuotaHistoryCursor>, + ) -> AdminStoreResult { + unreachable!("测试不读取历史额度文档") + } + async fn load_quota_forecast_history( &self, _: &AccountUsageWindowQuery, diff --git a/backend/crates/gateway-api/tests/admin/mod.rs b/backend/crates/gateway-api/tests/admin/mod.rs index 09e5eb91e..0eacd0fbf 100644 --- a/backend/crates/gateway-api/tests/admin/mod.rs +++ b/backend/crates/gateway-api/tests/admin/mod.rs @@ -1300,6 +1300,17 @@ impl AccountStore for UnusedStore { Err(unavailable("account quota window usage")) } + async fn quota_documents( + &self, + _: &gateway_core::account::ProviderAccountId, + _: &gateway_core::routing::ProviderKind, + _: chrono::DateTime, + _: gateway_admin::model::observability::TimeRange, + _: Option<&gateway_admin::model::quota_history::QuotaHistoryCursor>, + ) -> AdminStoreResult { + unreachable!("测试不读取历史额度文档") + } + async fn load_quota_forecast_history( &self, _: &AccountUsageWindowQuery, diff --git a/backend/crates/gateway-plugin/runtime/src/callback/data.rs b/backend/crates/gateway-plugin/runtime/src/callback/data.rs index 2bd4ff19a..0990c8aed 100644 --- a/backend/crates/gateway-plugin/runtime/src/callback/data.rs +++ b/backend/crates/gateway-plugin/runtime/src/callback/data.rs @@ -98,6 +98,7 @@ impl PluginData { next_cursor: page.next_cursor.map(|id| id.as_str().to_owned()), }) } + data::QUOTA_HISTORY => return self.quota_history(payload).await, data::QUOTA_GET | data::QUOTA_REFRESH | data::QUOTA_DETAILS => { let accounts = self.accounts.upgrade().map_err(map_admin_error)?; let query: data::QuotaFactsQuery = @@ -162,4 +163,67 @@ impl PluginData { payload, }) } + + async fn quota_history(&self, payload: &[u8]) -> Result { + use gateway_admin::model::{ + observability::TimeRange, + quota_history::{QuotaHistoryPoint, QuotaHistoryQuery}, + }; + + let wire: data::QuotaHistoryQuery = + serde_json::from_slice(payload).map_err(|_| invalid())?; + let id = ProviderAccountId::new(wire.account_id).map_err(|_| invalid())?; + let time = |ms| chrono::DateTime::from_timestamp_millis(ms).ok_or_else(invalid); + let range = + TimeRange::new(time(wire.start_ms)?, time(wire.end_ms)?).map_err(|_| invalid())?; + if wire.start_ms < 0 + || wire.window_key.is_empty() + || wire.window_key.len() > 256 + || wire.window_key.chars().any(char::is_control) + { + return Err(invalid()); + } + let query = QuotaHistoryQuery { + window_key: wire.window_key, + range, + cursor: wire + .cursor + .as_deref() + .map(serde_json::from_str) + .transpose() + .map_err(|_| invalid())?, + }; + if query.cursor.as_ref().is_some_and(|c| { + c.completed_at >= range.end + || c.completed_at < query.scan_start() + || c.id.is_empty() + || c.id.contains('\0') + }) { + return Err(invalid()); + } + let page = self + .accounts + .upgrade() + .map_err(map_admin_error)? + .quota_history(&id, query) + .await + .map_err(map_admin_error)?; + let sample = |p: QuotaHistoryPoint| data::QuotaHistorySample { + observed_at_ms: p.observed_at.timestamp_millis(), + used_percent: p.reading.used_percent, + reset_at_ms: p.reading.reset_at.map(|at| at.timestamp_millis()), + plan_type: p.reading.plan_type, + }; + super::admin::encode(&data::QuotaHistoryPage { + schema_version: 1, + samples: page.samples.into_iter().map(sample).collect(), + baseline: page.baseline.map(sample), + next_cursor: page + .next_cursor + .as_ref() + .map(serde_json::to_string) + .transpose() + .map_err(|_| invalid())?, + }) + } } diff --git a/backend/crates/gateway-plugin/runtime/src/callback/dispatch.rs b/backend/crates/gateway-plugin/runtime/src/callback/dispatch.rs index 8db99d145..6b53c1948 100644 --- a/backend/crates/gateway-plugin/runtime/src/callback/dispatch.rs +++ b/backend/crates/gateway-plugin/runtime/src/callback/dispatch.rs @@ -216,6 +216,7 @@ impl CallbackHandler for PluginCallbacks { | gateway_plugin_sdk::call::data::KEYS_GET | gateway_plugin_sdk::call::data::QUOTA_GET | gateway_plugin_sdk::call::data::QUOTA_REFRESH + | gateway_plugin_sdk::call::data::QUOTA_HISTORY | gateway_plugin_sdk::call::data::QUOTA_DETAILS ) { return data.call(&method, params, &payload).await; diff --git a/backend/crates/gateway-plugin/runtime/tests/adapter/command_line/execution.rs b/backend/crates/gateway-plugin/runtime/tests/adapter/command_line/execution.rs index 6828ea34b..20f79af55 100644 --- a/backend/crates/gateway-plugin/runtime/tests/adapter/command_line/execution.rs +++ b/backend/crates/gateway-plugin/runtime/tests/adapter/command_line/execution.rs @@ -15,6 +15,17 @@ struct BudgetAccountAccess { #[async_trait::async_trait] impl gateway_admin::ports::plugin_accounts::PluginAccountAccess for BudgetAccountAccess { + async fn quota_history( + &self, + _: &gateway_core::account::ProviderAccountId, + _: gateway_admin::model::quota_history::QuotaHistoryQuery, + ) -> Result< + gateway_admin::model::quota_history::QuotaHistoryPage, + gateway_admin::model::AdminError, + > { + unreachable!("账号提交不读取额度历史") + } + async fn list( &self, _: gateway_admin::model::provider_credentials::PluginAccountListQuery, diff --git a/backend/crates/gateway-plugin/runtime/tests/generation/data.rs b/backend/crates/gateway-plugin/runtime/tests/generation/data.rs index 5b614389e..95ab15a17 100644 --- a/backend/crates/gateway-plugin/runtime/tests/generation/data.rs +++ b/backend/crates/gateway-plugin/runtime/tests/generation/data.rs @@ -75,6 +75,30 @@ fn account() -> AccountRecord { #[async_trait] impl PluginAccountAccess for Facts { + async fn quota_history( + &self, + id: &ProviderAccountId, + query: gateway_admin::model::quota_history::QuotaHistoryQuery, + ) -> Result { + use gateway_admin::model::quota_history::{ + QuotaHistoryPage, QuotaHistoryPoint, QuotaReading, + }; + assert_eq!(id.as_str(), "acct_facts"); + assert_eq!(query.window_key, "weekly"); + assert!(query.cursor.is_none()); + Ok(QuotaHistoryPage { + samples: vec![QuotaHistoryPoint { + observed_at: query.range.start, + reading: QuotaReading { + plan_type: None, + used_percent: 12.5, + reset_at: None, + }, + }], + ..Default::default() + }) + } + async fn refresh_quota( &self, account: &ProviderAccountId, @@ -201,6 +225,9 @@ async fn management_facts_validate_queries_without_permission_declarations() { {"method":"host.data.accounts.list","query":{"provider_id":"openai","cursor":"acct_before","limit":1}}, {"method":"host.data.quota.get","query":{"account_id":"acct_facts"}}, {"method":"host.data.quota.details","query":{"account_id":"acct_facts"}}, + {"method":"host.data.quota.history","query":{"account_id":"acct_facts","window_key":"weekly","start_ms":1000,"end_ms":2000}}, + {"method":"host.data.quota.history","query":{"account_id":"acct_facts","window_key":"weekly","start_ms":2000,"end_ms":1000}}, + {"method":"host.data.quota.history","query":{"account_id":"acct_facts","window_key":"weekly","start_ms":1000,"end_ms":2000,"cursor":"invalid"}}, {"method":"host.data.accounts.list","query":{"limit":0}}, {"method":"host.data.accounts.list","query":{"limit":65535}}, {"method":"host.data.quota.get","query":{"account_id":"acct_facts","sql":"SELECT secret"}} @@ -269,7 +296,12 @@ async fn management_facts_validate_queries_without_permission_declarations() { Some("123456789.123456789") ); assert!(!result[2].to_string().contains("provider-internal-fixture")); - for invalid in &result.as_array().unwrap()[3..] { + let history: gateway_plugin_sdk::call::data::QuotaHistoryPage = + serde_json::from_value(result[3].clone()).unwrap(); + assert_eq!(history.samples[0].used_percent, 12.5); + assert_eq!(history.samples[0].observed_at_ms, 1000); + assert_eq!(history.samples[0].reset_at_ms, None); + for invalid in &result.as_array().unwrap()[4..] { assert_eq!(invalid["error"], "invalid_input"); } diff --git a/backend/crates/gateway-plugin/runtime/tests/rpc/dispatch.rs b/backend/crates/gateway-plugin/runtime/tests/rpc/dispatch.rs index 4704e18c9..fbee0488f 100644 --- a/backend/crates/gateway-plugin/runtime/tests/rpc/dispatch.rs +++ b/backend/crates/gateway-plugin/runtime/tests/rpc/dispatch.rs @@ -107,6 +107,7 @@ async fn callbacks_are_dispatched_in_every_stage_without_permission_declarations "host.data.accounts.list", "host.data.keys.get", "host.data.quota.get", + "host.data.quota.history", "host.groups.ensure", "host.groups.change_members", "host.keys.ensure", diff --git a/backend/crates/gateway-plugin/sdk/README.md b/backend/crates/gateway-plugin/sdk/README.md index 77b144405..1d846c9ab 100644 --- a/backend/crates/gateway-plugin/sdk/README.md +++ b/backend/crates/gateway-plugin/sdk/README.md @@ -23,7 +23,7 @@ SDK 包版本为 `0.1.0`,独立于网关版本,处于实验阶段。能力 | `call::upstream_adapter` | 内置 OpenAI / xAI 的[受管上游适配器](docs/upstream-adapters.md)注册、执行、出站与续接合同 | | `call::policy` | 模型路由、账号调度与重试决策合同 | | `call::catalog` | 固定 Provider 的直接别名与适配模型注册合同,见[模型目录](docs/capabilities.md#模型目录) | -| `call::data` | 最小账号事实与已有额度观测的只读合同 | +| `call::data` | 账号事实、当前额度与历史额度观测 | | `call::observation` | 请求完成、用量、费用与实际上游 WebSocket 响应事件的统一观察合同 | | `call::host` | 账号、私有状态、受管 HTTP、模型、亲和、日志及调用内流的宿主回调合同 | | `call::management` | 管理 API、页面与资源声明、公开回调,以及 CLI 命令与待保存账号 | diff --git a/backend/crates/gateway-plugin/sdk/docs/capabilities.md b/backend/crates/gateway-plugin/sdk/docs/capabilities.md index 1a3bfaf20..63a851009 100644 --- a/backend/crates/gateway-plugin/sdk/docs/capabilities.md +++ b/backend/crates/gateway-plugin/sdk/docs/capabilities.md @@ -89,6 +89,7 @@ Provider 固定为宿主内置的 OpenAI 与 xAI。宿主开放以下 11 类扩 | `call.host.quota_details(query)` | `host.data.quota.details` | `QuotaFactsQuery { account_id }`:读取完整额度事实,包含窗口归属、触顶和点数 | | `call.host.check_access(query)` | `host.data.access.check` | `AccessQuery { client_key_id, account_ids, upstream_model }`:读取 Key 对指定账号及可选上游模型的冻结授权 | | `call.host.verify_client(request)` | `host.client.verify` | `VerifyClientRequest { authorization }`:复用入口认证,返回 `VerifiedClient { client_key_id }` | +| `call.host.quota_history(query)` | `host.data.quota.history` | 按账号、窗口键和时间范围分页读取已保留的额度观测 | | `call.host.quota_facts(query)` | `host.data.quota.get` | `QuotaFactsQuery { account_id }`:读取 Provider 现有观测,不访问上游刷新 | | `call.host.key_facts(query)` | `host.data.keys.get` | `ClientKeyFactsQuery { client_key_id }`:读取当前 Key 的启用状态及显式分组 ID,不返回密钥 | @@ -108,6 +109,16 @@ SDK 解析响应时忽略未知字段,包含账号分页、账号及额度窗 `quota_details` 保留 Provider 已解释的 `limit_reached`、窗口 `group`、`label`、`limit_id`、`limit_name`、`role` 及点数 `has_credits`、`unlimited`、`balance`;缺失值仍为 `null`,不返回上游原始文档,不发起刷新 +`quota_history(QuotaHistoryQuery { account_id, window_key, start_ms, end_ms, cursor })` 按请求完成时间倒序返回 +`[start_ms, end_ms)` 内的同桶读数。窗口键与 `quota_details` 相同,区间最长 366 天。每个样本包含 +`observed_at_ms`、`used_percent` 和当时观测到的 `reset_at_ms`、`plan_type`,后两项可为 `null`。 +首次省略游标;即使 `samples` 为空,只要有 `next_cursor` 就沿用原查询继续。末页的 `baseline` 是起点前最近的同桶读数, +最多向前查一个等长区间。例如查最近 48 小时,基线最多再向前找 48 小时;没有基线时返回 `null` + +历史来自保留的已结束请求,不含独立额度刷新。Provider 未提供可解析的同桶观测时没有样本。 +缺样不代表零;跨重置或套餐变更不能直接相减。这是观测记录,不是精确消耗账本。 +分页不冻结数据,长区间建议在后台读取并复用结果 + `verify_client` 使用当前请求设置和原认证计划,包含外部 principal 到 Key 的映射;没有 HTTP 入口时使用当前发布配置。 认证可以调用认证插件,继续扣减父预算并响应取消;验证成功不做推理准入、账号租约、使用记录或计费。 授权原文只作本次认证输入,不进入返回值 diff --git a/backend/crates/gateway-plugin/sdk/src/call/data.rs b/backend/crates/gateway-plugin/sdk/src/call/data.rs index df2cbc696..fb237118e 100644 --- a/backend/crates/gateway-plugin/sdk/src/call/data.rs +++ b/backend/crates/gateway-plugin/sdk/src/call/data.rs @@ -5,6 +5,7 @@ use serde::{Deserialize, Serialize}; pub const ACCOUNTS_LIST: &str = "host.data.accounts.list"; pub const QUOTA_REFRESH: &str = "host.quota_observations.refresh"; +pub const QUOTA_HISTORY: &str = "host.data.quota.history"; pub const QUOTA_GET: &str = "host.data.quota.get"; pub const KEYS_GET: &str = "host.data.keys.get"; pub const CLIENT_VERIFY: &str = "host.client.verify"; @@ -93,6 +94,35 @@ pub struct QuotaFactsQuery { pub account_id: String, } +/// UTC 毫秒半开区间;续页沿用原查询并原样传回游标 +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct QuotaHistoryQuery { + pub account_id: String, + pub window_key: String, + pub start_ms: i64, + pub end_ms: i64, + pub cursor: Option, +} + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct QuotaHistorySample { + pub plan_type: Option, + pub observed_at_ms: i64, + pub used_percent: f64, + pub reset_at_ms: Option, +} + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct QuotaHistoryPage { + pub schema_version: u32, + /// 请求完成时间倒序;空页也可能需要继续 + pub samples: Vec, + /// 最后一页才可能包含起点前的最近同桶观测 + pub baseline: Option, + pub next_cursor: Option, +} + /// Provider 已有快照的必要投影;空观测时间表示没有可用样本,不代表额度为零 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub struct QuotaFacts { diff --git a/backend/crates/gateway-plugin/sdk/src/client/data.rs b/backend/crates/gateway-plugin/sdk/src/client/data.rs index b415352c3..c2573b8dd 100644 --- a/backend/crates/gateway-plugin/sdk/src/client/data.rs +++ b/backend/crates/gateway-plugin/sdk/src/client/data.rs @@ -75,6 +75,17 @@ impl HostClient { payload_call(self, data::QUOTA_GET, query).await } + /// 按账号、额度桶和时间范围读取已保留的观测,不刷新上游 + /// + /// # Errors + /// 账号不存在、查询无效或宿主读取失败时返回错误 + pub async fn quota_history( + &self, + query: data::QuotaHistoryQuery, + ) -> Result { + payload_call(self, data::QUOTA_HISTORY, query).await + } + /// 读取已有额度窗口标签、触顶与点数事实,不触发刷新或补算 /// /// # Errors diff --git a/backend/crates/gateway-store/src/postgres/provider_accounts/admin_adapter.rs b/backend/crates/gateway-store/src/postgres/provider_accounts/admin_adapter.rs index d76ddb2d1..b64d719f2 100644 --- a/backend/crates/gateway-store/src/postgres/provider_accounts/admin_adapter.rs +++ b/backend/crates/gateway-store/src/postgres/provider_accounts/admin_adapter.rs @@ -235,10 +235,11 @@ impl AccountStore for PgAdminAccountStore { account_id: &CoreProviderAccountId, ) -> AdminStoreResult> { self.accounts - .load_provider_account(account_id.as_str()) + .list_provider_account_summaries(None, true, Some(&[account_id.as_str()]), None) .await .map_err(|error| admin_store_error(ENTITY, error))? - .map(|record| admin_account_record(record.summary)) + .pop() + .map(admin_account_record) .transpose() } @@ -455,6 +456,26 @@ impl AccountStore for PgAdminAccountStore { self.usage_by_windows(windows).await } + async fn quota_documents( + &self, + account: &gateway_core::account::ProviderAccountId, + provider: &gateway_core::routing::ProviderKind, + created_at: chrono::DateTime, + range: gateway_admin::model::observability::TimeRange, + before: Option<&gateway_admin::model::quota_history::QuotaHistoryCursor>, + ) -> AdminStoreResult { + super::quota_history::documents( + &self.pool, + &self.query_budget, + account, + provider, + created_at, + range, + before, + ) + .await + } + async fn load_quota_forecast_history( &self, window: &AccountUsageWindowQuery, diff --git a/backend/crates/gateway-store/src/postgres/provider_accounts/mod.rs b/backend/crates/gateway-store/src/postgres/provider_accounts/mod.rs index 32733da07..824a01677 100644 --- a/backend/crates/gateway-store/src/postgres/provider_accounts/mod.rs +++ b/backend/crates/gateway-store/src/postgres/provider_accounts/mod.rs @@ -61,6 +61,7 @@ mod mapping; mod model_catalogs; mod quota; mod quota_forecast; +mod quota_history; mod quota_warmup; mod repository; mod reset_credit_automation; diff --git a/backend/crates/gateway-store/src/postgres/provider_accounts/quota_history.rs b/backend/crates/gateway-store/src/postgres/provider_accounts/quota_history.rs new file mode 100644 index 000000000..2f037c529 --- /dev/null +++ b/backend/crates/gateway-store/src/postgres/provider_accounts/quota_history.rs @@ -0,0 +1,72 @@ +//! 按账号完成时间索引分页读取历史观测;过滤窗口的协议字段由 Provider 解释 + +use futures::TryStreamExt as _; +use gateway_admin::model::quota_history::{QuotaDocumentPage, QuotaHistoryCursor}; + +use super::*; + +pub(super) async fn documents( + pool: &PgPool, + budget: &crate::postgres::ObservabilityQueryBudget, + account: &CoreProviderAccountId, + provider: &gateway_core::routing::ProviderKind, + created_at: DateTime, + range: TimeRange, + before: Option<&QuotaHistoryCursor>, +) -> AdminStoreResult { + const PAGE_SIZE: usize = 64; + const PAGE_BYTES: usize = 2 * 1024 * 1024; + + let (until, last_id) = before.map_or((range.end, ""), |c| (c.completed_at, c.id.as_str())); + budget + .run(pool, "read quota documents", |mut connection| async move { + let mut rows = sqlx::query_as::<_, (DateTime, String, String)>( + "select completed_at,id,provider_observation_json::text from model_requests + where provider_account_ref=$1 and provider_kind=$2 and started_at >= $3 + and completed_at >= $4 and completed_at < $5 and (completed_at,id) < ($6,$7) + and outcome <> 'running' and provider_observation_json is not null + order by completed_at desc,id desc limit $8", + ) + .bind(account.as_str()) + .bind(provider.as_str()) + .bind(created_at) + .bind(range.start) + .bind(range.end) + .bind(until) + .bind(last_id) + .bind((PAGE_SIZE + 1) as i64) + .fetch(&mut *connection); + let mut documents = Vec::new(); + let mut bytes = 0; + let mut last = None; + while let Some((completed_at, id, json)) = rows + .try_next() + .await + .map_err(|error| postgres_unavailable("read quota documents", error))? + { + // 首份文档独占一页也要前进,否则大文档会卡住所有后续页 + if documents.len() == PAGE_SIZE + || (!documents.is_empty() && bytes + json.len() > PAGE_BYTES) + { + return Ok(QuotaDocumentPage { + documents, + next_cursor: last, + }); + } + bytes += json.len(); + let document = serde_json::from_str(&json) + .map_err(|_| invalid("invalid provider observation"))?; + documents.push(( + completed_at, + ProviderDocument::new(OpaqueProviderData::new(document)), + )); + last = Some(QuotaHistoryCursor { completed_at, id }); + } + Ok(QuotaDocumentPage { + documents, + next_cursor: None, + }) + }) + .await + .map_err(|error| admin_store_error(ENTITY, error)) +} diff --git a/backend/crates/gateway-store/tests/postgres/provider_accounts/mod.rs b/backend/crates/gateway-store/tests/postgres/provider_accounts/mod.rs index 0523079dc..b5a1e421b 100644 --- a/backend/crates/gateway-store/tests/postgres/provider_accounts/mod.rs +++ b/backend/crates/gateway-store/tests/postgres/provider_accounts/mod.rs @@ -13,6 +13,7 @@ mod deletion; mod protection_revision; mod quota; mod quota_forecast; +mod quota_history; mod timestamps; mod usage_projection; diff --git a/backend/crates/gateway-store/tests/postgres/provider_accounts/quota_history.rs b/backend/crates/gateway-store/tests/postgres/provider_accounts/quota_history.rs new file mode 100644 index 000000000..f271c9387 --- /dev/null +++ b/backend/crates/gateway-store/tests/postgres/provider_accounts/quota_history.rs @@ -0,0 +1,162 @@ +//! 验证历史额度按账号与完成时间翻页,保留重置和最近有效基线 + +use gateway_admin::model::quota_history::{QuotaHistoryPage, QuotaHistoryQuery, QuotaReading}; + +use super::*; + +#[tokio::test] +async fn quota_history_pages_sparse_tied_observations_through_the_nearest_baseline() { + let Some(db) = TestDatabase::create("quota_history").await else { + return; + }; + let store = admin_account_store(&db.pool); + let id = ProviderAccountId::new("acct_history").unwrap(); + let mut saved = account(id.as_str(), "history"); + saved.enabled = false; + PgProviderAccountRepository::new(db.pool.clone()) + .insert_provider_account(saved) + .await + .unwrap(); + let record = store.load_account_record(&id).await.unwrap().unwrap(); + let created = record.created_at; + let provider = record.provider_kind; + let start = chrono::DateTime::from_timestamp(created.timestamp() + 3600, 0).unwrap(); + let range = TimeRange::new(start, start + TimeDelta::minutes(10)).unwrap(); + let tied = start + TimeDelta::microseconds(1_123_456); + let before_reset = start.timestamp() + 1; + let after_reset = before_reset + 604800; + let weekly = |percent, reset| json!({"weekly":[percent,reset]}); + let row = |key: String, at, doc| (key, "acct_history", "openai", at, doc); + + // 同一微秒的请求跨页时,继续扫描才能找到其中唯一的同桶读数 + let mut rows: Vec<_> = (0..66) + .map(|i| { + row( + format!("tied_{i:02}"), + tied, + if i == 0 { + weekly(3, after_reset) + } else { + json!({}) + }, + ) + }) + .collect(); + rows.extend([ + row("start".into(), start, weekly(96, before_reset)), + row("end".into(), range.end, weekly(90, after_reset)), + row( + "wrong_window".into(), + start - TimeDelta::microseconds(1), + json!({"daily":[60,before_reset]}), + ), + row( + "baseline".into(), + start - TimeDelta::minutes(1), + weekly(94, before_reset), + ), + row( + "older".into(), + start - TimeDelta::minutes(2), + weekly(80, before_reset), + ), + row( + "outside_lookback".into(), + start - TimeDelta::minutes(11), + json!({"unknown":[75,before_reset]}), + ), + ( + "other".into(), + "acct_other", + "openai", + tied, + weekly(90, after_reset), + ), + ( + "other_provider".into(), + "acct_history", + "other", + tied, + weekly(88, after_reset), + ), + ]); + for (request_id, account_id, provider_kind, at, doc) in rows { + seed_model_request( + &db.pool, + ModelRequestSeed { + request_id: &request_id, + account_id, + provider_kind, + model: "gpt-test", + total_tokens: 1, + cost_amount: "1", + started_at: at - TimeDelta::seconds(1), + }, + ) + .await + .unwrap(); + sqlx::query("update model_requests set provider_observation_json=$2 where id=$1") + .bind(request_id) + .bind(doc) + .execute(&db.pool) + .await + .unwrap(); + } + for key in ["weekly", "unknown"] { + let mut query = QuotaHistoryQuery { + window_key: key.into(), + range, + cursor: None, + }; + let scan = TimeRange { + start: query.scan_start(), + end: range.end, + }; + let mut samples = Vec::new(); + let mut pages = 0; + let baseline = loop { + let raw = store + .quota_documents(&id, &provider, created, scan, query.cursor.as_ref()) + .await + .unwrap(); + let page = QuotaHistoryPage::from_documents(raw, &query, |doc, key| { + let pair = doc.expose_to_provider().expose_to_provider().get(key)?; + Some(QuotaReading { + used_percent: pair[0].as_f64()?, + reset_at: chrono::DateTime::from_timestamp(pair[1].as_i64()?, 0), + plan_type: None, + }) + }); + pages += 1; + if pages == 1 { + assert!(page.samples.is_empty() && page.next_cursor.is_some()); + } + samples.extend(page.samples.into_iter().map(|p| { + ( + p.observed_at, + p.reading.used_percent, + p.reading.reset_at.unwrap().timestamp(), + ) + })); + query.cursor = page.next_cursor; + if query.cursor.is_none() { + break page.baseline; + } + assert!(pages < 4, "游标未前进"); + }; + if key == "weekly" { + assert_eq!( + samples, + [(tied, 3.0, after_reset), (start, 96.0, before_reset)] + ); + let base = baseline.unwrap(); + assert_eq!( + (base.observed_at, base.reading.used_percent), + (start - TimeDelta::minutes(1), 94.0) + ); + } else { + assert!(samples.is_empty() && baseline.is_none()); + } + } + db.close().await; +} diff --git a/backend/crates/providers/openai/src/admin/mod.rs b/backend/crates/providers/openai/src/admin/mod.rs index 011f77f7d..711b291fe 100644 --- a/backend/crates/providers/openai/src/admin/mod.rs +++ b/backend/crates/providers/openai/src/admin/mod.rs @@ -797,35 +797,31 @@ impl ProviderAdmin for OpenAiAdminProvider { } } + fn quota_history_parser( + &self, + ) -> Option { + Some(quota::history_reading) + } + fn quota_forecast_observation( &self, document: &ProviderDocument, window: &ProviderQuotaWindow, ) -> Option { - use gateway_protocol::openai::events::parse_rate_limit_headers; - if window.local_usage_attribution != QuotaLocalUsageAttribution::AccountWide { return None; } - let value = document - .expose_to_provider() - .expose_to_provider() - .get("rateLimitHeaders")?; - let headers: Vec<(String, String)> = serde_json::from_value(value.clone()).ok()?; - let parsed = parse_rate_limit_headers(&headers)?; - let limit = parsed.limits.get(window.limit_id.as_deref()?)?; - let observed = match window.role? { - ProviderQuotaWindowRole::Primary => limit.primary?, - ProviderQuotaWindowRole::Secondary => limit.secondary?, - ProviderQuotaWindowRole::Monthly => return None, - }; - if observed.window_minutes?.checked_mul(60)? != window.window_seconds? { + let (observed, plan_type) = quota::history_window(document, &window.key)?; + if Some(observed.source()) != window.limit_id.as_deref() + || Some(quota_role(observed.role())) != window.role + || observed.window_seconds()? != window.window_seconds? + { return None; } Some(QuotaForecastObservation { - used_percent: observed.used_percent, - reset_at: DateTime::::from_timestamp(observed.reset_at?, 0)?, - plan_type: parsed.plan_type, + used_percent: observed.used_percent()?, + reset_at: observed.reset_at()?, + plan_type, }) } diff --git a/backend/crates/providers/openai/src/admin/quota.rs b/backend/crates/providers/openai/src/admin/quota.rs index fc981770f..d4f1625ec 100644 --- a/backend/crates/providers/openai/src/admin/quota.rs +++ b/backend/crates/providers/openai/src/admin/quota.rs @@ -1,4 +1,4 @@ -//! 管理端批量读取原生额度,不在列表查询中访问上游 +//! 管理端额度快照与历史请求观测的只读投影 use super::*; @@ -74,3 +74,29 @@ impl OpenAiAdminProvider { .collect() } } + +pub(super) fn history_window( + document: &ProviderDocument, + key: &str, +) -> Option<(crate::credential::CodexQuotaWindow, Option)> { + let headers = document + .expose_to_provider() + .expose_to_provider() + .get("rateLimitHeaders")?; + let headers: Vec<(String, String)> = serde::Deserialize::deserialize(headers).ok()?; + let parsed = gateway_protocol::openai::events::parse_rate_limit_headers(&headers)?; + let window = crate::credential::observed_quota_window(&parsed, key)?; + Some((window, parsed.plan_type)) +} + +pub(super) fn history_reading( + document: &ProviderDocument, + key: &str, +) -> Option { + let (window, plan_type) = history_window(document, key)?; + Some(gateway_admin::model::quota_history::QuotaReading { + plan_type, + used_percent: window.used_percent()?, + reset_at: window.reset_at(), + }) +} diff --git a/backend/crates/providers/openai/src/credential/mod.rs b/backend/crates/providers/openai/src/credential/mod.rs index fb161470e..a89c8d782 100644 --- a/backend/crates/providers/openai/src/credential/mod.rs +++ b/backend/crates/providers/openai/src/credential/mod.rs @@ -59,6 +59,7 @@ pub use oauth::{ pub use profile_statistics::{ CodexCredentialProfileService, CodexProfileAvatarError, CodexProfileStatisticsError, }; +pub(crate) use quota::observed_quota_window; pub use quota::{ CodexAccountQuotaSnapshot, CodexCredentialQuotaError, CodexCredentialQuotaService, CodexInitialSyncDelays, CodexQuotaFact, CodexQuotaRefreshPolicy, CodexQuotaSyncSummary, diff --git a/backend/crates/providers/openai/src/credential/quota/mod.rs b/backend/crates/providers/openai/src/credential/quota/mod.rs index 935eb347e..52adb8303 100644 --- a/backend/crates/providers/openai/src/credential/quota/mod.rs +++ b/backend/crates/providers/openai/src/credential/quota/mod.rs @@ -18,6 +18,7 @@ mod warmup; const BUCKET_USAGE_FIELD: &str = "_cpr_bucket_last_used_at"; +pub(crate) use passive::observed_quota_window; pub use reset_credits::CodexResetCreditsError; use reset_credits::ResetCreditLocks; use scheduling::CodexQuotaSchedulingProjection; diff --git a/backend/crates/providers/openai/src/credential/quota/passive.rs b/backend/crates/providers/openai/src/credential/quota/passive.rs index 305dbb972..fc9bb0ba8 100644 --- a/backend/crates/providers/openai/src/credential/quota/passive.rs +++ b/backend/crates/providers/openai/src/credential/quota/passive.rs @@ -151,6 +151,18 @@ impl CodexCredentialQuotaService { } } +pub(crate) fn observed_quota_window( + parsed: &ParsedRateLimits, + key: &str, +) -> Option { + // 只解释本次响应,不借用当前快照补全旧观测或把具名桶镜像当作账号额度 + let (quota, _) = merge_passive_quota(Map::new(), std::slice::from_ref(parsed), None); + snapshot::quota_windows("a) + .ok()? + .into_iter() + .find(|window| window.key() == key) +} + fn merge_passive_quota( mut quota: Map, observations: &[ParsedRateLimits], diff --git a/backend/crates/providers/openai/src/credential/quota/snapshot.rs b/backend/crates/providers/openai/src/credential/quota/snapshot.rs index b56fe7031..a94674ec5 100644 --- a/backend/crates/providers/openai/src/credential/quota/snapshot.rs +++ b/backend/crates/providers/openai/src/credential/quota/snapshot.rs @@ -416,16 +416,7 @@ pub(crate) fn parse_account_quota_snapshot( ) -> Result { let object = canonical_quota_object(usage)?; let fact = parse_codex_quota_object(&object)?; - let mut windows = Vec::new(); - for limit in canonical_rate_limits(&object)? { - parse_rate_limit_windows( - &limit.source, - limit.account_wide, - limit.limit_name.as_deref(), - limit.rate_limit, - &mut windows, - )?; - } + let mut windows = quota_windows(&object)?; windows.sort_by(|left, right| { quota_source_order(left.source()) .cmp("a_source_order(right.source())) @@ -610,6 +601,22 @@ fn is_codex_limit_id(value: &str) -> bool { value.trim().eq_ignore_ascii_case("codex") } +pub(super) fn quota_windows( + object: &Map, +) -> Result, CodexCredentialQuotaError> { + let mut windows = Vec::new(); + for limit in canonical_rate_limits(object)? { + parse_rate_limit_windows( + &limit.source, + limit.account_wide, + limit.limit_name.as_deref(), + limit.rate_limit, + &mut windows, + )?; + } + Ok(windows) +} + fn parse_rate_limit_windows( source: &str, account_wide: bool, diff --git a/backend/crates/providers/openai/tests/admin/mod.rs b/backend/crates/providers/openai/tests/admin/mod.rs index 66261defc..ca2918f25 100644 --- a/backend/crates/providers/openai/tests/admin/mod.rs +++ b/backend/crates/providers/openai/tests/admin/mod.rs @@ -352,6 +352,33 @@ async fn quota_forecast_observation_reuses_protocol_parser_and_keeps_window_iden .unwrap() .clone(), )); + let history = provider.quota_history_parser().unwrap(); + let short = history(&document, "codex:18000s").unwrap(); + assert_eq!(short.used_percent, 4.0); + assert_eq!(short.reset_at.unwrap().timestamp(), 1_789_218_647); + assert!(history(&document, "other:18000s").is_none()); + let named = ProviderDocument::new(OpaqueProviderData::new( + json!({ + "rateLimitHeaders": [ + ["x-codex-primary-used-percent","23"],["x-codex-primary-window-minutes","1"], + ["x-feature-primary-used-percent","23"],["x-feature-primary-window-minutes","1"], + ["x-feature-secondary-used-percent","56"],["x-feature-secondary-window-minutes","1"] + ] + }) + .as_object() + .unwrap() + .clone(), + )); + assert!(history(&named, "codex:60s").is_none()); + assert!(history(&named, "feature:60s").is_none()); + let primary = history(&named, "feature:60s:primary_window").unwrap(); + assert_eq!((primary.used_percent, primary.reset_at), (23.0, None)); + assert_eq!( + history(&named, "feature:60s:secondary_window") + .unwrap() + .used_percent, + 56.0 + ); let observed = provider .quota_forecast_observation(&document, &window) .unwrap(); diff --git a/docs/architecture.md b/docs/architecture.md index c80fe4bd5..d060aa75e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1175,7 +1175,9 @@ Admin 按卡片与所选指标向 Store 请求计数、金额或分布,缓存 预测数值复用统计投影的十五分钟开始时间桶,并以账号与五分钟完成时间桶分组。 完整完成时间桶合并累计量,跨采样截止值的小桶、开始时间边界和重建区间读取窄事实; 同一快照撤销待投影旧版本并加入当前源版本。预测采样保留请求完成状态,不按恢复标记排除请求;其他业务统计排除恢复请求。 -Provider 文档按账号和完成时间索引读取,每个采样槽只保留最后一份 +Provider 文档按账号和完成时间索引读取,预测每个采样槽只保留最后一份。 +插件的[额度历史查询](../backend/crates/gateway-plugin/sdk/docs/capabilities.md#基础事实)沿同一索引分页,由 Provider 解释所选窗口; +它保留重置前后的读数,不计算预测或累计消耗 ### 请求记录与交付