基于Langfuse的智能体评估平台实战项目

很多人做智能体，卡住的地方不在写 prompt，而在“改完到底变好了没有”。同一个问题，调了系统提示词、换了检索策略、加了工具调用，回答看起来顺眼了，但你没法证明它比上一版强，也没法说清是哪个环节拖了后腿。这门课要解决的，就是这个说不清的地方：把 Langfuse 用起来，给智能体建一套能反复跑、能对比、能定位问题的评估流程。

先想清楚你到底缺哪一块

如果你现在是这样几种状态之一，这门课会比较对得上：智能体能跑通 demo，但一上真实输入就时好时坏，只能靠人工试几条看感觉；团队里有人在改 prompt、有人在调模型参数，改动之间互相对不上，出了回归问题找不到是哪个版本引入的；想引入自动化评估，但不知道评估集怎么攒、指标怎么定、结果怎么和线上 trace 对上。

反过来，如果你还停留在“怎么让模型返回 JSON”这一步，或者根本没接触过 trace、span 这类概念，先补基础会更顺，不然评估平台反而会变成新的负担。

这门课会把 Langfuse 放到什么位置

Langfuse 在这门课里不是被当成一个“日志工具”来介绍的，而是当作评估环节的中枢：智能体每次运行的输入、输出、工具调用、耗时、token 消耗都留痕，评估结果再挂回这些 trace 上。这样一来，“这条回答为什么差”和“这次改动让整体分数掉了多少”是同一个视图里的事，而不是两套互不相干的记录。

课程会沿着数据准备、评估执行、结果分析、迭代优化这条线往下走，中间会带出 LangChain、LangGraph、OpenAI Agent 这些常见搭建方式在评估时的差异——它们各自留下的 trace 结构不一样，评估脚本接进去的方式也不一样，这块是纯看文档不容易绕明白的。

配套练习会逼你做的几件事

• 攒出一份自己的评估集：不是随便找几条问答，而是覆盖正常输入、边界输入和已知容易翻车的情况，并说明每类占比为什么这么定。
• 跑一次可对比的评估：同一批数据，两个版本的智能体，输出能被放在一起看的分数，而不是只截图给人看。
• 从 trace 里定位一次退化：给定“这版比上版差”的结论，顺着调用链找到是哪一步、哪个工具或哪段上下文出的问题。
• 处理异常和版本：当工具报错、模型超时、返回格式不对时，评估流程不能直接崩，这部分会带着做。

看完你应该能回答的问题

评估集应该从真实流量里采样，还是人工构造？两者怎么配合。线上 trace 和离线评估集之间怎么建立对应关系，避免“测的”和“跑的”是两回事。当主观指标（比如回答是否得体）没法用规则判断时，用什么方式让它可比较、可复现。智能体版本迭代时，哪些东西该跟着版本走，哪些该单独管理。评估跑出分数之后，下一步具体动 prompt、动检索还是动工具，判断依据是什么。

这些问题没有唯一答案，但课程会给出可落地的取舍方式。学的时候建议边看边把自己手上那个智能体接进去跑一遍，哪怕只有十几条评估数据，也比空看一遍强。评估这件事，第一版通常很粗糙，重要的是先跑起来，再逐步收紧。