深入浅出RAG——第19章:RAG 系统监控与可观测性

5 阅读24分钟

📖 本章学习目标

  • 用 OpenTelemetry 实现 RAG 请求的全链路追踪,定位每个阶段的耗时
  • 定义和采集 RAG 系统的核心 Prometheus 指标,包括检索质量、生成质量和 Token 消耗
  • 搭建用户反馈收集 API 并建立从反馈到改进的闭环工作流
  • 基于系统运行基线设计告警规则,避免硬编码阈值的误报

《第18章:生产环境部署》在部署检查清单中提到了监控告警,之所以没有展开是因为监控是一个独立的话题,值得独立写一篇文章来讨论。部署是让系统跑起来,监控则是让系统持续跑好。这是一个从部署上线到持续感知的过程。

RAG 系统的监控比普通 Web 服务更复杂。一个 REST API 只需要关注 HTTP 状态码和响应延迟,而 RAG 请求还涉及检索是否找到了正确文档、生成内容是否忠实于来源、Token 消耗是否在预算范围内。这些问题无法通过传统的 CPU 和内存监控来回答,,而是需要一套覆盖检索到生成全链路的可观测性体系。

本章依次介绍 OpenTelemetry 全链路追踪、Prometheus 业务指标采集、用户反馈闭环和告警机制,最后简要讨论 LangSmith 在 LLM 调用层面的补充作用。

一、可观测性的三个维度

1. Metrics、Logs、Traces 的分工

Metrics、Logs、Traces是可观测性领域有三个核心维度,它们分别处理不同层面的问题。Metrics 回答"发生了什么",它是一段时间内的聚合数据,比如过去五分钟的平均检索延迟和 P95 值。Logs 回答"具体细节是什么",比如某次查询检索到的文档列表和对应的相似度分数。Traces 回答"发生在哪里",它将单次请求在所有组件上的执行路径串联起来,展示每个阶段的时间分布。

graph TD
    A[RAG 可观测性] --> B[Metrics 量化指标]
    A --> C[Logs 事件记录]
    A --> D[Traces 全链路追踪]
    B --> B1[延迟/吞吐/错误率/检索质量/Token 消耗]
    C --> C1[每次检索和生成的结构化日志]
    D --> D1[单次请求在各阶段的耗时与状态]

三者之间的关系是互补的而不是互斥的。当你收到一条告警说检索延迟 P95 飙升到某个阈值,你会先看 Metrics 确认趋势,然后用 Traces 找到是哪个阶段变慢,最后用 Logs 查看那次慢请求的具体参数和返回内容。三者组合起来才能形成完整的问题定位链路,单独依赖任何一维都会留下盲区。

二、全链路追踪

1. 初始化 OpenTelemetry

OpenTelemetry(简称 OTel)是一个中立于厂商的可观测性框架,由 CNCF 托管。它不负责存储和展示数据,而是定义了一套统一的 API 和协议(OTLP),让你的代码只需要埋点一次,就可以把 Trace、Metric、Log 同时导出到任意兼容的后端(Jaeger、Zipkin、Grafana Tempo、Datadog 等)。可以把 OpenTelemetry 理解为"数据采集层",后端系统是"数据存储和展示层"。

在 RAG 系统中使用它,主要目标是让每一次查询请求的完整执行路径可视化。下面先初始化 SDK 并创建 Tracer 实例。

import { trace } from "@opentelemetry/api";
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";

// 创建 SDK 实例,通过 OTLP 协议将 Trace 数据导出到 Jaeger/Zipkin
const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: "http://localhost:4318/v1/traces", // 可观测后端的接收地址
  }),
});

sdk.start(); // 启动后所有自动埋点开始工作
const tracer = trace.getTracer("rag-service"); // 创建一个归属本服务的 Tracer

导出器的 URL 在示例中指向 Jaeger 或 Zipkin 地址,生产环境中应替换为实际的可观测性后端地址,如 Grafana Tempo 或 Datadog。

Jaeger 和 Zipkin 都是开源的分布式追踪系统,用来接收、存储和可视化 OpenTelemetry 发过来的 Trace 数据。

2. 在 RAG 请求中注入追踪

核心思路是将一次 RAG 请求包裹在一个名为 rag-request 的父级 Span 中,检索、Prompt 组装和 LLM 生成各为一个子 Span。每个 Span 记录起止时间和关键属性,比如检索返回的文档数量、生成阶段的 Token 估算值。

下面的代码拆分为函数签名、检索和 Prompt 组装、生成与错误处理三个部分。

import { SpanStatusCode } from "@opentelemetry/api";

async function ragWithTracing(query: string): Promise<string> {
  return tracer.startActiveSpan("rag-request", async (span) => {
    // 将查询元信息设为 Span 属性,方便在 UI 中检索
    span.setAttribute("query.length", query.length);
    const startTime = Date.now();

    try {

检索子 Span 记录了查询耗时和返回的文档数量,这两个数据后续可以用于分析检索环节是否正常。

      // 为"检索"阶段创建一个子 Span,与父 Span 自动关联
      const docs = await tracer.startActiveSpan(
        "retrieval",
        async (retrievalSpan) => {
          const retrieveStart = Date.now();
          const docs = await retriever.invoke(query);

          retrievalSpan.setAttribute("docs.count", docs.length); // 返回文档数
          retrievalSpan.setAttribute(
            "retrieval.time_ms",
            Date.now() - retrieveStart
          );
          retrievalSpan.end(); // 子 Span 需要手动结束,耗时统计到此为止
          return docs;
        }
      );

Prompt 组装子 Span 记录了拼接后 Prompt 的长度,这个值与 Token 消耗直接相关。

      const prompt = await tracer.startActiveSpan(
        "prompt-assembly",
        async (promptSpan) => {
          const start = Date.now();
          const prompt = buildPrompt(query, docs);
          promptSpan.setAttribute("prompt.length", prompt.length); // Prompt 长度与 Token 消耗正相关
          promptSpan.setAttribute("prompt.time_ms", Date.now() - start);
          promptSpan.end();
          return prompt;
        }
      );

生成子 Span 记录了输入 Token 和输出 Token 的估算值,以及生成耗时。

      const answer = await tracer.startActiveSpan(
        "generation",
        async (genSpan) => {
          const start = Date.now();
          const answer = await llm.invoke(prompt);
          const elapsed = Date.now() - start;
          genSpan.setAttribute("generation.time_ms", elapsed);
          // estimateTokens 可以用 tiktoken 等库实现,在创建 Span 时就统计好
          genSpan.setAttribute("tokens.input", estimateTokens(prompt));
          genSpan.setAttribute(
            "tokens.output",
            estimateTokens(answer.content as string)
          );
          genSpan.end();
          return answer.content as string;
        }
      );

      span.setAttribute("total.time_ms", Date.now() - startTime);
      span.setStatus({ code: SpanStatusCode.OK }); // 标记请求成功,UI 中显示绿色
      return answer;

错误处理需要同时设置 Span 状态并记录异常对象,这样在 Jaeger 等 UI 中可以直接看到哪些请求失败了以及失败原因。

    } catch (error) {
      // 将错误信息写入 Span,在 Jaeger 中可以直接看到异常详情
      span.setStatus({
        code: SpanStatusCode.ERROR,
        message: error instanceof Error ? error.message : "Unknown error",
      });
      span.recordException(error); // 记录完整异常对象,包含堆栈信息
      throw error; // 继续向上抛出,由上层中间件统一处理
    } finally {
      span.end(); // finally 确保无论如何 Span 都会关闭,不会产生"僵尸 Span"
    }
  });
}

每个 Span 的时间属性不需要手动计算起止差,如果你直接使用 startActiveSpan 配合自动时间戳,OpenTelemetry 的 SDK 会记录 Span 的起止时刻,后端 UI 可以据此绘制火焰图。这里的显式计时是为了同时将耗时作为 Span 属性暴露出来,方便在 Metrics 查询侧直接使用。

3. 集成到 Express 中间件

应用层面的 Span 覆盖了 RAG 业务逻辑,但 HTTP 请求的入口需要额外的中间件来创建 Trace 的根 Span。@opentelemetry/instrumentation-express 会在每个 HTTP 请求到达时自动创建 Span,并在响应返回时结束它。

import { expressMiddleware } from "@opentelemetry/instrumentation-express";

// 将中间件挂载到 Express 实例,每个 HTTP 请求自动生成一个根 Span
app.use(
  expressMiddleware({
    requestHook: (span, info) => {
      // 在请求到达时向 Span 写入 HTTP 方法、URL 等元信息
      span.setAttribute("http.method", info.request.method);
      span.setAttribute("http.url", info.request.url);
    },
  })
);

这个中间件创建的 Span 会成为 rag-request 的父级,二者组合在一起构成完整的调用链。在 Jaeger UI 中看到的结构是这样的:HTTP 请求 Span 作为顶层,内部包含 rag-request 及其子 Span。

4. 解读追踪数据

追踪数据本身不给出优化建议,但它能帮你精确回答一个 RAG 请求的时间到底花在哪里。如果 retrieval Span 的耗时突然增加了两倍,说明向量数据库的索引或网络出问题了。如果 generation Span 的 Input Token 明显比以前多,检查是否有冗余文档进入了检索结果。Span 属性的价值在于把推测变成可验证的假设。

三、业务指标采集

1. 核心指标分类

Prometheus 是一个开源的监控与时序数据库,通过定期拉取(scrape)应用暴露的 /metrics 端点来采集指标数据。它不推送、不埋点,应用只管暴露当前状态,Prometheus 负责定时来取。本章使用 prom-client 这个 Node.js 库来定义指标和暴露端点。

Prometheus 的系统层面指标(CPU、内存)不能反映 RAG 系统的业务健康状况。一个 CPU 使用率正常但检索结果全为空的系统,对用户来说就是不可用的。RAG 业务指标可以分为四个维度,用 Prometheus 的不同指标类型来承载。

检索维度的指标类型说明和定义如下。

import { Counter, Histogram, Gauge } from "prom-client";
// Counter: 只增不减的累计值,适合统计"发生过多少次"
// Histogram: 按区间(buckets)统计分布,适合延迟和大小这类有波动的数据
// Gauge: 可增可减的瞬时值,适合统计"当前有多少"

// 检索无结果次数 —— Counter,每次检索为空时 +1
const retrievalNoResults = new Counter({
  name: "rag_retrieval_no_results_total",
  help: "检索返回零结果的次数",
  labelNames: ["tenant_id"], // 按租户维度区分,方便多租户场景下独立统计
});

// 检索延迟分布 —— Histogram,buckets 定义了延时区间的划分粒度
const retrievalLatency = new Histogram({
  name: "rag_retrieval_latency_ms",
  help: "检索阶段延迟",
  buckets: [5, 10, 25, 50, 100, 200, 500],
  labelNames: ["strategy"], // 区分不同检索策略(dense/hybrid/sparse)的性能表现
});

生成维度和 Token 消耗维度用 Histogram 记录延迟分布和每次查询的 Token 消耗。

// 生成阶段延迟 —— 按模型区分,便于对比不同 LLM 的响应速度
const generationLatency = new Histogram({
  name: "rag_generation_latency_ms",
  help: "生成阶段延迟",
  buckets: [100, 500, 1000, 2000, 5000, 10000],
  labelNames: ["model"], // 如 claude-sonnet-5、claude-haiku-4-5
});

// 单次查询的 Token 消耗 —— 统计 Input + Output 的总量
const tokensPerQuery = new Histogram({
  name: "rag_tokens_per_query",
  help: "每次查询的总 Token 消耗",
  buckets: [100, 500, 1000, 2000, 5000, 10000],
});

用户反馈和质量维度的指标使用 Counter 和 Histogram 记录幻觉标记次数与用户满意度分布。

// 幻觉标记次数 —— Counter,累计被用户标记为"内容有误"的次数
const hallucinationFlagged = new Counter({
  name: "rag_hallucination_flagged_total",
  help: "被用户反馈标记为幻觉的次数",
  labelNames: ["query_id"],
});

// 用户满意度分布 —— Histogram,buckets 1~5 对应五星评分
const userSatisfaction = new Histogram({
  name: "rag_user_satisfaction_score",
  help: "用户反馈的满意度评分",
  buckets: [1, 2, 3, 4, 5],
});

系统健康维度用 Gauge 记录活跃查询数,它反映的是瞬时值而非累计值。

// 活跃查询数 —— Gauge,查询开始时 +1,结束时 -1,反映瞬时并发量
const activeQueries = new Gauge({
  name: "rag_active_queries",
  help: "当前正在处理的查询数量",
});

以上指标覆盖了检索质量、生成质量、Token 消耗和系统健康四个维度。Histogram 的 buckets 值需要根据自己系统的实际延迟分布调整,示例中的分桶数值只是起点而非推荐值。Counter 适合累计型数据(错误次数、幻觉标记次数),Histogram 适合分布型数据(延迟、Token 数),Gauge 适合瞬时状态(当前活跃查询数)。

2. 指标采集与暴露

在每次 RAG 查询中采集上述指标,并在 /metrics 端点暴露给 Prometheus 拉取。

查询函数的核心逻辑是每次调用时递增活跃查询数、记录各阶段耗时和 Token 消耗、在结束或出错时递减活跃查询数。

async function ragWithMetrics(
  query: string,
  tenantId: string
): Promise<string> {
  activeQueries.inc(); // 查询开始:并发数 +1

  try {
    const retrieveStart = Date.now();
    const docs = await retriever.invoke(query);
    retrievalLatency.observe(
      { strategy: "dense" }, // 按检索策略打标签
      Date.now() - retrieveStart
    );

    if (docs.length === 0) {
      retrievalNoResults.inc({ tenant_id: tenantId }); // 无结果计数
    }

    const generateStart = Date.now();
    const answer = await generate(query, docs);
    generationLatency.observe(
      { model: "claude-sonnet-5" },
      Date.now() - generateStart
    );

    // Token 消耗 = 输入(Prompt + 文档)+ 输出(生成的答案)
    const totalTokens = estimateTokens(buildPrompt(query, docs))
      + estimateTokens(answer);
    tokensPerQuery.observe(totalTokens);

    return answer;
  } finally {
    activeQueries.dec(); // 查询结束:并发数 -1(出错时也执行)
  }
}

暴露 /metrics 端点的代码非常简短。Express 中只需设置正确的 Content-Type 并返回 register.metrics() 的结果即可。

import { register } from "prom-client";

// 暴露 /metrics 端点供 Prometheus 定时拉取(scrape)
app.get("/metrics", async (_req, res) => {
  res.set("Content-Type", register.contentType); // Prometheus 要求的文本格式
  res.end(await register.metrics()); // 返回所有已注册指标的当前值
});

Prometheus 每隔一段时间(通常 15 到 60 秒)向 /metrics 端点发起一次拉取,将数据存入时序数据库。随后在 Grafana 中配置 Prometheus 数据源并创建以下面板。

Grafana 是一个开源的可视化平台,本身不存储数据,而是连接到 Prometheus 等数据源,将时序数据渲染为折线图、柱状图、热力图等可配置的面板。它和 Prometheus 的关系类似于前端和后端:Prometheus 负责存储和查询,Grafana 负责展示和告警面板。

面板关注指标用途
检索质量检索无结果率、检索 P50/P95/P99 延迟、返回文档数量分布判断向量数据库是否正常、检索参数是否需要调整
生成质量生成 P50/P95/P99 延迟、按模型分组的延迟对比监控 LLM 调用的性能趋势,发现某类模型的延迟异常
Token 消耗Embedding Token 与 LLM Token 的日消耗趋势、单次查询平均 Token 数跟踪成本变化,识别 Prompt 组装是否引入了冗余上下文
用户反馈满意度评分分布、幻觉标记累计次数、正面与负面反馈占比从用户视角评估答案质量,发现系统性的内容准确性问题
系统健康活跃查询数、错误率、QPS(每秒查询数)监控整体负载和可用性,判断是否需要扩容或限流

前三个面板关注系统内部运行状态,后两个面板关注用户体验和系统可用性。不需要一次全部建完,从检索质量和生成质量两个面板开始即可,它们覆盖了 RAG 请求的两个关键环节。

四、用户反馈闭环

1. 反馈收集 API

自动化指标能告诉你系统是否正常,但不能告诉你答案是否好用。用户点赞或点踩是对答案质量的直接判断,被标记为幻觉的回答则需要立即审查。这些反馈数据是补充自动化评估的最重要信号。

反馈接口的请求体定义和提交处理逻辑如下。输入校验排除缺少必要字段和评分超出范围的请求。

interface FeedbackData {
  queryId: string;         // 关联到某次具体查询
  rating: number;          // 1~5 分
  comment?: string;        // 可选的文字评价
  hallucination?: boolean; // 是否标记为幻觉/内容有误
}

app.post("/feedback", async (req, res) => {
  const feedback: FeedbackData = req.body;

  // 输入校验:必填字段和取值范围
  if (!feedback.queryId || !feedback.rating) {
    return res.status(400).json({ error: "缺少必要字段" });
  }
  if (feedback.rating < 1 || feedback.rating > 5) {
    return res.status(400).json({ error: "评分必须在 1-5 之间" });
  }

校验通过后将反馈数据写入数据库,同时更新 Prometheus 指标。

  try {
    // 写入数据库,保留完整反馈记录用于离线分析
    await db.insert("feedback", {
      query_id: feedback.queryId,
      rating: feedback.rating,
      comment: feedback.comment || null,
      hallucination: feedback.hallucination || false,
      timestamp: new Date(),
    });

    // 同步更新 Prometheus 指标,用于实时告警和 Grafana 面板
    userSatisfaction.observe(feedback.rating);
    if (feedback.hallucination) {
      hallucinationFlagged.inc({ query_id: feedback.queryId });
    }

    res.json({ status: "ok" });
  } catch (error) {
    res.status(500).json({ error: "保存失败" });
  }
});

前端展示反馈按钮时,每条回答附带一个 queryId,用户点击即可提交评分。下面是一个 React 组件示例,展示了点赞、点踩和标记幻觉三个操作的最小实现。

function FeedbackBar({ queryId }: { queryId: string }) {
  const [submitted, setSubmitted] = useState(false);

  const sendFeedback = async (
    rating: number,
    hallucination: boolean = false
  ) => {
    await fetch("/feedback", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ queryId, rating, hallucination }),
    });
    setSubmitted(true); // 提交后隐藏按钮,避免重复提交
  };

  if (submitted) return <span>已收到反馈,感谢</span>;

  return (
    <div className="feedback-bar">
      <button onClick={() => sendFeedback(5)}>有用</button>
      <button onClick={() => sendFeedback(1)}>无用</button>
      <button onClick={() => sendFeedback(2, true)}>内容有误</button>
    </div>
  );
}

对于标记为幻觉的回答,生产环境中建议同时保存当前检索到的文档列表和完整生成结果,方便后续回溯分析 API 返回的内容与知识库来源之间的差异。

除了收集反馈,还需要一个统计接口来查看整体趋势。下面这个端点按周汇总评分分布和幻觉标记数量。

app.get("/feedback/stats", async (_req, res) => {
  const stats = await db.query(`
    SELECT
      COUNT(*) as total,
      AVG(rating) as avg_rating,
      SUM(CASE WHEN rating >= 4 THEN 1 ELSE 0 END) as positive,   -- 高分(4~5)
      SUM(CASE WHEN rating <= 2 THEN 1 ELSE 0 END) as negative,   -- 低分(1~2)
      SUM(CASE WHEN hallucination THEN 1 ELSE 0 END) as hallucination
    FROM feedback
    WHERE timestamp >= NOW() - INTERVAL '7 days'  -- 只看最近一周
  `);
  res.json(stats);
});

这两个接口组合起来形成了反馈数据流的入口和出口:POST /feedback 负责采集,GET /feedback/stats 负责汇总。

2. 从反馈到改进

反馈数据的关键价值不在于展示统计数字,而在于驱动改进。按以下流程建立闭环。

graph LR
    A[用户提交反馈] --> B[存储到数据库并更新指标]
    B --> C{低分反馈}
    C -->|是| D[加入待审查队列]
    C -->|否| E[归档]
    D --> F[开发者审查]
    F --> G{确实存在问题}
    G -->|是| H[加入评估集]
    G -->|否| E
    H --> I[分析根因并优化]
    I --> J[部署新版本]
    J --> K[对比前后指标]

具体执行的五个步骤是:

**(1)**每轮对话附带唯一的 queryId,前端展示评分按钮。

**(2)**低分回答自动汇总到审查队列,触发开发者排查。

**(3)**被标记为幻觉的回答连同检索结果一起保存,作为 《第12章:RAG 系统评估与指标体系》 评估集的补充样本。

**(4)**按周汇总低分反馈,归纳共性问题:某类问题总是答不好说明 Prompt 需要调整,某个主题检索不到说明知识库需要补充,某种查询格式识别不了说明查询改写逻辑需要改进。

**(5)**将验证后的问题转化为具体的优化任务,排入下一轮迭代。

反馈率低是常态,即使只有百分之一到百分之五的用户参与了反馈,累积的数据量也足以识趋势。关键是降低反馈的操作成本,一键点赞或点踩的参与率远高于要求用户填写文字评论。

五、告警机制

1. 告警规则的设计原则

告警规则不是在系统上线第一天就应该定义好的,因为那时候你还没有任何基线数据。建议先让系统运行一到两周,积累真实的 P50、P95、P99 延迟分布和错误率基线,再基于这些数据确定告警阈值。

告警条件的设计有两条核心原则。第一,基于相对变化而非绝对阈值。如果检索延迟的 P95 在过去 24 小时内稳定在某个值附近,突然增长了 50%,即使绝对值还在外界认为合理的范围内,也应该触发告警。第二,区分严重程度。检索无结果率上升通常说明知识库覆盖不足,属于需要关注但不至于半夜叫醒人的警告级别。LLM API 的大面积错误直接影响所有用户的查询结果,属于需要立即响应的严重级别。

下面是一组告警规则的表述方式,不包含具体数值,数值需要在建立了自己的基线后填入。

指标触发条件严重程度响应动作
检索无结果率超过自身基线阈值,持续 5 分钟以上警告检查知识库覆盖和检索参数
检索 P99 延迟环比增长超过基线的一定比例警告检查向量数据库负载和索引质量
生成 P99 延迟环比增长超过基线的一定比例严重检查 LLM API 状态和服务端负载
LLM 调用错误率超过基线的一定比例,持续 1 分钟以上严重考虑切换到备用模型
用户负面反馈率周期性统计中显著上升警告审查近期低分回答的共性问题
幻觉标记次数小时级累计超出基线严重检查最近生成的答案和 Prompt

这里的"超过基线的一定比例"和"持续 X 分钟"是设计框架而不是具体数字。一套告警配置在知识库规模为 1000 篇文档的环境中合理,换到 10 万篇文档的环境中可能完全不同。

2. 告警检查的实现

告警检查的核心是一个定期任务,从 Prometheus 或数据库中拉取指标当前值,与配置的阈值对比后决定是否发送告警。

// AlertConfig 的值都应从配置中心或环境变量读取,不要硬编码到代码中
interface AlertConfig {
  warningRetrievalNoResultRate: number;
  criticalGenerationLatencyMs: number;
  criticalHallucinationPerHour: number;
}

async function runAlertChecks(config: AlertConfig): Promise<void> {
  // 检查检索无结果率:从 Prometheus 查询 counter 增量后除以总查询数
  const noResultsRate = await getNoResultsRate();
  if (noResultsRate > config.warningRetrievalNoResultRate) {
    await alertManager.sendAlert({
      severity: "warning",
      metric: "retrieval_no_results_rate",
      value: noResultsRate,
      message: `检索无结果率超过阈值,当前值为 ${(noResultsRate * 100).toFixed(1)}%`,
    });
  }

生成延迟和幻觉标记的检查逻辑类似,只是严重程度和对应的响应动作不同。

  // 检查生成 P99 延迟:从 Histogram 的 _bucket 时序中计算分位值
  const p99Latency = await getP99Latency();
  if (p99Latency > config.criticalGenerationLatencyMs) {
    await alertManager.sendAlert({
      severity: "critical", // 生成延迟直接影响用户体验,用"严重"级别
      metric: "generation_p99_latency",
      value: p99Latency,
      message: `生成 P99 延迟超过阈值,当前值为 ${p99Latency}ms`,
    });
  }

  // 检查幻觉标记:从 Counter 的增量中统计最近一小时的新增次数
  const hallucinationCount = await getHallucinationCount("1h");
  if (hallucinationCount > config.criticalHallucinationPerHour) {
    await alertManager.sendAlert({
      severity: "critical",
      metric: "hallucination_flagged",
      value: hallucinationCount,
      message: `幻觉标记次数小时级超出阈值,当前为 ${hallucinationCount} 次`,
    });
  }
}

告警通知的渠道取决于团队的工作流,Slack、飞书、邮件或 PagerDuty 都是常见的选项。通知内容应包含指标名称、当前值和阈值、时间戳三项信息,确保接收者不需要切换到监控面板就能判断是否需要立即行动。

六、LangSmith 的补充作用

LangSmith 是 LangChain 团队开发的 LLM 应用可观测性平台,聚焦于 LLM 调用层面的追踪和分析。和 OpenTelemetry 关注全链路延迟不同,LangSmith 关注的是 Prompt 版本演变、同一次输入在不同模型下的输出差异、单次调用的 Token 细节等。

OpenTelemetry 和 Prometheus 覆盖了基础设施和服务层面的可观测性,LangSmith 则聚焦于 LLM 调用层面的追踪,包括 Prompt 版本管理、Token 消耗细化和输出对比。

这两者不是替代关系。OpenTelemetry 告诉你一个 RAG 请求中检索花了多久、生成花了多久,LangSmith 则告诉你这一次 LLM 调用使用了哪个版本的 Prompt、输出内容和之前那次有什么差异。如果你的团队在频繁迭代 Prompt 设计或需要在不同模型之间做 AB 对比,LangSmith 的版本管理和对比能力会很有价值。如果你的团队更关注整体延迟和错误率,OpenTelemetry 的组合已经够用。

集成方式非常简单,只需要在 ChatOpenAI 的 callback 列表中挂载 LangChainTracer。

import { LangChainTracer } from "langchain/callbacks";

// 将 tracer 挂载到 LLM 实例的 callbacks 中
const llm = new ChatOpenAI({
  modelName: "claude-sonnet-5",
  callbacks: [
    new LangChainTracer({
      projectName: "rag-production", // 按项目名称分组,区分生产/测试环境
    }),
  ],
});

配置完成后所有通过这个 LLM 实例发起的调用会自动记录到 LangSmith,无需在业务代码中额外埋点。在 LangSmith UI 中,你可以查看每次调用的完整 Prompt 和输出内容、Token 消耗的详细分布,以及同一组测试用例在不同 Prompt 版本下的表现对比。

FAQ

Q1:OpenTelemetry 和 LangSmith 应该选哪个?

它们覆盖不同层面,不存在"选哪个"的问题。OpenTelemetry 负责全链路追踪,展示检索、组装和生成各阶段的耗时,以及哪个组件出错了。LangSmith 负责 LLM 调用层面的追踪,关注 Prompt 版本演变和单次调用的 Token 细节。两者可以同时接入,各自管理各自的数据。如果预算有限,优先从 OpenTelemetry 开始,因为它覆盖的范围更广,而且 LangSmith 的代码改动量极小,后续接入几乎无成本。

Q2:检索质量的持续监控需要人工标注吗?

趋势监控不需要全量标注。检索无结果率、低相似度分数占比等信号可以从指标中自动提取,用于判断整体趋势。精确的检索质量评估(如 MRR 和 NDCG)需要标注数据,但按周用 RAGAS 跑一次即可,不需要实时计算。如果趋势指标出现了异常波动,再用精确评估确认是假报警还是真问题。

Q3:告警阈值应该如何确定?

没有通用数值,需要在系统稳定运行一到两周后,用自己环境中的 P50、P95 和 P99 作为基线。初次设置可以取基线值的 1.5 倍到 2 倍,运行一段时间后根据误报频率调整。如果一条告警在一周内触发了三次但没有一次对应实际的用户影响,说明阈值过于严格。告警的目的是让正确的人在正确的时间处理真正的问题,而不是让人对告警麻木。

Q4:用户反馈率很低怎么办?

反馈率低是常态,百分之一到百分之五的参与率已属正常范围。提升的方向是将反馈操作简化为一次点击,在用户完成连续多轮查询后主动询问"这些回答对你有帮助吗",或者在产品中展示反馈直接驱动了哪些改进,让用户感知到反馈的价值。即使数据量不大,每一条低分反馈都可能揭示一个系统性问题,更重要的不是追求反馈率,而是对每一条低分反馈都做彻底分析。

练习

练习 1:为你的 RAG 服务添加 Prometheus 指标

集成 prom-client 到你的 RAG 服务中,至少实现检索延迟、生成延迟和检索无结果计数三个指标,并暴露 /metrics 端点。

验证步骤:

  1. curl http://localhost:3000/metrics 确认返回正确的 Prometheus 格式文本
  2. 发送几条查询后再次 curl,观察指标数值的变化是否与查询行为一致
  3. 在本地启动 Grafana(Docker 容器),添加 Prometheus 数据源,创建一个简单的折线图面板

预期结果:/metrics 端点正常暴露指标,Grafana 面板能展示检索延迟和生成延迟的趋势曲线。

练习 2:实现 OpenTelemetry 全链路追踪

参照本章第二节的代码,在你的 RAG 服务中集成 OpenTelemetry,用 Jaeger 可视化每次请求的完整 Span 树。

验证步骤:

  1. 在本地启动 Jaeger(docker run -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one)
  2. 发送一条 RAG 查询请求,访问 Jaeger UI(http://localhost:16686),确认能看到 rag-request 及其子 Span
  3. 检查每个 Span 的属性,确认 retrieval.time_ms、docs.count 等关键字段已记录

预期结果:Jaeger UI 中能看到一次完整 RAG 请求的追踪数据,每个阶段的耗时和关键属性一目了然。

练习 3:实现用户反馈收集并分析数据

在你的服务中添加 /feedback 端点,并在前端(或命令行工具)中加入评分功能。收集 20 条以上反馈后分析数据。

验证步骤:

  1. 提交几条不同评分(包括低分和高分)的反馈,确认数据库中记录完整
  2. 查询 /feedback/stats 接口,检查平均评分和各分数段分布是否正确
  3. 筛选出所有低分回答,检查它们的共同特征(问题类型、检索到的文档、生成内容)

预期结果:能够按查询 ID 关联反馈与原始请求,低分回答的分析结果能为下一步优化提供方向。

练习 4:配置告警规则

基于练习 1 和练习 2 积累的指标数据,为你的系统配置至少三条告警规则,并测试告警能否正常触发。

验证步骤:

  1. 在本地运行一到两天后,从 Prometheus 中导出各指标的 P50、P95、P99 值
  2. 基于基线数据设置告警规则(同时检查相对变化和绝对阈值)
  3. 通过故意触发错误(如暂时停止向量数据库、发送无效查询)验证告警是否能正常发送

预期结果:告警规则基于真实基线数据设定,误报率在可接受范围内,且能在问题确实发生时发出通知。

📚 延伸阅读

  • OpenTelemetry JS — OpenTelemetry JavaScript SDK 官方文档,涵盖自动埋点和手动 Span 创建
  • prom-client — Node.js Prometheus 客户端库,GitHub 仓库包含 Histogram、Counter、Gauge 的完整用法
  • Grafana Documentation — Grafana 官方文档,从数据源配置到面板创建的分步指南
  • LangFuse — LLM 应用可观测性开源平台,可作为 LangSmith 的替代方案
  • Alertmanager — Prometheus 告警管理器,用于管理告警路由、静默和去重
  • LangSmith Documentation — LangSmith 官方文档,包含 Prompt 版本管理和 LLM 调用对比功能指南