多实验编排与 CI

CLI 支持 discernlens.benchmark-workflow/v1 简洁 JSON，不支持 YAML 或参数矩阵。每次显式列出要运行的实验。

准备编排文件

下载串行样例或并行与汇合样例，修改目标地址、模型和负载。

{
  "schema_version": "discernlens.benchmark-workflow/v1",
  "name": "串行并发扫描",
  "target": {
    "endpoint_url": "https://model.example/v1",
    "model": "my-model",
    "secret_slot": "model-api-key"
  },
  "defaults": {
    "request_count": 40,
    "input_tokens": 256,
    "output_tokens": 64,
    "request_timeout_seconds": 60
  },
  "experiments": [
    { "key": "c1", "profile": { "concurrency": 1 } },
    { "key": "c8", "profile": { "concurrency": 8 } },
    { "key": "c32", "profile": { "concurrency": 32 } }
  ]
}

无需鉴权时，移除 target.secret_slot 并省略凭据注入参数。

依赖与覆盖规则

省略 depends_on：依赖前一个实验，第一个实验只依赖共享目标，因此默认串行。
depends_on: []：允许独立运行。
depends_on: ["c1", "c8"]：等待两个前置实验。依赖图必须无环。
defaults 提供公共负载，profile 覆盖当前实验。dataset、extra_inputs 和 aiperf_config 整对象替换。
地址、模型、API Key 和环境快照属于共享 target，不能在 defaults 或 profile 覆盖。
最多 24 个实验，每个节点最多 7 个实验依赖；target 是保留名称。

同一服务上的并行实验会互相影响。测量不同并发时，先考虑串行。

生成 UUIDv7 幂等键

编排提交要求 UUIDv7，不能用 UUIDv4 代替。以下脚本只依赖 Python 3 标准库：

python3 - <<'PY' > submission-id.txt
import secrets
import time
import uuid

value = (time.time_ns() // 1_000_000) << 80
value |= (7 << 76) | (secrets.randbits(12) << 64)
value |= (2 << 62) | secrets.randbits(62)
print(uuid.UUID(int=value))
PY

同一次提交的网络重试复用这个文件中的键、相同输入和凭据。 有意开始新的执行时，才生成新键。CI 应把键保存到能跨提交重试保留的位置。

执行并取得结果

将样例保存为 workflow.json，并按单次实验设置推理 Key：

submission_id=$(cat submission-id.txt)
discernctl benchmark workflow run --project pilot --file workflow.json \
  --idempotency-key "$submission_id" --api-key-env MODEL_API_KEY \
  --wait --output json > execution.json

命令进度和已接受的执行 ID 写入 stderr；--wait --output json 的 stdout 是最终执行响应。失败时也应保留输出和退出码。

execution_id=$(jq -er '.data.id' execution.json)
discernctl benchmark workflow get "$execution_id" --project pilot --output json
discernctl benchmark workflow results "$execution_id" --project pilot --output json

results 按定义顺序汇总节点，包括尚未执行或已跳过的节点。部分实验读取失败时保留其他行，并返回 40。

保存为可复用流程

discernctl benchmark workflow save --project pilot --file workflow.json \
  --output json > saved-flow.json
flow_id=$(jq -er '.data.flow.id' saved-flow.json)

保存时不传凭据注入参数；共享流程保留 secret slot 要求，不保存实际密钥或个人连接选择。后续使用 discernctl delivery execution start 启动并重新提供凭据，见交付流程。

接入 CI

在 CI secret store 中配置 DISCERNLENS_API_URL、DISCERNLENS_TOKEN 和 MODEL_API_KEY。以性能任务为例，在 Bash 中保留最终退出码：

set -euo pipefail
# PERF_SUBMISSION_ID 是本次逻辑提交预先保存的 UUIDv7。
# 上述三个连接变量由 CI secret store 注入。
set +e
discernctl benchmark workflow run --project pilot --file workflow.json \
  --idempotency-key "$PERF_SUBMISSION_ID" --api-key-env MODEL_API_KEY \
  --wait --output json > execution.json
result=$?
set -e

# 可在这里归档 execution.json，然后原样返回任务结果。
exit "$result"

不要开启 shell tracing。也可用 --secrets-file FILE 提供 secret slot 到值的 JSON 映射；文件必须是普通非符号链接文件、通常为 0600、最大 64 KiB，同一个 slot 不能由多个来源重复提供。

退出码与取消

退出码	含义
`0`	请求成功，或等待的任务成功
`10`	自动质量 Gate 失败；性能实验不使用此码
`20`	基础设施、证据或性能任务失败，或流程需显式重试节点
`30`	取消、中断或等待超时
`40`	输入、API、认证或版本兼容错误

查询成功不等于远端任务成功。等待默认最多三十分钟，每两秒轮询。等待超时默认保留远端运行；--cancel-on-interrupt 只处理调用方中断。

流程取消和显式重试需要最新强 ETag。先查询，再用响应 meta.etag 执行操作；遇到冲突重新读取，不要盲目重试写入。