FDE 作品集仓库,要展示 Agent 在哪里失败
单次正确率 80% 的 Agent,连对三次只有 51%,基于真实失败的评测胜过精美演示。
要点速览
- 一个附带案例分析的深度项目,胜过许多精美演示;选一个带脏数据的真实企业场景。
- Agent 循环保持简单易读,把精力投在工具描述上,从一开始就记录每次运行。
- 从真实失败构建评测,先用低成本断言,报告 pass^k,并阅读运行记录来检验评分器。
假设你的 Agent 在 80% 的运行中给出正确答案。听起来不错,直到你算一下它连续三次都答对的概率:0.8 × 0.8 × 0.8 = 51.2%。
所以,前线部署工程师(FDE)的作品集仓库不能止步于一个跑得漂亮的演示。演示只是一次尝试。值得拿出手的仓库,必须说明 Agent 在哪里失败、失败得有多频繁,以及你如何处理每一次失败。本文的度量方法参考了 Anthropic、OpenAI 和 Hamel Husain 关于 AI 系统评测的建议。
培训机构 FDE Academy 的博客上有一篇指南说得很直白:一个真正部署过、并写成案例分析的项目,分量超过八个精美的演示。
这是建议,不是定律,但道理不难理解:在真实数据上跑通的系统,比八个在干净数据上运行的原型更能体现能力。
下面分五步讲如何搭建这样的仓库。文中代码是精简示意:调用模型的函数留空,方便你接入自己使用的 SDK。
第 1 步:什么样的问题才够“企业级”?
同一篇 FDE Academy 指南建议:选一个贴近现实的企业场景,只做最小可行产品(MVP),不追求完整愿景,并使用真实或接近真实的脏数据。最后这个条件,正是 FDE 作品集和课程作业的分水岭。
设想一家分销公司通过邮件接收供应商发票。有的是歪着打印再扫描的 PDF;币种有的写“VND”,有的写“đ”;有的税号缺了几位。MVP 只做一件事:Agent 读取发票,与采购订单比对,返回“匹配”、附原因的“不匹配”,或“需人工审核”。
invoice-agent/
agent/loop.py # 核心循环
agent/tools.py # 工具及其描述
data/raw/ # 脏发票
logs/ # 每次运行一个 JSONL 文件
evals/cases.jsonl # 用例集
evals/test_basic.py # pytest 风格的断言
README.md
(注释依次为:核心循环;工具及其描述;脏发票;每次运行一个 JSONL 文件;用例集;pytest 风格的断言。)
**检查:**你能用一句话说清 MVP 的范围。如果这句话里“和”字超过两次,就继续删减。
第 2 步:为什么核心循环必须五分钟内读懂?
Anthropic 在《Building effective agents》中建议,先找最简单的方案,只在确实需要时才增加复杂度。它还提醒,框架往往会叠加抽象层,掩盖底层的提示词和响应。对作品集来说,这是硬伤:评审打开仓库却找不到提示词,就无从判断你的思路。
# agent/loop.py — 精简示意
def run(invoice_text, po, call_model, tools, log):
messages = [system_prompt(), user_msg(invoice_text, po)]
for step in range(8): # 限制步数上限
reply = call_model(messages, tools)
log.write(step, messages, reply) # 记录一切
if reply.tool_call is None:
return parse_verdict(reply)
result = tools[reply.tool_call.name](**reply.tool_call.args)
messages += [reply, tool_result(result)]
return {"verdict": "needs_review", "reason": "步数用尽"}
(注释分别标注步数上限和记录一切;兜底返回的原因是“步数用尽”。)
真正值得下功夫的是工具。Anthropic 称之为 Agent 与计算机的接口(agent-computer interface),建议精心设计:把工具文档写充分,并做测试。落到这个仓库,每个工具的 docstring 都应写明输入格式、何时返回空值,并附一个示例。
def lookup_po(po_number: str) -> dict:
"""按 PO 编号查询采购订单。
po_number:'PO-' 加 6 位数字,例如 'PO-004512'。
未找到时返回 {};不要猜测相近的编号。"""
(docstring 的意思是:按 PO 编号查询采购订单;格式为 ‘PO-’ 加六位数字,例如 ‘PO-004512’;未找到时返回 {},且不要猜测相近的编号。)
**检查:**把 loop.py 交给一个从没看过仓库的人。读五分钟后,对方能讲清 Agent 在做什么。
第 3 步:先记日志,再写评测
OpenAI 的《Evaluation best practices》建议在开发阶段记录一切,日后再从日志中挖掘评测用例。Hamel Husain 在《Your AI Product Needs Evals》中更进一步,主张清除查看数据的一切障碍。如果查看一次运行要打开三个文件、滚动到手酸,你很快就不会再看了。
最省事的做法是每次运行写一行 JSONL,包含输入、每次工具调用和最终结论。再写一个小脚本,把每次运行以易读的形式打印到终端。
在 data/raw/ 上把 Agent 跑 20-30 次,逐条阅读。你很可能会发现没预料到的失败,比如 Agent 把“1.200.000”(越南写法,用点作千位分隔符)读成一百二十万,还是读成 1.2。
**检查:**你手上有一份亲自记录的真实失败清单,每条都附有对应日志文件的路径。
第 4 步:评测从失败出发,而不是从理论出发
Anthropic 对评测的定义很简洁:给 AI 系统一个输入,再用评分逻辑处理其输出,衡量是否成功。在它看来,从真实失败中提取 20-50 个简单任务,就已经是不错的起点。第 3 步的失败清单,就是评测集的原材料。
{"id": "c07", "invoice": "data/raw/inv_07.pdf", "po": "PO-004512", "expect": "mismatch", "must_mention": "quantity"}
Husain 建议第一层用快速、低成本的断言,也就是你在 pytest 里本来就会写的那种。代码能检查的,交给代码;只有代码查不了的,才让模型来评分。
# evals/test_basic.py — 示意
@pytest.mark.parametrize("case", load_cases("evals/cases.jsonl"))
def test_verdict(case):
out = run_case(case)
assert out["verdict"] == case["expect"]
assert case["must_mention"] in out["reason"]
pytest evals/ -q
据 Anthropic 介绍,Agent 评测通常组合三类评分器:基于代码的、基于模型的和人工的。对作品集仓库而言,代码这一层要扎实。再加一个基于模型的评分器,判断 Agent 给出的理由是否成立,并在 README 中写清哪些部分是人工评分的。
OpenAI 把这种做法称为评测驱动开发(eval-driven development):尽早评测,经常评测,为每个阶段编写测试。
放在 README 最上方的数字应该是 pass^k。Anthropic 区分了 pass@k 和 pass^k:pass^k 是 k 次尝试全部成功的概率。本文开头的计算,正是单次正确率 80% 的 Agent 在各次运行相互独立时的 pass^3:51.2%。
设想一位会计每天用这个 Agent 三次。某一天三次全对的概率只比一半略高,也就是说,大约每隔一天就会碰上一次错误。
用例集还小的时候,解读这个数字要谨慎。只有 20 个用例时,一个用例结果翻转,pass^k 就会变动 5 个百分点;k 越小,单次运行的运气越容易让数字显得好看。
实践中,每个用例至少跑三次,再把整套评测重跑一遍,看数字是否波动,并且始终在结果旁注明用例数量和 k 值。
评测的最后一步最常被跳过。Anthropic 强调,不阅读多次尝试的运行记录和分数,就无法知道评分器打分是否准确。随机挑十个判为“通过”的运行,重新读一遍。过于宽松的评分器,比能力弱的 Agent 更危险。
检查:pytest 能跑完整套用例,但不必全部通过。用例来自真实失败,部分保持红色很正常,这些红色用例就是你的待办清单。README 应写明通过数与总数,并附一张按失败类别统计的 pass^3 表格。
第 5 步:为不运行代码的人准备 README 和视频
GitHub Docs 列出了 README 应回答的问题,第一个就是项目做什么。对 FDE 仓库来说,README 应该读起来像一篇简短的案例分析。
内容应包括:假想客户的问题,MVP 范围以及你刻意舍弃的部分,含 pass^k 的评测结果,仍未解决的三个失败,以及如果再给两周你会如何处理。
“遗留失败”这一节值得用心写。它让读者看到,你能衡量自己的系统,也能坦诚面对它的局限。
3 分钟视频要做给经理看,而不是给工程师看。一种分配方式:30 秒讲清问题,90 秒用 data/raw/ 里一张真实的脏发票运行 Agent,45 秒打开评测结果并读出 pass^k,最后 15 秒讲一个尚未修复的失败。不要录自己敲代码的画面。
常见错误
最常见的错误,是还没弄清需求就选了重量级框架,结果提示词被埋在五层类下面。其次是用自己生成的干净数据,评测一片绿,却什么也证明不了。第三是只报告最好的一次运行,而不报告 pass^k。
这项能力如何迁移到客户项目?
这五步不只适用于作品集,也是你在客户部署中必需的习惯,而仓库就是你最先练习的地方。
简历上别写笼统的“开发了 AI Agent”,而是写一句带数字的话,例如“基于真实失败构建了 40 个评测用例,将 pass^3 从 X 提升到 Y”,其中 X 和 Y 来自你自己的仓库。如果岗位描述提到“evaluation”或“reliability”,投递时附上这个仓库的链接。
让仓库提前回答每个客户迟早会问的问题:Agent 在哪里失败,失败得有多频繁?
这篇文章对你有帮助吗?
感谢你的反馈!
6 个信源
- Building effective agents · 2024-12-19
- Demystifying evals for AI agents · 2026-01-09
- Your AI Product Needs Evals · 2024-03-29
- Evaluation best practices (OpenAI API docs)
- How to build a forward deployed engineer portfolio · 2026-09-19
- About READMEs - GitHub Docs