📖 本章学习目标
- 用 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 端点。
验证步骤:
curl http://localhost:3000/metrics确认返回正确的 Prometheus 格式文本- 发送几条查询后再次 curl,观察指标数值的变化是否与查询行为一致
- 在本地启动 Grafana(Docker 容器),添加 Prometheus 数据源,创建一个简单的折线图面板
预期结果:/metrics 端点正常暴露指标,Grafana 面板能展示检索延迟和生成延迟的趋势曲线。
练习 2:实现 OpenTelemetry 全链路追踪
参照本章第二节的代码,在你的 RAG 服务中集成 OpenTelemetry,用 Jaeger 可视化每次请求的完整 Span 树。
验证步骤:
- 在本地启动 Jaeger(
docker run -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one) - 发送一条 RAG 查询请求,访问 Jaeger UI(
http://localhost:16686),确认能看到rag-request及其子 Span - 检查每个 Span 的属性,确认
retrieval.time_ms、docs.count等关键字段已记录
预期结果:Jaeger UI 中能看到一次完整 RAG 请求的追踪数据,每个阶段的耗时和关键属性一目了然。
练习 3:实现用户反馈收集并分析数据
在你的服务中添加 /feedback 端点,并在前端(或命令行工具)中加入评分功能。收集 20 条以上反馈后分析数据。
验证步骤:
- 提交几条不同评分(包括低分和高分)的反馈,确认数据库中记录完整
- 查询
/feedback/stats接口,检查平均评分和各分数段分布是否正确 - 筛选出所有低分回答,检查它们的共同特征(问题类型、检索到的文档、生成内容)
预期结果:能够按查询 ID 关联反馈与原始请求,低分回答的分析结果能为下一步优化提供方向。
练习 4:配置告警规则
基于练习 1 和练习 2 积累的指标数据,为你的系统配置至少三条告警规则,并测试告警能否正常触发。
验证步骤:
- 在本地运行一到两天后,从 Prometheus 中导出各指标的 P50、P95、P99 值
- 基于基线数据设置告警规则(同时检查相对变化和绝对阈值)
- 通过故意触发错误(如暂时停止向量数据库、发送无效查询)验证告警是否能正常发送
预期结果:告警规则基于真实基线数据设定,误报率在可接受范围内,且能在问题确实发生时发出通知。
📚 延伸阅读
- 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 调用对比功能指南