13274243a0
Keep K3 suite selection and report-schema scoring in bash, merge K3/vision dataset_args into dpv4 yamls, and pin EvalScope at 735d920ee911 with local patches. Co-authored-by: Cursor <cursoragent@cursor.com>
140 lines
5.5 KiB
Markdown
140 lines
5.5 KiB
Markdown
# Toolathlon
|
||
|
||
Toolathlon 用于评测智能体在真实 MCP 软件环境中的长程工具使用能力。EvalScope 的 `toolathlon` 集成是官方 Toolathlon evaluation service 的 wrapper，不重新实现 MCP 环境、任务容器、agent loop 或官方评分器。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
pip install evalscope[toolathlon]
|
||
```
|
||
|
||
EvalScope wrapper 只需要客户端依赖 `httpx` 和 `websockets`。如果使用官方公共服务，不需要安装完整 Toolathlon 仓库。
|
||
|
||
## 服务模式
|
||
|
||
EvalScope 支持 Toolathlon 官方服务的 private mode。
|
||
|
||
在 private mode 中，Toolathlon 服务负责运行任务容器、MCP 环境、agent loop 和评分。EvalScope 会启动本地 WebSocket relay；当服务端需要模型响应时，请求会通过 WebSocket 转回 EvalScope 所在机器，再调用你的本地或内网 OpenAI-compatible endpoint。因此即使 Toolathlon 服务在远端，也可以使用 `api_url=http://localhost:8000/v1`。
|
||
|
||
官方 Toolathlon client 还支持 public mode，即服务端直接用提交的 API key 调用公共模型 API。EvalScope wrapper 目前固定使用 private mode，让模型 endpoint 和 API key 留在 EvalScope 侧。
|
||
|
||
## 官方公共服务
|
||
|
||
默认服务是官方公共服务：
|
||
|
||
- HTTP service: `47.253.6.47:8080`
|
||
- WebSocket proxy: `47.253.6.47:8081`
|
||
|
||
官方公共服务主要用于快速试跑和调试。根据官方文档，它按 IP 在 24 小时窗口内限流：
|
||
|
||
- 每个 IP 每 24 小时累计执行时长 180 分钟
|
||
- 每个 IP 每 24 小时 3 次 evaluation request
|
||
- 累计执行时长低于 180 分钟时，不受 3 次请求数限制
|
||
- 累计执行时长超过 180 分钟后，开始应用 3 次请求数限制
|
||
|
||
如果提交阶段返回 `HTTP 503 Service Unavailable`，通常表示官方服务忙，因为服务端一次只运行一个 evaluation job。如果返回 `HTTP 429`，则表示触发了 IP 限流。
|
||
|
||
## 快速调试
|
||
|
||
建议先用很小的 `task_list` 调试：
|
||
|
||
```python
|
||
from evalscope import TaskConfig, run_task
|
||
|
||
task_cfg = TaskConfig(
|
||
model='your-model-name',
|
||
api_url='http://localhost:8000/v1',
|
||
api_key='your-local-api-key',
|
||
datasets=['toolathlon'],
|
||
dataset_args={
|
||
'toolathlon': {
|
||
'extra_params': {
|
||
'task_list': ['find-alita-paper'],
|
||
'skip_container_restart': True,
|
||
}
|
||
}
|
||
},
|
||
limit=1,
|
||
)
|
||
|
||
run_task(task_cfg)
|
||
```
|
||
|
||
`skip_container_restart=True` 只建议用于小规模调试。正式评测时应移除它，让官方服务在任务之间重启容器。
|
||
|
||
## 自建官方服务
|
||
|
||
自建服务可以避开公共服务排队和公共 IP 限流，但它不是一个 `docker compose up` 就能完成的部署。官方 Docker 镜像 `docker.io/lockon0927/toolathlon-task-image:1016beta` 主要是任务运行镜像，不包含 Toolathlon evaluation service 所需的所有服务、账号、凭据和评测进程。
|
||
|
||
启动自建服务前，先按官方 Toolathlon 材料完成环境准备：
|
||
|
||
- `README.md`：安装依赖、Docker/Podman、`configs/global_configs.py`、应用凭据、本地服务部署和 smoke check
|
||
- `global_preparation/how2register_accounts.md`：MCP 任务需要的账号、token 和 session
|
||
- `configs/global_configs_example.py`：复制为 `configs/global_configs.py`，并配置 `podman_or_docker`
|
||
- `global_preparation/pull_toolathlon_image.sh`：拉取官方任务镜像
|
||
- `global_preparation/deploy_containers.sh`：部署 Canvas、email、WooCommerce、k8s/kind 等本地服务
|
||
- `EVAL_SERVICE_README.md`：启动官方 `eval_server.py` HTTP 服务和 private mode WebSocket proxy
|
||
|
||
完整 Toolathlon 环境准备好后，在 Toolathlon 仓库中启动官方服务：
|
||
|
||
```bash
|
||
python eval_server.py 8080 8081 3 10 180
|
||
```
|
||
|
||
参数含义：
|
||
|
||
- `server_port`：HTTP 服务端口
|
||
- `ws_proxy_port`：private mode 的 WebSocket proxy 端口
|
||
- `max_submissions_per_ip`：每个 IP 每 24 小时请求数限制，`-1` 表示不限
|
||
- `max_workers`：每个 job 内部最大的 Toolathlon workers 数
|
||
- `max_duration_minutes`：每个 IP 每 24 小时累计执行时长限制，`-1` 表示不限
|
||
|
||
如果是内部自用服务，可以关闭限流：
|
||
|
||
```bash
|
||
python eval_server.py 8080 8081 -1 10 -1
|
||
```
|
||
|
||
## 在 EvalScope 中使用自建服务
|
||
|
||
通过 `extra_params` 指向自建服务：
|
||
|
||
```python
|
||
from evalscope import TaskConfig, run_task
|
||
|
||
task_cfg = TaskConfig(
|
||
model='your-model-name',
|
||
api_url='http://localhost:8000/v1',
|
||
api_key='your-local-api-key',
|
||
datasets=['toolathlon'],
|
||
dataset_args={
|
||
'toolathlon': {
|
||
'extra_params': {
|
||
'server_host': 'your.toolathlon.server',
|
||
'server_port': 8080,
|
||
'ws_proxy_port': 8081,
|
||
'workers': 10,
|
||
'task_list': ['find-alita-paper'],
|
||
}
|
||
}
|
||
},
|
||
limit=1,
|
||
)
|
||
|
||
run_task(task_cfg)
|
||
```
|
||
|
||
如果使用 CLI，把同样的配置放到 `--dataset-args` 的 `toolathlon.extra_params` 下即可。
|
||
|
||
## 运维注意点
|
||
|
||
- 官方服务一次只运行一个 evaluation job。`workers` 控制的是单个 job 内部并行度，不是提交 job 的并发数。
|
||
- 官方服务为了驱动 agent loop 和评分，会接收 prompt、模型响应和工具上下文。
|
||
- 需要保持 client protocol 和官方服务版本一致。当前 EvalScope wrapper 对齐 Toolathlon service protocol `1.3`。
|
||
- 长期或正式评测建议使用 dedicated official service 或自建服务，不建议依赖共享公共服务。
|
||
|
||
官方来源：
|
||
|
||
- [Toolathlon repository](https://github.com/hkust-nlp/Toolathlon)
|
||
- [Toolathlon evaluation service README](https://github.com/hkust-nlp/Toolathlon/blob/main/EVAL_SERVICE_README.md)
|