sidebar_position: 12 title: “Batch Processing” description: “Generate agent trajectories at scale — parallel processing, checkpointing, and toolset distributions”

批量处理

批量处理功能允许您并行运行Hermes智能体，同时处理数百甚至数千条提示，从而生成结构化的轨迹数据。该功能主要用于训练数据生成——输出包含工具使用统计信息的ShareGPT格式轨迹数据，这些数据可用于模型微调或性能评估。

概述

批量处理器（batch_runner.py）会读取包含提示的JSONL数据集，并为每条提示启动一次具备工具访问权限的完整智能体会话。每条提示都会拥有独立的运行环境。最终生成的则是结构化的轨迹数据，其中包含完整的对话历史、工具调用统计信息以及推理覆盖度指标。

快速入门

# Basic batch run
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

# Resume an interrupted run
python batch_runner.py \
    --dataset_file=data/prompts.jsonl \
    --batch_size=10 \
    --run_name=my_first_run \
    --resume

# List available toolset distributions
python batch_runner.py --list_distributions

:::提示：实现大规模应用下的成本可预测性
批量运行会启动多个并发的 Agent 会话，每个会话都会进行模型调用和工具调用。通过 Nous Portal 订阅服务，可将模型访问权限与网页搜索、图像生成、文本转语音以及云浏览器功能整合到同一账单中——这非常适合那些希望获得稳定的单次处理成本、而无需在五个不同供应商的账户间管理各种速率限制的场景。只需使用 hermes setup --portal 进行配置，再将 --model 参数指向相应的 Nous 模型即可。

::

数据集格式

输入数据集为 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：任务终端会话的工作目录覆盖值

配置选项

提供商路由（OpenRouter）

推理控制 |

高级选项

工具集分布

每个提示词都会从某个分布中随机抽取一组工具集。这样可确保训练数据涵盖多种不同的工具组合。可使用 --list_distributions 查看所有可用的分布。

在当前的实现方式中，各分布会为每一个单独的工具集分配一个概率值。采样器会独立地为每个工具集进行随机选择，同时保证至少有一个工具集被启用。这与手动编写的预构建组合表有所不同。

输出格式

所有输出内容都会保存至 data/<run_name>/ 目录下：

data/my_run/
├── trajectories.jsonl    # Combined final output (all batches merged)
├── batch_0.jsonl         # Individual batch results
├── batch_1.jsonl
├── ...
├── checkpoint.json       # Resume checkpoint
└── statistics.json       # Aggregate tool usage stats

轨迹格式

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 两个字段。工具统计信息经过标准化处理，会列出所有可能使用的工具且不设置默认值，从而确保各条记录的架构一致，便于与 HuggingFace 数据集兼容。

检查点机制

批量运行器具备强大的检查点功能，以提高容错能力：

• 检查点文件：在每个批次处理完成后生成，用于记录已完成提示的索引。
• 基于内容的恢复：当使用 --resume 参数时，运行器会扫描现有的批次文件，并通过实际文本内容（而非仅索引）来匹配已完成的提示，即便数据集顺序发生变化也能实现恢复。
• 失败的提示：只有成功处理完成的提示才会被标记为已完成——失败的提示会在恢复时重新尝试处理。
• 批次合并：处理完成后，所有批次文件（包括之前运行生成的文件）都会被合并为一个 trajectories.jsonl 文件。

恢复功能的运作原理

1. 扫描所有的 batch_*.jsonl 文件，通过内容匹配找出已完成的提示。
2. 过滤数据集，排除那些已经处理完成的提示。
3. 将剩余的提示重新分组为新的批次。
4. 仅对剩余的提示进行后续处理。
5. 将所有批次文件（旧文件和新文件）合并为最终输出。

质量过滤

批量运行器会自动应用质量过滤功能：

• 无推理过滤：会剔除那些所有助手回复均不包含推理内容（即没有 <REASONING_SCRATCHPAD> 标记或原生思考标记）的样本。
• 损坏条目过滤：在最终合并阶段，会筛选掉工具名称出现错误（不在有效工具列表中）的条目。
• 推理统计：统计整个运行过程中包含推理与不包含推理的回复所占的比例。

统计数据

运行完成后，工具会输出详细的统计数据：

• 工具使用情况：各工具的调用次数以及成功/失败率。
• 推理覆盖率：包含推理内容的助手回复所占的百分比。
• 被剔除的样本数：因缺乏推理内容而被筛选掉的样本数量。
• 处理时长：整个处理的总时间。

这些统计数据还会被保存到 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 镜像是否可访问。