DeepChat实操手册：DeepChat与Grafana+Loki构建全链路可观测性监控体系

DeepChat实操手册：DeepChat与Grafana+Loki构建全链路可观测性监控体系

1. 为什么需要为AI对话服务做可观测性监控

你有没有遇到过这样的情况：DeepChat界面一切正常，但用户突然反馈“提问没反应”“回复卡住了”“等了两分钟才出结果”？或者更糟——某天早上发现服务完全不响应，日志里却只有一片空白？

这不是个别现象。本地大模型服务看似简单，实则暗藏多层依赖：Ollama服务进程是否存活、llama3:8b模型是否加载成功、GPU显存是否被占满、HTTP请求是否超时、WebUI后端API连接是否中断……任何一个环节出问题，都会导致用户体验断崖式下跌，而问题根源却像藏在迷雾里。

更关键的是，DeepChat的“私有化”特性是一把双刃剑——它保障了数据不出域，但也意味着你失去了云厂商提供的开箱即用监控能力。没有指标、没有日志、没有链路追踪，你就只能靠“重启试试”来排障，既低效又被动。

本文不讲抽象概念，不堆砌术语。我们将手把手带你用Grafana + Loki搭建一套轻量、可靠、真正能落地的可观测性体系，专为DeepChat这类本地AI服务设计。你会看到：

• 如何让Ollama的每一次推理都变成可度量的指标
• 怎样从海量日志中秒级定位“为什么用户提问没回复”
• 不改一行DeepChat代码，就能实现请求耗时、错误率、模型加载状态的实时可视化
• 一套配置文件搞定全部，5分钟完成部署，零学习成本

这不是理论方案，而是我们已在生产环境稳定运行三个月的实操路径。

2. DeepChat服务架构与可观测性切入点

2.1 DeepChat到底由哪些部分组成

先放下“AI”这个光环，把它看作一个标准的本地Web服务：

• 最底层：Ollama服务进程
  这是真正的“大脑”，负责加载模型、执行推理。它是一个独立的后台服务（ollama serve），监听127.0.0.1:11434。DeepChat前端所有请求，最终都转发给它。它的健康状况直接决定AI能否工作。

• 中间层：DeepChat WebUI应用
  这是一个Python Flask应用（或类似轻量框架），提供聊天界面，处理用户输入，调用Ollama API，并将流式响应渲染成打字机效果。它本身不参与模型计算，但承担了请求路由、会话管理、错误包装等关键职责。

• 最上层：用户浏览器
  纯静态HTML+JS，通过WebSocket或HTTP长连接与WebUI通信。这里不产生服务端日志，但它是整个链路的起点和终点。

可观测性的黄金三角就在这里：

• 指标（Metrics）：Ollama的CPU/GPU使用率、推理请求数、平均延迟；WebUI的HTTP请求成功率、响应时间
• 日志（Logs）：Ollama服务启动日志、模型加载日志、推理错误日志；WebUI的请求记录、异常堆栈
• 链路（Traces）：一次用户提问 → WebUI接收 → 调用Ollama → Ollama返回 → WebUI推送 → 浏览器显示，全程耗时分解

本手册聚焦前两者——指标与日志。因为对DeepChat这类单体服务，它们已能覆盖95%的故障场景，且实施成本最低、见效最快。

2.2 为什么选Grafana + Loki而不是其他方案

你可能听过Prometheus+Grafana、ELK、Datadog……但对DeepChat，它们要么太重，要么不匹配：

• Prometheus：擅长抓取HTTP接口暴露的指标，但Ollama默认不提供/metrics端点，强行改造需修改源码，违背“零侵入”原则。
• ELK（Elasticsearch+Logstash+Kibana）：功能强大，但资源消耗高，单节点部署常因内存不足崩溃，不适合边缘或开发机。
• 商业SaaS（如Datadog）：需要外网上传日志，直接违反DeepChat“数据不出服务器”的核心安全承诺。

而Grafana + Loki的组合，完美契合：

• Loki不索引日志内容，只索引标签：日志体积小、查询快、资源占用极低（2核4G内存轻松承载）。
• Grafana原生支持Loki日志查询，并能与指标面板无缝联动：比如在看到“HTTP错误率飙升”时，直接点击跳转到同一时间段的错误日志详情。
• 所有组件均可容器化，与DeepChat镜像共存于同一台机器：无需额外服务器，一条docker-compose命令即可拉起整套监控。

一句话：它用最小的代价，给你最大的掌控力。

3. 一键部署：Grafana+Loki监控栈

3.1 准备工作：确认环境与权限

在开始前，请确保你的DeepChat镜像已成功运行（可通过HTTP按钮访问聊天界面）。本次部署要求：

• 操作系统：Linux（Ubuntu/CentOS/Debian等主流发行版）
• Docker版本：≥20.10（检查命令：docker --version）
• 可用内存：≥2GB（Loki+Grafana基础运行需求）
• 端口空闲：3000（Grafana）、3100（Loki）

重要提醒：本方案所有组件均运行在本地，不访问任何外部网络，完全符合DeepChat的私有化安全要求。

3.2 创建监控配置文件

新建一个目录，例如deepchat-monitoring，并在其中创建docker-compose.yml文件，内容如下：

version: '3.8' services: # Loki日志聚合服务 loki: image: grafana/loki:2.9.2 container_name: loki ports: - "3100:3100" command: -config.file=/etc/loki/local-config.yaml volumes: - ./loki-config.yaml:/etc/loki/local-config.yaml:ro - ./loki-data:/loki # Promtail日志采集器（负责把DeepChat日志发给Loki） promtail: image: grafana/promtail:2.9.2 container_name: promtail volumes: - /var/log:/var/log # 挂载宿主机日志目录（DeepChat日志将写入此处） - ./promtail-config.yaml:/etc/promtail/config.yml:ro - /var/run/docker.sock:/var/run/docker.sock # 读取Docker容器日志 depends_on: - loki # Grafana可视化平台 grafana: image: grafana/grafana-enterprise:10.2.2 container_name: grafana ports: - "3000:3000" environment: - GF_SECURITY_ADMIN_PASSWORD=admin - GF_USERS_ALLOW_SIGN_UP=false volumes: - ./grafana-storage:/var/lib/grafana - ./grafana-datasources.yaml:/etc/grafana/provisioning/datasources/datasource.yaml:ro - ./grafana-dashboards.yaml:/etc/grafana/provisioning/dashboards/dashboard.yaml:ro - ./dashboards:/var/lib/grafana/dashboards:ro depends_on: - loki

接着，创建配套配置文件：

loki-config.yaml（Loki服务配置）：

auth_enabled: false server: http_listen_port: 3100 common: path_prefix: /loki storage: filesystem: chunks_directory: /loki/chunks rules_directory: /loki/rules replication_factor: 1 ring: kvstore: store: inmemory schema_config: configs: - from: 2020-10-24 store: boltdb-shipper object_store: filesystem schema: v11 index: prefix: index_ period: 24h ruler: alertmanager_url: http://localhost:9093

promtail-config.yaml（日志采集配置）：

server: http_listen_port: 9080 positions: filename: /tmp/positions.yaml clients: - url: http://loki:3100/loki/api/v1/push scrape_configs: - job_name: deepchat-logs static_configs: - targets: [localhost] labels: job: deepchat-webui __path__: /var/log/deepchat/*.log # DeepChat WebUI日志路径 - job_name: ollama-logs static_configs: - targets: [localhost] labels: job: ollama-service __path__: /var/log/ollama/*.log # Ollama服务日志路径 - job_name: docker-logs docker_sd_configs: - host: unix:///var/run/docker.sock refresh_interval: 5s relabel_configs: - source_labels: ['__meta_docker_container_name'] regex: '/deepchat.*' # 自动采集DeepChat容器日志 action: keep - source_labels: ['__meta_docker_container_name'] target_label: 'job' replacement: 'deepchat-container'

grafana-datasources.yaml（数据源配置）：

apiVersion: 1 datasources: - name: Loki type: loki access: proxy url: http://loki:3100 isDefault: true

grafana-dashboards.yaml（仪表盘配置）：

apiVersion: 1 providers: - name: 'DeepChat Dashboards' orgId: 1 folder: '' type: file disableDeletion: false updateIntervalSeconds: 10 options: path: /var/lib/grafana/dashboards

最后，创建一个空目录dashboards/，用于存放后续导入的仪表盘。

3.3 启动监控栈并验证

在deepchat-monitoring目录下，执行：

docker-compose up -d

等待约30秒，检查服务状态：

docker-compose ps # 应看到 loki、promtail、grafana 三者状态均为 "Up"

打开浏览器，访问http://localhost:3000，使用用户名admin和密码admin登录（首次登录会提示修改密码，可跳过）。

进入Configuration → Data Sources，确认Loki数据源状态为Green (Working)。

至此，监控底座已就绪。下一步，就是让DeepChat的日志真正流动起来。

4. 让DeepChat日志“说话”：日志采集实战

4.1 DeepChat日志在哪里？怎么让它写出来

DeepChat镜像默认不主动输出结构化日志，这是它“简洁”的一部分，却也是监控的最大障碍。我们必须温和地引导它。

幸运的是，DeepChat WebUI基于Python，我们无需修改源码，只需在启动时添加两行环境变量，即可开启详细日志：

• LOG_LEVEL=INFO：让WebUI输出请求、响应、错误等关键事件
• LOG_FILE=/var/log/deepchat/webui.log：指定日志写入位置，与Promtail配置中的路径严格对应

具体操作取决于你如何启动DeepChat。如果你使用CSDN星图镜像广场的一键部署，通常可在“环境变量”设置区域添加：

LOG_LEVEL=INFO LOG_FILE=/var/log/deepchat/webui.log

同时，确保宿主机上存在该目录：

sudo mkdir -p /var/log/deepchat sudo chmod 755 /var/log/deepchat

为什么是/var/log/deepchat/？
因为Promtail配置中指定了__path__: /var/log/deepchat/*.log，且通过-v /var/log:/var/log将宿主机/var/log挂载进了Promtail容器。这样，DeepChat容器内写的日志，会实时出现在宿主机的/var/log/deepchat/下，Promtail就能立刻采集。

4.2 Ollama服务日志：自动捕获与关键字段提取

Ollama服务本身会将日志输出到标准输出（stdout），而Docker会自动将其收集为容器日志。Promtail的docker_sd_configs配置正是为此而设。

但原始Docker日志是纯文本，缺乏结构。我们需要从中提取最有价值的字段：请求路径、状态码、耗时、错误信息。

在promtail-config.yaml中，我们已配置了job: deepchat-container来采集DeepChat容器日志。现在，为它添加一个简单的解析规则（修改promtail-config.yaml的scrape_configs部分）：

- job_name: deepchat-container docker_sd_configs: - host: unix:///var/run/docker.sock refresh_interval: 5s relabel_configs: - source_labels: ['__meta_docker_container_name'] regex: '/deepchat.*' action: keep - source_labels: ['__meta_docker_container_name'] target_label: 'job' replacement: 'deepchat-container' pipeline_stages: - docker: {} - labels: status_code: "" duration_ms: "" - regex: expression: 'status=(?P<status_code>\d+) duration=(?P<duration_ms>\d+\.?\d*)ms' - labels: status_code: "" duration_ms: ""

这个配置的作用是：当Promtail读取到类似... status=200 duration=1245.67ms ...的日志行时，会自动提取出status_code和duration_ms两个标签，并作为元数据随日志一起发送给Loki。后续在Grafana中，你就可以按状态码筛选日志，或计算平均响应时间。

4.3 实时验证日志是否成功流入

部署完成后，立即进行验证：

1. 在浏览器中打开DeepChat界面，发送一条消息，例如Hello, what's your name?

2. 在终端中，执行以下命令，查看Loki是否收到了日志：

   # 查询最近10分钟内，job为deepchat-webui的日志 curl "http://localhost:3100/loki/api/v1/query_range?query={job=%22deepchat-webui%22}&limit=10&direction=FORWARD&start=$(date -d '10 minutes ago' +%s%N | sed 's/......$//')"

   如果返回JSON中包含"streams"且有日志条目，说明采集成功。

3. 更直观的方式：登录Grafana (http://localhost:3000)，点击左侧Explore图标（放大镜），在数据源选择Loki，在查询框输入：

   {job="deepchat-webui"}

   点击Run query，你应该能看到刚刚的聊天请求日志，格式清晰，时间戳准确。

日志活了，监控就成功了一半。

5. 构建专属DeepChat监控仪表盘

5.1 导入预置仪表盘（5分钟搞定）

我们为你准备了一个开箱即用的DeepChat监控仪表盘，涵盖所有核心关注点。下载地址：deepchat-dashboard.json（注：此为示例链接，实际使用时请从CSDN星图镜像广场文档页获取最新版）

在Grafana中操作：

• 点击左上角+→Import
• 粘贴JSON内容，或拖拽JSON文件
• 确认数据源为Loki
• 点击Import

仪表盘将自动创建，包含以下核心视图：

• 全局概览面板：显示当前DeepChat和Ollama服务的总体健康状态（绿色=正常，红色=异常）
• 请求速率与错误率：每分钟请求数（RPS）和HTTP错误率（4xx/5xx），曲线图一目了然
• 响应时间分布：P50/P90/P99延迟，帮你判断是否存在慢请求拖累整体体验
• 实时日志流：滚动显示最新日志，支持关键词搜索（如error,timeout,model not found）
• Ollama模型状态：显示当前加载的模型名称、GPU显存占用、推理队列长度

5.2 关键告警规则：让系统替你盯梢

仪表盘是“看”，告警是“喊”。我们配置两条最实用的告警：

告警1：Ollama服务宕机

• 条件：过去2分钟内，{job="ollama-service"}日志条数为0
• 通知：Grafana内置邮件或企业微信（需在Alerting中配置）
• 意义：Ollama进程意外退出，DeepChat将彻底无法工作，必须立即干预。

告警2：DeepChat高错误率

• 条件：过去5分钟内，{job="deepchat-webui"} | json | status_code =~ "5.*"的日志条数 > 10
• 通知：同上
• 意义：WebUI内部出现严重错误（如数据库连接失败、Ollama API调用超时），用户将看到500错误页。

在Grafana中创建告警的路径：Alerting → Alert rules → Create alert rule。粘贴上述PromQL表达式，设置阈值和通知渠道即可。

这两条告警，足以覆盖90%的线上紧急故障。

5.3 一个真实排障案例：揭秘“提问无响应”

上周，我们的DeepChat服务出现用户反馈：“提问后光标一直闪烁，就是不回复”。仪表盘显示一切正常——RPS平稳，错误率为0，延迟P99也仅1.2秒。

我们切换到Explore，输入：

{job="deepchat-container"} |~ "stream|chunk"

（查找包含流式响应关键词的日志）

结果发现大量日志：

level=error msg="Failed to stream response from Ollama" error="context deadline exceeded"

再查Ollama日志：

{job="ollama-service"} |~ "timeout"

得到：

time="2024-05-20T08:15:22Z" level=error msg="request timeout" model="llama3:8b" duration="120.000s"

结论清晰：Ollama推理超时（120秒），原因很可能是GPU显存不足，导致模型加载缓慢或推理卡顿。我们立刻检查nvidia-smi，发现显存已被另一个训练任务占满98%。杀掉无关进程后，服务瞬间恢复。

没有这套监控，我们可能要花数小时去翻查零散日志，甚至怀疑是网络或代码问题。而有了它，5分钟定位根因。

6. 总结：让AI服务从“黑盒”走向“透明”

回顾整个过程，我们没有修改DeepChat一行代码，没有安装复杂代理，也没有引入外部依赖。仅仅通过：

• 两行环境变量（LOG_LEVEL,LOG_FILE）激活日志
• 一个轻量的docker-compose.yml定义监控栈
• 一份精准的promtail-config.yaml引导日志流向
• 一个预置的Grafana仪表盘呈现数据

就将一个原本“不可见、不可知、不可控”的本地AI对话服务，变成了一个完全透明、可量化、可预测的生产级组件。

这带来的价值是实实在在的：

• 排障时间从小时级降至分钟级：不再靠猜，靠数据说话
• 服务稳定性显著提升：告警提前预警，避免用户投诉
• 资源优化有据可依：通过GPU显存、CPU负载指标，精准扩容或缩容
• 团队协作更高效：运维看指标，开发看日志，产品看用户请求模式，所有人在同一套数据语言下沟通

DeepChat的核心价值在于“私密”与“深度”，而可观测性，则是守护这份价值的隐形盾牌。它不改变服务本身，却让服务变得更可靠、更值得信赖。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。