feat: 新增 AI 用量落库与统计接口
- 新增 ai_usage_records 表(系统级表,不按租户过滤)与幂等上报接口 - 新增按时间/任务类型/模型的汇总、趋势、明细查询,仅白名单用户可见 - 登录响应返回 aiAdmin,供前端决定是否展示入口
This commit is contained in:
@@ -0,0 +1,307 @@
|
||||
package com.guo.learningprogresstracker.service.impl;
|
||||
|
||||
import cn.dev33.satoken.stp.StpUtil;
|
||||
import com.baomidou.mybatisplus.core.toolkit.Wrappers;
|
||||
import com.guo.learningprogresstracker.common.TenantContext;
|
||||
import com.guo.learningprogresstracker.config.AiUsageProperties;
|
||||
import com.guo.learningprogresstracker.dto.AiUsageBalance;
|
||||
import com.guo.learningprogresstracker.dto.AiUsageBreakdownItem;
|
||||
import com.guo.learningprogresstracker.dto.AiUsageIngestResult;
|
||||
import com.guo.learningprogresstracker.dto.AiUsageSeriesPoint;
|
||||
import com.guo.learningprogresstracker.dto.AiUsageSummary;
|
||||
import com.guo.learningprogresstracker.dto.AiUsageSummaryRow;
|
||||
import com.guo.learningprogresstracker.dto.request.AiUsageQuery;
|
||||
import com.guo.learningprogresstracker.dto.request.AiUsageRecordRequest;
|
||||
import com.guo.learningprogresstracker.entity.AiUsageRecordEntity;
|
||||
import com.guo.learningprogresstracker.exception.ErrorParameterException;
|
||||
import com.guo.learningprogresstracker.mapper.AiUsageRecordMapper;
|
||||
import com.guo.learningprogresstracker.service.AiUsageService;
|
||||
import com.guo.learningprogresstracker.service.UserService;
|
||||
import lombok.RequiredArgsConstructor;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.springframework.dao.DuplicateKeyException;
|
||||
import org.springframework.stereotype.Service;
|
||||
import org.springframework.transaction.annotation.Transactional;
|
||||
|
||||
import java.math.BigDecimal;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.time.LocalDateTime;
|
||||
import java.time.OffsetDateTime;
|
||||
import java.time.ZoneOffset;
|
||||
import java.time.format.DateTimeParseException;
|
||||
import java.util.ArrayList;
|
||||
import java.util.HashSet;
|
||||
import java.util.List;
|
||||
import java.util.Set;
|
||||
import java.util.stream.Collectors;
|
||||
|
||||
/**
|
||||
* AI 用量统计实现。
|
||||
*/
|
||||
@Slf4j
|
||||
@Service
|
||||
@RequiredArgsConstructor
|
||||
public class AiUsageServiceImpl implements AiUsageService {
|
||||
|
||||
/** 契约 2.2:不传时间范围时看最近 30 天 */
|
||||
private static final Duration DEFAULT_RANGE = Duration.ofDays(30);
|
||||
|
||||
private static final String BUCKET_DAY = "day";
|
||||
private static final String BUCKET_HOUR = "hour";
|
||||
private static final String GROUP_BY_TASK_TYPE = "taskType";
|
||||
private static final String GROUP_BY_MODEL = "model";
|
||||
|
||||
private final AiUsageRecordMapper aiUsageRecordMapper;
|
||||
private final UserService userService;
|
||||
private final AiUsageProperties properties;
|
||||
private final AiUsageClient aiUsageClient;
|
||||
|
||||
// ============ 落库 ============
|
||||
|
||||
@Override
|
||||
@Transactional(rollbackFor = Exception.class)
|
||||
public AiUsageIngestResult ingest(List<AiUsageRecordRequest> records) throws ErrorParameterException {
|
||||
if (records == null || records.isEmpty()) {
|
||||
return new AiUsageIngestResult(0, 0);
|
||||
}
|
||||
|
||||
// 先解析成实体:时间格式不对要在这里响亮失败,而不是写进半条脏数据
|
||||
List<AiUsageRecordEntity> entities = new ArrayList<>(records.size());
|
||||
for (AiUsageRecordRequest record : records) {
|
||||
entities.add(toEntity(record));
|
||||
}
|
||||
|
||||
Set<String> knownRecordIds = findExistingRecordIds(entities);
|
||||
// 上报接口没有登录态(/internal/** 已排除 Sa-Token),公共字段填充去取 StpUtil 会抛异常;
|
||||
// 这里显式声明「没有用户身份」,该表是系统级表,created_by 只是审计列,留空即可。
|
||||
return TenantContext.callAs(null, null, () -> insertSkippingDuplicates(entities, knownRecordIds));
|
||||
}
|
||||
|
||||
/** 批量取已存在的 recordId:这些就是本次要跳过的重复上报 */
|
||||
private Set<String> findExistingRecordIds(List<AiUsageRecordEntity> entities) {
|
||||
List<String> recordIds = entities.stream()
|
||||
.map(AiUsageRecordEntity::getRecordId)
|
||||
.collect(Collectors.toList());
|
||||
return aiUsageRecordMapper.selectList(Wrappers.<AiUsageRecordEntity>lambdaQuery()
|
||||
.select(AiUsageRecordEntity::getRecordId)
|
||||
.in(AiUsageRecordEntity::getRecordId, recordIds))
|
||||
.stream()
|
||||
.map(AiUsageRecordEntity::getRecordId)
|
||||
.collect(Collectors.toSet());
|
||||
}
|
||||
|
||||
/**
|
||||
* 逐条插入,跳过重复。
|
||||
*
|
||||
* <p>已在库里的、以及同一批里重复出现的 recordId 都算 duplicated;库里的唯一索引是最终防线,
|
||||
* 并发下撞上它同样按「重复上报不报错」处理,不让整批数据白报。</p>
|
||||
*/
|
||||
private AiUsageIngestResult insertSkippingDuplicates(List<AiUsageRecordEntity> entities,
|
||||
Set<String> knownRecordIds) {
|
||||
Set<String> seen = new HashSet<>(knownRecordIds);
|
||||
int accepted = 0;
|
||||
int duplicated = 0;
|
||||
for (AiUsageRecordEntity entity : entities) {
|
||||
if (!seen.add(entity.getRecordId())) {
|
||||
duplicated++;
|
||||
continue;
|
||||
}
|
||||
try {
|
||||
aiUsageRecordMapper.insert(entity);
|
||||
accepted++;
|
||||
} catch (DuplicateKeyException e) {
|
||||
duplicated++;
|
||||
}
|
||||
}
|
||||
if (duplicated > 0) {
|
||||
log.info("AI 用量上报:落库 {} 条,跳过重复 {} 条", accepted, duplicated);
|
||||
}
|
||||
return new AiUsageIngestResult(accepted, duplicated);
|
||||
}
|
||||
|
||||
private AiUsageRecordEntity toEntity(AiUsageRecordRequest record) throws ErrorParameterException {
|
||||
AiUsageRecordEntity entity = new AiUsageRecordEntity();
|
||||
entity.setRecordId(record.getRecordId());
|
||||
entity.setOccurredAt(parseUtc(record.getOccurredAt()));
|
||||
entity.setTaskType(record.getTaskType());
|
||||
entity.setTaskId(record.getTaskId());
|
||||
entity.setModel(record.getModel());
|
||||
entity.setAttempts(record.getAttempts());
|
||||
entity.setIsLlmCall(record.getIsLlmCall());
|
||||
entity.setUsageSource(record.getUsageSource());
|
||||
entity.setPromptTokens(record.getPromptTokens());
|
||||
entity.setCompletionTokens(record.getCompletionTokens());
|
||||
entity.setTotalTokens(record.getTotalTokens());
|
||||
entity.setCacheHitTokens(record.getCacheHitTokens());
|
||||
entity.setCacheMissTokens(record.getCacheMissTokens());
|
||||
entity.setReasoningTokens(record.getReasoningTokens());
|
||||
entity.setCostUsd(record.getCostUsd());
|
||||
entity.setPricingVersion(record.getPricingVersion());
|
||||
entity.setPeak(record.getPeak());
|
||||
entity.setDurationMs(record.getDurationMs());
|
||||
entity.setStatus(record.getStatus());
|
||||
entity.setErrorCode(record.getErrorCode());
|
||||
return entity;
|
||||
}
|
||||
|
||||
/** 契约 1:occurredAt 是 ISO 8601 UTC 字符串,落库统一换算成 UTC 的本地时间 */
|
||||
private static LocalDateTime parseUtc(String occurredAt) throws ErrorParameterException {
|
||||
try {
|
||||
return OffsetDateTime.parse(occurredAt.trim())
|
||||
.withOffsetSameInstant(ZoneOffset.UTC)
|
||||
.toLocalDateTime();
|
||||
} catch (DateTimeParseException e) {
|
||||
throw new ErrorParameterException("上报数据里的时间格式不对,需要 ISO 8601 UTC 时间");
|
||||
}
|
||||
}
|
||||
|
||||
// ============ 权限 ============
|
||||
|
||||
@Override
|
||||
public boolean isAdmin() {
|
||||
List<String> adminUsernames = properties.getAdminUsernames();
|
||||
if (adminUsernames == null || adminUsernames.isEmpty()) {
|
||||
return false;
|
||||
}
|
||||
// 登录态里是用户 id,白名单配的是用户名,需要这一次转换
|
||||
String userName = userService.getUserNameById(StpUtil.getLoginIdAsString());
|
||||
return userName != null && adminUsernames.contains(userName);
|
||||
}
|
||||
|
||||
// ============ 聚合查询 ============
|
||||
|
||||
@Override
|
||||
public AiUsageSummary summary(AiUsageQuery query) {
|
||||
ResolvedFilter filter = resolve(query);
|
||||
AiUsageSummaryRow row = aiUsageRecordMapper.selectSummary(
|
||||
filter.from(), filter.to(), filter.taskType(), filter.model());
|
||||
Integer p95DurationMs = aiUsageRecordMapper.selectP95DurationMs(
|
||||
filter.from(), filter.to(), filter.taskType(), filter.model());
|
||||
|
||||
long cacheHitTokens = nullToZero(row.getCacheHitTokens());
|
||||
long cacheMissTokens = nullToZero(row.getCacheMissTokens());
|
||||
long cacheTotal = cacheHitTokens + cacheMissTokens;
|
||||
BigDecimal costUsd = nullToZero(row.getCostUsd());
|
||||
|
||||
AiUsageSummary summary = new AiUsageSummary();
|
||||
summary.setTotalCalls(nullToZero(row.getTotalCalls()));
|
||||
summary.setSuccessCalls(nullToZero(row.getSuccessCalls()));
|
||||
summary.setFailedCalls(nullToZero(row.getFailedCalls()));
|
||||
summary.setPromptTokens(nullToZero(row.getPromptTokens()));
|
||||
summary.setCompletionTokens(nullToZero(row.getCompletionTokens()));
|
||||
summary.setTotalTokens(nullToZero(row.getTotalTokens()));
|
||||
summary.setCacheHitTokens(cacheHitTokens);
|
||||
summary.setCacheMissTokens(cacheMissTokens);
|
||||
// 分母为 0 时给 null 而不是 0:面板要能区分「没数据」和「命中率为零」
|
||||
summary.setCacheHitRate(cacheTotal == 0 ? null : (double) cacheHitTokens / cacheTotal);
|
||||
summary.setCostUsd(costUsd);
|
||||
summary.setCostCny(costUsd.multiply(properties.getUsdToCny()));
|
||||
summary.setAvgDurationMs(row.getAvgDurationMs() == null ? null : Math.round(row.getAvgDurationMs()));
|
||||
summary.setP95DurationMs(p95DurationMs == null ? null : p95DurationMs.longValue());
|
||||
summary.setUnreportedUsageCalls(nullToZero(row.getUnreportedUsageCalls()));
|
||||
return summary;
|
||||
}
|
||||
|
||||
@Override
|
||||
public List<AiUsageSeriesPoint> series(AiUsageQuery query) throws ErrorParameterException {
|
||||
ResolvedFilter filter = resolve(query);
|
||||
String bucket = requireBucket(query == null ? null : query.getBucket());
|
||||
|
||||
return aiUsageRecordMapper.selectSeries(
|
||||
filter.from(), filter.to(), filter.taskType(), filter.model(), bucket)
|
||||
.stream()
|
||||
.map(row -> {
|
||||
AiUsageSeriesPoint point = new AiUsageSeriesPoint();
|
||||
point.setBucket(row.getBucket());
|
||||
point.setCalls(nullToZero(row.getCalls()));
|
||||
point.setSuccessCalls(nullToZero(row.getSuccessCalls()));
|
||||
point.setFailedCalls(nullToZero(row.getFailedCalls()));
|
||||
point.setPromptTokens(nullToZero(row.getPromptTokens()));
|
||||
point.setCompletionTokens(nullToZero(row.getCompletionTokens()));
|
||||
point.setCostUsd(nullToZero(row.getCostUsd()));
|
||||
return point;
|
||||
})
|
||||
.collect(Collectors.toList());
|
||||
}
|
||||
|
||||
@Override
|
||||
public List<AiUsageBreakdownItem> breakdown(AiUsageQuery query) throws ErrorParameterException {
|
||||
ResolvedFilter filter = resolve(query);
|
||||
String groupBy = requireGroupBy(query == null ? null : query.getGroupBy());
|
||||
|
||||
return aiUsageRecordMapper.selectBreakdown(
|
||||
filter.from(), filter.to(), filter.taskType(), filter.model(), groupBy)
|
||||
.stream()
|
||||
.map(row -> {
|
||||
AiUsageBreakdownItem item = new AiUsageBreakdownItem();
|
||||
item.setKey(row.getGroupKey());
|
||||
item.setCalls(nullToZero(row.getCalls()));
|
||||
item.setSuccessCalls(nullToZero(row.getSuccessCalls()));
|
||||
item.setFailedCalls(nullToZero(row.getFailedCalls()));
|
||||
item.setPromptTokens(nullToZero(row.getPromptTokens()));
|
||||
item.setCompletionTokens(nullToZero(row.getCompletionTokens()));
|
||||
item.setCacheHitTokens(nullToZero(row.getCacheHitTokens()));
|
||||
item.setCostUsd(nullToZero(row.getCostUsd()));
|
||||
item.setAvgDurationMs(row.getAvgDurationMs() == null
|
||||
? null : Math.round(row.getAvgDurationMs()));
|
||||
return item;
|
||||
})
|
||||
.collect(Collectors.toList());
|
||||
}
|
||||
|
||||
@Override
|
||||
public AiUsageBalance balance() {
|
||||
return aiUsageClient.fetchBalance();
|
||||
}
|
||||
|
||||
/** 查询条件:时间范围补默认值(最近 30 天),并把 epoch millis 换算成 UTC 的本地时间 */
|
||||
private ResolvedFilter resolve(AiUsageQuery query) {
|
||||
Long from = query == null ? null : query.getFrom();
|
||||
Long to = query == null ? null : query.getTo();
|
||||
Instant now = Instant.now();
|
||||
LocalDateTime fromTime = from == null
|
||||
? LocalDateTime.ofInstant(now.minus(DEFAULT_RANGE), ZoneOffset.UTC)
|
||||
: LocalDateTime.ofInstant(Instant.ofEpochMilli(from), ZoneOffset.UTC);
|
||||
LocalDateTime toTime = to == null
|
||||
? LocalDateTime.ofInstant(now, ZoneOffset.UTC)
|
||||
: LocalDateTime.ofInstant(Instant.ofEpochMilli(to), ZoneOffset.UTC);
|
||||
return new ResolvedFilter(fromTime, toTime,
|
||||
query == null ? null : query.getTaskType(),
|
||||
query == null ? null : query.getModel());
|
||||
}
|
||||
|
||||
private static String requireBucket(String bucket) throws ErrorParameterException {
|
||||
if (bucket == null || bucket.isBlank()) {
|
||||
return BUCKET_DAY;
|
||||
}
|
||||
String value = bucket.trim();
|
||||
if (!BUCKET_DAY.equals(value) && !BUCKET_HOUR.equals(value)) {
|
||||
throw new ErrorParameterException("分桶粒度只支持 day 或 hour");
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
private static String requireGroupBy(String groupBy) throws ErrorParameterException {
|
||||
if (groupBy == null || groupBy.isBlank()) {
|
||||
return GROUP_BY_TASK_TYPE;
|
||||
}
|
||||
String value = groupBy.trim();
|
||||
if (!GROUP_BY_TASK_TYPE.equals(value) && !GROUP_BY_MODEL.equals(value)) {
|
||||
throw new ErrorParameterException("分组维度只支持 taskType 或 model");
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
private static long nullToZero(Long value) {
|
||||
return value == null ? 0L : value;
|
||||
}
|
||||
|
||||
private static BigDecimal nullToZero(BigDecimal value) {
|
||||
return value == null ? BigDecimal.ZERO : value;
|
||||
}
|
||||
|
||||
/** 解析后的查询条件(时间已转成 UTC 本地时间) */
|
||||
private record ResolvedFilter(LocalDateTime from, LocalDateTime to, String taskType, String model) {
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user