# 每分钟 10 次请求：从 Zendesk 拉出能做评测的干净工单

> 需要一个会等待的循环、一个保存好的游标，以及 300 条按预期结果而非措辞标注的工单。

原文: https://fdetimes.net/zh/guides/zendesk-incremental-export-eval-set/

Zendesk 的增量导出端点每分钟只给 10 次请求，而且这一限额由整组端点共享。High Volume 附加组件可以把它提高到 30 次。这个上限决定了拿到客户真实客服历史需要多长时间。

这些历史是所有客服 Agent 项目的原材料。客户请前线部署工程师（FDE）构建一个回复客服邮件的 Agent 时，第一个问题总是“它答得对吗？”，而唯一的回答方式，是用真实工单构建的评测集。这意味着拉取工单时既不能被封，也不能漏数据，还不能重复计数。

下文逐一处理每项工作：一个由游标驱动的 Python 拉取器、一个节流器、429 处理，以及把原始工单变成第一版黄金评测集的步骤。

## 要构建什么，事先需要准备什么

最终产物是两个文件。`tickets.jsonl` 存放去重、过滤后的工单；`golden.jsonl` 存放约 300 条已标注的评测用例。旁边还有一个 `cursor.txt`，下次运行只拉取新增内容。

需要安装了 `requests` 库的 Python 3、一个开通了 API 访问的 Zendesk 账号（最好是沙箱），以及该账号的子域名。下面的代码做了简化：认证部分假设已有一个携带凭据的 `requests.Session`；正式运行前，端点名称和游标参数应对照 Incremental Exports 页面核实。

## 第 1 步：运行前先算账

最短运行时间只取决于要拉取的页数，因为每页消耗一次请求。先在沙箱上试跑，看一页实际包含多少条工单，再用工单历史总量除以这个数。

以一段需要 300 页的历史为例：每分钟 10 次请求，至少要 30 分钟；如果客户有 High Volume，至少 10 分钟。这只是下限，还没算上 429 强制的等待。

由于整个 Incremental Exports 端点组共享限额，运行前要问客户：是否有其他集成在调用这些端点。如果有，拉取器会和对方系统争抢同样的每分钟 10 次请求，上面的估算就得拉长。

开始前就把这个数字告诉客户。一次没人事先知情的 30 分钟数据拉取，很容易被当成机器卡死。

## 第 2 步：写一个会等待的 API 调用

超出限额时，Zendesk 返回 429，并附带 `Retry-After` 响应头，说明要等多少秒才能重试。拉取器需要读取这个响应头，并精确地休眠这么久。

```python
import time, requests

BASE = "https://SUBDOMAIN.zendesk.com"
# 工单的游标端点；路径请对照 Incremental Exports 页面核实
PATH = "/api/v2/incremental/tickets/cursor.json"
MIN_GAP = 60 / 10  # 每次请求间隔 6 秒；有 High Volume 时改为 60/30

def get_page(session, params):
    while True:
        r = session.get(BASE + PATH, params=params, timeout=60)
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "60")))
            continue
        r.raise_for_status()
        return r.json()
```

缺少响应头时默认等 60 秒，是这段代码出于谨慎的选择，并非 Zendesk 的规定。**检查：**在沙箱上故意把 `MIN_GAP` 调成 0。应当看到 429 出现，随后循环自行恢复，不会崩溃。

## 第 3 步：用游标分页，在 end_of_stream 时停止

Zendesk 推荐基于游标的导出。`start_time` 参数只在第一次请求时使用，且必须早于当前时间一分钟以上，以免漏数据；从第二次请求起只发送游标。`exclude_deleted` 参数在源头剔除已删除的工单。

```python
def pull(session, start_time=None, cursor=None):
    params = {"exclude_deleted": "true"}
    if cursor:
        params["cursor"] = cursor
    else:
        params["start_time"] = start_time  # 必须早于 now - 60 秒
    tickets = {}
    while True:
        t0 = time.monotonic()
        data = get_page(session, params)
        for t in data.get("tickets", []):
            tickets[t["id"]] = t  # 按 id 覆盖：保留最新版本
        if data.get("end_of_stream"):
            return tickets, data.get("after_cursor")
        params = {"exclude_deleted": "true", "cursor": data["after_cursor"]}
        wait = MIN_GAP - (time.monotonic() - t0)
        if wait > 0:
            time.sleep(wait)
```

停止条件是 `end_of_stream`，与 Zendesk 的指引完全一致。不要因为某一页看起来很短就推断已到末尾：那是猜测，而这个标志才是官方信号。

循环结束后，把最后一个游标写入 `cursor.txt`。下次运行调用 `pull(session, cursor=...)`，只会收到发生过变更的工单。**检查：**连续运行两次，第二次返回的工单应当极少，甚至为零。

## 为什么还要去重和过滤？

Zendesk 文档提醒，基于时间的导出可能包含重复记录，建议按 ID 加时间戳去重。基于游标的导出能避免大量记录共享同一时间戳时产生的重复，但以 `id` 为键的字典仍然值得保留：一条被多次编辑的工单，在评测集里只应占一行。

已删除的工单是第二个陷阱。它们的记录仍然存在，所以仍可能出现在导出结果里；一旦混进评测集，就成了谁也无法再核实的用例。再加一道按状态的安全过滤：

```python
clean = [t for t in tickets.values() if t.get("status") != "deleted"]
```

打印过滤前后的数量。如果被剔除的比例异常高，这个问题值得带到与客户客服团队的会议上。

## 第 4 步：标注每条工单所需的结果

从 `clean` 中抽取约 300 条工单。Robylon 的指南认为，对每月处理几千封邮件的团队来说，300 到 600 条已标注工单足以构成第一版可用的黄金评测集。同一来源建议分层抽样，并让两个人独立标注一个重叠子集，以检验自己的标注是否一致。

标注应在每个维度上记录预期结果。一封客服邮件可以有很多种正确的措辞，拿文本和标准答案逐字比对，会不公平地惩罚正确的回复：

| 字段 | 示例值 | 评分方式 |
|---|---|---|
| `expected_actions` | `["issue_refund"]` | Agent 是否调用了正确的动作 |
| `expected_facts` | `["订单已于日期 X 送达"]` | 回复是否陈述了正确的事实 |
| `should_escalate` | `true` | 是否在正确的时机转交人工 |

表中每一行单独报告一个数字，不要取平均。动作和升级分开打分，能让客户清楚看到该改哪里；一个合并的总分会把问题掩盖掉。

## 一条工单变成 golden.jsonl 的一行

取一条示意工单，只保留几个字段；真实工单字段多得多，字段名应对照客户的导出结果核实：

```json
{"id": 4821, "status": "solved",
 "subject": "我的订单到货时已损坏，我要退款",
 "description": "订单 #A-1093 昨天到货，陶瓷花瓶摔成了两半。我要退款，不要换货。"}
```

基准答案通常来自客服人员实际解决工单的方式：这里是退款、复述订单号、无需升级。评测行原样记录这些：

```json
{"ticket_id": 4821,
 "input": "订单 #A-1093 昨天到货，陶瓷花瓶摔成了两半。我要退款，不要换货。",
 "expected_actions": ["issue_refund"],
 "expected_facts": ["订单号 A-1093", "客户要退款，不要换货"],
 "should_escalate": false,
 "labeled_by": "support_agent"}
```

Agent 写“对这个问题深表歉意”还是“给您带来不便，非常抱歉”，都算正确；而提出换货的 Agent 会在 `expected_facts` 上失分。**检查：**重读前 20 行，问自己两位不同的评分者能否得出同样的结果。

把任何一行写入 `golden.jsonl` 之前，先对 `input` 中的姓名、邮箱地址、电话号码和街道地址脱敏。Tian Pan 写道，PII 脱敏必须在工单进入评测集的那一刻完成，而不是等到之后发布时。评测集就是附带答案的客户数据，它会被复制到比预想更多的地方。

**要点:** 好的评测集给 Agent 做了什么打分，而不是给它写了什么字打分。

## 悄悄污染数据的几类错误

最难发现的是把 `start_time` 设得离现在太近。Zendesk 要求它早于当前时间一分钟以上，API 也会扣下最近一分钟的数据以避免竞态条件，因此时间戳太新会在没有任何报错的情况下丢掉工单。

其次是按页面大小结束循环，而不是等待 `end_of_stream`。中间只要有一页异常短，剩余的历史就会从数据集中消失。

第三是收到 429 后立即重试、无视 `Retry-After`，结果循环把请求白白耗在注定被拒的尝试上。

最后一个出在评测集本身：让黄金评测集一成不变。Tian Pan 建议，把连续九十天保持通过、且在套件其他地方有重复的用例归档。

OneUptime 的指南建议对数据集做版本管理。每次发布黄金评测集时，记录新增的用例、删除的用例、去掉的重复项以及已知局限。

新增用例的成本也很低。第 3 步保存的游标意味着，下次运行只拉取发生过变更的工单。

## 第一次客户会议带什么，简历上写什么

在申请对线上数据运行之前，先给客户的 IT 团队带去沙箱运行的三个数字：页数、429 次数，以及用第 1 步的算法估出的完整历史所需时间。同时带上那个问题：是否有集成共享 Incremental Exports 的限额。

这三个数字能让对方看到，拉取器不会把他们的系统拖垮。它们也正是该写进简历的数字。

一个可以填入自己数据的模板：“在每分钟 10 次请求的限额下，通过基于游标的导出拉取 N 条 Zendesk 工单，借助 Retry-After 处理 429；构建了 300 条 PII 脱敏的黄金评测集，对动作、事实和升级分别打分。”如果面试官追问，要能解释循环为什么在 `end_of_stream` 时停止，以及 `start_time` 为什么必须早于一分钟以上。

Agent 的可信程度取决于背后的评测集。而评测集的可信程度，取决于为它供数的那个循环，一条工单都不能漏。

**本周动手试试:**

- 把 start_time 设为几天前，对 Zendesk 沙箱运行 pull()，记录页数、工单数和 429 次数。
- 为评测用例写一个涵盖动作、事实和升级标志的 JSONL schema，自己标注 20 条工单，再请同事重新标注，比较一致程度。
- 在简历里加一行，描述自己构建过的一条数据管道，写明 API 的限流规则以及应对方式。

## 信源

- [Rate limits | Zendesk API reference](https://developer.zendesk.com/api-reference/introduction/rate-limits/)

- [Incremental Exports | Zendesk API reference](https://developer.zendesk.com/api-reference/ticketing/ticket-management/incremental_exports/)

- [Using the Incremental Exports API | Zendesk Developer Documentation](https://developer.zendesk.com/documentation/api-basics/working-with-data/using-the-incremental-export-api)

- [Zendesk API incremental export: A complete developer guide](https://www.eesel.ai/blog/zendesk-api-incremental-export)

- [Evals for Email Agents: Building a Golden Set From Real Tickets](https://www.robylon.ai/blog/llm-evals-customer-support-golden-set)

- [The Support Ticket to Eval Case Pipeline Nobody Builds](https://tianpan.co/blog/2026/05/14/support-ticket-to-eval-case-pipeline)

- [Eval Datasets Are Customer Data With a Right Answer Attached](https://tianpan.co/blog/2026/05/10/eval-datasets-customer-data-right-answer-attached)

- [How to Build a Golden Evaluation Dataset from Real LLM Production Failures](https://oneuptime.com/blog/post/2026-08-31-build-golden-evaluation-dataset-production-failures/view)
