> ## Documentation Index
> Fetch the complete documentation index at: https://niceeval.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# defineConfig：项目默认配置

> defineConfig 参考：Judge Runtime、Reporters、并发、超时和 Sandbox 默认值。

`defineConfig` 从根目录的 `niceeval.config.ts` 默认导出，只放项目级默认值。agent、model、flags、attempts 和实验预算写在 `experiments/` 下的 `defineExperiment` 文件里。

```ts theme={null}
import { defineConfig } from "niceeval";
import { OpenAIProvider } from "niceeval/judge";

export default defineConfig({
  judgeRuntime: OpenAIProvider({ model: "gpt-5.4-mini", maxOutputTokens: 512 }),
  maxConcurrency: 4,
  timeoutMs: 300_000,
});
```

## Config 字段

#### `name`

```ts theme={null}
name?: LocalizedText;
```

项目名,显示在 `niceeval view` 顶部 hero(`<h1>`),省略则回退到通用标题。
可传字符串,或按 locale 提供多语言(如 `{ en: "...", "zh-CN": "..." }`),随 view 语言切换。

#### `workspace`

```ts theme={null}
workspace?: string;
```

上传进 Sandbox 的工作区根目录,省略则用项目根;评估用例的 sandbox 视图从这里起步。

#### `judgeRuntime`

```ts theme={null}
judgeRuntime?: JudgeProvider;
```

项目级默认 Judge Provider；Eval 与 Experiment 可替换模型或整个 Provider。

#### `reporters`

```ts theme={null}
reporters?: Reporter[];
```

项目级默认 reporter 列表(如落盘 / 上传结果);EvalDef.reporters 会与它合并。

#### `maxConcurrency`

```ts theme={null}
maxConcurrency?: number;
```

项目级默认并发上限;CLI flag / experiment 的同名设置优先级更高(没有环境变量层)。

#### `maxBuildConcurrency`

```ts theme={null}
maxBuildConcurrency?: number;
```

Run 级 Sandbox 镜像准备并发；与 attempt 并发独立，省略时安全默认 2。

#### `maxSetupPrefixConcurrency`

```ts theme={null}
maxSetupPrefixConcurrency?: number;
```

Run 级 PreparedArtifact 前缀 DAG 准备并发；与 build / attempt 并发独立。

#### `sandboxCache`

```ts theme={null}
sandboxCache?: SandboxCacheConfig;
```

项目级 SetupPrefix cache 默认；Experiment 与显式 CLI flag 可覆盖。

#### `timeoutMs`

```ts theme={null}
timeoutMs?: number;
```

项目级默认单次 attempt 超时(毫秒);CLI flag / experiment / EvalDef 的同名设置优先级更高。

#### `telemetry`

```ts theme={null}
telemetry?: { host?: string; port?: number };
```

OTLP 接收配置,niceeval 项目内唯一入口(不读 NICEEVAL\_OTLP\_\* 环境变量)。
`port` 钉住接收端口(固定端口模式:长驻服务把 OTEL\_EXPORTER\_OTLP\_ENDPOINT 一次性指到
`http://localhost:<port>/v1/traces`,跑多少次评估用例都不用改)。省略 = 每次运行动态分配
临时端口(经 ctx.telemetry 交给 adapter)。代价:固定端口下同机同时只能跑一个 niceeval 进程,
且该端口被别的进程占用时会报错——换一个空闲端口写回这里即可。
`host` 是报给 adapter 的接收端 hostname(而非监听地址,监听地址恒为 0.0.0.0):默认
"127.0.0.1"。只有作者已经提供受控 tunnel / 可达路由时才在这里覆盖；Docker Sandbox
默认把 receiver 放在 Sandbox 内，不依赖隐式宿主 gateway。

#### `pricing`

```ts theme={null}
pricing?: globalThis.Record<string, PriceOverride>;
```

内置价格表(`o11y/prices.json`)之上的用户覆盖 / 补充,按 model 查(见 Observability
· 用量与成本)。key 支持精确 model 名或 `provider/*` 通配(自托管/网关折扣按 provider 批量覆盖);
精确 key 优先于通配。Runner 用它计算 `maxCost` 的预算 estimate；Adapter physical-call
collector 只在 reported cost 缺席时，把命中的显式 fixed profile 封存为 call-bound estimate proof。
Inspection 只读已封存 proof，不把 mutable config 作为 operation 输入，也不按 endpoint 倒填历史调用。

> 成本边界：这里的 `pricing` 只提供 Runner 的 Config/runtime price table 输入。Runner 不论是否已有 `Usage.costUSD`，都会从 `model`、上报的 token 用量和这个表独立产生 `estimatedCostUSD`。Experiment 的预算与 `t.maxCost()` 使用该 estimate，`Usage.costUSD` 不驱动它。读取结果时使用固定 Inspection operation，它不把运行期价格配置变成另一个输入。

[NiceEval](https://niceeval.com/) 把环境准备放在普通代码里：评估用例自己需要的文件写在 `test(t)`，agent 自己的准备写在 adapter 的 setup。`Config` 刻意没有 `sandbox` 字段，也不自动探测 provider。请在评估用例或 Experiment 上声明 template-bearing `SandboxLayer`，让 link planning 在创建任何资源前确定它的 owner 与配对结果。


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