<!-- Source: https://hermesbible.com/docs/user-guide/features/batch-processing -->

Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/batch-processing

批次處理讓你能在數百或數千個 prompt 上平行執行 Hermes agent，產生結構化的軌跡資料。這主要用於訓練資料生成——產生 ShareGPT 格式的軌跡，包含工具使用統計，可用於微調或評估。

概覽

批次執行器 (batch_runner.py) 會處理一個 JSONL 資料集，將每個 prompt 透過完整的 agent session 搭配工具存取來執行。每個 prompt 都有自己獨立的環境。輸出是結構化的軌跡資料，包含完整的對話歷史、工具呼叫統計和推理覆蓋指標。

快速開始

# 基本批次執行
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

TIP — 大規模執行的成本可預測

批次執行會啟動多個並行的 agent session，每個都會進行模型呼叫和工具呼叫。Nous Portal 訂閱方案將模型存取加上網頁搜尋、圖片生成、TTS 和雲端瀏覽器整合在同一張帳單下——當你需要穩定的每軌跡成本，而不必在五個供應商帳戶之間切換限流時特別實用。透過 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：用於此 prompt 沙箱的容器映像（適用於 Docker、Modal 和 Singularity 後端）
• cwd：任務終端 session 的工作目錄覆蓋

設定選項

供應商路由（OpenRouter）

推理控制

進階選項

工具組分佈

每個 prompt 都會從分佈中隨機取樣一組工具組。這確保訓練資料涵蓋多樣化的工具組合。使用 --list_distributions 查看所有可用的分佈。

在目前的實作中，分佈會為每個獨立的工具組分配一個機率。取樣器會獨立翻轉每個工具組，然後保證至少有一個工具組被啟用。這與手動編寫的預設組合表格不同。

輸出格式

所有輸出都存放在 data/<run_name>/：

data/my_run/
├── trajectories.jsonl    # 合併的最終輸出（所有批次合併）
├── batch_0.jsonl         # 單一批次結果
├── batch_1.jsonl
├── ...
├── checkpoint.json       # 恢復用 checkpoint
└── 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 欄位。工具統計會標準化為包含所有可能的工具（預設值為零），確保所有條目使用一致的 schema，以相容 HuggingFace 資料集。

Checkpoint 機制

批次執行器具有強健的 checkpoint 機制以確保容錯：

• Checkpoint 檔案： 每個批次完成後儲存，追蹤已完成的 prompt 索引
• 基於內容的恢復： 執行 --resume 時，執行器會掃描現有的批次檔案，並透過實際的文字內容（而非僅靠索引）匹配已完成的 prompt，即使資料集順序改變也能恢復
• 失敗的 prompt： 只有成功完成的 prompt 才會標記為完成——失敗的 prompt 會在恢復時重試
• 批次合併： 完成後，所有批次檔案（包括先前執行的）會合併成單一 trajectories.jsonl

恢復機制運作方式

1. 掃描所有 batch_*.jsonl 檔案以找出已完成的 prompt（透過內容匹配）
2. 過濾資料集以排除已完成的 prompt
3. 將剩餘的 prompt 重新分批
4. 只處理剩餘的 prompt
5. 將所有批次檔案（舊的 + 新的）合併為最終輸出

品質過濾

批次執行器會自動套用品質過濾：

• 無推理過濾： 捨棄 assistant 回合中零推理的樣本（沒有 <REASONING_SCRATCHPAD> 或原生思考 token）
• 損壞條目過濾： 在最終合併時，過濾掉包含幻覺工具名稱（不在有效工具清單中）的條目
• 推理統計： 追蹤整個執行過程中，有/無推理的回合百分比

統計資料

完成後，執行器會輸出完整的統計資料：

• 工具使用： 每個工具的呼叫次數、成功/失敗率
• 推理覆蓋率： 有推理的 assistant 回合百分比
• 捨棄的樣本： 因缺乏推理而被過濾的樣本數
• 執行時間： 總處理時間

統計資料也會儲存到 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

模型評估

評估模型在標準化 prompt 上使用工具的能力：

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 的容器映像

對於需要特定環境的基準測試，每個 prompt 可以指定自己的容器映像：

{"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"}

批次執行器會在執行每個 prompt 前驗證 Docker 映像是否可存取。

---

---

語音模式