> ## 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.

# Environment 资源限制

Environment 资源参数用于限制本地实例可使用的资源，或指定远程实例申请的 CPU、内存、存储和 GPU。

这些参数可以防止单个任务占用过多资源，也可以让远程 provider 创建符合 Benchmark 要求的实例。它们不限制 AgentCompass host 进程、model 服务或其他外部服务。

<Warning>
  `host_process` 直接在 host 上运行命令，无法强制执行 Environment 级 CPU、内存、存储或 GPU 限制。需要资源隔离时，请选择其他 provider。
</Warning>

<a id="理解作用范围" />

## 先区分资源与调度

下面四类设置解决的问题不同：

| 设置 | 控制内容 |
| - | - |
| Environment 资源参数 | 一个 Environment 实例能够使用或申请的资源。通过 Environment 参数设置；CLI 中使用 `--env-params`。 |
| `--task-concurrency` | 一次评测中最多同时处理多少个 Benchmark 任务。 |
| `--provider-limit <provider>=<count>` | 当前 AgentCompass 进程中，同一个 provider 最多同时处理多少个任务尝试。 |
| `--env-open-qps <provider>=<qps>` | 同一个 provider 每秒最多开始创建多少个 Environment；它限制创建速度，不限制已运行实例的数量。 |

例如，Docker 的 `resources.cpu: 2` 表示每个容器最多使用 2 核；`--task-concurrency 8` 表示最多可以同时处理 8 个任务。两者不能互相替代。

任务 Environment 与验证 Environment 也按实例分别计算资源。需要新建验证 Environment 时，AgentCompass 通常会先关闭任务 Environment，再创建验证 Environment。只有使用 `--keep-environment` 保留任务 Environment 时，两者才可能同时占用资源。

并发、创建速率和 `--keep-environment` 的完整说明见[运行控制](/zh/user_guide/using_agentcompass/run_controls)。

## provider 能力与单位

AgentCompass 提供统一的 provider-neutral 资源模型，再由各 provider adapter 转换为平台原生字段和单位。

| 字段 | 统一格式 |
| - | - |
| `cpu` | 正数 CPU 核心数；部分 provider 要求整数。 |
| `memory_mb` | 正整数，单位为 MiB；不要添加单位后缀。 |
| `storage_mb` | 正整数，单位为 MiB；不要添加单位后缀。 |
| `gpu` | 非负整数 GPU 数量；显式设置为 `0` 时会清除继承的 `gpu_type`。 |
| `gpu_type` | 非空 GPU 型号字符串；未指定 `gpu` 时会隐含 `gpu: 1`。 |
| `ignore_gpu_type` | 布尔型覆盖指令；设为 `true` 时删除继承的 `gpu_type` 约束，同时保留 GPU 数量。 |

各 provider 支持该模型的一个子集：

| provider | `cpu` | `memory_mb` | `storage_mb` | `gpu` | `gpu_type` |
| - | - | - | - | - | - |
| [`host_process`](/zh/user_guide/modules/environments/providers/host_process) | 否 | 否 | 否 | 否 | 否 |
| [`docker`](/zh/user_guide/modules/environments/providers/docker) | 是 | 是 | 是 | 是 | 否 |
| [`daytona`](/zh/user_guide/modules/environments/providers/daytona) | 是，须为整数 | 是 | 是 | 是，最多 1 个 | 是 |
| [`modal`](/zh/user_guide/modules/environments/providers/modal) | 是 | 是 | 否 | 是 | 是 |
| [`opensandbox`](/zh/user_guide/modules/environments/providers/opensandbox) | 是 | 是 | 否 | 是 | 否 |

AgentCompass 会在创建 Environment 前报告不受支持的显式资源字段。`storage_mb` 是一个例外：无法强制限制存储的 provider 会打印 warning 并忽略它，避免 task 声明的磁盘需求阻止其他方面兼容的运行。

GPU 型号约束默认保持 fail-closed。如果 Benchmark 要求特定型号，但你明确希望所选 provider 分配任意可用 GPU，可以显式设置 `ignore_gpu_type: true`：

```bash theme={"system"}
agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --env <provider> \
  --env-params '{"resources":{"gpu":1,"ignore_gpu_type":true}}'
```

该指令只删除 `gpu_type`，不会删除或修改 `gpu`；AgentCompass 应用该指令时会打印 warning。它与其他资源字段遵循相同的优先级和 phase 作用范围，因此也可以写入 `run_resources` 或 `evaluation_resources`；更高优先级重新指定 `gpu_type` 时，对应 phase 会恢复严格型号选择。任务依赖特定 GPU 架构、显存容量或性能特征时不要使用该覆盖；比较结果时也应记录这项变更。

运行下面的命令，可以查看当前安装版本接受的准确字段和默认值：

```bash theme={"system"}
agentcompass config docs env <provider>
```

各 provider 页会进一步解释字段格式、账号配额和运行条件。

## 设置资源

### 为 fresh 验证分别设置资源

`evaluation_environment_mode="fresh"` 的 Benchmark 会分别创建 run Environment 和 evaluation Environment。可以在 `--env-params` 中使用以下字段控制两者的资源：

| 字段 | 作用范围 |
| - | - |
| `resources` | 同时覆盖 run Environment 和 fresh evaluation Environment；其他 mode 只有一个共享 Environment，因此应用于该 Environment。 |
| `run_resources` | 只覆盖任务运行使用的 Environment。 |
| `evaluation_resources` | 只覆盖 fresh evaluation Environment；实际 evaluation mode 不是 `fresh` 时，AgentCompass 会拒绝该字段。 |

Phase-specific 字段的优先级高于 `resources` 中的同名字段。例如，下面的配置为两个 Environment 都分配 8192 MiB 内存，同时为 run Environment 分配 4 个 CPU，为 evaluation Environment 分配 2 个 CPU：

```bash theme={"system"}
agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env docker \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --env-params '{
    "resources":{"memory_mb":8192},
    "run_resources":{"cpu":4},
    "evaluation_resources":{"cpu":2}
  }'
```

Benchmark task metadata 是最低优先级的资源来源。显式公共 `resources` 会覆盖两个 fresh Environment 对应的 task 字段，`run_resources` 和 `evaluation_resources` 再分别覆盖公共字段。fresh Benchmark 没有单独声明 evaluation resources 时，evaluation Environment 会回退到该任务的公共资源。

下面对 Docker、Daytona 和 Modal 使用同一种统一资源参数写法。三个示例都通过 [`sample_ids`](/zh/user_guide/modules/benchmarks/overview#共享-benchmark-字段) 只运行一个任务，并为每个 Environment 设置 2 核 CPU 和 6144 MiB 内存；这些数值只用于说明格式，不代表 Benchmark 的推荐配置。

以下以 `agentcompass run` 为例。配置文件、Python SDK 和 `launch` 编排文件的写法见[配置 Environment](/zh/user_guide/modules/environments/configuration/overview)。

### Docker

```bash theme={"system"}
agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env docker \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --env-params '{"resources":{"cpu":2,"memory_mb":6144}}'
```

Docker adapter 会把这些值转换为 Docker 的 CPU 和内存参数。provider 要求见 [Docker 的资源参数](/zh/user_guide/modules/environments/providers/docker#资源)。

### Daytona

```bash theme={"system"}
agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env daytona \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --env-params '{"resources":{"cpu":2,"memory_mb":6144}}'
```

该组合的 Recipe 会选择任务镜像，因此资源请求会用于基于镜像创建的 sandbox。provider 要求见 [Daytona 的资源参数](/zh/user_guide/modules/environments/providers/daytona#资源)。

### Modal

```bash theme={"system"}
agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env modal \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --env-params '{"resources":{"cpu":2,"memory_mb":6144}}'
```

Modal adapter 会把 MiB 内存值传给 Modal。provider 要求见 [Modal 的资源参数](/zh/user_guide/modules/environments/providers/modal#资源)。

<Info>
  Docker 通过 `--storage-opt size=...` 应用 `storage_mb`。如果 Docker daemon 报告当前存储驱动无法执行该选项，AgentCompass 会记录 warning，并在不限制存储的情况下启动容器。远程 provider 也可能因为账号配额、区域容量或不提供所选规格而拒绝创建实例。
</Info>

## Recipe 资源设置与显式覆盖

部分 Recipe 会读取 Benchmark 中的任务资源要求，并写入统一资源模型；随后由选中的 provider adapter 完成平台侧校验和转换。

内置 Recipe 通常会保留兼容的显式资源值，但具体适配仍以对应 Recipe 和 Benchmark 说明为准。因此：

* 想复现 Benchmark 的资源条件时，优先使用其 Recipe 提供的默认值；
* 想比较另一种资源配置时，再显式覆盖，并在结果说明中记录修改。

资源变化可能影响任务完成率和得分。不要把使用不同资源限制的运行结果当作同一条件下的结果直接合并。

## 估算总资源需求

可以按以下步骤估算：

1. 从 Benchmark 或 Recipe 给出的资源要求开始。
2. 先运行一个有代表性的任务，观察内存峰值、CPU 使用率、磁盘增长和验证阶段的资源需求。
3. 为安装依赖、编译和缓存保留余量。
4. 根据单实例资源和实际并发估算总量，再调整任务并发与 provider 限制。
5. 逐步提高并发；出现 OOM、创建失败或明显排队时及时降低。

估算容量时，应关注同时存在的 Environment 实例数。`--env-open-qps` 只改变新实例的创建速度，不限制同时运行的实例数。

## 排查资源问题

| 现象 | 常见原因 | 处理方式 |
| - | - | - |
| Docker 返回 `137`、`OOMKilled`，或进程突然退出 | 超过容器内存限制。 | 检查容器状态和内存峰值，再与 Benchmark 要求比较。 |
| 多个任务运行时 host 无响应 | 所有 Environment 的资源总量超过 host 容量。 | 降低 `--task-concurrency` 或对应的 `--provider-limit`。 |
| Daytona 或 Modal 拒绝创建实例 | 字段格式、资源规格、区域容量或账号配额不符合要求。 | 核对 provider 页面和账号控制台，先用一个实例验证配置。 |
| CPU 使用率低但任务仍超时 | 时间花在 model、网络或 Harness 等待上，而不是 CPU 不足。 | 先检查阶段日志，再决定是否增加 CPU。 |
| Docker 可写层空间不足 | 任务产物超过可写层容量，或存储驱动不支持配置的限制。 | 检查存储驱动，改用受支持的存储设置或更合适的镜像布局。 |
| GPU 在 Environment 中不可见 | host runtime、镜像、驱动或 provider 的 GPU 请求不匹配。 | 先单独验证 provider 的 GPU 配置，再运行评测。 |

## 相关页面

* [选择 Environment](/zh/user_guide/modules/environments/overview)
* [网络策略](/zh/user_guide/modules/environments/configuration/network)
* [运行控制](/zh/user_guide/using_agentcompass/run_controls)


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