SeaHi

主题

00:00:00
SeaHi2026-04-142026-05-31Hermes Agent 中文教程
1650
6.5m

批处理 ​

批处理允许您在数百或数千个提示上并行运行 Hermes Agent，生成结构化的轨迹数据。这主要用于训练数据生成 —— 生成 ShareGPT 格式的轨迹，包含可用于微调或评估的工具使用统计信息。

概述 ​

批处理运行器 (batch_runner.py) 处理 JSONL 数据集的提示，通过具有工具访问权限的完整 Agent 会话运行每个提示。每个提示都有自己的隔离环境。输出是结构化的轨迹数据，包含完整的对话历史、工具调用统计信息和推理覆盖率指标。

快速开始 ​

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

数据集格式 ​

输入数据集是一个 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"从中采样的工具集分布
--modelclaude-sonnet-4.6要使用的模型
--base_urlhttps://openrouter.ai/api/v1API 基础 URL
--api_key(环境变量)模型的 API 密钥
--max_turns10每个提示的最大工具调用迭代次数
--num_workers4并行工作进程数
--resumefalse从检查点恢复
--verbosefalse启用详细日志记录
--max_samplesall仅处理数据集中的前 N 个样本
--max_tokens模型默认值每次模型响应的最大令牌数

提供商路由 (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完全禁用推理/思考令牌

高级选项 ​

参数描述
--ephemeral_system_prompt执行期间使用但不保存到轨迹的系统提示
--log_prefix_chars日志预览中显示的字符数（默认：100）
--prefill_messages_file用于 few-shot 引导的预填充消息的 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

恢复的工作原理 ​

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

质量过滤 ​

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

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

统计 ​

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

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

统计信息也保存到 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 镜像是否可访问。