> 原文链接：Batch Processing
sidebar_position: 12 title: "Batch Processing" description: "Generate agent trajectories at scale — parallel processing, checkpointing, and toolset distributions"
Batch Processing（批量处理）
批量处理允许你在数百或数千个 Prompt 上并行运行 Hermes Agent，生成结构化的轨迹（Trajectory）数据。这主要用于训练数据生成——生成包含工具使用统计的 ShareGPT 格式轨迹，可用于微调或评估。
概述
批量运行器（batch_runner.py）处理 JSONL 格式的 Prompt 数据集，通过完整的带工具访问的 Agent 会话运行每个 Prompt。每个 Prompt 获得独立的隔离环境。输出是包含完整对话历史、工具调用统计和推理覆盖率指标的结构化轨迹数据。
快速开始
# 基本批量运行
python batch_runner.py \
--dataset_file=data/prompts.jsonl \
--batch_size=10 \
--run_name=my_first_run \
--model=anthropic/claude-sonnet-4.6 \
--num_workers=4
# 恢复中断的运行
python batch_runner.py \
--dataset_file=data/prompts.jsonl \
--batch_size=10 \
--run_name=my_first_run \
--resume
# 列出可用的工具集分布
python batch_runner.py --list_distributions
数据集格式
输入数据集是 JSONL 文件（每行一个 JSON 对象）。每条记录必须有 prompt 字段：
{"prompt": "编写一个 Python 函数，找出最长回文子串"}
{"prompt": "使用 Flask 创建一个用户认证的 REST API 端点"}
{"prompt": "调试这个错误：TypeError: cannot unpack non-iterable NoneType object"}
记录可以可选地包含：
image或docker_image：用于此 Prompt 沙盒的容器镜像（适用于 Docker、Modal 和 Singularity 后端）cwd：任务终端会话的工作目录覆盖
配置选项
| 参数 | 默认值 | 描述 |
|---|---|---|
--dataset_file | （必需） | JSONL 数据集路径 |
--batch_size | （必需） | 每批次 Prompt 数量 |
--run_name | （必需） | 运行名称（用于输出目录和检查点） |
--distribution | "default" | 工具集分布采样来源 |
--model | claude-sonnet-4.6 | 使用的模型 |
--base_url | https://openrouter.ai/api/v1 | API 基础 URL |
--api_key | （环境变量） | 模型 API 密钥 |
--max_turns | 10 | 每个 Prompt 最大工具调用迭代次数 |
--num_workers | 4 | 并行工作进程数 |
--resume | false | 从检查点恢复 |
--verbose | false | 启用详细日志 |
--max_samples | 全部 | 仅处理数据集前 N 个样本 |
--max_tokens | 模型默认值 | 每次模型响应的最大 Token 数 |
Provider 路由 (OpenRouter)
| 参数 | 描述 |
|---|---|
--providers_allowed | 允许的 Provider，逗号分隔（如 "anthropic,openai"） |
--providers_ignored | 忽略的 Provider，逗号分隔（如 "together,deepinfra"） |
--providers_order | 首选 Provider 顺序，逗号分隔 |
--provider_sort | 按 "price"、"throughput" 或 "latency" 排序 |
推理控制
| 参数 | 描述 |
|---|---|
--reasoning_effort | 推理强度级别：none、minimal、low、medium、high、xhigh |
--reasoning_disabled | 完全禁用推理/思考 Token |
高级选项
| 参数 | 描述 |
|---|---|
--ephemeral_system_prompt | 执行期间使用但不保存到轨迹的系统提示词 |
--log_prefix_chars | 日志预览中显示的字符数（默认：100） |
--prefill_messages_file | 用于少样本启动的预填充消息 JSON 文件路径 |
工具集分布
每个 Prompt 从分布中随机采样一组工具集。这确保训练数据涵盖多样的工具组合。使用 --list_distributions 查看所有可用分布。
在当前实现中，分布为每个工具集分配一个概率。采样器独立地翻转每个工具集，然后保证至少启用一个工具集。这与手工编写的预构建组合表不同。
输出格式
所有输出保存在 data/<run_name>/：
data/my_run/
├── trajectories.jsonl # 合并的最终输出（所有批次合并）
├── batch_0.jsonl # 单个批次结果
├── batch_1.jsonl
├── ...
├── checkpoint.json # 恢复检查点
└── statistics.json # 汇总工具使用统计
轨迹格式
trajectories.jsonl 中每行是一个 JSON 对象：
{
"prompt_index": 42,
"conversations": [
{"from": "human", "value": "Write a function..."},
{"from": "gpt", "value": "I'll create that function...",
"tool_calls": [...]},
{"from": "tool", "value": "..."},
{"from": "gpt", "value": "Here's the completed function..."}
],
"metadata": {
"batch_num": 2,
"timestamp": "2026-01-15T10:30:00",
"model": "anthropic/claude-sonnet-4.6"
},
"completed": true,
"partial": false,
"api_calls": 3,
"toolsets_used": ["terminal", "file"],
"tool_stats": {
"terminal": {"count": 2, "success": 2, "failure": 0},
"read_file": {"count": 1, "success": 1, "failure": 0}
},
"tool_error_counts": {
"terminal": 0,
"read_file": 0
}
}
conversations 字段使用类似 ShareGPT 的格式，包含 from 和 value 字段。工具统计被标准化为包含所有可能工具的零默认值，确保跨条目的一致 Schema 以兼容 HuggingFace 数据集。
检查点
批量运行器具有强大的检查点容错机制：
- 检查点文件： 每个批次完成后保存，追踪哪些 Prompt 索引已完成
- 基于内容的恢复： 使用
--resume时，运行器扫描现有批次文件并通过实际文本内容匹配已完成的 Prompt（不仅仅是索引），即使数据集顺序发生变化也能恢复 - 失败的 Prompt： 只有成功完成的 Prompt 被标记为已完成——失败的 Prompt 会在恢复时重试
- 批次合并： 完成后，所有批次文件（包括之前运行的）被合并为单个
trajectories.jsonl
恢复工作原理
- 扫描所有
batch_*.jsonl文件中已完成的 Prompt（通过内容匹配） - 过滤数据集排除已完成的 Prompt
- 重新批次化剩余 Prompt
- 仅处理剩余 Prompt
- 将所有批次文件（旧 + 新）合并为最终输出
质量过滤
批量运行器应用自动质量过滤：
- 无推理过滤： 零个助手轮次包含推理的样本（无
<REASONING_SCRATCHPAD>或原生思考 Token）会被丢弃 - 损坏条目过滤： 具有幻觉工具名称（不在有效工具列表中）的条目在最终合并时被过滤掉
- 推理统计： 追踪整个运行中有/无推理的轮次百分比
统计信息
完成后，运行器打印综合统计信息：
- 工具使用： 调用次数、每个工具的成功/失败率
- 推理覆盖率： 包含推理的助手轮次百分比
- 丢弃样本： 因缺少推理而被过滤的样本计数
- 持续时间： 总处理时间
统计信息也保存到 statistics.json 用于程序化分析。
使用场景
训练数据生成
生成多样的工具使用轨迹用于微调：
python batch_runner.py \
--dataset_file=data/coding_prompts.jsonl \
--batch_size=20 \
--run_name=coding_v1 \
--model=anthropic/claude-sonnet-4.6 \
--num_workers=8 \
--distribution=default \
--max_turns=15
模型评估
评估模型在标准化 Prompt 上的工具使用能力：
python batch_runner.py \
--dataset_file=data/eval_suite.jsonl \
--batch_size=10 \
--run_name=eval_gpt4 \
--model=openai/gpt-4o \
--num_workers=4 \
--max_turns=10
按 Prompt 的容器镜像
对于需要特定环境的基准测试，每个 Prompt 可以指定自己的容器镜像：
{"prompt": "安装 numpy 并计算 3x3 矩阵的特征值", "image": "python:3.11-slim"}
{"prompt": "编译这个 Rust 程序并运行", "image": "rust:1.75"}
{"prompt": "搭建一个 Node.js Express 服务器", "image": "node:20-alpine", "cwd": "/app"}
批量运行器在运行每个 Prompt 之前会验证 Docker 镜像是否可访问。