Hermes Agent性能基准测试框架：设计与实现

Hermes Agent性能基准测试框架：设计与实现

Hermes Agent性能基准测试框架是一个强大的评估工具，专为测试和评估智能代理在终端环境中的性能而设计。该框架基于Terminal-Bench 2.0评估环境，能够对代理在各种挑战性终端任务上的表现进行全面评估。

框架概述：核心功能与设计理念

Hermes Agent性能基准测试框架的核心目标是提供一个标准化、可重复的评估流程，用于衡量智能代理在终端环境中的任务完成能力。该框架采用了模块化设计，主要包含以下关键组件：

• 评估环境配置：通过TerminalBench2EvalConfig类管理评估过程中的各种参数，包括数据集名称、测试超时时间、任务过滤条件等。
• 任务执行引擎：负责加载任务数据集、解析任务定义、执行代理交互过程，并验证任务完成情况。
• 结果收集与分析：记录每个任务的执行结果，计算通过率等关键指标，并生成详细的评估报告。

该框架的设计遵循了以下原则：

1. 隔离性：每个任务在独立的Docker容器中执行，确保任务之间互不干扰。
2. 可重复性：通过标准化的环境配置和任务定义，确保评估结果的一致性和可重复性。
3. 可扩展性：支持添加新的任务类型和评估指标，便于框架的持续扩展。

快速上手：环境搭建与基础配置

要开始使用Hermes Agent性能基准测试框架，首先需要搭建相应的环境并进行基础配置。

环境要求

• Python 3.8+
• Docker
• 必要的Python依赖包（详见项目根目录下的requirements.txt）

安装步骤

1. 克隆项目仓库：

   git clone https://gitcode.com/GitHub_Trending/he/hermes-agent cd hermes-agent

2. 安装依赖：

   pip install -r requirements.txt

3. 配置环境变量： 创建.env文件，添加必要的API密钥和配置信息，例如：

   OPENROUTER_API_KEY=your_api_key_here

基础配置

框架的核心配置文件位于environments/benchmarks/terminalbench_2/default.yaml，可以根据需要调整以下关键参数：

• dataset_name：指定要使用的评估数据集，默认为"NousResearch/terminal-bench-2"
• test_timeout：测试执行的超时时间（秒），默认为180秒
• task_timeout：每个任务的总超时时间（秒），默认为1800秒（30分钟）
• max_agent_turns：代理最大交互轮次，默认为60轮

核心组件详解：评估流程与实现原理

数据集加载与任务过滤

框架使用HuggingFace Datasets库加载Terminal-Bench 2.0数据集。在setup方法中，数据集被加载并应用任务过滤：

async def setup(self): """Load the Terminal-Bench 2.0 dataset from HuggingFace.""" from datasets import load_dataset # Auto-set terminal_lifetime to task_timeout + 120s lifetime = self.config.task_timeout + 120 self.config.terminal_lifetime = lifetime os.environ["TERMINAL_LIFETIME_SECONDS"] = str(lifetime) print(f" Terminal lifetime auto-set to {lifetime}s (task_timeout + 120s)") print(f"Loading TB2 dataset from: {self.config.dataset_name}") ds = load_dataset(self.config.dataset_name, split="train") # Apply task filters (comma-separated strings from CLI) tasks = list(ds) if self.config.task_filter: allowed = {name.strip() for name in self.config.task_filter.split(",")} tasks = [t for t in tasks if t["task_name"] in allowed] print(f" Filtered to {len(tasks)} tasks: {sorted(allowed)}")

任务执行与评估流程

框架的核心评估逻辑在evaluate方法中实现，主要流程包括：

1. 初始化任务列表和进度跟踪
2. 为每个任务创建异步评估任务
3. 执行评估并收集结果
4. 计算和展示评估指标

关键代码实现如下：

async def evaluate(self, *args, **kwargs) -> None: """ Run Terminal-Bench 2.0 evaluation over all tasks. """ start_time = time.time() # 日志和进度条配置... print(f"\n{'='*60}") print("Starting Terminal-Bench 2.0 Evaluation") print(f"{'='*60}") print(f" Dataset: {self.config.dataset_name}") print(f" Total tasks: {len(self.all_eval_items)}") # 打印其他配置信息... # 创建评估任务 total_tasks = len(self.all_eval_items) eval_tasks = [ asyncio.ensure_future(self._eval_with_timeout(item)) for item in self.all_eval_items ] results = [] passed_count = 0 pbar = tqdm(total=total_tasks, desc="Evaluating TB2", dynamic_ncols=True) try: for coro in asyncio.as_completed(eval_tasks): result = await coro results.append(result) if result and result.get("passed"): passed_count += 1 done = len(results) pct = (passed_count / done * 100) if done else 0 pbar.set_postfix_str(f"pass={passed_count}/{done} ({pct:.1f}%)") pbar.update(1) # 异常处理和清理...

任务沙箱与环境隔离

为确保评估的公平性和可重复性，框架为每个任务创建独立的Docker容器环境。_resolve_task_image方法负责解析任务所需的Docker镜像：

def _resolve_task_image( self, item: Dict[str, Any], task_name: str ) -> Tuple[str, Optional[Path]]: """ Resolve the Docker image for a task, with fallback to Dockerfile. """ docker_image = item.get("docker_image", "") environment_tar = item.get("environment_tar", "") # Fast path: use pre-built Docker Hub image if docker_image and not self.config.force_build: logger.info("Task %s: using pre-built image %s", task_name, docker_image) return docker_image, None # Slow path: extract Dockerfile from environment_tar and build if environment_tar: task_dir = Path(tempfile.mkdtemp(prefix=f"tb2-{task_name}-")) _extract_base64_tar(environment_tar, task_dir) dockerfile_path = task_dir / "Dockerfile" if dockerfile_path.exists(): logger.info( "Task %s: building from Dockerfile (force_build=%s, docker_image=%s)", task_name, self.config.force_build, bool(docker_image), ) return str(dockerfile_path), task_dir # Fallback logic...

测试验证机制

任务完成后，框架通过执行测试脚本来验证任务是否成功完成。_run_tests方法实现了这一验证过程：

def _run_tests( self, item: Dict[str, Any], ctx: ToolContext, task_name: str ) -> float: """ Upload and execute the test suite in the agent's sandbox, then download the verifier output locally to read the reward. """ tests_tar = item.get("tests_tar", "") test_sh = item.get("test_sh", "") if not test_sh: logger.warning("Task %s: no test_sh content, reward=0", task_name) return 0.0 # 创建必要目录 ctx.terminal("mkdir -p /tests /logs/verifier") # 上传测试文件 if tests_tar: tests_temp = Path(tempfile.mkdtemp(prefix=f"tb2-tests-{task_name}-")) try: _extract_base64_tar(tests_tar, tests_temp) ctx.upload_dir(str(tests_temp), "/tests") except Exception as e: logger.warning("Task %s: failed to upload test files: %s", task_name, e) finally: shutil.rmtree(tests_temp, ignore_errors=True) # 执行测试脚本并获取结果...

高级功能：并行评估与结果分析

并发评估机制

为提高评估效率，框架支持多任务并行执行。通过asyncio和信号量控制并发数量：

# 在config_init方法中设置工具池大小 tool_pool_size=128,

结果收集与可视化

评估完成后，框架会生成详细的结果报告，包括总体通过率、各分类任务通过率以及每个任务的具体执行情况：

# 计算指标 total = len(valid_results) passed = sum(1 for r in valid_results if r.get("passed")) overall_pass_rate = passed / total if total > 0 else 0.0 # 分类统计 cat_results: Dict[str, List[Dict]] = defaultdict(list) for r in valid_results: cat_results[r.get("category", "unknown")].append(r) # 打印总结报告 print(f"\n{'='*60}") print("Terminal-Bench 2.0 Evaluation Results") print(f"{'='*60}") print(f"Overall Pass Rate: {overall_pass_rate:.4f} ({passed}/{total})") print(f"Evaluation Time: {end_time - start_time:.1f} seconds") print("\nCategory Breakdown:") for category, cat_items in sorted(cat_results.items()): cat_passed = sum(1 for r in cat_items if r.get("passed")) cat_total = len(cat_items) cat_rate = cat_passed / cat_total if cat_total > 0 else 0.0 print(f" {category}: {cat_rate:.1%} ({cat_passed}/{cat_total})")

与Wandb集成

框架还支持与Weights & Biases (Wandb)集成，实现评估结果的可视化和跟踪：

async def wandb_log(self, wandb_metrics: Optional[Dict] = None): """Log TB2-specific metrics to wandb.""" if wandb_metrics is None: wandb_metrics = {} # Add stored eval metrics for metric_name, metric_value in self.eval_metrics: wandb_metrics[metric_name] = metric_value self.eval_metrics = [] await super().wandb_log(wandb_metrics)

实际应用：自定义任务与扩展方法

创建自定义评估任务

要添加自定义评估任务，需要创建符合Terminal-Bench 2.0格式的任务定义。每个任务定义应包含以下关键信息：

• task_name：任务名称
• category：任务分类
• instruction：任务描述和要求
• docker_image：任务所需的Docker镜像
• test_sh：用于验证任务完成情况的测试脚本

扩展评估指标

框架支持扩展自定义评估指标。可以通过修改evaluate方法中的指标计算部分，添加新的评估维度：

# 在evaluate方法中添加自定义指标计算 eval_metrics = { "eval/pass_rate": overall_pass_rate, "eval/total_tasks": total, "eval/passed_tasks": passed, "eval/evaluation_time_seconds": end_time - start_time, # 添加自定义指标 "eval/average_turns": average_turns, "eval/success_rate_by_category": category_success_rates, }

最佳实践：性能优化与常见问题解决

性能优化建议

1. 合理设置并发数：根据系统资源情况调整tool_pool_size参数，避免资源竞争。
2. 使用预构建镜像：优先使用预构建的Docker镜像，减少任务启动时间。
3. 优化测试脚本：确保测试脚本高效执行，避免不必要的延迟。

常见问题解决

1. 任务超时：如果多个任务出现超时，可能需要增加task_timeout参数值，或检查任务是否过于复杂。
2. 资源占用过高：可通过减少并发任务数量或增加系统资源来解决。
3. 测试脚本失败：检查测试脚本是否与任务环境兼容，确保所有依赖都已正确安装。

总结与展望

Hermes Agent性能基准测试框架提供了一个全面、灵活的评估解决方案，帮助开发者客观衡量智能代理在终端环境中的性能表现。通过标准化的评估流程和丰富的分析功能，框架能够为代理的改进提供有价值的 insights。

未来，框架可以在以下方面进一步完善：

1. 支持更多类型的评估任务和环境
2. 提供更详细的性能分析和瓶颈识别
3. 增强与其他评估工具和平台的集成

通过持续优化和扩展，Hermes Agent性能基准测试框架将成为智能代理开发和评估的重要工具，推动代理技术的不断进步。

要了解更多关于Hermes Agent的信息，请参考项目文档：docs/agents.md 和 docs/tools.md。