08 状态、评测与观测:从会话到可测量
一句话结论
会话状态、评测和日志是三件互相支撑的事:checkpointer 决定历史放在哪,评测集决定改动有没有用,分阶段日志决定问题出在哪。没有评测和观测,前六篇的所有优化都只能靠感觉。
它解决什么问题
做完检索和失败路径的优化后,仍会遇到三类问题:
- 历史由客户端传入,可以被伪造,也无法断点续传;
- 改了阈值或改写策略,不知道整体是变好还是变坏;
- 首 token 变慢,但不知道慢在 embedding、检索还是模型。
它们分别对应状态、评测、观测。
1. LangGraph 的状态模型
图按 super-step 执行:运行可运行节点 → 合并状态更新 → 根据边决定下一步。节点返回局部状态,默认覆盖同名字段。
要追加列表,必须用 reducer:
from typing import Annotated
from langgraph.graph.message import add_messages
class RagState(TypedDict, total=False):
messages: Annotated[list, add_messages]
理解这一点很重要:{"chunks": [...]} 会覆盖旧值,{"triage": "greeting"} 也只影响对应键。不要指望把两个列表自动合并。
2. checkpointer:把会话搬到服务端
checkpointer 在每一步之后自动存盘,按 thread_id 保存整个 state。相当于把会话从 localStorage 搬到服务端,还带版本历史。
from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
async with AsyncPostgresSaver.from_conn_string(settings.database_url) as saver:
await saver.setup()
graph = builder.compile(checkpointer=saver)
config = {"configurable": {"thread_id": session_id}}
await graph.astream({"query": query}, config=config)
它解锁四件事:
- 服务端会话:客户端只发
thread_id + query,历史从 checkpoint 读,不再信任客户端。 - 断点续传:生成中断后可以接着来(但要显式处理取消,否则图可能继续跑、继续花钱)。
- 时间旅行:从任意 checkpoint 重放,调试很方便。
- 人审中断:
interrupt()暂停等待确认,当前场景不需要。
代价也要写清楚:
| 问题 | 说明 |
|---|---|
| 有状态 | 多实例必须共享存储;Postgres saver 正好满足 |
| 隐私 | 对话落库,需要 TTL 和说明 |
| 会话标识 | 无登录时用随机 UUID,不可枚举,加 TTL |
| 数据增长 | checkpoint 持续增长,要定期清理 |
| 取消 | 用户关页面时要取消图执行 |
| 生命周期 | 编译后的 graph 应复用,不要每请求重建 |
这是一次服务形态的改动,应该独立成一个 change,不要和检索参数混在一起。
3. 评测:先有基线,再改参数
假设两个正确结果,检索返回五条:
[A 命中] [X 无关] [B 命中] [Y 无关] [Z 无关]
- Recall@5 = 2/2 = 1.0:该找到的找到没有;
- Precision@5 = 2/5 = 0.4:返回的多干净;
- MRR = 1/1 = 1.0:第一个正确结果有多靠前。
聊天场景里 Recall@5 和 MRR 最重要,因为用户先看第一段资料。
评测集怎么造
- question: 多阶段构建解决了什么问题?
expected: [build-practice-05-deployment-docker]
- question: 那它有什么缺点?
history:
- role: user
content: 多阶段构建解决了什么问题?
- role: assistant
content: 多阶段构建把依赖分层……
expected: [build-practice-05-deployment-docker]
- question: Qwen3-Embedding-0.6B 是多少维?
expected: [build-log-...]
- question: 今天天气怎么样?
expected: []
原则:
- 用用户口吻写,不要照抄标题,否则评测虚高;
- 覆盖四类:概念问法、多轮追问、精确标识符、站外问题;
- 每条标注期望 slug;
- 30~50 条起步,关键是要稳定,每次改动都跑同一套。
只跑检索,成本极低
def evaluate(questions, retriever, k=5):
hits, rr = 0, 0.0
for q in questions:
slugs = [r.slug for r in retriever(q["question"], k)]
expected = set(q["expected"])
if not expected:
hits += not slugs
continue
found = [i for i, s in enumerate(slugs, 1) if s in expected]
if found:
hits += 1
rr += 1 / found[0]
return {"recall": hits / len(questions), "mrr": rr / len(questions)}
它只调 embedding,不调生成模型。几秒钟跑完,每次改检索都跑。
生成质量另算
| 指标 | 怎么测 |
|---|---|
| 引用合法率 | [n] 是否都在范围内 |
| 拒答正确率 | 站外是否拒答、站内是否误拒 |
| 忠实度 | 回答的事实能否在资料里找到 |
前两个可以自动算;忠实度人工抽查 20 条,或用 LLM 评审,但要记住评审本身有偏差。
4. 观测:把「感觉慢了」变成数字
每个阶段打点:
logger.info(
"chat request_id=%s rewrite_ms=%d embed_ms=%d search_ms=%d "
"first_token_ms=%d total_ms=%d sources=%d "
"prompt_tokens≈%d answer_tokens≈%d",
request_id, rewrite_ms, embed_ms, search_ms,
first_token_ms, total_ms, source_count,
prompt_token_estimate, answer_token_estimate,
)
至少要能回答四个问题:
- 首 token 慢,慢在 embedding、检索还是 prefill?
- 一次请求真实消耗多少 token?输入和输出分别是多少?
- 改写节点有没有经常失败退回原文?
- 哪些 query 稳定检索为空?它们是内容缺口还是阈值问题?
日志里绝对不能有:
- API Key(错误信息也要做
_redact); - 完整回答(属于隐私,最多记长度和是否拒答);
- 未截断的 query(如需要,截断或哈希)。
统一 token 口径
本仓库的限流器有一个需要确认的账目问题:settle() 之后,最终只累计了「回答 token」,预占的 prompt token 被释放了。
如果 ASSISTANT_DAILY_TOKEN_BUDGET 的本意是「总 token」,这里少算了约一个数量级;如果只想统计生成量,变量名和文档应该说清楚。无论哪种,全链路要用同一个口径,否则既算不准成本,也解释不清额度为什么用完。
我怎么试的
1. 先跑检索评测,不跑生成
cd backend
uv run python -m eval.run # 假设评测脚本
第一版只需要输出 recall 和 mrr 两个数。改动阈值、改写策略、RRF 权重前后各跑一次,数字变化就是证据。
2. 用固定问题看分阶段耗时
挑三个问题:一个站内概念、一个多轮追问、一个站外问题。分别记录 embed_ms、search_ms、first_token_ms。不要只看平均值,至少记录 10 次取 p50 和 p95。
3. 验证 checkpointer 的边界
在接入会话之前,先确认三件事:
- 同一
thread_id的第二次请求能读到第一次的历史; - 不同
thread_id互不串; - 用户断开连接后,图执行会被取消,而不是继续跑。
坑和限制
- 有状态会放大隐私问题。 对话落库后,要有清理策略和用户说明;没有登录时不要存可识别身份的信息。
- checkpoint 不是免费的。 每一步都序列化 state,写入频率高;要监控表大小并定期清理。
- 评测集不能一次写完就不管。 内容更新后要补题,否则评测和真实内容脱节。
- LLM 评审不能当真理。 它更适合做粗筛,最终结论仍要人工抽查。
- 日志不要记录完整回答。 调试方便和信息安全之间要选后者。
- 不要在没有基线时调参数。 一次「看起来更好」的改动,可能只是换了评测样本。
适合谁
适合已经完成检索和失败路径优化、想把工作变成可复现流程的人。这一篇不提供新的检索技巧,它提供的是让别人相信你的改动有效的方法。
下一篇把前面所有内容合成一张图:目标架构、节点职责、事件协议和分阶段落地清单。