> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bubench.lexmount.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速开始

> 5 分钟内完成 browseruse-bench 的安装和首次运行

## 前置要求

* Python 3.11+
* Node.js 18+（仅 Agent-TARS 需要）
* [uv](https://docs.astral.sh/uv/)（推荐的 Python 包管理器）

## 安装

<Steps>
  <Step title="克隆仓库">
    ```bash theme={null}
    git clone https://github.com/lexmount/browseruse-bench.git
    cd browseruse-bench
    ```
  </Step>

  <Step title="安装 Python 依赖">
    ```bash theme={null}
    # 安装核心依赖并注册 bubench CLI
    uv sync
    ```

    激活 venv，确保 `bubench` 可用：

    ```bash theme={null}
    source .venv/bin/activate
    ```

    Windows PowerShell:

    ```bash theme={null}
    .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`。
  </Step>

  <Step title="配置环境变量 (.env)">
    ```bash theme={null}
    cp .env.example .env
    ```

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

    ```bash theme={null}
    ### 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](https://browser.lexmount.cn)（国内）或 [browser.lexmount.com](https://browser.lexmount.com)（国外）申请 `LEXMOUNT_API_KEY` 与 `LEXMOUNT_PROJECT_ID`。完整配置步骤参见 [Lexmount 云浏览器](/zh/browser/lexmount)。
  </Step>

  <Step title="配置 config.yaml">
    ```bash theme={null}
    cp config.example.yaml config.yaml
    ```

    根目录 `config.yaml` 是项目的运行时主配置，`$VAR` 占位符会在运行时从 `.env` 解析。
    需要配置三部分：

    **1. Agent 模型** — 在 `agents.<agent>` 下指定默认使用的模型：

    ```yaml theme={null}
    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
    ```

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

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

    ```yaml theme={null}
    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 浏览器](/zh/browser/local)、[Lexmount 云浏览器](/zh/browser/lexmount) 及各 Agent 的文档页。**重要**：本地 Chromium 不会继承系统 / clash / v2ray 代理——若需访问裸连不可达的站点（如 `bloomberg.com`、`archive.org`），请配 `local_proxy_server`。

    **3. Eval 评估模型** — 供 `bubench eval` 作为 LLM-as-judge 评判使用：

    ```yaml theme={null}
    eval:
      model: gpt-5.4
      api_key: $OPENAI_API_KEY
      base_url: $OPENAI_BASE_URL   # 直连 api.openai.com 时可删掉
    ```
  </Step>

  <Step title="安装 Agent-TARS CLI（可选）">
    ```bash theme={null}
    npm install -g @agent-tars/cli@0.3.0
    ```
  </Step>

  <Step title="安装技能包（可选）">
    ```bash theme={null}
    bubench skills
    ```
  </Step>
</Steps>

## 快速运行

### 运行你的第一个 Benchmark

<CodeGroup>
  ```bash LexBench-Browser theme={null}
  # 运行 LexBench-Browser 前 3 个任务
  bubench run \
    --agent browser-use \
    --data LexBench-Browser \
    --mode first_n \
    --count 3
  ```

  ```bash Online-Mind2Web theme={null}
  # 运行 Online-Mind2Web 前 3 个任务
  bubench run \
    --agent Agent-TARS \
    --data Online-Mind2Web \
    --mode first_n \
    --count 3
  ```

  ```bash BrowseComp theme={null}
  # 运行 BrowseComp 前 3 个任务
  bubench run \
    --agent browser-use \
    --data BrowseComp \
    --mode first_n \
    --count 3
  ```
</CodeGroup>

### 快速自检（推荐）

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

```bash theme={null}
bubench run \
  --agent browser-use \
  --data LexBench-Browser \
  --mode single \
  --dry-run
```

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

### 评估结果

```bash theme={null}
# 默认使用 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
```

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

> **日志**: 脚本执行日志保存在 `output/logs/` 目录下。
>
> * `run.py`: `output/logs/run/`
> * `eval.py`: `output/logs/eval/`
> * `leaderboard`: `output/logs/leaderboard/`

### 生成排行榜

```bash theme={null}
# 自动收集所有评估结果，生成 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。

## 常用参数

```bash theme={null}
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` 跳过已完成的任务：

```bash theme={null}
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 拆分到多个终端并行运行：

```bash theme={null}
# 终端 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 后可在任意终端运行：

```bash theme={null}
bubench run --agent Agent-TARS ...
```

## 下一步

<CardGroup cols={2}>
  <Card title="支持的 Agents" icon="robot" href="/zh/agents/overview">
    了解可用的浏览器代理
  </Card>

  <Card title="Benchmarks 详解" icon="chart-bar" href="/zh/benchmarks/overview">
    深入了解各个基准测试
  </Card>

  <Card title="云浏览器配置" icon="cloud" href="/zh/browser/lexmount">
    使用 Lexmount 云浏览器
  </Card>

  <Card title="查看排行榜" icon="trophy" href="/zh/leaderboard/overview">
    对比不同 Agent 的性能
  </Card>
</CardGroup>