批處理

批處理允許你並行運行 Hermes Agent 處理數百甚至數千個提示，生成結構化的軌跡數據。這主要用於 訓練數據生成 —— 生成包含工具使用統計信息的 ShareGPT 格式軌跡，可用於微調或評估。

概述

批處理運行器（batch_runner.py）會處理一個 JSONL 格式的提示數據集，將每個提示通過完整的 Agent 會話（帶工具訪問權限）運行。每個提示都有其獨立的隔離環境。輸出為結構化的軌跡數據，包含完整的對話歷史、工具調用統計信息以及推理覆蓋度指標。

快速開始

# 基本批處理運行
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

# 列出可用的 toolset 發行版
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	(必需)	每批處理的提示數量
--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>/：

data/my_run/
├── trajectories.jsonl    # 合併最終輸出（所有批次合併）
├── batch_0.jsonl         # 個別批次結果
├── batch_1.jsonl
├── ...
├── checkpoint.json       # 恢復檢查點
└── statistics.json       # 聚合 tool 使用統計數據

軌跡格式

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 鏡像是否可訪問。