H繁中版
文件Flows社群 Repos開始使用
文件開發者指南trajectory format
<!-- Source: https://hermesbible.com/docs/developer-guide/trajectory-format -->

Trajectory 格式

Hermes Agent 以 ShareGPT 相容的 JSONL 格式儲存對話軌跡，用於訓練資料、除錯工件和強化學習資料集。

原始碼檔案：agent/trajectory.py、run_agent.py（搜尋 _save_trajectory）、batch_runner.py

檔案命名慣例

軌跡被寫入當前工作目錄中的檔案：

檔案時機
trajectory_samples.jsonl成功完成的對話（completed=True）
failed_trajectories.jsonl失敗或被中斷的對話（completed=False）

批次運行器（batch_runner.py）寫入每個批次的自訂輸出檔案（例如 batch_001_output.jsonl），帶有額外的中繼資料欄位。

你可以透過 save_trajectory() 中的 filename 參數覆寫檔案名稱。

JSONL 條目格式

檔案中的每一行是一個獨立的 JSON 物件。有兩種變體：

CLI/互動式格式（來自 _save_trajectory）

{
  "conversations": [ ... ],
  "timestamp": "2026-03-30T14:22:31.456789",
  "model": "anthropic/claude-sonnet-4.6",
  "completed": true
}

批次運行器格式（來自 batch_runner.py）

{
  "prompt_index": 42,
  "conversations": [ ... ],
  "metadata": { "prompt_source": "gsm8k", "difficulty": "hard" },
  "completed": true,
  "partial": false,
  "api_calls": 7,
  "toolsets_used": ["code_tools", "file_tools"],
  "tool_stats": {
    "terminal": {"count": 3, "success": 3, "failure": 0},
    "read_file": {"count": 2, "success": 2, "failure": 0},
    "write_file": {"count": 0, "success": 0, "failure": 0}
  },
  "tool_error_counts": {
    "terminal": 0,
    "read_file": 0,
    "write_file": 0
  }
}

tool_stats 和 tool_error_counts 字典被正規化以包含所有可能的工具（來自 model_tools.TOOL_TO_TOOLSET_MAP），預設值為零，確保跨條目的一致 schema 用於 HuggingFace 資料集載入。

對話陣列（ShareGPT 格式）

conversations 陣列使用 ShareGPT 角色慣例：

API 角色ShareGPT from
system"system"
user"human"
assistant"gpt"
tool"tool"

完整範例

{
  "conversations": [
    {
      "from": "system",
      "value": "You are a function calling AI model. You are provided with function signatures within <tools> </tools> XML tags. You may call one or more functions to assist with the user query. If available tools are not relevant in assisting with user query, just respond in natural conversational language. Don't make assumptions about what values to plug into functions. After calling & executing the functions, you will be provided with function results within <tool_response> </tool_response> XML tags. Here are the available tools:\n<tools>\n[{\"name\": \"terminal\", \"description\": \"Execute shell commands\", \"parameters\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}}, \"required\": null}]\n</tools>\nFor each function call return a JSON object, with the following pydantic model json schema for each:\n{'title': 'FunctionCall', 'type': 'object', 'properties': {'name': {'title': 'Name', 'type': 'string'}, 'arguments': {'title': 'Arguments', 'type': 'object'}}, 'required': ['name', 'arguments']}\nEach function call should be enclosed within <tool_call> </tool_call> XML tags.\nExample:\n<tool_call>\n{'name': <function-name>,'arguments': <args-dict>}\n</tool_call>"
    },
    {
      "from": "human",
      "value": "What Python version is installed?"
    },
    {
      "from": "gpt",
      "value": "<think>\nThe user wants to know the Python version. I should run python3 --version.\n</think>\n<tool_call>\n{\"name\": \"terminal\", \"arguments\": {\"command\": \"python3 --version\"}}\n</tool_call>"
    },
    {
      "from": "tool",
      "value": "<tool_response>\n{\"tool_call_id\": \"call_abc123\", \"name\": \"terminal\", \"content\": \"Python 3.11.6\"}\n</tool_response>"
    },
    {
      "from": "gpt",
      "value": "<think>\nGot the version. I can now answer the user.\n</think>\nPython 3.11.6 is installed on this system."
    }
  ],
  "timestamp": "2026-03-30T14:22:31.456789",
  "model": "anthropic/claude-sonnet-4.6",
  "completed": true
}

正規化規則

推理內容標記

軌跡轉換器將所有推理正規化為 <think> 標籤，不論模型最初是如何產生它的：

  1. 原生思考 token（來自 Anthropic、OpenAI o 系列等 provider 的 msg["reasoning"] 欄位）：包裝為 <think>\n{reasoning}\n</think>\n 並前置在內容之前。

  2. REASONING_SCRATCHPAD XML（當原生思考被停用且模型透過系統提示詞指示的 XML 進行推理時）：<REASONING_SCRATCHPAD> 標籤透過 convert_scratchpad_to_think() 轉換為 <think>。

  3. 空的 think 區塊：每個 gpt 回合保證有一個 <think> 區塊。如果沒有產生推理，會插入一個空區塊：<think>\n</think>\n — 這確保了訓練資料的一致格式。

工具呼叫正規化

API 格式中的工具呼叫（帶有 tool_call_id、函式名稱、參數作為 JSON 字串）被轉換為 XML 包裝的 JSON：

<tool_call>
{"name": "terminal", "arguments": {"command": "ls -la"}}
</tool_call>
  • 參數從 JSON 字串解析回物件（不會雙重編碼）
  • 如果 JSON 解析失敗（不應該發生 — 在對話期間已驗證），會使用空的 {} 並記錄警告
  • 一個助理回合中的多個工具呼叫會在單個 gpt 訊息中產生多個 <tool_call> 區塊

工具回應正規化

助理訊息之後的所有工具結果被分組到一個帶有 XML 包裝 JSON 回應的單一 tool 回合中：

<tool_response>
{"tool_call_id": "call_abc123", "name": "terminal", "content": "output here"}
</tool_response>
  • 如果工具內容看起來像 JSON（以 { 或 [ 開頭），它會被解析，使 content 欄位包含 JSON 物件/陣列而非字串
  • 多個工具結果在一個訊息中以換行符連接
  • 工具名稱按位置對應父級助理的 tool_calls 陣列

系統訊息

系統訊息在儲存時生成（不是從對話中取得）。它遵循 Hermes 函式呼叫提示詞模板，包含：

  • 解釋函式呼叫協定的前言
  • <tools> XML 區塊，包含 JSON 工具定義
  • FunctionCall 物件的 schema 參考
  • <tool_call> 範例

工具定義包含 name、description、parameters 和 required（設為 null 以匹配規範格式）。

載入軌跡

軌跡是標準 JSONL — 使用任何 JSON-lines 讀取器載入：

import json

def load_trajectories(path: str):
    """從 JSONL 檔案載入軌跡條目。"""
    entries = []
    with open(path, "r", encoding="utf-8") as f:
        for line in f:
            line = line.strip()
            if line:
                entries.append(json.loads(line))
    return entries

# 篩選只保留成功完成的
successful = [e for e in load_trajectories("trajectory_samples.jsonl")
              if e.get("completed")]

# 只提取對話用於訓練
training_data = [e["conversations"] for e in successful]

用於 HuggingFace Datasets

from datasets import load_dataset

ds = load_dataset("json", data_files="trajectory_samples.jsonl")

正規化的 tool_stats schema 確保所有條目具有相同的欄位，防止資料集載入期間的 Arrow schema 不匹配錯誤。

控制軌跡儲存

在 CLI 中，軌跡儲存由以下設定控制：

# config.yaml
agent:
  save_trajectories: true  # 預設：false

或透過 --save-trajectories 旗標。當代理程式以 save_trajectories=True 初始化時，_save_trajectory() 方法會在每個對話回合結束時被呼叫。

批次運行器始終儲存軌跡（這是它的主要目的）。

批次運行器會自動丟棄所有回合中零推理的範例，以避免用非推理範例污染訓練資料。

Video Generation Provider Plugins

tools runtimevideo gen provider plugin