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

# Clousight Bench

> 一条命令,把公认基准可复现地跑在托管云产品与大模型上,得到带溯源链的数字。

**Clousight Bench 是面向云计算的 Eval 工具。** 它把公认基准——SWE-bench、
TPC-DS/H、YCSB、TPC-C、MMLU、GSM8K、HumanEval——**原样**跑在五类云产品与服务上
(agent 运行时、数据仓库、事务数据库、KV 存储、大模型 endpoint),并给出带可验证
溯源链的数字:哪个基准、哪份固定数据集、哪个 evaluator、跑在哪个被测系统上。

它从不二次打分、也不混合分数。基准自带的 harness 出结论;框架只补上可复现性簿记
与云产品维度(延迟、成本、逐项分数、可选的 LLM 判定)。

## 快速开始

<Steps>
  <Step title="安装">
    ```bash theme={null}
    pip install clousight-bench          # 按需加 extra:[store] [llm] [tpcds] [swebench]
    # 或从源码克隆:  uv sync --all-extras
    ```
  </Step>

  <Step title="看已注册了什么">
    ```bash theme={null}
    csbench list
    ```

    所有已注册的 benchmark、evaluator、platform——外加一条可直接复制的"run one"提示。
  </Step>

  <Step title="跑一个——离线,无云,无密钥">
    ```bash theme={null}
    printf 'target:\n  mode: mock\n' > mock.yaml
    csbench run --domain agent-runtime --benchmark swe-bench --platform local-sim --config mock.yaml
    ```

    stdout 上得到 `status: completed` 记录。✅ 这是完整跑了一遍四阶段生命周期
    (prepare → connect → measure → conclude),基于内置 fixture——无云账号、无 API key。
    任何*未*完成的运行都会在 stderr 上打印一段自解释摘要——哪个阶段坏了、哪道门拒绝了
    ——你永远不用去 grep JSON 找失败原因。
  </Step>

  <Step title="对准真实系统(配置接入)">
    ```bash theme={null}
    printf 'target:\n  mode: runtime\n  endpoint: "https://dashscope.aliyuncs.com/compatible-mode/v1"\n  model: qwen-max\n  credentials_ref: env:DASHSCOPE_API_KEY\n' > qwen.yaml
    export DASHSCOPE_API_KEY=...
    csbench run --domain llm --benchmark mmlu --platform llm-endpoint --config qwen.yaml
    ```

    同样的命令形状;现在数字来自你已在运行的 endpoint。之后 `csbench serve` 在
    `http://127.0.0.1:8787` 打开 web 查看器。
  </Step>
</Steps>

<Tip>
  在 CI 里用阈值门控:`csbench run … --assert thresholds.yaml`,任一测量未达标即非零退出。
  见 [pytest 与 CI](/docs/zh/pytest-ci)。
</Tip>

## 心智模型

三样东西,各自是一个由入口点发现的插件:

* **`BenchmarkSuite`** 包装一个公认 harness(或任意可复现负载):`resolve → prepare
  → run → mock_artifacts`。
* **`Evaluator`** 把运行产物变成命名空间化的 **`Measurement`**(以及可选逐项 **`items`**)
  ——一个纯粹、离线、可重打分的函数。
* **被测系统**由 `--platform` + 一个 `target` 选定:模拟参考、**你配置接入的已运行
  服务**(endpoint + 凭证)、或框架为你制备的云。

新增基准 = 写一个 Suite + Evaluator;运行 = `csbench run --benchmark <id>`。见
[新增一个 benchmark](/docs/zh/adding-a-suite)。

## 可复现性契约

每条记录带一个 `provenance` 块(benchmark id、固定数据集 digest、evaluator id、
`unmodified` 标记、scaffold)+ 三个独立指纹(`benchmark` / `environment` /
`implementation`),让你能判断两个数字是否可比。每条测量带一个 `reproducibility_class`:

| 类别 | 含义 |
| - | - |
| **deterministic** | 同输入同数字——如 `swe-bench.resolved`、`mmlu.accuracy` |
| **environmental** | 方法可复现;数字随网络/区域/账号漂移——成本、延迟 |
| **judge-based** | 有 LLM 判定参与——见 [判定](/docs/zh/judges) |

`official=true` 的测量是基准自身在 `<suite_id>.` 命名空间下的结论(一个溯源标记,
由 `csbench conformance` 强制);附加 [metrics](/docs/zh/metrics) 与社区 evaluator
待在各自的命名空间。结果始终**按维度——从不混合成一个分**。

## 下一步

<CardGroup cols={2}>
  <Card title="新增一个 benchmark" icon="plus" href="/docs/zh/adding-a-suite">写一个 Suite + Evaluator 并运行。</Card>
  <Card title="Metrics" icon="chart-simple" href="/docs/zh/metrics">在任意运行上组合逐项指标。</Card>
  <Card title="判定(LLM-as-judge)" icon="gavel" href="/docs/zh/judges">可复现的判定型打分。</Card>
  <Card title="架构" icon="sitemap" href="/docs/zh/architecture">阶段机、记录 schema、插件。</Card>
</CardGroup>


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