用量统计

概述

用量统计模块基于 AI 调用日志数据（AiLlmCallLog、AiKnowledgeRetrievalLog、AiKnowledgeDocLog），提供模型调用、知识库检索、文档处理等操作的用量统计和分析功能。支持按日期范围过滤、按天/小时聚合，提供多维度的数据可视化展示。

页面功能

筛选栏

• 日期范围：选择统计的起止日期，默认显示最近 7 天数据
• 聚合粒度：按天（DAY）或按小时（HOUR）聚合统计数据
• 查询/重置：点击查询按钮刷新数据，重置恢复默认值

用量总览卡片

展示 8 个核心统计指标：

1. LLM 总调用次数 - 模型调用总次数
2. LLM 成功率(%) - 调用成功的百分比
3. LLM 总 Token - 消耗的 Token 总数
4. LLM 平均耗时(ms) - 每次调用的平均耗时
5. 检索总次数 - 知识库检索总次数
6. 召回文档块总数 - 检索召回的文档块总数
7. 检索 Embedding Token - 检索消耗的 Embedding Token
8. 文档处理总次数 - 文档处理操作总次数

用量趋势折线图

展示按时间序列的用量趋势，包含 4 条曲线：

• LLM 调用次数
• LLM 总 Token
• 检索次数
• 文档处理次数

模型用量柱状图

按模型维度统计 LLM 用量，双 Y 轴显示：

• 左 Y 轴：总调用次数
• 右 Y 轴：总 Token

知识库检索饼图

按知识库维度统计检索次数占比，使用环形饼图展示。

文档处理柱状图

按操作类型（ADD/UPDATE/DELETE）统计文档处理用量，堆叠柱状图展示：

• 成功次数
• 失败次数
• 总分块数

数据库实体

AiLlmCallLog（AI大模型调用日志）

字段	类型	说明
id	Long	主键ID
traceId	String	链路追踪ID
callSource	String	调用来源：AGENT/CHAT/FLOW/API
sourceId	Long	来源ID(智能体ID/会话ID/流程ID)
sourceNodeId	String	来源节点ID(工作流节点ID)
modelId	Long	模型ID
modelName	String	模型名称
modelProvider	String	模型提供商：QWEN/DOUBAO/OPENAI/CUSTOM
temperature	BigDecimal	生成温度
maxTokens	Integer	最大生成长度
inputCharCount	Integer	输入字符数
inputTokens	Integer	输入消耗token数
outputCharCount	Integer	输出字符数
outputTokens	Integer	输出消耗token数
totalTokens	Integer	总消耗token数
finishReason	String	结束原因：STOP/TOOL_EXECUTION等
callStatus	Integer	调用状态：0-失败，1-成功
errorCode	String	错误码
errorMessage	String	错误信息
startTime	LocalDateTime	调用开始时间
endTime	LocalDateTime	调用结束时间
duration	Integer	调用时长(毫秒)
timeSign	LocalDate	日期
hourSign	Integer	小时(0-23,用于按小时聚合)
createBy	Long	创建人ID
createTime	LocalDateTime	记录创建时间
orgId	Integer	所属组织ID

AiKnowledgeRetrievalLog（AI知识库检索日志）

字段	类型	说明
id	Long	主键ID
traceId	String	链路追踪ID
callSource	String	调用来源：AGENT/CHAT/FLOW/API
sourceId	Long	来源ID(智能体ID/会话ID/流程ID)
sourceNodeId	String	来源节点ID(工作流节点ID)
knowledgeBaseId	Long	知识库ID
knowledgeBaseName	String	知识库名称
queryCharCount	Integer	查询字符数
queryEmbeddingTokens	Integer	查询向量化消耗token
topK	Integer	召回条数
retrievedCount	Integer	实际召回数量
callStatus	Integer	调用状态：0-失败，1-成功
errorMessage	String	错误信息
startTime	LocalDateTime	调用开始时间
endTime	LocalDateTime	调用结束时间
duration	Integer	调用时长(毫秒)
timeSign	LocalDate	日期
hourSign	Integer	小时(0-23,用于按小时聚合)
createBy	Long	创建人ID
createTime	LocalDateTime	记录创建时间
orgId	Integer	所属组织ID

AiKnowledgeDocLog（AI知识库文档处理日志）

字段	类型	说明
id	Long	主键ID
knowledgeBaseId	Long	知识库ID
knowledgeBaseName	String	知识库名称
docId	Long	文档ID
docName	String	文档名称
operationType	String	操作类型：ADD/UPDATE/DELETE
chunkCount	Integer	分块数量
totalCharCount	Integer	总字符数
totalEmbeddingTokens	Integer	embedding总消耗token
callStatus	Integer	调用状态：0-失败，1-成功
errorMessage	String	错误信息
startTime	LocalDateTime	调用开始时间
endTime	LocalDateTime	调用结束时间
duration	Integer	调用时长(毫秒)
timeSign	LocalDate	日期
hourSign	Integer	小时(0-23,用于按小时聚合)
createBy	Long	创建人ID
createTime	LocalDateTime	记录创建时间
orgId	Integer	所属组织ID

后端 API

公共请求参数（AiUsageStatQueryRequest）

字段	类型	说明
startDate	LocalDate	开始日期
endDate	LocalDate	结束日期
startHour	Integer	起始小时(0-23,可选)
endHour	Integer	结束小时(0-23,可选)
granularity	String	聚合粒度：DAY(按天)/HOUR(按小时)，默认 DAY
orgId	Integer	组织ID(可选)

用量总览

接口：POST /bapi/ai/usage/overview

返回数据（AiUsageOverviewVo）：

字段	类型	说明
llmTotalCalls	Long	LLM 总调用次数
llmSuccessCalls	Long	LLM 成功次数
llmFailCalls	Long	LLM 失败次数
llmSuccessRate	BigDecimal	LLM 成功率(%)
llmInputTokens	Long	LLM 总输入 Token
llmOutputTokens	Long	LLM 总输出 Token
llmTotalTokens	Long	LLM 总 Token
llmAvgDurationMs	BigDecimal	LLM 平均耗时(毫秒)
retrievalTotalCalls	Long	检索总次数
retrievalSuccessCalls	Long	检索成功次数
retrievalTotalChunks	Long	召回文档块总数
retrievalEmbeddingTokens	Long	检索 Embedding 消耗总 Token
retrievalAvgDurationMs	BigDecimal	检索平均耗时(毫秒)
docTotalOps	Long	文档处理总次数
docSuccessOps	Long	文档处理成功次数
docTotalChunks	Long	文档处理总分块数
docEmbeddingTokens	Long	文档处理 Embedding 消耗总 Token

用量趋势

接口：POST /bapi/ai/usage/trend

返回数据（List<AiUsageTrendItem>）：

字段	类型	说明
timeLabel	String	时间标签(按天:2026-07-15;按小时:2026-07-15 13)
date	LocalDate	日期
hour	Integer	小时(0-23,按天聚合时为 null)
llmCalls	Long	LLM 调用次数
llmTotalTokens	Long	LLM 总 Token
llmAvgDurationMs	BigDecimal	LLM 平均耗时(毫秒)
retrievals	Long	检索次数
retrievalEmbeddingTokens	Long	检索 Embedding Token
docOps	Long	文档处理次数

按模型统计 LLM 用量

接口：POST /bapi/ai/usage/statByModel

返回数据（List<LlmModelUsageItem>）：

字段	类型	说明
modelId	Long	模型 ID
modelName	String	模型名称
modelProvider	String	模型提供商
totalCalls	Long	总调用次数
successCalls	Long	成功次数
failCalls	Long	失败次数
totalInputTokens	Long	总输入 Token
totalOutputTokens	Long	总输出 Token
totalTokens	Long	总 Token
avgDurationMs	BigDecimal	平均耗时(毫秒)

按知识库统计检索用量

接口：POST /bapi/ai/usage/statByKnowledgeBase

返回数据（List<KbRetrievalUsageItem>）：

字段	类型	说明
knowledgeBaseId	Long	知识库 ID
knowledgeBaseName	String	知识库名称
totalRetrievals	Long	总检索次数
successRetrievals	Long	成功次数
totalRetrievedChunks	Long	召回文档总数
totalEmbeddingTokens	Long	Embedding 消耗总 Token
avgDurationMs	BigDecimal	平均耗时(毫秒)

按操作类型统计文档处理用量

接口：POST /bapi/ai/usage/statByDocOperation

返回数据（List<DocOperationUsageItem>）：

字段	类型	说明
operationType	String	操作类型(ADD/UPDATE/DELETE)
totalOps	Long	总处理次数
successOps	Long	成功次数
failOps	Long	失败次数
totalChunks	Long	总分块数
totalCharCount	Long	总字符数
totalEmbeddingTokens	Long	Embedding 消耗总 Token

核心类

AiUsageStatController

用量统计控制器，提供 5 个统计接口：

• /overview - 用量总览
• /trend - 用量趋势
• /statByModel - 按模型统计
• /statByKnowledgeBase - 按知识库统计
• /statByDocOperation - 按操作类型统计

IAiUsageStatService & AiUsageStatServiceImpl

用量统计服务接口及实现，基于 MyBatis Mapper 查询三类日志表并聚合统计数据。

AiUsageStatMapper

自定义 Mapper，使用 XML 编写复杂的聚合查询 SQL。