实验配置
概述
实验配置文件采用 YAML 格式,用于在多任务运行中共享模型设置并支持逐任务覆盖。这将「如何运行」(模型、超时、Agent 设置)与「测试什么」(任务目录)解耦。
官方 leaderboard 配置
all-tasks-k8s 示例中的 experiment YAML 就是 EdgeBench leaderboard 官方数字所使用的配置。
YAML 格式
model:
api_key: ${OPUS_KEY}
api_base_url: https://api.anthropic.com
model: claude-opus-4-6
stagger: 300 # 在 300 秒内均匀分散任务启动
defaults:
agent: claude-code
timeout: 7200
eval_interval: 300
env:
SFORGE_K8S_NAMESPACE: "sforge-runs"
tasks:
ad_placement_optimization:
eval_interval: 1800
smt_solver:
work_cpu_limit: 16
graph_node_classification: {}字段说明
env
在读取文件其余部分之前设置到 sforge run 进程中的环境变量,效果等同于 export(例如 SFORGE_K8S_IMAGE_REGISTRY 或 SFORGE_JUDGE_EXTRA_ENV)。值按字面使用;${VAR} 展开只在 model 段生效。
model
配置 Agent 使用的 LLM。所有字符串值支持 ${ENV_VAR} 环境变量展开 --- 引用的环境变量必须在运行时已设置。
| 字段 | 类型 | 说明 |
|---|---|---|
api_key | string | API 密钥(支持 ${ENV_VAR} 展开) |
api_base_url | string | API Base URL |
model | string | 模型名称(如 claude-opus-4-6、claude-sonnet-4-20250514) |
defaults
应用于所有任务的默认设置,可被逐任务覆盖。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
agent | string | --- | Agent 名称(claude-code、codex、opencode),可带 @<版本>(如 claude-code@2.1.258) |
model | string | --- | 模型覆盖(在逐任务设置中可覆盖 model.model) |
effort | string | --- | 推理强度(low、medium、high 或 max),在所选 Agent 支持时映射到其原生配置 |
timeout | int | --- | Agent 超时时间(秒) |
eval_interval | int | --- | 自动评测间隔(秒) |
disable_stop_hook | bool | false | 禁用 Agent Stop Hook |
disable_auto_eval | bool | false | 禁用后台自动评测 |
disable_auto_resume | bool | false | 禁用 Agent 异常退出时的自动恢复 |
internet | bool | --- | 覆盖任务对 work 容器的 internet 设置 |
extra_env | dict | --- | 注入 Agent 容器的额外环境变量 |
backend | string | --- | 容器后端(docker、k8s 或 e2b) |
judge_url | string | --- | 外部 judge server 的 URL(默认由 sforge run 自己提供 judge) |
max_submissions | int | --- | 每次运行中 Agent 最大提交次数 |
submission_cooldown | int | --- | Agent 两次提交之间的最小间隔(秒) |
work_cpu_limit | int | --- | Work 容器的 CPU 限制 |
work_mem_limit | string | --- | Work 容器的内存限制 |
judge_cpu_limit | int | --- | Judge 容器的 CPU 限制 |
judge_mem_limit | string | --- | Judge 容器的内存限制 |
tasks
逐任务覆盖。每个 key 是任务 ID,即 benchmark 的 tasks/ 下的目录名。value 支持与 defaults 相同的字段。此处列出的任务决定了运行范围 --- 如果 CLI 中没有指定 --task,则使用实验配置中的任务列表。
空对象({})表示「使用所有默认设置,无覆盖」。
stagger
顶层整数字段,在运行多个任务时将任务启动均匀分散在指定的秒数内。这可以避免同时启动大量容器和 API 调用造成的"惊群效应"。
stagger: 300 # 在 5 分钟内均匀间隔启动任务例如,6 个任务配合 stagger: 300,每个任务间隔 50 秒启动。
优先级链
配置值按以下顺序解析(优先级从高到低):
CLI 参数 > 逐任务覆盖 > 实验默认值 > task.toml / 环境变量 / 内置默认值举例来说:
- CLI 中的
--timeout 3600总是优先 - 逐任务的
timeout: 1800覆盖实验级的defaults.timeout - 实验中的
work_cpu_limit覆盖任务task.toml中的cpus
对于 extra_env,字典是合并(而非替换)的。逐任务的 key 在冲突时覆盖默认值:
defaults:
extra_env:
FOO: "from-defaults"
BAR: "shared"
tasks:
ad_placement_optimization:
extra_env:
FOO: "from-task" # 覆盖 defaults
BAZ: "task-only" # 新增
# 最终结果:FOO=from-task, BAR=shared, BAZ=task-only使用方法
运行实验中的所有任务
sforge run --experiment experiments/my_config.yaml --run-id batch-001不指定 --task 时,实验文件中列出的所有任务会并行运行。
运行部分任务
sforge run --experiment experiments/my_config.yaml --task ad_placement_optimization smt_solver使用实验配置中的模型和默认设置,但只运行指定的任务。
CLI 覆盖
sforge run \
--experiment experiments/my_config.yaml \
--timeout 3600 \
--disable-stop-hook \
--run-id experiment-v2CLI 参数具有最高优先级,会覆盖逐任务和默认设置。
环境变量展开
model 部分的字符串值支持 ${VAR_NAME} 语法:
model:
api_key: ${MY_API_KEY}
api_base_url: ${API_ENDPOINT}如果引用的变量未设置,SForge 会报错退出。这样可以将密钥保存在环境变量中,而实验配置文件本身可以安全地提交到版本控制。
运行产物
使用实验配置运行时,还会保存配置文件的副本和完整解析后的配置,见运行输出。