> ## Documentation Index
> Fetch the complete documentation index at: https://opencompass-docs-preview-pr-335-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 运行控制

通过[快速开始](/zh/get_started/quick_start)验证一个任务后，再调整并发、重试、结果命名和恢复。这些控制适用于 CLI 和 SDK；`launch` 的多个请求共享一个调度器。

| 想做什么 | 从哪里开始 |
| - | - |
| 同时运行更多任务 | [并发](#安全扩展并发) |
| 设置执行或评分预算 | [超时设置](/zh/user_guide/using_agentcompass/timeouts) |
| 应对临时失败 | [重试](#只重试瞬时失败) |
| 命名运行或继续中断任务 | [输出与复用](#输出与复用) |
| 保存任务 Environment 中的文件 | [保存与准备产物](/zh/user_guide/using_agentcompass/artifacts) |
| 检查失败原因 | [调试](#保留-environment-以便调试)与[日志](#日志与进度) |

## 安全扩展并发

先用并发 `1` 跑几个有代表性的任务，再逐步增加到 `2` 或 `4`。观察模型延迟、错误率、Environment 启动时间和内存使用；错误增加时，回到上一个稳定值。

| 控制项 | 默认值 | 作用范围 |
| - | - | - |
| `--task-concurrency` | `32` | 跨任务同时执行的 attempt 数，包括重试。 |
| `--provider-limit <provider=count>` | 每个内置 provider 为 `128` | 通过一个 Environment provider 同时执行的 attempt 数；`0` 表示禁用该限制。 |
| `--env-open-qps <provider=qps>` | 本地：`0`；远程：`10` | 每秒创建的新 Environment 数；`0` 表示禁用启动限速。 |

任务并发和 provider 上限中的较小值决定实际并发上限，模型配额和主机资源还可能进一步限制它。创建速率控制启动节奏，不控制活跃任务数。单个 sandbox 的 CPU 和内存见 [Environment 资源设置](/zh/user_guide/modules/environments/configuration/resource_limits)。

### CLI 写法

在已有的 `run` 命令中添加 `--task-concurrency 4`。通过 Docker 和 Modal 运行多个请求时，可以分别设置 provider 上限：

```bash theme={"system"}
agentcompass launch evaluations.yaml \
  --task-concurrency 32 \
  --provider-limit docker=8 \
  --provider-limit modal=24 \
  --env-open-qps modal=4
```

### 配置文件写法

将重复使用的设置保存到[配置文件](/zh/user_guide/using_agentcompass/cli/config#配置文件结构)，并通过 `--config` 加载：

```yaml theme={"system"}
runtime:
  provider_limits:
    docker: 8
    modal: 24
  env_open_qps:
    modal: 4

execution:
  task_concurrency: 32
```

在 `launch` 编排文件中，公共 `task_concurrency` 放在顶层，provider 映射仍放在 `runtime` 下。详见[编排字段](/zh/user_guide/using_agentcompass/cli/launch#字段说明)。

为每个任务配置多次 attempt 时，它们共享同一个并发池。只有 Benchmark 和 Harness 都支持隔离执行时，同一任务的多个 attempt 才会重叠。详见[重复尝试](/zh/user_guide/other_features/results/metrics_aggregation#配置多次尝试)。

## 只重试瞬时失败

默认不重试。在命令中添加 `--max-retries 2`，允许每个逻辑 attempt 在首次执行后最多重试两次。如果还想重试指定的 agent 错误，需要配置匹配模式，例如：

```yaml theme={"system"}
execution:
  max_retries: 2
  retry_pattern_list:
    - "(?i)connection.*reset"
    - "(?i)temporar"
```

| 问题严重级别 | 还有预算时的重试行为 |
| - | - |
| FATAL | 始终允许重试。 |
| ERROR | 只有模式匹配 message 或 code 时才重试。 |
| WARNING | 不触发重试。 |

未填写、`null` 或空的模式列表只重试 FATAL。模式匹配单个问题的 message 或 code，不匹配 traceback。端点错误、缺少凭证或配置无效时，需要先修正配置；重复相同请求无法解决这些问题。

重试替换当前逻辑 attempt 内的工作，不增加评分样本数。已完成的其他 attempt 仍会保留。`none` 或 `fresh` 模式下，具备完整评分输入时可以只重试评测；`reuse` 模式会重跑整个 attempt。历史记录见[重试详情](/zh/user_guide/other_features/results/task_results#retry-详情)，未解决失败的影响见[评分有效性](/zh/user_guide/other_features/results/metrics_aggregation#明确处理失败与缺失尝试)。

## 输出与复用

### 命名新运行

在 `run` 命令中添加 `--run-name ablation --run-id baseline`，指定实验分组和运行 ID。使用默认结果根目录时，输出路径为：

```text theme={"system"}
results/ablation/<model>_<benchmark>_<harness>/baseline/
```

| 参数 | 默认值 | 命名哪一层 |
| - | - | - |
| `--results-dir` | `results` | 结果根目录。 |
| `--run-name` | 空 | 可选的实验分组目录。 |
| `--run-id` | 当前时间戳 | 本次运行的最终目录。 |

Model、Benchmark 和 Harness ID 会规范化后拼成一个目录名。`launch` 使用每个请求的 `name` 替代这个组合目录，详见[请求命名](/zh/user_guide/using_agentcompass/cli/launch#映射规则)。

通过[结果查看器](/zh/user_guide/using_agentcompass/cli/view)打开已完成的运行：

```bash theme={"system"}
agentcompass view results/ablation/<model>_<benchmark>_<harness>/baseline
```

每个目录保存哪些文件，见[评测结果](/zh/user_guide/other_features/results/overview)。

### 继续中断的运行

在相同的评测命令中添加 `--reuse`，从最近一次兼容运行继续；也可以用 `--reuse 20260806_120000` 选择源运行 ID。保持相同的结果根目录、run-name 分组以及 Model、Benchmark 和 Harness 选择，以便 AgentCompass 找到源运行。

复用会写入新运行并保留源目录。AgentCompass 检查 Benchmark、task ID、attempt 计划和保存的数据后，再复用已完成结果或恢复待处理工作。`launch` 在每个请求的命名输出目录内查找。

| 已保存的状态 | 复用时做什么 |
| - | - |
| 完整结果，没有 FATAL 或匹配的 ERROR | 复用结果及其有效分数。 |
| 评测未完成，具有完整的 `none` 或 `fresh` 输入 | 恢复评分输入，并应用当前重试策略。 |
| 已保存输入不完整或不兼容 | 重新执行必要的 attempt。 |
| 多次 attempt 的任务被中断 | 保留可复用的 attempt，恢复待处理工作。 |

当前重试预算适用于未解决的失败，历史重试次数仍作为记录保留。恢复待完成评测时，可以调整评测超时或资源；复用不会恢复正在运行的 agent 进程或 sandbox。兼容性要求见[复用校验](/zh/user_guide/other_features/results/run_records#复用校验)和[评测恢复记录](/zh/user_guide/other_features/results/run_records#评测恢复记录)。

如果希望重跑待处理工作，而不是恢复其评测输入，可以添加 `--no-checkpoint-resume`：

```yaml theme={"system"}
runtime:
  checkpoint_resume: false
```

该选项默认为 `true`，不会强制重跑已经完成的结果。使用 `launch` 时，将其放在 `defaults.runtime` 或 `requests[].runtime` 下；SDK 中传入 `checkpoint_resume=False`。

## 保留 Environment 以便调试

失败后需要检查任务或评分器 sandbox 时，在命令中添加 `--keep-environment`。AgentCompass 会关闭 Harness session，但跳过 Environment 清理。

重试和多个任务可能留下多个活跃资源，请在检查后使用 provider 工具释放。如果只需要本地文件副本，可以[保存产物](/zh/user_guide/using_agentcompass/artifacts)。

## 日志与进度

在 CI 或重定向输出时添加 `--progress plain`；需要更详细的控制台信息时添加 `--log-level DEBUG`。控制台与文件日志级别独立设置：

| 参数 | 默认值 | 可选值 |
| - | - | - |
| `--progress` | `auto` | `auto`、`plain`、`none` |
| `--log-level` | `INFO` | `DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL` |
| `--file-log-level` | `DEBUG` | `DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL` |

`auto` 在交互式终端显示实时进度，否则输出文本进度。`none` 关闭终端进度，但 AgentCompass 仍会保存进度、日志和任务结果。检查方法见[排查运行失败](/zh/user_guide/other_features/results/run_records#排查运行失败)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.