可观测性 on lategege 的技术博客

RAG 上线前 Checklist：把坑提前填完（数据/检索/生成/评测/安全）

Sun, 22 Mar 2026 23:25:00 +0800

上线一个 RAG，难点从来不是“把文档塞进向量库”。真正麻烦的是：命中率飘、延迟变大、答案开始胡说、出了问题还复盘不了。

这篇文章我把上线前最值得做的事情整理成三张图：

架构图：你到底在上线什么（数据管道/索引/检索/rerank/生成/校验/观测）
对比卡片：混合检索 vs 纯向量 vs 纯 BM25，怎么选不纠结
Checklist 卡片：上线前逐项勾掉，避免“上线后边跑边修”

1) 你上线的不是模型，是一条链路（架构图）

RAG 的“能力上限”往往由最弱的一环决定：数据质量、切分、检索、拼接、校验、观测。

这张图里有三个节点特别容易被忽略：

上下文构建（去重/截断/引用）：很多胡说来自“证据被截断/重复污染”
后置校验：引用是否存在？关键数值是否一致？敏感内容是否外泄？
可观测性：出了 badcase，必须能回放到“当时检到了什么、拼了什么 prompt”

2) 选型别纠结：先混合，再 rerank（对比卡片）

不少团队一上来就想“把 embedding 调到完美”。但工程上更稳的默认是：混合检索做底，rerank 提质。

2.1 一个简单结论

你对“型号/ID/精确术语”敏感：BM25 不能丢
你对“同义词/长尾表达”敏感：向量检索必须有
你想上线后能排障：混合检索 + 可观测是性价比最高的组合

3) 上线前 Checklist（可收藏卡片）

如果你只想把这篇文章的核心复制到团队 wiki：就复制这张图。

4) 代码块：一次请求要记录哪些东西（最小可用）

上线后排障最怕一句话：

“它刚才明明可以的。”

你要能回放，就得把关键中间产物打出来：规范化后的 query、top chunks、最终 prompt 长度、是否截断。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


from dataclasses import dataclass
from typing import List, Dict, Any
import time

@dataclass
class Chunk:
 doc_id: str
 score: float
 text: str


def rag_debug_once(question: str) -> Dict[str, Any]:
 t0 = time.time()

 # 1) query
 query = " ".join(question.strip().split())

 # 2) retrieve (mock)
 chunks: List[Chunk] = [
 Chunk(doc_id="doc:pricing", score=0.78, text="..."),
 Chunk(doc_id="doc:limits", score=0.74, text="..."),
 ]

 # 3) build prompt
 context = "\n\n".join(
 f"[source:{c.doc_id} score={c.score:.2f}]\n{c.text}" for c in chunks
 )
 prompt = (
 "只允许基于 sources 回答，并在结尾列出引用。\n\n"
 f"Question:\n{query}\n\n"
 f"Sources:\n{context}\n\n"
 "Answer:\n"
 )

 # 4) llm call (mock)
 answer = "(mock) ..."

 return {
 "latency_ms": int((time.time() - t0) * 1000),
 "query": query,
 "top_docs": [{"doc_id": c.doc_id, "score": c.score} for c in chunks],
 "prompt_chars": len(prompt),
 "answer": answer,
 }

5) 收尾：把“可回放”当成上线前置条件

RAG 的迭代不是玄学。

你只要能把一次 badcase 的链路完整记录下来（检索→拼接→生成→校验），后面每一次优化都会更快、更确定。

RAG 失败复盘手册：一张流程图 + 一段代码，把问题定位到检索/生成/数据

Sun, 22 Mar 2026 08:16:00 +0800

很多 RAG 系统的问题，表面看起来是“模型不行”，但真正的根因往往在更前面：数据切分、索引构建、检索策略、拼接截断、或后置校验。

这篇文章我给你一套可复用的排障流程：

一张“从 Query 到日志”的流程图（你可以贴到团队 wiki）
一段最小可用的 Python 代码：把一次请求的关键中间产物都打出来（便于复盘）

1) 先统一语言：RAG 失败到底分哪几类？

我把 RAG 的失败分成三类（按排查优先级）：

检索失败：检索出来的内容不相关 / 证据不足
拼接失败：检索对了，但上下文被截断、重复、排序错误
生成失败：证据足够，但模型没按证据回答（提示词/格式/温度等问题）

你只要能把一次失败明确归类，后面的优化就不会“凭感觉”。

2) 一张流程图：把排障步骤固定下来

下面这张图是我做 RAG 排障时的默认流程：

你可以把它当作 checklist：每次线上出现“答非所问/胡说八道/延迟突然变大”，就按这个顺序走。

3) 一段最小可用代码：把一次请求的关键中间产物都记录下来

下面这段代码示例做三件事：

记录规范化后的 query
记录检索结果（文档 id、score、片段）
记录最终 prompt（以及截断信息）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


from dataclasses import dataclass
from typing import List, Dict, Any
import time

@dataclass
class Chunk:
 doc_id: str
 score: float
 text: str


def normalize_query(q: str) -> str:
 # 你可以在这里做：全角半角、大小写、同义词、实体标准化…
 return " ".join(q.strip().split())


def retrieve(q: str, topk: int = 5) -> List[Chunk]:
 # 示例：这里替换成你的 BM25/向量检索
 # 返回 doc_id/score/text，便于后续定位“到底检索到了什么”
 return [
 Chunk(doc_id="doc:pricing", score=0.78, text="..."),
 Chunk(doc_id="doc:limits", score=0.74, text="..."),
 ][:topk]


def build_prompt(q: str, chunks: List[Chunk], max_chars: int = 6000) -> str:
 context = "\n\n".join(
 f"[source:{c.doc_id} score={c.score:.2f}]\n{c.text}" for c in chunks
 )
 prompt = (
 "你是一个严谨的助手。只允许基于给定的 sources 回答，并在结尾列出引用。\n\n"
 f"Question:\n{q}\n\n"
 f"Sources:\n{context}\n\n"
 "Answer:\n"
 )
 truncated = len(prompt) > max_chars
 if truncated:
 prompt = prompt[:max_chars] + "\n\n[TRUNCATED]"
 return prompt


def rag_once(question: str) -> Dict[str, Any]:
 t0 = time.time()

 q = normalize_query(question)
 chunks = retrieve(q, topk=8)
 prompt = build_prompt(q, chunks, max_chars=6000)

 # 这里替换成你的 LLM 调用
 answer = "(mock) ..."

 return {
 "latency_ms": int((time.time() - t0) * 1000),
 "query": q,
 "top_docs": [{"doc_id": c.doc_id, "score": c.score} for c in chunks],
 "prompt_chars": len(prompt),
 "answer": answer,
 }


if __name__ == "__main__":
 result = rag_once("你们套餐的价格和限制是什么？")
 print(result)

3.1 这段代码你应该怎么用

在你真实服务里，把 rag_once 的输出写进一次请求的 trace/log
线上出现 badcase 时，你能立刻回答三个问题：
1. query 进来后被改成了什么？
2. 检索到底检到了哪些 doc？score 如何？
3. prompt 有没有被截断？

4) 结尾：把“能复盘”当成 RAG 的第一优先级

RAG 的优化不是玄学。

只要你能把一次失败的链路完整记录下来，下一步该改数据、改检索、改提示词，结论会非常清晰。

从 0 到可用：AI Agent 工程化的 7 个关键点（工具调用、状态、回放、护栏）

Sun, 22 Mar 2026 01:40:00 +0800

很多人第一次做 Agent 都会经历同一条路径：

Demo 很惊艳
一上线就开始“偶尔很好、偶尔发疯”

原因通常不是模型不够强，而是缺少工程化要素：状态、约束、回放、观测、失败恢复。

这篇文章把我认为最关键的 7 点整理成一份“上线前检查表”。

1) 明确 Agent 的边界：它到底能做什么，不能做什么

先写一段非常具体的“职责说明”（类似产品 PRD 的一句话版本）：

输入范围：用户问题、已有上下文
输出范围：文本答复/结构化 JSON/创建任务
禁止事项：涉及资金、删除数据、外发内容必须人工确认

边界越清晰，越容易做护栏和测试。

2) 工具调用要“可验证”：宁可少，也别玄学

工具调用（function calling / tool use）要做到两件事：

参数可校验（schema + 业务校验）
结果可复用（工具输出结构化，别是长段自然语言）

常见错误：工具返回一大段文本，模型再总结一次 → 误解 + 幻觉概率翻倍。

3) 状态管理：不要把一切都塞进 prompt

你需要区分三种状态：

短期对话上下文（最近几轮）
任务状态（步骤 3/7、已完成哪些）
长期记忆（偏好、固定资料）

工程里更靠谱的做法是：

任务状态用结构化对象保存（JSON/DB）
只把“必要摘要”注入 prompt

4) 计划（Plan）要轻量：可执行比好看重要

很多 Agent 失败在“计划很宏大但无法执行”。

建议：

计划最多 3~7 步
每一步都要能映射到工具/动作
每步输出都有明确的验收条件

如果做不到，说明任务需要拆分或需要更多信息。

5) 护栏（Guardrails）：别只靠“请你谨慎”

护栏最好是多层的：

前置拦截：敏感意图识别（删库/转账/外发）→ 直接要求确认
参数拦截：危险参数（rm -rf、高权限操作）直接拒绝
后置检查：输出是否包含隐私、是否引用了不存在的来源

最有效的一招：对外部副作用操作必须二次确认（human-in-the-loop）。

6) 可回放（Replay）：能复现才能修

上线后用户会说：

“刚才它明明说可以，现在又不行了”

如果你没有回放能力，就只能猜。

至少记录：

用户输入
Agent 当时看到的上下文摘要
工具调用序列（含参数、结果、耗时）
最终输出

有了回放，你才能做“失败样本集”，然后针对性修。

7) 评测：用真实任务做回归

Agent 的评测不要只看“答得像不像”。

更应该看：

工具调用成功率
任务完成率（端到端）
平均步骤数（越少越好）
人工介入次数

做一个最小回归集（比如 30 条真实任务），每次改 prompt/策略/模型都跑一遍。

结语

Agent 不是“更复杂的聊天”，而是一个会产生行为的系统。

如果你把它当软件工程来做：

有状态
有护栏
有回放
有评测

它的稳定性会比你想象中提升得快。