大模型离线批量任务怎么对账：从 JSONL 提交到结果回写的分步实验

客服团队把一万多条历史工单交给模型归类，白天接口却开始变慢。问题不在提示词，而在任务性质：这些旧数据不需要用户立刻看到结果，和在线聊天、实时检索放在同一条请求路径里，只会互相挤占资源。更合适的做法是把它们拆成离线批次，并把「结果返回」与「结果可回写」分成两次校验环节。

整套实操用一份最小 JSONL 文件走完全链路：准备单行请求、提交异步批次、检查状态、下载输出和错误文件，再按 custom_id 与业务表对齐。核心关注点不是一次提交多少条，而是每一条的结果都能追溯回对应的原始记录。

先判断：这件事能不能等

这一步很容易被跳过。批量接口走异步处理逻辑，不适合用户点完操作就要立刻看到结果的页面。拿工单标签归类举例子，客服打开列表时触发的单条判断继续走在线请求即可；每天凌晨重算历史标签、补齐旧摘要、批量抽取问题类型这类操作，才是离线批次的适用范围。

可以先给任务套两个校验规则：单条输入完全彼此独立，同时业务侧允许延后拿到结果。如果某一条的输出会作为下一条的输入，或者需要根据前一条的结果实时调整提示内容，先把流程拆解开，不要硬把有依赖关系的任务塞到同一个批次里。

第 1 步：为每条业务记录生成稳定标识

JSONL 的每一行就是一条独立的 API 请求。这里刻意不用数组下标当标识，而是把工单主键放进 custom_id。哪怕后续输出文件的行顺序发生变化，也能准确定位模型结果对应的原始工单。

import { createWriteStream } from "node:fs";

const tickets = [
  { id: 1042, text: "支付后页面仍显示待付款" },
  { id: 1043, text: "收不到登录验证码" },
];

const file = createWriteStream("ticket-labels.jsonl");

for (const ticket of tickets) {
  const line = {
    custom_id: `ticket-${ticket.id}`,
    method: "POST",
    url: "/v1/responses",
    body: {
      model: "gpt-5",
      input: `给下面工单归到一个简短类型，只输出类型名称：${ticket.text}`,
    },
  };

  file.write(`${JSON.stringify(line)}\n`);
}

file.end();

写完随手打开文件扫两行：必须是一行对应一个完整的 JSON 对象，不能把整个请求数组一次性写进去。custom_id 不要直接拼接手机号、邮箱这类用户隐私信息或者未脱敏的用户原话，用内部主键或者已经完成脱敏的标识，后续排查问题也更稳妥。

第 2 步：上传输入文件后创建异步批次

输入文件先以 batch 分类用途上传，拿到返回的文件 ID 再传给批次接口。下面的示例代码省略了密钥配置逻辑，密钥必须存放在服务端环境变量或者专用密钥管理服务中，绝对不能出现在浏览器代码或者 JSONL 文件里。

const inputFile = await client.files.create({
  file: await toFile("ticket-labels.jsonl"),
  purpose: "batch",
});

const batch = await client.batches.create({
  input_file_id: inputFile.id,
  endpoint: "/v1/responses",
  completion_window: "24h",
});

console.log({ batchId: batch.id, status: batch.status });

创建请求返回成功，只能说明批次已经被服务端接收，不代表所有请求都已经处理完成。接口会返回 validating、in_progress、finalizing、completed 等状态字段；业务数据库里至少要存好批次 ID、创建时间和待处理总条数，后续的轮询校验和结果回写才能有可追溯的依据。

第 3 步：用状态和计数判断「能不能取结果」

批次没有进入 completed 状态前，不要急着下载结果往业务表里写。等待过程中只记录状态变化即可；如果出现 failed、expired 或者 cancelled 这类异常状态，先把批次留在异常待处理列表，查清楚输入文件问题和具体报错信息，不要直接整份重提任务。

const batch = await client.batches.retrieve(batchId);

const counts = batch.request_counts ?? {
  total: 0,
  completed: 0,
  failed: 0,
};

if (batch.status === "completed") {
  console.log({
    outputFile: batch.output_file_id,
    total: counts.total,
    completed: counts.completed,
    failed: counts.failed,
  });
} else {
  console.log({ status: batch.status, ...counts });
}

这里有个很容易踩的误区：批次状态标记为完成，不等于所有请求都执行成功。把接口返回的 total、completed 和 failed 三个数值一起存下来，和本地生成的原始 JSONL 总条数做比对，再决定走结果回写、单条补偿还是人工复查流程。

第 4 步：按 custom_id 合并，不按文件位置合并

拿到输出文件后，逐行读取内容，构建 custom_id → 结果 的映射关系。业务回写的时候，只处理能匹配到原始工单、响应状态正常、返回内容可正常解析的记录；剩余记录统一保存失败原因，放进补偿队列。这样就算单次批次里有少量请求失败，也不会污染其余已经生成的可用结果。

const resultByTicket = new Map();

for (const row of outputRows) {
  const ticketId = row.custom_id.replace("ticket-", "");

  if (row.response?.status_code === 200) {
    resultByTicket.set(ticketId, row.response.body);
  }
}

for (const ticket of tickets) {
  const result = resultByTicket.get(String(ticket.id));

  if (result) {
    await saveTicketLabel(ticket.id, result);
  } else {
    await markForRetry(ticket.id, batchId);
  }
}

如果接口同时返回了 error_file_id，也用同一个标识收集所有失败行和对应的报错原因。不要把错误文件当成没用的日志直接丢弃，它是判断「哪些条目需要补跑、是不是存在统一的参数错误」的核心依据。

第 5 步：把单次批量任务收拢成可复查记录

一次任务执行结束后，至少留存四类字段：batch_id、输入文件 ID、输出文件 ID/错误文件 ID、三类请求计数。再加上本地生成 JSONL 时记录的任务版本，后续如果发现某类标签结果不符合预期，也能顺利追溯到是哪一批次、用了哪套提示词和模型配置执行的。

离线批量的优势不只是把大量请求塞到同一个文件里提交，而是给大规模任务搭出清晰的边界：输入数量可统计、执行状态可观测、返回结果可对账、异常失败可补跑。先把这条链路跑稳定，再考虑要不要提升单批次的提交条数，或者接入更多类型的离线任务。

延伸问答

批量任务能替代实时对话接口吗？

不能。它只适合允许延迟的离线处理场景。用户正在等待的问答、页面生成或者实时交互操作，仍然走同步请求路径更合理，同时要配置好超时和降级策略。

为什么不直接按输出文件的第几行更新工单？

业务对账需要稳定的唯一主键。使用 custom_id 可以把输出记录直接关联到原始输入，完全避免行顺序变化、补跑任务或者部分执行失败时出现的数据错位问题。

批次失败后应该整份重提吗？

先查看错误文件和返回的请求计数。如果只有少量单条执行失败，优先单独补跑这部分条目；如果是输入格式或者公共参数有问题，修复后再生成全新的任务提交，同时保留旧批次的所有记录方便后续比对。

相关阅读

• 大模型接口 429 怎么排查：区分请求额度、令牌额度和并发积压
• RAG 知识库怎么防提示词注入：外部文档只能当资料，不能当指令
• AI 对话流式输出怎么做停止按钮：AbortController、状态播报和断线收尾

核对资料

• OpenAI 官方 Batch API 参考：批次状态、输入文件、输出文件、错误文件与请求计数说明。
• OpenAI 官方 API 概览：生产环境中的密钥保护、请求标识和接口兼容性注意事项。