Langchain-Chatchat与Prometheus+Grafana监控栈集成实践

Langchain-Chatchat 与 Prometheus+Grafana 监控栈集成实践

在企业级 AI 应用日益普及的今天，一个核心矛盾逐渐凸显：我们渴望智能问答系统的便捷高效，却又不得不面对数据隐私与系统稳定性的严峻挑战。尤其是金融、医疗和政务等高合规性行业，任何潜在的数据外泄风险都可能带来不可逆的后果。于是，越来越多组织开始将目光转向本地化部署的知识库系统——既能享受大模型带来的智能化红利，又能牢牢掌控数据主权。

Langchain-Chatchat 正是在这一背景下脱颖而出的开源方案。它基于 LangChain 框架构建，支持将 PDF、Word 等私有文档转化为可检索的知识源，并通过本地大语言模型（如 ChatGLM、Qwen）实现离线智能问答。然而，功能实现只是第一步。当系统真正投入生产环境后，运维团队很快会面临新的难题：如何判断服务是否健康？为什么某次查询突然变慢？是向量检索拖了后腿，还是模型推理出现了瓶颈？

这些问题指向了一个常被忽视的关键环节——可观测性。没有监控的 AI 系统就像一辆没有仪表盘的汽车，即便引擎轰鸣，你也无法知道油量还剩多少、水温是否异常。为此，我们将 Prometheus 与 Grafana 引入 Langchain-Chatchat 的技术栈中，打造一套完整的“采集—存储—可视化”监控闭环。

构建本地知识库问答系统的核心逻辑

Langchain-Chatchat 的本质是一个典型的 RAG（Retrieval-Augmented Generation）架构，其工作流程贯穿了从原始文档到自然语言回答的完整链条。整个过程可以拆解为五个关键阶段：

首先是文档加载与解析。用户上传 PDF 或 DOCX 文件后，系统调用 PyPDF2、python-docx 等解析器提取纯文本内容。这一步看似简单，实则暗藏坑点——比如扫描版 PDF 的 OCR 处理、表格结构丢失等问题都会影响后续质量。

接着是文本分块。长篇幅的技术手册或制度文件必须切分为语义连贯的小段落（chunks），否则嵌入模型难以有效编码。通常采用RecursiveCharacterTextSplitter按字符长度分割，同时设置重叠区域以保留上下文连续性。这个参数的选择非常讲究：chunk_size 太小会导致信息不完整，太大则降低检索精度。实践中建议结合业务场景测试调整，中文文档一般取 300~600 字符较为合适。

第三步是向量化嵌入。这是整个流程中最耗资源的环节之一。系统使用 BGE、text2vec 等中文优化的嵌入模型，将每个文本块转换为高维向量，并存入 FAISS 或 Chroma 这类向量数据库。值得注意的是，嵌入模型本身也可以本地运行，避免敏感文本上传至第三方 API。

当用户提问时，问题同样被编码为向量，在向量空间中进行近似最近邻搜索（ANN），找出最相关的几个文本片段。最后，这些相关片段作为上下文注入提示词（prompt），连同原始问题一起送入 LLM 生成最终答案。

下面这段代码浓缩了上述核心逻辑：

from langchain.document_loaders import PyPDFLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain.embeddings import HuggingFaceEmbeddings from langchain.vectorstores import FAISS from langchain.chains import RetrievalQA from langchain.llms import ChatGLM # 1. 加载PDF文档 loader = PyPDFLoader("knowledge.pdf") pages = loader.load_and_split() # 2. 文本分块 splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50) docs = splitter.split_documents(pages) # 3. 向量化并存入FAISS embeddings = HuggingFaceEmbeddings(model_name="BAAI/bge-large-zh") db = FAISS.from_documents(docs, embeddings) # 4. 构建检索式问答链 llm = ChatGLM(endpoint_url="http://localhost:8000") qa_chain = RetrievalQA.from_chain_type(llm, retriever=db.as_retriever()) # 5. 执行查询 query = "公司年假政策是什么？" result = qa_chain.run(query) print(result)

这套流程高度模块化，各组件均可替换。例如你可以换成不同的 Splitter 实现按句子或段落切分，也可以接入 Milvus 替代 FAISS 以支持更大规模的向量检索。这种灵活性正是 LangChain 生态的魅力所在。

但这也带来了新的挑战：随着组件增多、链路拉长，性能瓶颈可能出现在任意一环。你很难仅凭日志判断“响应慢”到底是分块耗时、向量化延迟，还是模型推理卡顿。这就引出了我们对精细化监控的需求。

如何让 AI 系统“看得见”

要实现真正的可观测性，光有功能还不够，必须让系统的每一个动作都能留下痕迹。Prometheus + Grafana 组合之所以成为云原生时代的监控标配，就在于它提供了一套简洁而强大的指标采集与展示机制。

Prometheus 采用主动拉取模式，定期从目标应用的/metrics接口抓取数据。这意味着我们需要在 Langchain-Chatchat 的 Web 服务中暴露这些指标。假设系统使用 Flask 提供接口，可以通过prometheus_client库轻松实现：

from flask import Flask, request, jsonify from prometheus_client import Counter, Histogram, generate_latest, CONTENT_TYPE_LATEST import time app = Flask(__name__) # 定义核心监控指标 REQUEST_COUNT = Counter( 'chatchat_requests_total', 'Total number of Chat requests', ['method', 'endpoint', 'status'] ) LATENCY_HISTOGRAM = Histogram( 'chatchat_request_duration_seconds', 'Latency of Chat requests', ['endpoint'], buckets=[0.1, 0.5, 1.0, 2.5, 5.0, 10.0] ) @app.route("/ask", methods=["POST"]) def ask(): start_time = time.time() try: result = qa_chain.run(request.json["question"]) duration = time.time() - start_time LATENCY_HISTOGRAM.labels(endpoint="/ask").observe(duration) REQUEST_COUNT.labels(method="POST", endpoint="/ask", status="200").inc() return jsonify({"answer": result}) except Exception as e: duration = time.time() - start_time LATENCY_HISTOGRAM.labels(endpoint="/ask").observe(duration) REQUEST_COUNT.labels(method="POST", endpoint="/ask", status="500").inc() return jsonify({"error": str(e)}), 500 @app.route("/metrics") def metrics(): return generate_latest(), 200, {'Content-Type': CONTENT_TYPE_LATEST}

这里定义了两个关键指标：

• chatchat_requests_total是一个带标签的计数器，记录不同状态码下的请求数量，可用于计算错误率和服务可用性。
• chatchat_request_duration_seconds是直方图类型指标，不仅能反映平均延迟，还能分析 P95/P99 分位值，帮助识别尾部延迟问题。

一旦暴露了/metrics接口，剩下的事情就交给 Prometheus。只需在其配置文件中添加一个 job：

scrape_configs: - job_name: 'langchain-chatchat' static_configs: - targets: ['<your-server-ip>:5000']

Prometheus 就会每隔 15 秒自动拉取一次指标，写入本地时间序列数据库（TSDB）。随后，Grafana 可连接该数据源，实时查询并渲染图表。

从指标到洞察：构建实用监控视图

很多人以为监控就是“画几张图”，但实际上，真正有价值的仪表盘应该能引导运维人员快速定位问题。我们在 Grafana 中设计了几类关键面板：

首先是整体健康概览。顶部放一个大数字面板，显示过去 5 分钟内的请求成功率（rate(chatchat_requests_total{status="200"}[5m]) / rate(chatchat_requests_total[5m])），下方辅以折线图展示 QPS 趋势。一旦成功率跌破阈值，立刻触发告警。

其次是延迟分布分析。使用直方图指标，我们可以绘制出请求耗时的累积分布曲线，甚至叠加 P50/P95/P99 标记线。如果发现 P99 延迟陡增而平均值变化不大，说明存在偶发性长尾请求，可能是某些复杂问题导致模型反复重试。

再者是资源关联分析。单独看应用指标还不够，必须结合主机层面的数据。通过部署 Node Exporter，我们可以采集 CPU 使用率、内存占用、磁盘 IO 等系统指标。当发现问答延迟上升时，查看同一时间段的内存使用情况，若两者同步飙升，则很可能是嵌入模型加载过大导致频繁 GC 或交换分区激活。

更进一步，还可以为不同模块打上细粒度标签。例如在向量化阶段记录embedding_duration_seconds，在检索阶段记录retrieval_top_k_latency，从而精确判断瓶颈所在。曾有一次我们发现整体响应时间波动剧烈，经排查竟是因为向量数据库未建立索引，导致每次 ANN 搜索都要全表扫描。正是通过细分指标才得以快速定位。

当然，在实施过程中也有不少经验教训值得分享：

• 采样频率不能一刀切：对于高频访问的生产系统，15 秒抓取间隔可能导致漏掉瞬时高峰。可适当缩短至 5 秒，但需评估存储成本。
• 警惕标签爆炸（Cardinality Explosion）：不要把用户 ID、完整 URL 这类高基数字段作为标签，否则时间序列数量会指数级增长，拖垮 Prometheus 性能。
• 保护/metrics接口安全：该端点可能暴露内部调用路径和错误统计，应通过反向代理加身份验证，或限制内网访问。
• 合理规划数据保留周期：根据业务需求设定 retention period。例如保留 30 天足以应对多数故障回溯，无需无限期存档。

监控不只是“看”，更是“行动”

最终，监控的价值不仅体现在“发现问题”，更在于推动自动化响应。我们通过 Alertmanager 配置了多级告警策略：

• 当连续 3 分钟 P95 延迟超过 3 秒时，发送通知给值班工程师；
• 若错误率持续高于 5%，则升级为电话告警；
• 若主机内存使用率突破 90%，自动触发扩容脚本或重启服务。

此外，还将 Grafana 与企业微信/钉钉集成，关键指标每日早报自动推送，让非技术人员也能掌握系统运行趋势。

这套监控体系上线后，最直观的变化是 MTTR（平均修复时间）显著下降。以前遇到性能问题往往需要人工逐层排查日志，现在打开仪表盘就能看到异常指标源头。有一次凌晨触发告警，值班同事通过延迟曲线和资源图对比，迅速锁定是某次批量导入新文档后未重建向量索引所致，十分钟内完成修复。

更重要的是，它改变了团队的运维思维——从被动救火转向主动预防。基于历史数据，我们开始做容量预测：当前硬件条件下最多支撑多少并发？若业务增长三倍，是否需要引入 GPU 加速？这些决策背后都有实实在在的数据支撑。

结语

Langchain-Chatchat 解决了“能不能答”的问题，而 Prometheus + Grafana 则回答了“答得怎么样”。两者结合，构建了一个既智能又可靠的本地知识管理系统。

但这只是一个起点。未来我们可以在此基础上探索更多可能性：比如结合 OpenTelemetry 实现分布式追踪，深入剖析每一轮问答的内部调用链；或者利用 PromQL 做 A/B 测试效果对比，科学评估不同嵌入模型对准确率的影响；甚至接入 Kubernetes 实现自动扩缩容，让系统随负载动态伸缩。

技术的本质不是炫技，而是服务于真实场景。在一个越来越强调数据安全与系统韧性的时代，这样的组合或许正代表了下一代企业级 AI 应用的发展方向：不仅聪明，而且稳健；不仅可用，而且可信。