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

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

技能指南 · 指南

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

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

分享微博

要点速览

  • Zendesk 增量导出端点每分钟只允许 10 次请求,客户购买 High Volume 附加组件后为 30 次,且整组端点共享这一限额。
  • 使用基于游标的导出,在 end_of_stream 时停止,按 id 去重,并在构建评测集前剔除已删除的工单。
  • 第一版黄金评测集约 300 条工单,分层抽样,入集时即对 PII 脱敏,每个版本的改动都要记录。
横向条形图:对于 300 页的工单历史,默认每分钟 10 次请求的限额至少需要 30 分钟;High Volume 附加组件每分钟 30 次请求,至少需要 10 分钟。
每页消耗一次请求,因此限流决定了最短拉取时间;这是下限,不含 429 错误后的等待。来源:Zendesk Incremental Exports 限额说明,计算见正文。

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 个信源
路线图上的下一篇 · 阶段 3: AI 应用一个CTE名字,足以骗过text-to-SQL智能体的只读防护SQLGlot自称是转译器而非校验器,语法树上的安全规则,包括作用域解析,都得自己动手写。