LLM Inference Logging System：为每一次模型调用建立完整的可观测性

一个基于 FastAPI、React、PostgreSQL 和 Groq 的全栈聊天应用，自动记录每次 LLM 调用的延迟、Token 用量、模型类型和状态，并内置 PII 脱敏与实时监控面板。

• 原作者/维护者：Kumkum-kaushik
• 来源平台：github
• 原始标题：llm-inference-logger
• 原始链接：https://github.com/Kumkum-kaushik/llm-inference-logger
• 来源发布时间/更新时间：2026-05-27T19:44:47Z

原作者与来源

• 原作者/维护者：Kumkum-kaushik
• 来源平台：github
• 原始标题：llm-inference-logger
• 原始链接：https://github.com/Kumkum-kaushik/llm-inference-logger
• 来源发布时间/更新时间：2026-05-27T19:44:47Z 原作者与来源\n\n- 原作者/维护者： Kumkum-kaushik\n- 来源平台： GitHub\n- 原项目标题： LLM Inference Logging System\n- 原始链接： https://github.com/Kumkum-kaushik/llm-inference-logger\n- 发布时间： 2026年5月27日\n\n---\n\n项目概述\n\n在 LLM 应用快速普及的今天，大多数开发者只关注如何让模型"说出正确的话"，却很少有人系统性地追踪"模型是怎么说的"。Kumkum-kaushik 开源的 LLM Inference Logging System 填补了这一空白——它是一个全栈聊天应用，不仅实现了与 LLM 的多轮对话功能，更重要的是为每一次推理调用建立了完整的可观测性（Observability）体系。\n\n这个项目采用 FastAPI + React + PostgreSQL + Groq 的技术栈，核心设计理念是**"记录一切"：从用户输入到模型响应的完整生命周期中，延迟、Token 用量、模型类型、响应状态等关键指标都被自动捕获并持久化存储。对于需要生产环境部署的 LLM 应用而言，这种细粒度的监控能力是排查性能瓶颈、控制成本支出、保障服务质量的必要基础设施。\n\n---\n\n核心功能解析\n\n1. 全链路推理日志记录\n\n系统最核心的能力是自动记录每一次 LLM 调用的完整上下文。这包括：\n\n- 延迟指标：从发送请求到收到完整响应的时间\n- Token 用量：输入和输出 Token 的精确统计\n- 模型信息：具体使用的模型版本（如 llama-3.1-8b-instant 或 llama-3.3-70b-versatile）\n- 提供商标识：当前使用的 API 提供商（Groq）\n- 响应状态：成功、失败或异常的具体状态码\n\n这些数据被写入 PostgreSQL 的 inference_logs 表中，与 conversations 和 messages 表形成完整的数据关系网，既支持单条查询也支持聚合分析。\n\n2. 敏感信息自动脱敏\n\n在生产环境中，用户输入可能包含邮箱、电话号码等 PII（个人身份信息）。项目内置的 pii.py 模块使用正则表达式在数据入库前自动识别并脱敏：\n\n- 邮箱地址替换为 [EMAIL REDACTED]\n- 电话号码替换为 [PHONE REDACTED]\n\n这种设计体现了 Privacy by Design 的理念——敏感数据处理不是事后补丁，而是内建在数据流中的默认行为。\n\n3. 实时监控面板\n\n前端集成了基于 Recharts 的数据可视化组件，在 Stats 标签页提供：\n\n- 平均延迟卡片：直观展示响应速度趋势\n- Token 总量统计：帮助评估成本消耗\n- 请求计数器：监控使用频率\n- 错误率追踪：快速发现异常波动\n- 延迟分布柱状图：识别长尾延迟问题\n\n这种开箱即用的监控能力，让开发者无需额外搭建 Grafana 或 Datadog 就能实现基础的可观测性。\n\n4. 多模型切换与流式响应\n\n系统支持在对话过程中随时切换两个不同的 Groq 模型：\n\n- Groq Fast：llama-3.1-8b-instant，适合对延迟敏感的场景\n- Groq Large：llama-3.3-70b-versatile，适合需要更强推理能力的任务\n\n此外，/chat/stream 端点实现了基于 FastAPI StreamingResponse 的流式输出，前端使用 fetch() 和 ReadableStream API 逐字渲染模型输出，显著提升了用户体验的响应感知。\n\n---\n\n技术架构与数据流\n\n后端架构\n\n后端采用 FastAPI 框架，整体架构遵循清晰的分层设计：\n\n1. API 层：处理 HTTP 请求，包括对话管理、消息发送、日志查询等端点\n2. SDK 层：封装 Groq API 调用，统一处理认证、重试、超时等逻辑\n3. 日志层：在请求响应周期中插入埋点，捕获性能指标并脱敏敏感数据\n4. 存储层：使用 PostgreSQL 持久化对话历史、消息内容和推理日志\n\n数据流示意\n\n\n用户输入 → React UI → FastAPI → SDK 层 → Groq API\n ↓\n 记录延迟、Token、模型信息\n ↓\n PII 脱敏处理\n ↓\n 写入 PostgreSQL\n ↓\n 返回响应给前端\n\n\n数据库设计\n\n项目使用三张核心表：\n\n- conversations：存储会话元数据（创建时间、标题、选用的模型等）\n- messages：存储对话中的每一条消息（角色、内容、时间戳）\n- inference_logs：存储每次 LLM 调用的技术指标（延迟、Token、状态等）\n\n这种分离设计让业务数据与监控数据解耦，便于独立扩展和归档。\n\n---\n\n部署与使用\n\nDocker 一键启动\n\n项目提供了完整的 Docker Compose 配置，实现真正的"一键启动"：\n\nbash\n创建环境变量文件\necho \"GROQ_API_KEY=your_groq_api_key_here\" > .env\n\n启动所有服务\ndocker compose up --build\n\n\n这条命令会并行启动后端（FastAPI）、前端（React/Vite）和 PostgreSQL 数据库。后端服务配置了健康检查依赖，确保数据库就绪后才启动应用。\n\n手动部署\n\n对于需要自定义环境的场景，项目也提供了详细的手动部署指南：\n\n后端设置：\nbash\ncd backend\npython -m venv venv\nsource venv/bin/activate Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --reload\n\n\n前端设置：\nbash\ncd frontend\nnpm install\nnpm run dev\n\n\n服务启动后，前端访问 http://localhost:5173，API 文档可在 http://localhost:8000/docs 查看。\n\n---\n\nAPI 端点设计\n\n项目提供了 RESTful 风格的 API，覆盖完整的对话生命周期：\n\n| 方法 | 端点 | 功能描述 |\n|------|------|----------|\n| POST | /conversation/new | 创建新对话 |\n| GET | /conversations | 列出所有对话 |\n| POST | /chat | 发送消息并获取响应 |\n| POST | /chat/stream | 流式发送消息 |\n| GET | /conversation/{id}/messages | 获取对话历史 |\n| DELETE | /conversation/{id} | 删除对话 |\n| GET | /logs | 查看推理日志 |\n| GET | /stats | 获取统计指标 |\n\n这种设计让系统既可以作为完整的聊天应用使用，也可以作为 LLM 调用监控的基础设施被其他服务集成。\n\n---\n\n设计权衡与未来方向\n\n作者在文档中坦诚地列出了当前实现的设计权衡：\n\n同步日志写入**：当前实现在请求周期内同步写入数据库，简化了代码逻辑，但在高并发场景下可能成为瓶颈。未来可考虑引入异步队列（如 Celery 或 RabbitMQ）将日志写入 offload 到后台任务。\n\n无连接池：每个数据库操作都新建连接，开发阶段便于调试，但生产环境应使用 psycopg2.pool 或 SQLAlchemy 的连接池管理。\n\n进程内 SDK：Groq SDK 与 FastAPI 运行在同一进程，架构简单但难以独立扩展。后续可考虑拆分为独立服务。\n\n日志截断：inference_logs 表中的消息预览限制为 100 字符，平衡了调试需求与存储成本。完整内容始终保留在 messages 表中。\n\n这些权衡反映了项目当前处于"功能验证"阶段，代码结构清晰，为后续演进预留了充足空间。\n\n---\n\n技术栈总结\n\n| 层级 | 技术选型 |\n|------|----------|\n| 后端框架 | FastAPI (Python 3.10+) |\n| 数据库 | PostgreSQL 17 |\n| LLM 服务 | Groq (LLaMA 3.1 8B / LLaMA 3.3 70B) |\n| 前端框架 | React + Vite |\n| 可视化 | Recharts |\n| HTTP 客户端 | Axios |\n| 容器化 | Docker + Docker Compose |\n\n---\n\n总结与适用场景\n\nLLM Inference Logging System 是一个面向生产准备的 LLM 应用模板，而非简单的 Demo。它的价值在于将"可观测性"作为一等公民纳入架构设计，让开发者从项目第一天就建立起对模型行为的完整洞察。\n\n适合的使用场景包括：\n\n- 需要监控 LLM 成本和性能的内部工具\n- 对数据隐私有要求的客服或咨询系统\n- 希望快速搭建带监控能力的聊天原型的团队\n- 学习 FastAPI + React 全栈开发的实践项目\n\n对于正在构建 LLM 应用的开发者而言，这个项目提供了一个经过深思熟虑的参考实现——不仅展示了如何让模型"工作"，更重要的是展示了如何让模型"可观测"。