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

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

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-27T19:44:47.000Z
- 最近活动: 2026-05-27T19:48:35.428Z
- 热度: 118.9
- 关键词: LLM, FastAPI, React, PostgreSQL, Groq, 可观测性, 日志系统, PII脱敏, 流式响应, Docker
- 页面链接: https://www.zingnex.cn/forum/thread/llm-inference-logging-system
- Canonical: https://www.zingnex.cn/forum/thread/llm-inference-logging-system
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：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\n### 1. 全链路推理日志记录\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\n### 2. 敏感信息自动脱敏\n\n在生产环境中，用户输入可能包含邮箱、电话号码等 PII（个人身份信息）。项目内置的 `pii.py` 模块使用正则表达式在数据入库前自动识别并脱敏：\n\n- 邮箱地址替换为 `[EMAIL REDACTED]`\n- 电话号码替换为 `[PHONE REDACTED]`\n\n这种设计体现了 Privacy by Design 的理念——敏感数据处理不是事后补丁，而是内建在数据流中的默认行为。\n\n### 3. 实时监控面板\n\n前端集成了基于 Recharts 的数据可视化组件，在 Stats 标签页提供：\n\n- **平均延迟卡片**：直观展示响应速度趋势\n- **Token 总量统计**：帮助评估成本消耗\n- **请求计数器**：监控使用频率\n- **错误率追踪**：快速发现异常波动\n- **延迟分布柱状图**：识别长尾延迟问题\n\n这种开箱即用的监控能力，让开发者无需额外搭建 Grafana 或 Datadog 就能实现基础的可观测性。\n\n### 4. 多模型切换与流式响应\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\n### Docker 一键启动\n\n项目提供了完整的 Docker Compose 配置，实现真正的"一键启动"：\n\n```bash\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**后端设置：**\n```bash\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**前端设置：**\n```bash\ncd frontend\nnpm install\nnpm run dev\n```\n\n服务启动后，前端访问 `http://localhost:5173`，API 文档可在 `http://localhost:8000/docs` 查看。\n\n---\n\n## API 端点设计\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 应用的开发者而言，这个项目提供了一个经过深思熟虑的参考实现——不仅展示了如何让模型"工作"，更重要的是展示了如何让模型"可观测"。