原文内容

AI 辅助设计长时间 API 调用任务的可观测运行方案

面向 USTC Token Plan / 词元计划成长营的实践案例。
关键词：后台任务、JSONL、健康检查、状态文件、长任务复盘。

这个案例解决什么问题

我觉得长时间 API 任务最容易出问题的地方，不是脚本不会启动。

而是我们太容易把「启动了」误认为「正在健康运行」。

这两个东西差很多。

一个后台进程存在，只能说明程序还没退出。它不能证明 API 请求真的在成功完成，也不能证明 token usage 在变化，更不能证明任务结果可复盘。

在校园模型 API 评测和批处理任务里，尤其容易遇到这种情况：

• 单次请求可能很慢；
• 平台统计可能只在请求完成后更新；
• 任务可能要后台跑几十分钟到数小时；
• 启动器打印了「已启动 N 个 worker」，但后面到底有没有成功请求，其实没人知道。

所以这个案例的核心不是「怎么让脚本在后台跑」。

这个很简单。

真正要解决的是，脚本跑起来以后，我们怎么判断它是否健康。

我采用的判断标准

我把信号分成两类。

第一类是启动信号。

比如：

• 进程存在；
• 终端没有立即报错；
• 日志里写了启动参数；
• worker 数打印出来了。

这些信号有用，但只能说明任务开始了。

第二类是完成信号。

比如：

• JSONL 结果文件新增了 ok=true 记录；
• 完成请求数持续增加；
• 最近成功时间还在更新；
• 成功记录里有模型名、耗时、输入 token、输出 token；
• 错误不是单一重复的 401、403、429、timeout 或 network error。

我现在更相信第二类信号。

如果一个任务说自己在跑，但 30 分钟没有任何成功请求，那它大概率不是「慢」，而是需要检查了。

方案设计

我把长时间 API 任务拆成四层。

1. 后台运行层

后台启动脚本只负责启动任务，并把 stdout 和 stderr 落盘。

它不负责宣称任务成功。

PowerShell 示例：

$runId = Get-Date -Format "yyyyMMdd-HHmmss"
$logPath = ".\runs\api-run-$runId.log"
$jsonlPath = ".\runs\api-run-$runId.jsonl"

Start-Process powershell -WindowStyle Hidden -ArgumentList @(
  "-NoProfile",
  "-ExecutionPolicy", "Bypass",
  "-File", ".\run_api_batch.ps1",
  "-ResultPath", $jsonlPath,
  "-LogPath", $logPath
)

这段逻辑只说明任务被放进后台。

后面是否健康，要看 JSONL、状态文件和日志。

2. 请求记录层

每个 API 请求都写入一行 JSONL。

成功和失败都要写。

因为失败分布本身就是评测结果的一部分。

成功记录示例：

{"ts":"2026-05-XXT10:00:02+08:00","request_id":"demo-001","model":"example-model-a","ok":true,"status":200,"latency_ms":48210,"input_tokens":1200,"output_tokens":3800,"total_tokens":5000,"error_type":null}

失败记录示例：

{"ts":"2026-05-XXT10:03:15+08:00","request_id":"demo-002","model":"example-model-a","ok":false,"status":429,"latency_ms":1300,"input_tokens":0,"output_tokens":0,"total_tokens":0,"error_type":"rate_limit"}

这种结构看起来朴素，但很可靠：

• 文件可以边运行边追加；
• 单次失败不会破坏整体结果；
• 后续可以统计成功率、错误类型和延迟分布；
• 不需要保存模型完整输出，日志更轻，也更适合复盘。

3. 状态文件层

长任务最好周期性写一个 latest-status.json。

它不需要包含完整日志，只要包含人和脚本都能看懂的健康摘要。

示例：

{
  "run_id": "demo_run_001",
  "state": "running",
  "last_success_at": "2026-05-XXT10:24:18+08:00",
  "completed_requests": 42,
  "failed_requests": 6,
  "total_tokens": 185432,
  "recent_error_types": {
    "rate_limit": 4,
    "timeout": 2
  },
  "health": "healthy"
}

这个文件的好处是，它让健康检查不依赖 AI 一直在线。

人可以看。

定时任务可以看。

CI 或监控脚本也可以看。

4. 健康检查层

健康检查不关心任务「看起来是不是还在跑」。

它关心最近一段时间是否真的有完成请求。

我会让检查脚本做几件事：

读取最新 JSONL 文件
统计总行数、成功行数、失败行数
找到最近一条 ok=true 的记录时间
统计最近 N 条错误的 error_type 分布

如果进程存在，但 30 分钟内没有任何成功请求：
    标记为 unhealthy
如果错误几乎全部是 401 或 403：
    标记为 auth_failed
如果错误几乎全部是 429：
    标记为 rate_limited，并建议降低并发或 QPS
如果成功请求数持续增长：
    标记为 healthy
如果进程已退出：
    结合 exit_code、最后日志和 JSONL 汇总判断是完成、失败还是被中断

这个检查能解决一个很烦的问题。

进程还在，但可能一直在重复失败。

平台统计没动，也可能只是因为第一批长请求还没完成。

没有结构化日志的时候，这两种情况很难分清。

目录内容

这个案例里，我放了几个可以直接参考的示例文件。

long-task-healthcheck/
├── README.md
├── examples/
│   ├── api-run.sample.jsonl
│   └── latest-status.sample.json
├── reports/
│   └── healthcheck-report.sample.md
└── scripts/
    └── healthcheck_jsonl.example.py

如何做一次本地健康检查

先准备一份 JSONL 结果文件。

可以直接使用示例文件：

python .\scripts\healthcheck_jsonl.example.py `
  --jsonl .\examples\api-run.sample.jsonl `
  --output .\runs\latest-status.local.json `
  --stale-minutes 30

脚本会读取 JSONL，统计成功请求、失败请求、最近成功时间、错误类型分布，并写出一个状态 JSON。

这个示例脚本不需要 API Key。

它只检查日志，不调用外部接口。

这也是我喜欢这种设计的原因。健康检查应该尽量独立，不能每次都依赖模型服务本身继续可用。

AI 在这里帮了什么

AI 在这个案例里适合做三件事。

第一，把人工经验转成脚本参数。

比如并发、QPS、超时、重试、退避时间，这些东西如果只写在脑子里，很容易每次都靠感觉调。

第二，把终端输出转成结构化数据。

终端输出适合当场看，但不适合事后统计。JSONL 和状态文件虽然朴素，但非常适合复盘。

第三，把「感觉卡住了」转成可验证条件。

比如，不再说「好像没动静」，而是说「30 分钟内没有任何 ok=true 记录」「最近 20 条失败里 18 条是 rate_limit」「进程存在但完成请求数没有增长」。

这就是工程化的好处。

它让讨论从感觉变成证据。

我从这个案例里学到的几件事

1. 启动成功不是运行健康

启动器只能说明任务被拉起来了。

真正要看的是请求有没有完成。

2. 长任务默认就应该可观测

只要一个任务会跑超过几分钟，就应该有日志、JSONL 和状态文件。

不要等出问题以后再想怎么排查。

3. 健康检查要能脱离 AI 自己运行

AI 可以帮忙写检查脚本，但检查脚本不能依赖 AI 一直在线。

它应该能被人、定时任务或 CI 直接读取。

4. 错误分布比单条错误更重要

一条 429 不一定说明任务坏了。

连续大量 429，就说明该降速了。

一条 timeout 可能只是长任务慢。

大量 timeout，就要重新看 timeout、输出长度和网络环境。

5. 报告要服务下一步行动

报告不是为了把日志漂亮地复述一遍。

它应该告诉我们下一步是继续观察、降低 QPS、增加 timeout、检查鉴权，还是停止任务。

给成长营同学的建议

如果你准备用词元计划做模型 API 评测、批处理、长文本生成或多模型对比，我建议从一开始就把任务当成一个小型可观测系统来设计。

不要只问「怎么跑起来」。

还要问：

• 跑起来以后怎么看它健康不健康；
• 出错以后能不能复盘；
• 下一轮参数怎么调；
• 报告能不能让别人看懂。

这些东西一开始看起来有点麻烦。

但等任务真的跑半小时、一小时、甚至更久的时候，你会发现它们非常值。