可观测性调用留痕与量化分析Agent 是匹烈马你得看得见它每一脚踩在哪。可观测性就是那台仪表盘——每次调用都留痕、trace 落盘、一句话提示词量化分析速度与成本。这也是整个理论区的收官章附第二部分完整自测清单。本文导航为什么看得见比跑得通更重要调用留痕每一个动作都有档案trace 落盘原始输入输出的追溯一句话提示词做分析日志挖掘实战量化指标体系min/max/avg 一网打尽第二部分自测清单小结下节预告第 25 节第 5 章收官也是整个理论区的收官。六层架构走到最高的第六层可观测性Observability。前五层决定 Agent “能不能干活”这一层决定你**“能不能看懂它在干什么”**——而一个你看不懂的 Agent是没有信心上生产的。这一节把看这件事做到极致记录每一个动作、存档每一次原始输入、用一句话提示词挖出规律。为什么看得见比跑得通更重要先讲一个我的亲历教训。早期我写的 Agent “能跑通一个 demo”但一上生产就露馅用户说某个任务卡住了、或者账单异常我完全不知道它内部干了啥——调了几次接口token 花了多少卡在哪一步两眼一抹黑。排查一个看不见的 Agent比排查一个普通 bug 痛苦十倍。可观测性的价值就在这儿故障可定位出问题能迅速锁定是哪一次调用、哪个动作引起的成本可解释token 花在哪、为什么花这么多账目门清呼应第 13 节行为可审计Agent 做过什么都能回溯呼应第 23 节权限的可审计诉求优化有依据从数据里看出瓶颈哪步慢、哪步贵对症下药。一句话没有可观测性的 Agent 是黑盒赌运气有可观测性的 Agent 是透明可复盘。这也是我们课程五条铁律如此强调留痕的原因。调用留痕每一个动作都有档案可观测性的地基是调用留痕——把每次模型调用记成一条结构化档案。我们课程的铁律定死了一套留痕五要素每次调用必须记录字段含义为什么重要base_url 端口请求打到哪个远端多服务/自建时区分来源key 末尾 6 位API Key 脱敏标识防泄密 区分用了哪个 key模型名用了哪个模型多模型路由/成本分析输入/输出长度提示词 token 数 / 回复 token 数成本核算、长度-速度分析开始/结束时间 总耗时年月日时分秒粒度性能监控、瓶颈定位一条典型的留痕记录长这样第 7 章 v0.2 会完整实现call_idcl_8f2a | ts2026-09-11 14:03:21 ~ 14:03:27 basehttps://api.deepseek.com | key...3f9a | modeldeepseek-flash in_tokens5210 | out_tokens384 | elapsed5.8s | finish_reasontool_calls这套字段是后续所有分析的原材料。没有它们后面的量化分析就是无米之炊。这也是为什么我反复强调留痕不是可选项是硬要求。trace 落盘原始输入输出的追溯留痕记的是元数据时长、token 数但还有一种更深的可观测性——trace 落盘把每次调用的原始输入提示词和原始输出完整存档到文件方便深挖式追溯。为什么这么做因为光看5000 token、5.8 秒你只能知道发生了什么量但不知道模型到底看到了啥、回了个啥。排查这个 Agent 怎么突然跑偏了时你需要回放那一次调用的完整输入输出——这就是 trace 落盘的价值。工程上长这样logs/trace/ cl_8f2a_request.json # 完整请求systemusertools 全量正文文件字节 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.1sin_tokens450最慢 18.3sin_tokens48000 - 输入 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: min450 max1.1e04 avg5.6e03 输出 token: min120 max900 avg468 耗时(s): min1.1 max12 avg6.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 节全部勾上可以放心进入第三部分实战。有勾不上的回头翻对应章节——理论是实战的地基别带着窟窿下楼。小结看得见比跑得通更重要可观测性 故障定位 成本解释 行为审计 优化依据。留痕五要素是分析地基base/端口、key末6位、模型、输入输出长度、起止时间耗时。trace 落盘存原始输入输出按 call_id 对应可追溯注意敏感信息脱敏。一句提示词做分析把结构化日志喂给模型直接挖平均速度、长度-耗时关系。退出打印量化总结min/max/avg 一网打尽程序结束有交代。理论区收官附上第二部分自测清单勾完再进实战。下节预告理论区第 3-5 章到此完结。从下一节起进入第三部分实战核心区我们用 DeepSeek 亲手把理论落地成代码。第 26 节是实战的第一块地基——uv Python 3.12现代化工程地基一日通把环境搭好、依赖管好DeepPilot v0.1 正式开工。如果觉得本文对你有帮助欢迎点赞、收藏、关注三连本系列持续更新中关注不迷路~