批处理

批处理允许你在数百到数千条提示词上并行运行 Hermes 智能体，并生成结构化轨迹数据。它主要用于 训练数据生成，也就是产出带工具使用统计的 ShareGPT 格式轨迹，可用于微调或评估。

概览

批处理运行器（batch_runner.py）会处理一个 JSONL 提示词数据集，让每条提示词都走完整的智能体会话与工具调用流程。每条提示词拥有自己的隔离环境。输出结果是结构化轨迹数据，包含完整对话历史、工具调用统计以及推理覆盖率指标。

快速开始

# 基础批处理运行
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": "Write a Python function that finds the longest palindromic substring"}
{"prompt": "Create a REST API endpoint for user authentication using Flask"}
{"prompt": "Debug this error: TypeError: cannot unpack non-iterable NoneType object"}

也可以额外包含：

• image 或 docker_image：为该提示词指定沙箱容器镜像（适用于 Docker、Modal 和 Singularity 后端）
• cwd：覆盖该任务终端会话的工作目录

配置项

参数	默认值	说明
--dataset_file	（必填）	JSONL 数据集路径
--batch_size	（必填）	每个 batch 的提示词数量
--run_name	（必填）	本次运行名称（用于输出目录与 checkpoint）
--distribution	"default"	要采样的工具集分布
--model	claude-sonnet-4.6	使用的模型
--base_url	https://openrouter.ai/api/v1	API 基础 URL
--api_key	（环境变量）	模型 API key
--max_turns	10	每条提示词允许的最大工具调用轮数
--num_workers	4	并行 worker 进程数
--resume	false	从 checkpoint 恢复
--verbose	false	启用详细日志
--max_samples	all	只处理前 N 条样本
--max_tokens	model default	单次模型响应最大 tokens

Provider Routing（OpenRouter）

参数	说明
--providers_allowed	允许的大模型提供商（provider），逗号分隔
--providers_ignored	忽略的大模型提供商（provider），逗号分隔
--providers_order	偏好的大模型提供商（provider）顺序
--provider_sort	按 price、throughput 或 latency 排序

推理控制

参数	说明
--reasoning_effort	推理强度：none、minimal、low、medium、high、xhigh
--reasoning_disabled	完全禁用 reasoning / thinking tokens

高级选项

参数	说明
--ephemeral_system_prompt	运行时使用、但不会写入轨迹的系统提示
--log_prefix_chars	日志预览中显示的字符数（默认 100）
--prefill_messages_file	预填充 few-shot 消息的 JSON 文件路径

工具集分布

每条提示词都会从一个 distribution 中随机采样一组工具集，以确保训练数据覆盖不同的工具组合。可通过 --list_distributions 查看所有可用分布。

当前实现中，分布是为 每个单独工具集 分配一个概率。采样器会独立决定每个工具集是否启用，并保证最终至少有一个工具集被启用。这与手工预定义一张工具组合表不同。

输出格式

所有输出都保存在 data/<run_name>/ 下：

data/my_run/
├── trajectories.jsonl    # 合并后的最终输出
├── batch_0.jsonl         # 单个 batch 的结果
├── 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 结构。工具统计会被规范化，确保所有可能工具都存在，未使用的默认记为 0，以保证 HuggingFace 数据集场景下的 schema 一致性。

Checkpointing

批处理运行器具备较强的 checkpoint 容错机制：

• Checkpoint file：每个 batch 完成后都会保存，用于追踪哪些提示词索引已处理
• Content-based resume：启用 --resume 时，运行器会扫描已有 batch 文件，并按提示词文本内容匹配已完成项，而不仅依赖索引，因此即使数据集顺序变化也可恢复
• Failed prompts：只有成功完成的提示词才会被标记完成；失败项会在恢复时重新尝试
• Batch merging：全部完成后，会把本次和历史运行中的 batch 文件合并成一个 trajectories.jsonl

恢复流程

1. 扫描所有 batch_*.jsonl，按内容匹配找出已完成提示词
2. 从数据集中排除这些已完成项
3. 对剩余提示词重新分批
4. 仅处理剩余部分
5. 合并全部 batch 文件（旧的 + 新的）形成最终输出

质量过滤

批处理运行器会自动进行质量过滤：

• 无推理过滤：若某个样本中 assistant 所有轮次都没有 reasoning（既无 <REASONING_SCRATCHPAD>，也无原生 thinking tokens），该样本会被丢弃
• 损坏条目过滤：若条目中出现幻觉出来的工具名（不在合法工具列表中），会在最终合并时被过滤掉
• 推理统计：统计整个运行中带推理 / 不带推理轮次的比例

统计信息

运行完成后，会输出详细统计：

• Tool usage：每个工具的调用次数、成功 / 失败率
• Reasoning coverage：assistant 轮次中带推理的比例
• Samples discarded：因缺乏推理被丢弃的样本数
• Duration：总处理时间

这些统计也会保存到 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

模型评估

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": "Install numpy and compute eigenvalues of a 3x3 matrix", "image": "python:3.11-slim"}
{"prompt": "Compile this Rust program and run it", "image": "rust:1.75"}
{"prompt": "Set up a Node.js Express server", "image": "node:20-alpine", "cwd": "/app"}

批处理运行器会在执行每条提示词前验证 Docker 镜像是否可访问。