cua-bench 测试与基础设施基准测试实战指南：为 Computer-Use Agent 构建可验证的跨平台评测环境-创锋一号

cua-bench 测试与基础设施基准测试实战指南：为 Computer-Use Agent 构建可验证的跨平台评测环境

【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua

cua-bench 是 CUA（Computer-Use Agents）开源仓库中负责基准测试的核心框架，它为 Computer-Use Agent 提供可验证的跨平台评测环境（gym 接口）、可并行的 Worker 基础设施以及完整的测试体系。本篇指南基于 libs/cua-bench/README.md 展开，结合仓库源码与测试用例，系统讲解如何安装依赖、运行单元测试与端到端测试、理解各测试模块的职责边界，以及如何使用benchmark_workers脚本量化 Worker 基础设施的吞吐能力。读完本文，你将能够独立搭建 cua-bench 的开发环境，读懂其测试矩阵的设计意图，并掌握一套可直接复用的并行环境性能评测方法。

一、框架定位与整体结构

cua-bench（项目内路径 libs/cua-bench）在 pyproject.toml 中被描述为 "Toolkit for computer-use RL environments and benchmarks"，即面向 Computer-Use 强化学习的环境与基准测试工具包，版本为 0.2.11，要求 Python 3.12 至 3.14。其核心目标是：用可验证的跨平台环境对 Computer-Use Agent 进行基准评测。

从包结构看，框架大致分为四层：

环境层：cua_bench/environment.py 与 cua_bench/core.py 提供 gym 风格环境接口（make()/reset()/step()/evaluate()），并支持通过 provider 切换真实的跨平台环境（如 simulated、Docker 等）。
动作层：cua_bench/types.py 定义ClickAction、TypeAction、DoneAction等动作类型；cua_bench/actions.py 提供动作字符串解析（repr_to_action）。
Worker 层：cua_bench/workers 目录下包含worker_server.py（FastAPI 服务端）、worker_client.py（HTTP 客户端）、worker_manager.py（Worker 管理与 dataloader 训练循环）、dataloader.py。
任务与评测层：cua_bench/tasks 下提供cua-bench-basic、cua-bench-kicad、cua-bench-workflows等数据集，以及 slack、wordpad、2048 等示例环境，用于训练、评测与数据生成。

README 的核心篇幅集中在两件事：如何运行测试与如何做基础设施基准测试，下面分别展开。

二、安装开发依赖：快速搭建测试环境

cua-bench 使用 uv 作为包管理器（见 uv.lock），安装开发依赖的命令为：

uv pip install -e ".[dev,browser,server,rl]"

这条命令通过 extras 组合安装了几类依赖（各 extra 定义见 pyproject.toml）：

Extra	作用	关键依赖
`dev`	测试与代码检查	pytest、pytest-asyncio、fastapi、httpx、uvicorn、ruff
`browser`	Playwright 浏览器自动化，供 simulated provider 的 e2e 测试使用	playwright
`server`	FastAPI 服务端，用于自定义环境的 HTTP API	fastapi、uvicorn、python-multipart、aiosqlite
`rl`	强化学习训练栈	torch、torchvision、transformers

README 特别提示：browserextra 安装的 Playwright 是 simulated provider 执行 e2e 测试的前提。如果你的目标是训练模型，还需要rl；如果要起 Worker 服务端，则需要server。仓库还提供all、daytona、cloud、agents、otel、spice、packaging、windows等其他 extra，例如spice（PySpice，用于 KiCad 网表评测）、cloud（Google Cloud Batch 云端批量执行）、otel（OpenTelemetry 追踪导出），可按需选用。

安装后，可通过cb或cua-bench命令入口（由 pyproject.toml 的[project.scripts]声明，指向cua_bench.cli.main:main）验证安装是否成功。

三、运行测试：从全量回归到精准定位

3.1 全量测试

uv run --with pytest pytest cua_bench/tests/ -v

uv run --with pytest会在隔离环境中临时附带 pytest 再执行，避免污染当前环境。-v输出详细用例名，便于定位失败用例。pyproject.toml 中已配置asyncio_mode = "auto"，因此异步测试无需手动添加@pytest.mark.asyncio（测试文件内保留该装饰器也无妨）。

3.2 按模块定点测试

当某个模块改动后，更高效的做法是只跑对应测试模块：

# 核心 gym 接口（make、reset、step、evaluate） uv run --with pytest pytest cua_bench/tests/test_gym_interface.py -v # HTTP worker 客户端（/reset、/step 端点） uv run --with pytest pytest cua_bench/tests/test_worker_client.py -v # Worker 服务端端点与动作序列化 uv run --with pytest pytest cua_bench/tests/test_worker_server.py -v # 基准评测 runner 函数 uv run --with pytest pytest cua_bench/tests/test_run_benchmark.py -v # Worker 管理器（spawning/managing workers） uv run --with pytest pytest cua_bench/tests/test_worker_manager.py -v # 动作解析 uv run --with pytest pytest cua_bench/tests/test_actions.py -v

实际仓库的测试目录 libs/cua-bench/cua_bench/tests 中还存在test_bundled_examples.py、test_dataset_metadata.py、test_iconify.py、test_task_runner.py等 README 未单独列出的测试模块，分别覆盖内置示例任务、数据集元数据、图标生成与任务运行器，可按需补充运行。

3.3 带覆盖率统计

uv run --with pytest --with pytest-cov pytest cua_bench/tests/ -v --cov=cua_bench --cov-report=term-missing

--cov=cua_bench统计包整体覆盖率，--cov-report=term-missing在终端输出时列出未覆盖行号，便于针对性补测。

四、测试结构解读：五个核心模块的分工与设计哲学

README 用一张表格清晰划分了五个核心测试模块的职责、测试内容与测试方式：

测试模块	测试内容	测试方式
`test_gym_interface.py`	核心环境 API：`make()`、`reset()`、`step()`、`evaluate()`	E2E：真实 simulated（Playwright）环境
`test_worker_client.py`	Worker 服务端的 HTTP 客户端（`CBEnvWorkerClient`）	Mock server：`@patch("requests.post")`mock HTTP 响应
`test_worker_server.py`	FastAPI 端点与动作序列化	Unit：动作序列化/反序列化、请求模型、简单端点
`test_run_benchmark.py`	`run_benchmark()`、`run_single_task()`、`run_interactive()`	E2E：真实 simulated（Playwright）环境
`test_worker_manager.py`	Workers + dataloader 训练循环	E2E：真实 workers、真实环境、mock 模型生成动作

4.1 test_gym_interface.py：验证环境 API 契约

该文件对 gym 风格接口进行端到端验证，覆盖了环境生命周期中的每一个关键行为（见 test_gym_interface.py）：

make()：从任务目录读取main.py构造环境；目录不存在或缺少main.py时抛出FileNotFoundError；支持按split参数（train/test）加载对应tasks_config。
reset()：返回截图（bytes）与任务配置，task_cfg.description可读；重置会清零step_count。
step()：执行ClickAction、WaitAction等动作并返回新截图，同时递增step_count。
evaluate()：调用任务内定义的evaluate_task回调返回评分列表（例如点击按钮后window.__score为 0.75，则返回[0.75]）。
solve()：运行求解器（bot 辅助函数，如session.click_element）完成任务，再用evaluate()验证前后分数变化（0.0 → 1.0）。
close()：释放 session；对无 session 的环境也能安全关闭。

测试中的任务定义方式值得留意：任务目录的main.py通过@cb.tasks_config(split=...)声明任务列表，用@cb.setup_task启动窗口（session.launch_window(html=...)），用@cb.evaluate_task定义评分逻辑，这是 cua-bench 任务的标准写法。

4.2 test_worker_client.py：Mock HTTP 隔离客户端逻辑

CBEnvWorkerClient是 worker 服务端的 HTTP 客户端。该测试通过@patch("requests.post")模拟服务端响应，在不启动真实服务的情况下验证（见 test_worker_client.py）：

初始化参数解析：server_url、task_configs、max_step、max_hist、timeout。
reset()正确 POST/reset，携带env_path、task_index，并返回含obs、done、is_init的观测结构与uid。
step()正确 POST/step，携带env_id与动作字符串，返回obs/action/reward/done；done=True时同步设置客户端状态。
动作容错：check_and_fix_action对非法动作回退为wait()，保证训练循环不因单次解析失败崩溃。
观测组装：prompt_to_input_obs将指令与多轮vision/action片段拼接为模型输入。

4.3 test_worker_server.py：验证 REST API 与动作序列化

服务端基于 FastAPI（实现在 worker_server.py），该测试覆盖（见 test_worker_server.py）：

动作序列化往返：serialize_action/deserialize_action支持 11 种动作类型（Click、RightClick、DoubleClick、MiddleClick、Drag、MoveTo、Scroll、Type、Key、Hotkey、Wait、Done），未知类型抛出ValueError。
请求模型默认值：ResetRequest默认task_index=0、split="train"、timeout=300；ShutdownRequest的env_id=None表示关闭全部环境。
HTTP 端点：GET /health返回status/available_envs/active_envs/max_envs；POST /shutdown释放环境；对不存在的env_id调用/step、/screenshot返回 404。

从源码看，服务端还内置了基于环境变量OSGYM_ALLOWED_IPS（默认127.0.0.1）的 IP 过滤中间件（非白名单 IP 返回 403），以及最多MAX_ENVS = 2个并发环境的槽位池管理（_get_available_env/_release_env），环境空闲超过DEFAULT_TIMEOUT（300 秒）会被回收。这些是理解服务端并发模型的关键细节。

4.4 test_worker_manager.py：模拟训练循环

该测试使用真实 workers + 真实环境 + mock 模型验证 dataloader 训练循环——mock 模型只返回简单动作，因此无需真实 ML 模型即可跑通从数据加载、环境交互到轨迹收集的整条链路，是 RL 训练闭环的最小可用验证。

4.5 test_actions.py：纯函数级动作解析

repr_to_action是纯函数，测试覆盖度最高（见 test_actions.py）：

全部动作类型的repr→ 解析 → 再repr的往返一致性（round-trip）。
默认值验证：WaitAction()默认seconds=1.0，ScrollAction()默认direction="up"、amount=100，DragAction()默认duration=1.0，MoveToAction()默认duration=0.0。
错误处理：None与非字符串输入抛出ValueError("action_repr must be a string")；空串、未知动作类型、参数缺失（如ClickAction(x=100)缺 y）均抛出ValueError("Unknown action representation")。
鲁棒性：首尾空白会被正确剔除。

4.6 测试方法论小结

README 明确总结了三种测试方式的取舍：

E2E 测试使用真实 simulated（Playwright）环境——simulated provider 足够快，适合端到端验证环境交互；
Mock server 测试（test_worker_client.py）mock HTTP 响应，在隔离环境中验证客户端逻辑；
Mock model（test_worker_manager.py）用返回简单动作的 mock 模型驱动 dataloader 训练循环，避免引入真实 ML 模型的重量级依赖。

这套"三层递进"的测试策略（纯函数单元测试 → 服务端接口测试 → 端到端环境测试）值得在同类评测框架中借鉴。

五、基础设施基准测试：量化 Worker 吞吐

除了功能正确性，cua-bench 还关心worker 基础设施的吞吐能力——即并行的环境服务端在单位时间内能处理多少 reset/step。这是 RL 训练数据生成速度的硬指标。

5.1 运行基准测试

uv run python -m cua_bench.scripts.benchmark_workers --num_workers 16 --num_steps 10

5.2 命令行参数

参数	默认值	说明
`--num_workers`	16	并行 worker 数量
`--num_steps`	10	每个 worker 执行的 step 数
`--task_path`	None	任务目录路径；为空时自动创建临时任务

5.3 输出指标

运行结束后脚本输出：

平均 reset 时间（Average reset time）
平均 step 时间（Average step time）
平均 finish 时间（Average finish time）
step 吞吐（Step throughput，steps/sec）

5.4 实现细节：脚本是如何测的

从 benchmark_workers.py 源码可以看出完整的测量流程：

任务准备：未指定--task_path时，脚本在临时目录中生成一个含 20 个任务的模拟环境（simulated provider + 一个可点击按钮的 HTML 窗口），每个任务定义setup_task与evaluate_task。
启动 worker 服务端：调用create_workers(n_workers=..., allowed_ips=["127.0.0.1"], startup_timeout=120.0)批量拉起 worker 服务端并记录启动耗时。
并行驱动：为每个 worker 启动一个multiprocessing.Process，进程内创建CBEnvWorkerClient（env_config含server_url、task_configs、max_step=100、max_hist=10、timeout=300），执行reset()后循环step()，动作以<|action_start|>click(500,500)<|action_end|>这种带标签的字符串形式下发；当某轮返回done时自动重新reset()进入下一轮，最后以done()动作收尾。
聚合统计：通过multiprocessing.Manager共享字典收集各 worker 的耗时，最后汇总计算平均 reset/step/finish 时间，并分别输出单 worker 吞吐与总吞吐（per_worker_throughput * num_workers）。

这套流程与test_worker_manager.py共享同一套 worker 语义，即"服务端负责环境槽位管理、客户端负责动作下发、进程级并行负责吞吐扩展"。基准测试使用click(500,500)这类固定动作而非真实模型策略，因此测到的是基础设施本身的吞吐上限，与策略质量无关——这正是"Infrastructure Benchmarking"的定位：在搭建大规模数据生成或 RL 训练流水线之前，先量化底层的天花板。

六、从测试到实战：可复用的三条经验

把环境 API 契约测试作为一切改动的回归基线：test_gym_interface.py覆盖了make/reset/step/evaluate/solve/close全生命周期，任何 provider、session 或动作执行链路的改动都应先跑该模块。
用 Worker 抽象解耦"评测逻辑"与"训练/数据生成"：CBEnvWorkerClient只依赖server_url与任务配置，训练进程可以像调用本地环境一样驱动远程环境，配合/health、/shutdown端点实现弹性伸缩与优雅回收。
基准测试先行：在批量跑任务之前，用benchmark_workers以--num_workers 16 --num_steps 10起步，根据平均 step 时间与吞吐决定并行度与超时预算（默认 300 秒），避免盲目扩并发导致服务端槽位耗尽（MAX_ENVS=2的服务端在并发不足时会返回 503 "No available environments"）。

七、进一步探索

测试目录：libs/cua-bench/cua_bench/tests（含 README 未展开的 bundled examples、dataset metadata 等测试）
Worker 实现：libs/cua-bench/cua_bench/workers/worker_server.py、worker_client.py、worker_manager.py
基准脚本：libs/cua-bench/cua_bench/scripts/benchmark_workers.py
动作类型与解析：libs/cua-bench/cua_bench/types.py、libs/cua-bench/cua_bench/actions.py
依赖与入口：libs/cua-bench/pyproject.toml
数据集与示例任务：libs/cua-bench/datasets/（cua-bench-basic、cua-bench-kicad、cua-bench-workflows）与libs/cua-bench/example_tasks/、libs/cua-bench/tasks/（slack_env、wordpad_env、winarena_adapter 等）

cua-bench 的价值在于把"环境定义、动作协议、并行基础设施、性能度量"完整打通，而其测试体系恰恰是这套协议最精确的文档。对于任何希望在 Computer-Use 评测或 RL 数据生成方向做工程落地的开发者，这份测试矩阵与基准脚本都是可以直接借鉴的样板。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析