FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

FDE 作品集仓库,要展示 Agent 在哪里失败

单次正确率 80% 的 Agent,连对三次只有 51%,基于真实失败的评测胜过精美演示。

分享微博

要点速览

  • 一个附带案例分析的深度项目,胜过许多精美演示;选一个带脏数据的真实企业场景。
  • Agent 循环保持简单易读,把精力投在工具描述上,从一开始就记录每次运行。
  • 从真实失败构建评测,先用低成本断言,报告 pass^k,并阅读运行记录来检验评分器。
醒目的橙色数字 51.2%:单次正确率 80% 的 Agent,连续三次都答对的概率只有 51.2%(0.8 × 0.8 × 0.8)。两根柱子在 0–100% 的刻度上对比:单次运行 80%,连续三次 51.2%。
Pass^k 是 k 次尝试全部成功的概率。假设各次运行相互独立,单次正确率 80% 的 Agent 连续三次答对的概率只有 51.2%。来源:本文计算,依据 Anthropic 对 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 个信源
路线图上的下一篇 · 阶段 8: 职业发展FDE 简历上,“6周缩到9天”胜过“提升效率”经验不足八年就只写一页,每条先写结果;无法核实的数字宁可空着,也别估得好看。