企业官网建设流程全解析

可观测性：调用留痕与量化分析

Agent 是匹烈马，你得看得见它每一脚踩在哪。可观测性就是那台仪表盘——每次调用都留痕、trace 落盘、一句话提示词量化分析速度与成本。这也是整个理论区的收官章（附第二部分完整自测清单）。

本文导航

• 为什么"看得见"比"跑得通"更重要
• 调用留痕：每一个动作都有档案
• trace 落盘：原始输入输出的追溯
• 一句话提示词做分析：日志挖掘实战
• 量化指标体系：min/max/avg 一网打尽
• 第二部分自测清单
• 小结
• 下节预告

第 25 节，第 5 章收官，也是整个理论区的收官。六层架构走到最高的第六层：可观测性（Observability）。

前五层决定 Agent “能不能干活”，这一层决定你**“能不能看懂它在干什么”**——而一个你看不懂的 Agent，是没有信心上生产的。这一节把"看"这件事做到极致：记录每一个动作、存档每一次原始输入、用一句话提示词挖出规律。

为什么"看得见"比"跑得通"更重要

先讲一个我的亲历教训。早期我写的 Agent “能跑通一个 demo”，但一上生产就露馅：用户说某个任务卡住了、或者账单异常，我完全不知道它内部干了啥——调了几次接口？token 花了多少？卡在哪一步？两眼一抹黑。排查一个"看不见"的 Agent，比排查一个普通 bug 痛苦十倍。

可观测性的价值就在这儿：

1. 故障可定位：出问题能迅速锁定是哪一次调用、哪个动作引起的；
2. 成本可解释：token 花在哪、为什么花这么多，账目门清（呼应第 13 节）；
3. 行为可审计：Agent 做过什么都能回溯（呼应第 23 节权限的可审计诉求）；
4. 优化有依据：从数据里看出瓶颈（哪步慢、哪步贵），对症下药。

一句话：没有可观测性的 Agent 是"黑盒赌运气"，有可观测性的 Agent 是"透明可复盘"。这也是我们课程"五条铁律"如此强调留痕的原因。

调用留痕：每一个动作都有档案

可观测性的地基是调用留痕——把每次模型调用记成一条结构化档案。我们课程的铁律定死了一套"留痕五要素"（每次调用必须记录）：

一条典型的留痕记录长这样（第 7 章 v0.2 会完整实现）：

call_id=cl_8f2a | ts=2026-09-11 14:03:21 ~ 14:03:27 base=https://api.deepseek.com | key=...3f9a | model=deepseek-flash in_tokens=5210 | out_tokens=384 | elapsed=5.8s | finish_reason=tool_calls

这套字段是后续所有分析的"原材料"。没有它们，后面的量化分析就是无米之炊。这也是为什么我反复强调：留痕不是可选项，是硬要求。

trace 落盘：原始输入输出的追溯

留痕记的是"元数据"（时长、token 数），但还有一种更深的可观测性——trace 落盘：把每次调用的原始输入提示词和原始输出完整存档到文件，方便深挖式追溯。

为什么这么做？因为光看"5000 token、5.8 秒"你只能知道"发生了什么量"，但不知道"模型到底看到了啥、回了个啥"。排查"这个 Agent 怎么突然跑偏了"时，你需要回放那一次调用的完整输入输出——这就是 trace 落盘的价值。

工程上长这样：

logs/trace/ cl_8f2a_request.json # 完整请求（system+user+tools 全量，正文+文件字节） cl_8f2a_response.json # 完整响应（content + tool_calls + usage） cl_8f2a_meta.json # 元数据（base/key末6位/模型/起止时间/耗时）

按call_id（和留痕记录同源）一一对应，出问题就能三件套一起调出来看。这套目录设计、文件命名规范、磁盘节约策略，是第 7 章第 32 节《trace 落盘》的主战场，这里先立下"原始内容要存档"的原则。（注意：这会触及隐私——trace 落盘前要做敏感信息脱敏，别把用户的密钥、口令原样写进去。）

一句话提示词做分析：日志挖掘实战

留痕 + trace 攒了一堆数据，怎么用起来？最高效的玩法是：把这些结构化日志丢给大模型，用一句自然语言提问，让它直接吐出分析结论。

我们课程有一个金句铁律叫"一句提示词做分析"——因为日志是结构化的（JSON/表格），大模型完全能读、能算、能总结。比如我想知道：

• “分析最近 100 次调用的平均速度、最慢最快”
• “算一下输入 token 长度与耗时的关系”
• “找出最贵的 5 次调用，看共性”

给日志 + 这样一句提问，配套的代码（第 7 章第 34 节会写个脚本把日志喂给模型）能直接吐出分析报告。举个简化示意（实际日志喂给 DeepSeek 后它会自己算）：

user: 以下是 DeepSeek Agent 的调用日志(CallRecord 列表)， 请分析调用平均速度、最慢最快，以及输入长度与耗时的关系: [ {in_tokens, out_tokens, elapsed}s, ... 共50条 ] assistant: - 平均耗时 4.2s，最快 1.1s（in_tokens=450），最慢 18.3s（in_tokens=48000） - 输入 token 与耗时呈明显正相关：输入>10K 的调用平均 3.4 倍慢于 <1K 的调用 - 推测瓶颈在长上下文处理阶段，建议对超大输入做压缩（见上下文工程）

这就是"一句话提示词做分析"的威力：不写复杂统计代码，把日志当"语料"让模型挖。而你手头积攒的这种"留痕数据"，本身就是你 Agent 的体检报告——这正是这套工程规范能反哺决策的地方（呼应第 78 节用调用日志算真实毛利）。

量化指标体系：min/max/avg 一网打尽

除了"按需提问"，还有一种持续性的可观测性：程序退出时打印一份量化总结。我们把留痕数据汇总成几个关键指标，程序结束时在控制台打出，一眼看清这次运行的"健康度"：

"""call_summary.py —— 退出时的调用量化总结（第25节 示意） 运行环境：Python 3.12 """fromstatisticsimportmeandefsummarize(records):"""records: [{'in':int,'out':int,'elapsed':float}, ...]"""inputs=[r['in']forrinrecords]outputs=[r['out']forrinrecords]times=[r['elapsed']forrinrecords]print("===== 本次运行调用总结 =====")print(f"调用次数:{len(records)}")forname,valsin[("输入 token",inputs),("输出 token",outputs),("耗时(s)",times)]:print(f"{name}: min={min(vals):.2g}max={max(vals):.2g}avg={mean(vals):.2g}")# 示意数据summarize([{'in':5210,'out':384,'elapsed':5.8},{'in':11200,'out':900,'elapsed':12.4},{'in':450,'out':120,'elapsed':1.1},])

运行输出：

===== 本次运行调用总结 ===== 调用次数: 3 输入 token: min=450 max=1.1e+04 avg=5.6e+03 输出 token: min=120 max=900 avg=468 耗时(s): min=1.1 max=12 avg=6.4

这套 min/max/avg 指标体系（输入输出 token、耗时、成功率），正是我们"铁律"里"退出时打印调用总结"的实现。它在第 7 章第 33 节会用atexit注册成真正随程序退出自动触发的钩子，现在先建立"程序结束要有量化交代"的习惯。

第二部分自测清单

到这里，理论区（第 3-5 章，第 10-25 节）全部收官。按课程设计（第 34 行工程规范），每个部分收官要附上自测清单。列个精简版，看看你是否真的吃透了理论区：

• 能说清 OpenAI 兼容协议的端点/请求/响应三件套（第 10 节）
• 能区分 messages 的 system/user/assistant/tool 四角色（第 11 节）
• 知道 tool_calls 的三份 JSON 怎么交换与对账（第 17 节）
• 能算出一次调用的成本（缓存命中 0.02 / 未命中 1 / 输出 4，第 13 节）
• 能画出 ReAct 循环的 Thought-Action-Observation 骨架（第 16 节）
• 掌握停机三闸与 finish_reason 四取值（第 18 节）
• 能区分可重试/不可重试错误并做指数退避（第 19 节）
• 知道三道熔断（token/时间/次数）是做什么的（第 20 节）
• 能说清工具注册中心 + pydantic 反射生成 Schema（第 21 节）
• 理解四件套类比：窗口=内存/历史=堆栈/系统提示=BIOS/工具结果=寄存器（第 22 节）
• 掌握三级信任模型（放行/审批/禁止）+ 最小权限原则（第 23 节）
• 能区分 router/pipeline/swarm 三种编排并做选型判断（第 24 节）
• 知道留痕五要素、trace 落盘、一句提示词分析（第 25 节）

全部勾上，可以放心进入第三部分实战。有勾不上的，回头翻对应章节——理论是实战的地基，别带着窟窿下楼。

小结

1. 看得见比跑得通更重要：可观测性 = 故障定位 + 成本解释 + 行为审计 + 优化依据。
2. 留痕五要素是分析地基：base/端口、key末6位、模型、输入输出长度、起止时间+耗时。
3. trace 落盘存原始输入输出，按 call_id 对应可追溯；注意敏感信息脱敏。
4. 一句提示词做分析：把结构化日志喂给模型，直接挖平均速度、长度-耗时关系。
5. 退出打印量化总结：min/max/avg 一网打尽，程序结束有交代。
6. 理论区收官，附上第二部分自测清单，勾完再进实战。

下节预告

理论区（第 3-5 章）到此完结。从下一节起进入第三部分：实战核心区，我们用 DeepSeek 亲手把理论落地成代码。第 26 节是实战的第一块地基——uv + Python 3.12：现代化工程地基一日通，把环境搭好、依赖管好，DeepPilot v0.1 正式开工。

如果觉得本文对你有帮助，欢迎点赞、收藏、关注三连！
本系列持续更新中，关注不迷路~