# 用 W&B Weave 把客户投诉变成可重跑的评测

> 一个装饰器就能记下输入、输出和代码，随时翻出昨天失败的调用，证明修复确实有效。

原文: https://fdetimes.net/zh/tools/wandb-weave-trace-failures-into-evals/

设想你的工单分类智能体在客户那里上线后的第二周。运营负责人发来一张截图：一张计费工单被错误地分给了技术团队，她想知道原因。没有追踪记录，你只能靠猜。

用 W&B Weave，记录所需的代码很少：调用一次初始化函数，再给 Python 函数加一个装饰器，就能保存它的输入、输出，连同函数本身的代码。在此基础上，可以搭起每个前线部署工程师（FDE）都需要的闭环：看到失败，留住失败，再证明失败已经消除。

官方文档把 Weave 描述为一个可观测性与评测平台；它的 PyPI 页面说得更简短：一个用于追踪和评测 AI 智能体的工具包。如果你要把 LLM 应用带进客户环境，这类工具应该在第一次质量沟通会之前就位，而不是之后。

## FDE 什么时候需要 Weave？

用这个标准判断：如果客户今天下午问起昨天的某次调用，而你无法重新打开它的输入和输出，那就该上追踪了。Weave 适用的条件是：应用运行在 Python 3.10 或更高版本上，智能体已经在处理真实请求，并且客户的安全团队同意记录这些内容。

以上面那张计费工单为例，讨论会从“大概是提示词的问题”变成一条具体的记录，包含输入、输出、延迟和 token 用量，双方都能看懂。

反过来，用假数据做的一次性演示暂时还用不上，因为没有真实失败可留。评测要等到你手里有了真实失败、又准备修改提示词或模型时才值得投入，因为那时你需要知道这次修复有没有弄坏别的地方。

## 一行初始化，一个装饰器

先从追踪开始。`weave.init` 接收一个 团队/项目 路径，项目不存在时会自动创建。

```python
import weave
from openai import OpenAI

weave.init("acme/ticket-triage")
client = OpenAI()

@weave.op
def classify_ticket(text: str) -> str:
    response = client.chat.completions.create(
        model=MODEL_NAME,
        messages=[{"role": "user", "content": PROMPT + text}],
    )
    return response.choices[0].message.content
```

代码中两个大写名称需要自己填写，运行前必须先定义。`MODEL_NAME` 是项目使用的模型，`PROMPT` 是分类指令，比如要求模型只返回 `billing` 或 `access` 这样的标签。

内部的 LLM 调用如果属于受支持的类型，就不需要单独加装饰器，因为 Weave 会自动追踪这些调用。`@weave.op` 用于你自己的代码：预处理、检索、后置检查。到客户那里的第一件事，就是把它加到出问题时你必须解释清楚的那些函数上，不多也不少。

## 从截图到测试

追踪能告诉你发生了什么，但无法阻止它再次发生。Weave 的文档提到，评测集中的样例通常是需要测试的失败案例，和单元测试很像。如果只能从 Weave 带走一个习惯用到其他项目，就选这一个。

**要点:** 客户的失败案例，只有变成可重跑的测试才有价值。

Dataset 可以从已追踪的调用生成：在界面中选中一个或多个调用，或在 Python 中使用 `Dataset.from_calls`。调用只给出失败那次运行的输入和输出，正确答案仍需自己补上。请运营负责人确认标签，因为懂业务的人通常比靠猜的工程师更可靠。

下面的代码手写了几行数据，方便看清结构，而且只勾勒了主要步骤；函数签名请对照你实际安装版本的文档核实。每一行都有自己的 `id`，以便之后跨运行对比。

```python
import asyncio

rows = [
    {"id": "case-01", "text": "九月发票被重复扣款", "expected": "billing"},
    {"id": "case-02", "text": "SSO 变更后无法登录", "expected": "access"},
]
dataset = weave.Dataset(name="ticket-failures", rows=rows)
weave.publish(dataset)

@weave.op
def exact_match(expected: str, output: str) -> dict:
    return {"correct": expected == output}

evaluation = weave.Evaluation(dataset=dataset, scorers=[exact_match])
asyncio.run(evaluation.evaluate(classify_ticket))
```

评分器必须有一个 `output` 参数，并返回一个分数字典。至于 `Evaluation`，文档把它比作一份蓝图，每调用一次 `.evaluate()` 就是一次运行。蓝图保持不变，改提示词或模型，然后再测一次。

## 总分可能会误导你

假设评测集里有 20 个真实失败，第一次运行答对 14 个，即 70%。你修改了提示词，下一次运行答对 17 个，即 85%。告诉客户质量提升了 15 个百分点，听起来很不错。

但要逐条看得分。可能你修好了 5 个案例，同时弄坏了 2 个原本正确的：14 加 5 减 2，结果同样是 17。如果这 2 个恰好是客户最在意的工单类型，85% 还不足以进入生产环境。

所以每次运行都需要单独一个 JSON 文件，每个案例一个键：键是案例的 `id`，值是评分器返回的 `correct`。数据可以通过 Python SDK 的 `client.get_calls` 获取；界面也可以导出选中的行或全部行。

有两件事需要到 [Query and export calls 页面](https://docs.coreweave.com/weave/guides/tracking/querying-calls) 查清，并对照实际安装的版本核实：如何筛选出属于某次运行的调用，以及存放 `id` 和分数的字段名。如果暂时找不到，备用办法是自己对每一行运行 `classify_ticket` 和 `exact_match`，再写入文件：

```python
import json

results = {}
for row in rows:
    output = classify_ticket(row["text"])
    results[row["id"]] = exact_match(row["expected"], output)["correct"]

with open("run_1.json", "w") as f:  # 第二次运行写入 run_2.json
    json.dump(results, f)
```

无论数据从哪里来，两个文件的格式必须一致，下面的对比才能运行。

```python
import json

# run_1.json、run_2.json 的格式：{"case-01": true, "case-02": true, "case-03": false}
run_1 = json.load(open("run_1.json"))
run_2 = json.load(open("run_2.json"))
assert run_1.keys() == run_2.keys()  # 两次运行必须覆盖相同的案例

fixed = [c for c in run_1 if not run_1[c] and run_2[c]]
regressions = [c for c in run_1 if run_1[c] and not run_2[c]]
```

`regressions` 列表才是该带去客户会议的内容，要在报告总分之前讲。

## 难的部分，装饰器帮不了你

第一个限制来自它的工作方式：`@weave.op` 只记录你标注的函数，自动追踪也只覆盖受支持的 LLM 调用。如果客户使用内部的 LLM 网关，要尽早测试它是否出现在追踪里，不要想当然。

第二个限制更关键。追踪会记录输入和输出，也就是说客户工单的内容，可能包括个人数据，都会存放在里面。对真实数据开启追踪之前，要和客户的安全团队一起确定数据存在哪里、谁能查看。

关于厂商和版本，有两点需要注意。CoreWeave 于 2025 年 5 月 5 日宣布完成对 Weights & Biases 的收购，Weave 的文档现在位于 docs.coreweave.com，因此在发给客户的文件中要把这层关系写清楚。

PyPI 上的 `weave` 包要求 Python 3.10 或更高版本；请锁定你测试过的确切版本，例如 `weave==0.54.0`。

最后，Weave 只能衡量评分器所衡量的东西。精确匹配适合分类问题，但面对自由文本，无论用 LLM 评审还是自定义评分器，“好”的标准仍要由你来定义，而且必须和客户达成一致。

## 先学什么，简历上写什么

按闭环的顺序学：先追踪，再 Dataset，然后是配一个简单评分器的 Evaluation。手里还没有 20 个真实失败之前，不要急着写复杂的评分器；一个好的数据集，比在编造数据上用精巧的评分方法更有用。

阅读 FDE 或应用 AI 岗位的招聘要求时，留意 evals 和 observability 这两个关键词，然后准备一个有数字的故事。一条有分量的简历描述应当说清：你用多少个真实失败搭建了评测集，前后得分各是多少，以及你在哪个回归进入生产环境之前拦住了它。工具叫什么名字反而是小事。

## 练习：建立你自己的回归列表

从数据集中取 20 个失败案例，运行一次，把逐条得分保存到 `run_1.json`。修改提示词中的一处细节，运行第二次，保存到 `run_2.json`，再用上面的 Python 代码对比两个文件。

数一数从错变对的案例和从对变错的案例各有多少。验算方法：用第一次运行的得分，加上修好的案例数，减去弄坏的案例数，结果必须等于第二次运行的得分，就像上文的 14 加 5 减 2 等于 17。

然后给客户写两句话的汇报。第一句给出前后得分；第二句点名刚刚出错的案例，以及你打算怎么处理。

下次客户再发来一张回答错误的截图，不要只是改提示词。往数据集里加一行，下一次测量就能告诉你这个失败有没有再出现。

**本周动手试试:**

- 在项目中选一个 LLM 函数，加上 weave.init 和 @weave.op，然后阅读 10 次调用的追踪记录。
- 把 20 个真实失败写进一个 Dataset，配一个简单的匹配评分器，并把第一次运行的逐条得分保存到以 id 为键的 JSON 文件中。
- 为客户的安全团队准备一份问题清单：追踪里包含什么、存放在哪里、谁能查看。

## 信源

- [W&B Weave](https://docs.coreweave.com/weave)

- [Weave by Weights & Biases](https://raw.githubusercontent.com/wandb/weave/master/README.md)

- [Quickstart: Instrument and trace functions](https://docs.coreweave.com/weave/quickstart)

- [Collect and track datasets](https://docs.coreweave.com/weave/guides/core-types/datasets)

- [Evaluations overview](https://docs.coreweave.com/weave/guides/core-types/evaluations)

- [Query and export calls (Weave docs)](https://docs.coreweave.com/weave/guides/tracking/querying-calls)

- [weave · PyPI](https://pypi.org/project/weave/)

- [CoreWeave Completes Acquisition of Weights & Biases (investor relations)](https://investors.coreweave.com/news/news-details/2025/CoreWeave-Completes-Acquisition-of-Weights--Biases/default.aspx)
