9.1 KiB
用量查询、维护与计价
call::services::usage 提供请求明细、聚合统计和 Token 费用试算。单次操作通过 call.host.service::<Operation>(input) 调用,完整扫描与分组统计通过 HostClient 的分批读取方法调用,均绑定当前父调用
基础操作
| SDK 操作 | 服务名 | 输入与结果 |
|---|---|---|
GetRecord |
usage.records.get |
按 id 读取原生请求明细,包含费用快照与 Provider 观测 |
ListRecords |
usage.records.list |
按时间、Provider、模型、账号、Key 筛选,返回明细与下一页游标 |
WriteRecords |
usage.records.write |
批量 put、update、delete,返回实际变更的 ID |
ListAggregates |
usage.aggregates.list |
分页读取调用方维护的聚合贡献,支持同样的时间与维度筛选 |
WriteAggregates |
usage.aggregates.write |
按聚合键批量覆盖或删除统计贡献 |
EvaluatePricing |
pricing.evaluate |
根据当前价目或指定价格试算,逐项返回 estimated 或 not_estimable |
请求列表只含明细。全局与分组统计包含聚合贡献,趋势由统计查询提供
完整扫描与分组统计
启用 io feature 后,HostClient::scan_usage_records(ScanUsageRecords) 与
HostClient::query_usage_statistics(QueryUsageStatistics) 返回 UsageReader,通过 next_batch() 逐批处理结果
use gateway_plugin_sdk::{PluginFault, client::HostClient};
use gateway_plugin_sdk::call::services::usage::{
QueryUsageStatistics, UsageGrouping, UsageReadBatch, UsageReadFilter,
};
async fn read_statistics(
host: &HostClient,
filter: UsageReadFilter,
mut consume: impl FnMut(UsageReadBatch),
) -> Result<(), PluginFault> {
let mut reader = host.query_usage_statistics(QueryUsageStatistics {
filter,
group_by: UsageGrouping::KeyModel,
batch_size: None,
}).await?;
while let Some(batch) = reader.next_batch().await? {
consume(batch);
}
Ok(())
}
范围与明细
- 时间按请求开始时间落入 UTC 毫秒
[start_ms, end_ms),外部贡献按自身归属时间纳入 - 筛选支持 Provider、上游模型、账号、稳定 Client Key ID 及请求时保存的路由分组 ID。模型筛选与分组均使用实际
model,请求侧名称单独保存在requested_model - 明细按
(started_at_ms, id)升序,包含UsageRecordData、User-Agent、推理强度、Subagent kind、请求类型、已保存的路由范围与分组、恢复标记及统计资格 request_counted表示请求计数资格,usage_counted表示完整交付用量资格,沿用宿主的预热和恢复关联规则- 原始 Provider 观测与计价明细通过
GetRecord获取,扫描只交付窄事实
分组与覆盖
UsageGrouping 支持 model、key、key_model、routing_group。首行 group = null 是全局总计,后续返回全部分组。observation.total_groups 表示分组数,排除总计行
路由分组使用记录中的 routing_group_refs,空列表进入未关联分组。多组请求分别计入各组,全局总计只计一次。分组筛选先选择匹配请求,再统计这些请求的全部分组归属
原生缺失身份使用 null。外部贡献缺少当前分组维度时,进入 unassigned_contribution = true 的独立分组并参与总计。显式维度筛选只匹配实际提供该维度的贡献,路由分组筛选排除外部贡献
values始终提供请求计数指标。Token 缺失表示未知,已知零保留为"0"native_request_count是原生请求数,native_token_samples是各 Token 指标的原生已知请求数contribution_count是外部贡献记录数,contribution_token_samples是提供对应指标的贡献记录数,请求覆盖率由调用方结合来源含义解释costs按原币种返回总额及原生、外部贡献金额。cost_coverage返回原生完整交付请求的 Provider 上报、宿主计算和不可用费用数量- 有符号贡献合并后若使任一分组计数或金额越界,读取返回错误,调用方据此判定整份结果未完成
快照、期限与关闭
一次读取使用固定只读快照,返回的 generated_at_ms 标记读取锚点。统计还返回投影覆盖、状态、滞后秒数和代次,结果反映快照内已发布投影,源记录的后续变化经 Worker 投影后可见
每批默认及最多 1024 行,编码后的 UsageReadBatch 最多 2 MiB。单行超过容量时返回 capacity_exceeded。总结果通过多批交付,只有收到 complete = true 才表示完整结束,SDK 随后返回 None
读取的总期限覆盖连接排队、SQL 和批次间消费等待,后续拉取共用同一期限。超时、取消、容量超限及存储失败返回错误,已经交付的批次属于未完成结果
next_batch() 的一次等待被取消后,再次调用会继续同一次在途读取。提前结束使用 reader.close().await,同一读取只允许一个消费者。句柄绑定插件实例及父调用,父调用结束或取消时宿主统一回收
普通停用阻止新调用进入实例,在途读取随原父调用完成。显式排空会取消在途调用。插件负责报表进度、重试策略和重新查询后的业务检查点
明细维护
put使用调用方提供的稳定id创建记录,已有 ID 则覆盖合同中的明细字段update按 ID 替换全部 Token 字段或费用;未提供的部分保持原值,目标不存在返回not_founddelete删除指定 ID;目标不存在时成功,且不加入changed_ids- 写入对象必须是已结束的请求,不能修改或删除仍在运行的请求
put和update清除原计价明细快照,后续读取使用写入的 Token 与费用
UsageTokens 中的缓存 Token 包含在输入 Token 中,推理 Token 包含在输出 Token 中。null 表示未知,"0" 表示已知为零;调用方负责从外部系统转换口径,宿主不核对各项业务关系
费用为 unavailable 或 known { source, amount, currency }。零费用属于已知费用;清空费用使用 unavailable。明细维护影响原生历史统计,不重新执行请求结算或修改 Key 预算账本
聚合维护
UsageAggregateKey 由 bucket_start_ms、dimensions 和调用方的 key 组成。put 按完整键覆盖,重复提交不会累加。移动记录须写入新键并删除旧键
dimensions 支持 Provider、模型、账号、Key、操作和传输类型。counts 的键由 UsageMetric 定义,包括请求次数、各终态次数、已完成次数和各项 Token;costs 按币种保存十进制金额。计数与费用允许负值,供调用方表达统计修正
贡献按 bucket_start_ms 计入查询区间与趋势时间桶。日汇总不会自动摊到各小时,需要小时分布时须写入小时数据
贡献计入原生总量、趋势、维度统计和账号用量,维度匹配与越界处理见分组与覆盖。按请求或响应 ID、状态码、请求结果或文字筛选时排除贡献。贡献不产生延迟样本、尝试次数或请求列表页数
统计重建保留贡献,须由写入方删除。请求历史保留策略只清理明细
费用试算与写回
EvaluatePricing 按 OpenAI 或 xAI 的单请求公式,用当前价目或指定价格试算 Token 费用。须提供输入、输出、缓存读取、缓存写入和图像 Token,纯文本的图像 Token 填零。Provider 不支持、用量不全或价格未知时返回 not_estimable
试算不含图像、工具等附加费用,也不写入请求记录
调用方可查询明细、选择目标、逐条试算,再通过 WriteRecords::Update 写回费用。补全缺失时只处理 unavailable;全部覆盖时自行选择整个范围。日汇总若缺少逐请求分布,长上下文档位和逐请求舍入可能无法复现,计算方法由调用方决定
批量、错误与重试
- 每次写入或试算接受 1~500 项,编码后的输入不超过 2 MiB
ListRecords、ListAggregates每页默认 100 条,最多 200 条,明细页累计内容超过 2 MiB 时需减小页大小- 时间为 UTC 毫秒,查询范围为左闭右开;游标不透明,仅用于相同筛选条件的后续页,分页不冻结跨调用快照
UsageCount、UsageDelta使用十进制字符串,避免 JavaScript 丢失整数精度;持久化数值受 PostgreSQL bigint 与费用精度范围限制- 单次写入按输入顺序在一个事务中执行,任一项失败则整批回滚;跨批次进度由调用方保存
- 存储操作共享宿主观测连接与执行预算,超时、锁等待或取消会结束该次执行并释放资源
- 错误类型包括
invalid_input、not_found、conflict、capacity_exceeded、unavailable,分批读取还区分cancelled与timeout
响应丢失时,按稳定 ID 或聚合键查询后重试覆盖。调用方负责来源映射、去重、并发写入、进度、调整记录和恢复。宿主按当前调用身份记录变更审计,不提供幂等回执