hermes教程-批处理 - 字节笔记本

概述

批处理运行器（batch_runner.py）可并行处理数百或数千个提示，生成结构化的轨迹数据。这主要用于训练数据生成——生成包含工具使用统计信息的 ShareGPT 格式轨迹，可用于微调或评估。

快速开始

bash

## 基本批处理运行
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

提示——可预测的大规模成本

批处理运行会启动多个并发的代理会话，每个会话都会进行模型调用和工具调用。订阅 Nous Portal 可将模型访问、网络搜索、图像生成、TTS 和云浏览器整合到一个账单中——当您希望获得稳定的每条轨迹成本，而无需在五个供应商账户之间周旋于速率限制时，这非常有用。使用 hermes setup --portal 进行设置，然后将 --model 指向一个 Nous 模型。

数据集格式

输入数据集是一个 JSONL 文件（每行一个 JSON 对象）。每个条目必须包含一个 prompt 字段：

jsonl

{"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`	(必需)	每批提示数
`--run_name`	(必需)	本次运行的名称（用于输出目录和检查点）
`--distribution`	`"default"`	要采样的工具集分布
`--model`	`claude-sonnet-4.6`	使用的模型
`--base_url`	`https://openrouter.ai/api/v1`	API 基础 URL
`--api_key`	(环境变量)	模型的 API 密钥
`--max_turns`	`10`	每个提示的最大工具调用迭代次数
`--num_workers`	`4`	并行工作进程数
`--resume`	`false`	从检查点恢复
`--verbose`	`false`	启用详细日志
`--max_samples`	全部	仅处理数据集中的前 N 个样本
`--max_tokens`	模型默认值	每个模型响应的最大 token 数

提供商路由（OpenRouter）

参数	描述
`--providers_allowed`	允许的提供商列表，以逗号分隔（例如 `"anthropic,openai"`）
`--providers_ignored`	忽略的提供商列表，以逗号分隔（例如 `"together,deepinfra"`）
`--providers_order`	首选提供商顺序，以逗号分隔
`--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 文件路径，用于少样本提示

工具集分布

每个提示会从一个分布中随机采样一组工具集。这确保了训练数据涵盖多样化的工具组合。使用 --list_distributions 可查看所有可用的分布。

在当前实现中，分布为每个单独的工具集分配一个概率。采样器独立地翻转每个工具集，然后保证至少启用一个工具集。这与手工编写的预构建组合表不同。

输出格式

所有输出都位于 data/<run_name>/ 目录下：

text

data/my_run/
├── trajectories.jsonl    # 合并后的最终输出（所有批次合并）
├── batch_0.jsonl         # 单个批次结果
├── batch_1.jsonl
├── ...
├── checkpoint.json       # 恢复检查点
└── statistics.json       # 聚合工具使用统计

轨迹格式

trajectories.jsonl 中的每一行都是一个 JSON 对象：

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 中

恢复的工作原理

扫描所有 batch_*.jsonl 文件，查找已完成的提示（通过内容匹配）
过滤数据集，排除已完成的提示
对剩余提示重新分批
仅处理剩余提示
将所有批次文件（旧 + 新）合并到最终输出

质量过滤

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

无推理过滤： 丢弃那些没有助手轮次包含推理（没有 <REASONING_SCRATCHPAD> 或原生思考 token）的样本
损坏条目过滤： 在最终合并过程中，过滤掉包含幻觉工具名称（不在有效工具列表中）的条目
推理统计： 跟踪整个运行中带有/不带有推理的轮次百分比

统计信息

完成后，运行器会打印全面的统计信息：

工具使用： 每个工具的调用次数、成功/失败率
推理覆盖率： 带有推理的助手轮次百分比
丢弃的样本： 因缺少推理而被过滤的样本数量
持续时间： 总处理时间

统计信息也会保存到 statistics.json 中，供程序化分析使用。

使用场景

训练数据生成

生成多样化的工具使用轨迹，用于微调：

bash

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

模型评估

评估模型在标准化提示下使用工具的能力：

bash

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

每个提示的容器镜像

对于需要特定环境的基准测试，每个提示可以指定自己的容器镜像：

jsonl

{"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 镜像是否可访问。