Token 分析平台系统架构设计：从前端到核心逻辑

4.1 职责

应用层是整个系统的'大脑'，它接收前端请求，调用核心逻辑层完成处理，并返回结果。具体职责包括：

• API Gateway：统一入口，路由分发，将不同请求转发给对应的处理函数。
• 请求验证：检查请求参数合法性、用户身份认证、权限校验。
• 内部调用协调：可能同时调用分析引擎和可视化器，组合结果返回。

4.2 技术选型

• FastAPI：作为现代 Python Web 框架，FastAPI 具备高性能（基于 Starlette）、自动生成 OpenAPI 文档、Pydantic 数据验证等优点，非常适合构建 RESTful API 服务。

4.3 关键 API 设计

• POST /api/logs：接收业务应用发来的 Token 日志，存储到数据库。
• GET /api/stats/summary：返回今日总成本、平均成本、异常标记等汇总信息。
• GET /api/stats/trend：返回时间序列数据（按小时/天聚合），用于前端绘制曲线。
• GET /api/stats/by-service：按服务聚合成本。
• GET /api/stats/by-user：按用户聚合成本，支持分页和排序。

4.4 性能考虑

• 使用异步处理（async def）提高 I/O 并发能力。
• 对于写入密集型接口（如/logs），可引入消息队列（如 RabbitMQ）缓冲请求，再由后台 Worker 批量写入数据库，避免瞬时压力。

五、核心逻辑与处理层：能力的源泉

这是系统的'发动机'，封装了所有核心业务逻辑。图中将其分为两个子模块：分析引擎和可视化器。

5.1 分析引擎

职责：

• Token 计数：集成 Tiktoken 库，精确计算每次请求的 Input/Output Token 数量。
• 成本计算：根据模型单价和 Token 数，计算每次调用的费用。
• 优化建议生成：基于历史数据，识别高消耗 Prompt、频繁重复请求，给出降本建议（如切换到更便宜模型、开启缓存等）。

技术实现：

• Tiktoken 是 OpenAI 官方 Tokenizer 库，支持多种模型（gpt-4, gpt-3.5-turbo 等）。对于非 OpenAI 模型，可扩展自定义计数函数。
• 成本计算逻辑可配置化，将模型单价存储在数据库或配置文件中，便于调整。

5.2 可视化器

职责：

• 根据查询参数，从数据库获取原始数据，进行聚合计算。
• 生成图表数据（如 Plotly 的 JSON 格式）或直接渲染为静态图表（如 Matplotlib 生成的图片）。
• 提供报表导出功能（如 PDF、Excel）。

技术实现：

• Plotly：生成交互式图表，前端可以直接嵌入 Plotly.js 渲染，用户体验好。
• Matplotlib：适合生成静态报表图片，用于邮件订阅或打印。
• 注意性能：对于大时间范围的数据，应在数据库层面完成聚合（如使用 SQL 的 GROUP BY），避免将大量原始数据传输到应用层。

六、数据流全景：从日志上报到图表展示

下面我们模拟一次完整的请求处理流程：

1. 日志上报：业务应用调用 POST /api/logs，将一次大模型调用的详细信息（用户 ID、模型、Prompt、Completion 等）发送给应用层。
2. 应用层验证：FastAPI 验证请求格式和认证信息，通过后调用分析引擎。
3. 分析引擎处理：
   • 使用 Tiktoken 计算 Prompt 和 Completion 的 Token 数。
   • 根据模型单价计算成本。
   • （可选）将 Prompt 存入异常检测队列，供后续分析。
4. 数据持久化：将完整的日志记录（含 Token 数和成本）存入 SQLite 数据库。
5. 用户查询：管理员打开 Dashboard，前端发起 GET /api/stats/trend?from=2025-03-01&to=2025-03-07 请求。
6. 应用层路由：FastAPI 接收请求，调用可视化器。
7. 可视化器处理：
   • 从数据库查询按天聚合的成本数据。
   • 使用 Plotly 生成交互式图表的 JSON 数据。
8. 返回前端：应用层将 JSON 数据返回，前端渲染出成本趋势曲线。
9. 用户交互：管理员点击曲线上某一点，前端发起更细粒度的查询（如按小时），重复步骤 5-8。

七、架构设计的优势

1. 分层清晰，职责分离：前端、应用、核心逻辑各司其职，便于团队分工和维护。
2. 易于扩展：如果需要增加新的分析功能（如引入机器学习预测），只需在核心层添加模块，不影响上层。
3. 技术栈现代：FastAPI 异步框架保证了高性能，Tiktoken 保证了 Token 计数的准确性，Plotly 提供了丰富的可视化能力。
4. 部署灵活：系统可以打包为 Docker 镜像，一键部署；数据库可从 SQLite 轻松迁移到 PostgreSQL，以适应更大规模。

八、总结

Token 分析平台的架构设计遵循了经典的'分层'思想，同时结合了现代 Web 技术和 AI 工具，构建出一个既实用又可扩展的成本监控系统。无论你的企业是刚开始接触大模型，还是已经大规模应用，这套架构都能帮助你建立起成本的可观测性，让每一分钱都花得明白。