# Mười request mỗi phút: kéo ticket Zendesk đủ sạch để dựng tập eval

> Bạn cần một vòng lặp biết chờ, một cursor được lưu lại và 300 ticket gán nhãn theo kết quả mong đợi, không theo câu chữ.

Bản gốc: https://fdetimes.net/vi/bach-khoa/thuc-hanh-zendesk-incremental-export-tao-bo-eval/

Zendesk chỉ cho bạn 10 request mỗi phút vào các endpoint incremental export, và con số này là giới hạn chung cho cả nhóm endpoint đó. Add-on High Volume nâng nó lên 30. Giới hạn ấy quyết định bạn mất bao lâu để lấy được lịch sử hỗ trợ thật của khách hàng.

Lịch sử đó là nguyên liệu của mọi dự án agent chăm sóc khách hàng. Khi khách nhờ FDE dựng agent trả lời email hỗ trợ, câu hỏi đầu tiên của họ là "nó có đúng không?", và bạn chỉ trả lời được nếu có tập eval làm từ ticket thật. Muốn vậy, bạn phải kéo ticket ra mà không bị chặn, không sót dữ liệu và không đếm trùng.

Phần dưới đây làm lần lượt từng việc: một puller Python chạy bằng cursor, một bộ giữ nhịp, phần xử lý lỗi 429, rồi bước biến ticket thô thành golden set đầu tiên.

## Bạn sẽ dựng gì, và cần gì trước

Kết quả cuối là hai file. `tickets.jsonl` chứa ticket đã khử trùng và lọc; `golden.jsonl` chứa khoảng 300 eval case có nhãn. Kèm theo là `cursor.txt` để lần chạy sau chỉ kéo phần mới.

Bạn cần Python 3 với thư viện `requests`, một tài khoản Zendesk có quyền gọi API (sandbox là tốt nhất) và subdomain của tài khoản đó. Code dưới đây được giản lược: phần xác thực giả định bạn đã có một `requests.Session` gắn sẵn thông tin đăng nhập, và tên endpoint, tham số cursor cần đối chiếu lại với trang Incremental Exports trước khi chạy thật.

## Bước 1: Tính trước thời gian, đừng đoán

Thời gian chạy tối thiểu chỉ phụ thuộc vào số trang cần kéo, vì mỗi trang tốn một request. Hãy chạy thử trên sandbox để biết mỗi trang thực tế chứa bao nhiêu ticket, rồi chia tổng số ticket lịch sử cho con số đó.

Làm phép tính với một lịch sử cần 300 trang: ở 10 request mỗi phút, bạn cần ít nhất 30 phút; nếu khách có High Volume, ít nhất 10 phút. Đó là mức sàn, chưa tính những lần bị 429 bắt chờ.

Vì đây là giới hạn chung của cả nhóm Incremental Exports, trước khi chạy hãy hỏi khách còn tích hợp nào khác đang gọi các endpoint này. Nếu có, puller của bạn và hệ thống của họ sẽ tranh nhau cùng 10 request mỗi phút, và phép tính ở trên phải nới ra.

Báo con số này cho khách trước khi chạy. Một lần kéo dữ liệu 30 phút mà không ai biết trước rất dễ bị hiểu nhầm là treo máy.

## Bước 2: Viết hàm gọi API biết chờ

Khi vượt giới hạn, Zendesk trả về mã 429 kèm header `Retry-After`, cho biết phải đợi bao nhiêu giây trước khi thử lại. Puller cần đọc header này và ngủ đúng số giây đó.

```python
import time, requests

BASE = "https://SUBDOMAIN.zendesk.com"
# Endpoint cursor-based cho ticket; đối chiếu đường dẫn trong trang Incremental Exports
PATH = "/api/v2/incremental/tickets/cursor.json"
MIN_GAP = 60 / 10  # 6 giây/request; đổi thành 60/30 nếu có High Volume

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()
```

Giá trị mặc định 60 giây khi thiếu header là lựa chọn thận trọng của riêng đoạn code này, không phải quy định của Zendesk. **Kiểm tra:** cố tình hạ `MIN_GAP` xuống 0 trên sandbox. Bạn phải thấy 429 xuất hiện, rồi vòng lặp tự hồi phục mà không văng lỗi.

## Bước 3: Phân trang bằng cursor, dừng bằng end_of_stream

Zendesk khuyến nghị dùng cursor-based export. Tham số `start_time` chỉ dùng ở request đầu tiên, và mốc này phải cách hiện tại hơn một phút để không sót dữ liệu; từ request thứ hai, bạn chỉ gửi cursor. Tham số `exclude_deleted` giúp bỏ ticket đã xóa ngay từ nguồn.

```python
def pull(session, start_time=None, cursor=None):
    params = {"exclude_deleted": "true"}
    if cursor:
        params["cursor"] = cursor
    else:
        params["start_time"] = start_time  # phải cũ hơn now - 60 giây
    tickets = {}
    while True:
        t0 = time.monotonic()
        data = get_page(session, params)
        for t in data.get("tickets", []):
            tickets[t["id"]] = t  # ghi đè theo id: giữ bản mới nhất
        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)
```

Điều kiện dừng là `end_of_stream`, theo đúng hướng dẫn của Zendesk. Đừng tự suy ra điểm kết thúc từ việc một trang trông có vẻ ngắn, vì đó là phỏng đoán, còn cờ kia là tín hiệu chính thức.

Khi vòng lặp kết thúc, ghi cursor cuối vào `cursor.txt`. Lần chạy sau gọi `pull(session, cursor=...)` và chỉ nhận ticket đã thay đổi. **Kiểm tra:** chạy hai lần liền nhau; lần thứ hai phải trả về rất ít ticket hoặc không có ticket nào.

## Vì sao vẫn phải khử trùng và lọc?

Tài liệu Zendesk cảnh báo rằng export theo thời gian có thể chứa mục trùng, và khuyên khử trùng theo ID cộng timestamp. Cursor-based export tránh được bản ghi trùng khi nhiều mục chung một timestamp, nhưng dictionary theo `id` vẫn đáng giữ: một ticket sửa nhiều lần chỉ nên chiếm một dòng trong tập eval.

Ticket đã xóa là cái bẫy thứ hai. Bản ghi của chúng vẫn tồn tại nên chúng vẫn có thể xuất hiện trong export, và nếu lọt vào tập eval, chúng thành những case chẳng ai còn kiểm chứng được. Thêm một lớp lọc an toàn theo trạng thái:

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

In số lượng trước và sau khi lọc. Nếu tỷ lệ bị loại cao bất thường, đó là câu hỏi đáng mang tới buổi họp với đội hỗ trợ của khách.

## Bước 4: Gán nhãn kết quả, đừng gán nhãn câu trả lời

Từ `clean`, lấy mẫu khoảng 300 ticket. Hướng dẫn của Robylon cho rằng 300 đến 600 ticket có nhãn là một golden set đầu tiên dùng được cho đội xử lý vài nghìn email mỗi tháng. Nguồn này cũng khuyên lấy mẫu phân tầng và cho hai người gán nhãn độc lập trên một phần chồng lấn, để biết chính nhãn của bạn có nhất quán không.

Nhãn nên ghi kết quả mong đợi theo từng chiều. Một email hỗ trợ có thể được trả lời đúng bằng nhiều cách viết, nên so chữ với một câu trả lời mẫu sẽ phạt oan những câu trả lời đúng:

| Trường | Ví dụ giá trị | Chấm thế nào |
|---|---|---|
| `expected_actions` | `["issue_refund"]` | Agent có gọi đúng hành động không |
| `expected_facts` | `["đơn đã giao ngày X"]` | Câu trả lời có nêu đúng dữ kiện không |
| `should_escalate` | `true` | Có chuyển cho người thật đúng lúc không |

Báo một con số riêng cho mỗi dòng trong bảng, đừng gộp thành điểm trung bình. Điểm riêng cho hành động và cho chuyển cấp giúp khách thấy đúng chỗ cần sửa, còn một điểm chung sẽ che mất chỗ đó.

## Một ticket thành một dòng golden.jsonl

Lấy một ticket minh họa, rút gọn còn vài trường; ticket thật có nhiều trường hơn và tên trường cần đối chiếu với export của khách:

```json
{"id": 4821, "status": "solved",
 "subject": "Hàng tới bị vỡ, tôi muốn hoàn tiền",
 "description": "Đơn #A-1093 giao hôm qua, bình gốm vỡ làm đôi. Tôi muốn hoàn tiền, không đổi hàng."}
```

Ground truth thường đến từ cách nhân viên hỗ trợ đã giải quyết ticket: ở đây là hoàn tiền, nhắc lại mã đơn, không cần chuyển cấp. Dòng eval ghi đúng những điều đó:

```json
{"ticket_id": 4821,
 "input": "Đơn #A-1093 giao hôm qua, bình gốm vỡ làm đôi. Tôi muốn hoàn tiền, không đổi hàng.",
 "expected_actions": ["issue_refund"],
 "expected_facts": ["mã đơn A-1093", "khách muốn hoàn tiền, không đổi hàng"],
 "should_escalate": false,
 "labelled_by": "support_agent"}
```

Agent viết "rất tiếc về sự cố" hay "xin lỗi vì bất tiện" đều được tính đúng; agent đề nghị đổi hàng thì trượt ở `expected_facts`. **Kiểm tra:** đọc lại 20 dòng đầu và hỏi liệu hai người chấm khác nhau có cho cùng một kết quả không.

Trước khi ghi dòng nào vào `golden.jsonl`, hãy che tên, email, số điện thoại và địa chỉ trong `input`. Tian Pan viết rằng việc che PII phải làm ngay lúc một ticket được đưa vào tập eval, chứ không đợi tới khi công bố. Tập eval là dữ liệu khách hàng kèm sẵn đáp án, và nó sẽ được chép đi nhiều nơi hơn bạn nghĩ.

**Điểm mấu chốt:** Tập eval tốt chấm điều agent làm, không chấm câu chữ agent viết.

## Những lỗi khiến dữ liệu hỏng âm thầm

Lỗi khó thấy nhất là đặt `start_time` sát giờ hiện tại. Zendesk yêu cầu mốc này cách hiện tại hơn một phút, và API cũng giữ lại dữ liệu của phút gần nhất để tránh race condition, nên mốc quá mới sẽ làm sót ticket mà không báo lỗi gì.

Lỗi tiếp theo là kết thúc vòng lặp theo kích thước trang thay vì chờ `end_of_stream`. Chỉ cần một trang ngắn bất thường ở giữa, phần còn lại của lịch sử sẽ biến mất khỏi tập dữ liệu.

Lỗi thứ ba là thử lại ngay sau 429 mà bỏ qua `Retry-After`, khiến vòng lặp đốt request vào những lần chắc chắn bị từ chối.

Lỗi cuối cùng nằm ở tập eval: để golden set đứng yên. Tian Pan đề xuất lưu trữ những case đã xanh suốt chín mươi ngày và có bản trùng trong bộ eval.

Hướng dẫn của OneUptime khuyên đánh phiên bản cho dataset. Mỗi lần phát hành golden set, hãy ghi lại những case được thêm, những case bị bỏ, các bản trùng đã khử và những hạn chế đã biết.

Việc bổ sung case mới cũng không tốn kém. Cursor bạn lưu ở Bước 3 cho phép lần sau chỉ kéo những ticket đã thay đổi.

## Mang gì tới buổi họp đầu với khách, và ghi gì lên CV

Trước khi xin quyền chạy trên dữ liệu thật, hãy mang tới đội IT của khách ba con số từ lần chạy sandbox: số trang, số lần gặp 429 và thời gian ước tính cho toàn bộ lịch sử theo phép tính ở Bước 1. Kèm theo đó là câu hỏi về các tích hợp đang dùng chung giới hạn Incremental Exports.

Ba con số ấy cho họ thấy puller của bạn sẽ không làm nghẽn hệ thống. Chúng cũng chính là những con số nên có mặt trong CV của bạn.

Một mẫu để điền số thật của mình: "Kéo N ticket Zendesk bằng cursor-based export dưới giới hạn 10 request/phút, xử lý 429 theo Retry-After; dựng golden set 300 case đã che PII, chấm riêng hành động, dữ kiện và chuyển cấp." Nếu người phỏng vấn hỏi tiếp, hãy sẵn sàng giải thích vì sao vòng lặp dừng theo `end_of_stream` và vì sao `start_time` phải cũ hơn một phút.

Agent chỉ đáng tin bằng tập eval đứng sau nó. Còn tập eval chỉ đáng tin khi vòng lặp lấy dữ liệu cho nó không bỏ sót ticket nào.

**Thử ngay tuần này:**

- Chạy hàm pull() trên một sandbox Zendesk với start_time lùi vài ngày, rồi ghi lại số trang, số ticket và số lần gặp 429.
- Viết schema JSONL cho một eval case gồm hành động, dữ kiện và cờ chuyển cấp, tự gán nhãn 20 ticket rồi nhờ một đồng nghiệp gán lại để so độ khớp.
- Thêm vào CV một dòng về pipeline dữ liệu bạn từng làm, ghi rõ giới hạn tốc độ của API và cách bạn xử lý nó.

## Nguồn

- [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)
