Skip to main content

轨迹格式

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）的完整形式，并以零值作为默认项，确保 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. 原生思考令牌（来自 Anthropic、OpenAI o 系列等提供方的 msg["reasoning"] 字段）：包裹在 <think>\n{reasoning}\n</think>\n 中，并前置到内容前。

  2. REASONING_SCRATCHPAD XML（当原生思考禁用且模型通过系统提示指令的 XML 进行推理时）：<REASONING_SCRATCHPAD> 标签通过 convert_scratchpad_to_think() 转换为 <think>。

  3. 空思考块：每个 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 解析失败（理论上不应发生——对话期间已验证），则使用空 {} 并记录警告
  • 单个助手回合中多个工具调用会产生多个 <tool_call> 块，出现在同一个 gpt 消息中

工具响应归一化​

所有跟随助手消息的工具结果被合并为单个 tool 转换，其内容为带 XML 包装的 JSON 响应：

<tool_response>
{"tool_call_id": "call_abc123", "name": "terminal", "content": "output here"}
</tool_response>
  • 若工具内容看起来像 JSON（以 { 或 [ 开头），则解析为对象/数组，而非字符串
  • 多个工具结果以换行符连接至同一消息
  • 工具名称通过位置匹配父级助手的 tool_calls 数组

系统消息​

系统消息在保存时生成（非来自对话本身）。它遵循 Hermes 函数调用提示模板，包含：

  • 解释函数调用协议的引言
  • <tools> XML 块，包含 JSON 工具定义
  • FunctionCall 对象的模式引用
  • <tool_call> 示例

工具定义包括 name、description、parameters 和 required（设为 null 以匹配标准格式）。

加载轨迹​

轨迹为标准 JSONL 格式——可使用任意 JSON 行读取器加载：

import json

def load_trajectories(path: str):
    """Load trajectory entries from a JSONL file."""
    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

# Filter to successful completions only
successful = [e for e in load_trajectories("trajectory_samples.jsonl")
              if e.get("completed")]

# Extract just the conversations for training
training_data = [e["conversations"] for e in successful]

用于 HuggingFace 数据集的加载​

from datasets import load_dataset

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

经过归一化的 tool_stats 模式确保所有条目具有相同列结构，防止数据集加载时出现 Arrow 模式不匹配错误。

控制轨迹保存​

在 CLI 中，轨迹保存由以下方式控制：

# config.yaml
agent:
  save_trajectories: true  # default: false

或通过 --save-trajectories 标志。当代理初始化时启用 save_trajectories=True，将在每个对话回合结束时调用 _save_trajectory() 方法。

批量运行器始终保存轨迹（这是其主要目的）。

所有回合中均无推理内容的样本会被批量运行器自动丢弃，以避免污染训练数据。