每分钟 10 次请求:从 Zendesk 拉出能做评测的干净工单
需要一个会等待的循环、一个保存好的游标,以及 300 条按预期结果而非措辞标注的工单。
要点速览
- Zendesk 增量导出端点每分钟只允许 10 次请求,客户购买 High Volume 附加组件后为 30 次,且整组端点共享这一限额。
- 使用基于游标的导出,在 end_of_stream 时停止,按 id 去重,并在构建评测集前剔除已删除的工单。
- 第一版黄金评测集约 300 条工单,分层抽样,入集时即对 PII 脱敏,每个版本的改动都要记录。
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 响应头,说明要等多少秒才能重试。拉取器需要读取这个响应头,并精确地休眠这么久。
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 参数在源头剔除已删除的工单。
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 为键的字典仍然值得保留:一条被多次编辑的工单,在评测集里只应占一行。
已删除的工单是第二个陷阱。它们的记录仍然存在,所以仍可能出现在导出结果里;一旦混进评测集,就成了谁也无法再核实的用例。再加一道按状态的安全过滤:
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 的一行
取一条示意工单,只保留几个字段;真实工单字段多得多,字段名应对照客户的导出结果核实:
{"id": 4821, "status": "solved",
"subject": "我的订单到货时已损坏,我要退款",
"description": "订单 #A-1093 昨天到货,陶瓷花瓶摔成了两半。我要退款,不要换货。"}
基准答案通常来自客服人员实际解决工单的方式:这里是退款、复述订单号、无需升级。评测行原样记录这些:
{"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 脱敏必须在工单进入评测集的那一刻完成,而不是等到之后发布时。评测集就是附带答案的客户数据,它会被复制到比预想更多的地方。
悄悄污染数据的几类错误
最难发现的是把 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 的可信程度取决于背后的评测集。而评测集的可信程度,取决于为它供数的那个循环,一条工单都不能漏。
这篇文章对你有帮助吗?
感谢你的反馈!
8 个信源
- Rate limits | Zendesk API reference
- Incremental Exports | Zendesk API reference
- Using the Incremental Exports API | Zendesk Developer Documentation
- Zendesk API incremental export: A complete developer guide
- Evals for Email Agents: Building a Golden Set From Real Tickets
- The Support Ticket to Eval Case Pipeline Nobody Builds · 2026-05-14
- Eval Datasets Are Customer Data With a Right Answer Attached · 2026-05-10
- How to Build a Golden Evaluation Dataset from Real LLM Production Failures · 2026-08-31