快速开始

前置要求

Python 3.11+
Node.js 18+（仅 Agent-TARS 需要）
uv（推荐的 Python 包管理器）

安装

克隆仓库

git clone https://github.com/lexmount/browseruse-bench.git
cd browseruse-bench

安装 Python 依赖

# 安装核心依赖并注册 bubench CLI
uv sync

激活 venv，确保 bubench 可用：

source .venv/bin/activate

Windows PowerShell:

.venv\Scripts\Activate.ps1

bubench run 会在首次运行时创建 config.yaml 中指定的 venv（内置默认： .venvs/browser_use、.venvs/skyvern、.venvs/agent_tars），并自动安装对应 Agent 的依赖。 Agent 的 venv 必须显式配置（不会回退到 .venv）。如果未安装 uv，创建/安装会退回到 python -m venv 与 pip。

配置环境变量 (.env)

cp .env.example .env

编辑 .env——以 .env.example 为准，下列是常用项。 config.yaml 中的 $VAR 占位符会在运行时从该文件解析。

### OpenAI API（Agent 与评估流程共用）
OPENAI_API_KEY=your-openai-api-key-here
# OPENAI_BASE_URL=https://api.openai.com/v1    # 可选：自定义 / OpenAI 兼容网关

### OpenAI 兼容网关（Skyvern 及使用 openai_compatible_* 的 Agent）
# OPENAI_COMPATIBLE_API_KEY=your-gateway-api-key
# OPENAI_COMPATIBLE_API_BASE=https://your-gateway.example.com/v1

### Anthropic API（Claude Code Agent）
ANTHROPIC_API_KEY=your-anthropic-api-key-here
# ANTHROPIC_BASE_URL=https://api.anthropic.com

### Lexmount 云浏览器
LEXMOUNT_API_KEY=your-lexmount-api-key
LEXMOUNT_PROJECT_ID=your-project-id
# LEXMOUNT_BASE_URL=https://api.lexmount.cn   # 可选。官方地址：
#   https://api.lexmount.cn               — 生产（国内）
#   https://api.lexmount.com              — 生产（国外）

### Browser Use API（仅当 models.*.model_type: BROWSER_USE 时）
BROWSER_USE_API_KEY=your-browser-use-api-key

### AgentBay（仅当 browser_id: agentbay 时）
# AGENTBAY_API_KEY=your-agentbay-api-key

### HuggingFace 镜像（可选，国内加速）
# HF_ENDPOINT=https://hf-mirror.com

Lexmount 凭据：到 browser.lexmount.cn（国内）或 browser.lexmount.com（国外）申请 LEXMOUNT_API_KEY 与 LEXMOUNT_PROJECT_ID。完整配置步骤参见 Lexmount 云浏览器。

配置 config.yaml

cp config.example.yaml config.yaml

根目录 config.yaml 是项目的运行时主配置，$VAR 占位符会在运行时从 .env 解析。需要配置三部分：1. Agent 模型 — 在 agents.<agent> 下指定默认使用的模型：

agents:
  browser-use:
    active_model: gpt-5.4         # 指向下方 models 里的任一 key
    models:
      gpt-5.4:
        model_type: OPENAI        # OPENAI | GEMINI | ANTHROPIC | AZURE | BROWSER_USE
        model_id: gpt-5.4
        api_key: $OPENAI_API_KEY
        base_url: $OPENAI_BASE_URL
      browser-use:
        model_type: BROWSER_USE
        model_id: bu-2-0
        api_key: $BROWSER_USE_API_KEY

运行时可通过 --model <name> 覆盖 active_model，无需改文件。

2. 浏览器后端 — 在 agents.<agent>.browser 下选择一个 browser_id，只保留对应后端所需的参数，其它注释掉：

agents:
  browser-use:
    browser:
      browser_id: lexmount          # lexmount | Chrome-Local | agentbay | browser-use-cloud | cdp
      # --- lexmount ---
      lexmount_browser_mode: normal
      lexmount_api_key: $LEXMOUNT_API_KEY
      lexmount_project_id: $LEXMOUNT_PROJECT_ID
      # --- Chrome-Local ---
      # browser_id: Chrome-Local   # 无需额外参数
      # --- agentbay ---
      # browser_id: agentbay       # 需在 .env 中设置 AGENTBAY_API_KEY

详细后端选项参见本地 Chromium 浏览器、Lexmount 云浏览器及各 Agent 的文档页。重要：本地 Chromium 不会继承系统 / clash / v2ray 代理——若需访问裸连不可达的站点（如 bloomberg.com、archive.org），请配 local_proxy_server。3. Eval 评估模型 — 供 bubench eval 作为 LLM-as-judge 评判使用：

eval:
  model: gpt-5.4
  api_key: $OPENAI_API_KEY
  base_url: $OPENAI_BASE_URL   # 直连 api.openai.com 时可删掉

安装 Agent-TARS CLI（可选）

npm install -g @agent-tars/cli@0.3.0

安装技能包（可选）

bubench skills

快速运行

运行你的第一个 Benchmark

# 运行 LexBench-Browser 前 3 个任务
bubench run \
  --agent browser-use \
  --data LexBench-Browser \
  --mode first_n \
  --count 3

# 运行 Online-Mind2Web 前 3 个任务
bubench run \
  --agent Agent-TARS \
  --data Online-Mind2Web \
  --mode first_n \
  --count 3

# 运行 BrowseComp 前 3 个任务
bubench run \
  --agent browser-use \
  --data BrowseComp \
  --mode first_n \
  --count 3

快速自检（推荐）

加上 --dry-run 可校验配置加载与任务筛选，不会真的执行任务：

bubench run \
  --agent browser-use \
  --data LexBench-Browser \
  --mode single \
  --dry-run

--dry-run 只校验 config.yaml / .env 能否正常解析、--data / --split / --mode 能否匹配到至少一个任务；不会创建 Agent venv、调用模型 API、也不会启动浏览器——这些都只在真实运行时发生。

评估结果

# 默认使用 config.yaml 中 active_model 对应的 model_id
bubench eval --agent browser-use --data LexBench-Browser

# 评估非默认模型的运行结果时，显式传 --model-id
bubench eval --agent browser-use --data LexBench-Browser --model-id gpt-5.4

# 自定义评分阈值
bubench eval --agent browser-use --data LexBench-Browser --score-threshold 70

--model-id 决定 eval 读取哪个输出子目录（experiments/<benchmark>/<split>/<agent>/<model_id>/）。不传时会回退到 config.yaml 中 agents.<agent>.active_model 对应的 model_id，与 bubench run 默认写入的路径一致。

日志: 脚本执行日志保存在 output/logs/ 目录下。

run.py: output/logs/run/

eval.py: output/logs/eval/

leaderboard: output/logs/leaderboard/

生成排行榜

# 自动收集所有评估结果，生成 HTML 排行榜
bubench leaderboard

# 启动本地服务器查看
bubench server
# 访问 http://localhost:8000

运行模式

模式	说明	示例
`single`	运行第一个任务（快速自检）	`--mode single`
`first_n`	运行前 N 个任务	`--mode first_n --count 5`
`sample_n`	随机抽样 N 个任务	`--mode sample_n --count 10`
`specific`	运行指定 ID 的任务	`--mode specific --task-ids id1 id2`
`by_id`	按数值 ID 运行单个任务	`--mode by_id --id 123`
`all`	运行所有任务	`--mode all`

注意: --task-ids 需要以空格分隔多个 ID。

常用参数

bubench run \
  --agent browser-use \
  --data LexBench-Browser \
  --mode first_n \
  --count 5 \
  --timeout 600 \
  --skip-completed \
  --dry-run

其他常用参数：

--data-source: local 或 huggingface。
--force-download: HuggingFace 模式下强制重新下载。
--agent-config: 可选的备用 root-config YAML 路径（与 config.yaml 同结构）。默认读取仓库根 config.yaml。
--timestamp: 指定运行/恢复的目录（格式 YYYYMMDD_HHmmss）。

--timeout 会覆盖 Agent 配置中的 TIMEOUT。

断点续跑

如果运行中途中断，可用 --timestamp 指向原输出目录，并加 --skip-completed 跳过已完成的任务：

bubench run \
  --agent browser-use \
  --data LexBench-Browser \
  --timestamp 20260101_120000 \
  --skip-completed \
  --mode all

提示: 在 experiments/{benchmark}/{split}/{agent}/ 下可查看已有的 timestamp 目录名。

并行运行多个 Agents

bubench run 使用 config.yaml 中为 agent 指定的 venv，并在首次运行时自动创建/安装依赖。内置 agent 默认使用独立 venv：

browser-use -> .venvs/browser_use
skyvern -> .venvs/skyvern
Agent-TARS -> .venvs/agent_tars

如果某个 agent 条目未配置 venv，bubench run 会直接报错，不会回退到 .venv。如果需要同时运行互斥的 Agent，可以在两个终端中分别运行各自的 Agent，确保使用不同的 venv。

并行执行任务（按 Task ID 分片）

对于大型 benchmark，可将任务按 ID 拆分到多个终端并行运行：

# 终端 1
bubench run --agent browser-use --data LexBench-Browser \
  --mode specific --task-ids task_001 task_002 task_003

# 终端 2
bubench run --agent browser-use --data LexBench-Browser \
  --mode specific --task-ids task_004 task_005 task_006

两个终端使用相同的 --timestamp，可将结果写入同一个输出目录。

Node.js Agents（无冲突）

Agent-TARS 通过 Node.js CLI 运行，不与 Python 依赖冲突。安装 CLI 后可在任意终端运行：

bubench run --agent Agent-TARS ...

下一步

支持的 Agents

了解可用的浏览器代理

Benchmarks 详解

深入了解各个基准测试

云浏览器配置

使用 Lexmount 云浏览器

查看排行榜

对比不同 Agent 的性能

开始

功能

示例

开发

前置要求

安装

快速运行

运行你的第一个 Benchmark

快速自检（推荐）

评估结果

生成排行榜

运行模式

常用参数

断点续跑

并行运行多个 Agents

并行执行任务（按 Task ID 分片）

Node.js Agents（无冲突）

下一步

支持的 Agents

Benchmarks 详解

云浏览器配置

查看排行榜

​前置要求

​安装

​快速运行

​运行你的第一个 Benchmark

​快速自检（推荐）

​评估结果

​生成排行榜

​运行模式

​常用参数

​断点续跑

​并行运行多个 Agents

​并行执行任务（按 Task ID 分片）

​Node.js Agents（无冲突）

​下一步

支持的 Agents

Benchmarks 详解

云浏览器配置

查看排行榜

前置要求

安装

快速运行

运行你的第一个 Benchmark

快速自检（推荐）

评估结果

生成排行榜

运行模式

常用参数

断点续跑

并行运行多个 Agents

并行执行任务（按 Task ID 分片）

Node.js Agents（无冲突）

下一步