基准测试

基准测试功能需要平台已启用基准测试服务。

创建要求 name、deploymentId、profile。profile 表示测试类型，仅支持 latency / throughput；测试方法由服务端按版本定义，客户端不传入任意目标 URL。

创建和停止返回 202，随后轮询 state；状态为 pending、running、completed、error、stopped。同一模型部署存在进行中的基准测试时返回 409 active_benchmark。

列表分页参数使用 size，缺省 20、最大 200。日志 tail 缺省 200，返回日志文本与截断标记。

方法	路径（产品接口统一前缀 /api/v1）	功能
GET	/benchmark-profiles	查询基准测试方法
GET	/benchmarks	查询基准测试任务
POST	/benchmarks	创建基准测试任务
GET	/benchmarks/{id}	查询基准测试详情
GET	/benchmarks/{id}/logs	查询基准测试日志
POST	/benchmarks/{id}/stop	停止基准测试任务
DELETE	/benchmarks/{id}	删除基准测试任务

查询基准测试方法

功能介绍

查询平台预定义的基准测试方法。

访问要求：有效 Token；需要对应资源读权限，并受项目、所有者、公共或共享资源规则限制。

URI

GET /api/v1/benchmark-profiles

请求消息

无请求体。

响应消息

参数	参数类型	描述
methodologyVersion	string	基准测试方法版本
items	array<benchmark.Profile>	结果列表

请求示例

GET https://{endpoint}/api/v1/benchmark-profiles
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "methodologyVersion": "beacon-benchmark/v1",
  "items": [
    {
      "id": "id-example",
      "methodologyVersion": "beacon-benchmark/v1",
      "datasetVersion": "beacon-jsonl/v1",
      "description": "",
      "inputShape": "",
      "outputTokens": 0,
      "runnerProfile": "",
      "warmup": {
        "mode": "",
        "value": 0
      },
      "dataSamples": 0,
      "maxRequests": 0,
      "maxSeconds": 0,
      "sampleRequests": 0,
      "maxErrors": 0
    }
  ]
}

状态码与错误码

成功状态码：200。

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

查询基准测试任务

功能介绍

查询基准测试任务。

访问要求：有效 Token；需要对应资源读权限，并受项目、所有者、公共或共享资源规则限制。

URI

GET /api/v1/benchmarks

查询参数

参数	类型	必选	描述
state	string	否	任务状态
profile	string	否	测试类型：latency 或 throughput
deploymentId	string	否	目标模型部署 ID
page	integer	否	页码，从 1 开始；默认 1
size	integer	否	数量或大小，单位见上下文；默认 20

请求消息

无请求体。

响应消息

参数	参数类型	描述
items	array<benchmark.Item>	结果列表
total	integer	匹配总数
page	integer	页码，从 1 开始
size	integer	数量或大小，单位见上下文

请求示例

GET https://{endpoint}/api/v1/benchmarks?page=1&size=20
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "items": [
    {
      "id": "id-example",
      "name": "示例资源",
      "deploymentId": "deploymentId-example",
      "profile": "latency",
      "state": "pending",
      "spec": {
        "methodologyVersion": "beacon-benchmark/v1",
        "datasetVersion": "beacon-jsonl/v1",
        "seed": 0,
        "profile": {}
      },
      "createdAt": "2026-09-21T00:00:00Z",
      "updatedAt": "2026-09-21T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 1
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	invalid_state	unsupported benchmark state
400	invalid_profile	unsupported benchmark profile
404	not_found	benchmark or deployment not found
409	active_benchmark	deployment already has an active benchmark
409	invalid_state	operation is not allowed in current state
422	invalid_spec	benchmark specification is too large
500	internal_error	internal server error

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

创建基准测试任务

功能介绍

创建基准测试任务。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

POST /api/v1/benchmarks

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
name	string	是	显示名称
deploymentId	string	是	目标模型部署 ID
profile	string	是	测试类型，latency 表示延迟测试，throughput 表示吞吐测试；创建流程默认 latency。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
projectId	string	所属项目 ID；空值时可能省略
projectName	string	项目名称；空值时可能省略
domainId	string	所属部门 ID；空值时可能省略
domainName	string	部门名称；空值时可能省略
deploymentId	string	目标模型部署 ID
profile	string	测试类型：latency 或 throughput
state	string	任务状态
cancelRequested	boolean	是否已请求停止；空值时可能省略
runnerPodPhase	string	执行 Pod 阶段；空值时可能省略
spec	benchmark.Spec	资源配置快照
result	JSON	基准测试结果；空值时可能省略
errorMessage	string	错误详情；空值时可能省略
startedAt	string(date-time) / null	执行开始时间；空值时可能省略
finishedAt	string(date-time) / null	结束时间；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

POST https://{endpoint}/api/v1/benchmarks
x-keystone-token: <Keystone Token>
Content-Type: application/json

{
  "name": "延迟基准",
  "deploymentId": "deployment-id",
  "profile": "latency"
}

正常响应示例

HTTP/1.1 202
Content-Type: application/json

{
  "id": "id-example",
  "name": "示例资源",
  "deploymentId": "deploymentId-example",
  "profile": "latency",
  "state": "pending",
  "spec": {
    "methodologyVersion": "beacon-benchmark/v1",
    "datasetVersion": "beacon-jsonl/v1",
    "seed": 0,
    "profile": {
      "id": "id-example",
      "methodologyVersion": "beacon-benchmark/v1",
      "datasetVersion": "beacon-jsonl/v1",
      "description": "",
      "inputShape": "",
      "outputTokens": 0,
      "runnerProfile": "",
      "warmup": {
        "mode": "",
        "value": 0
      },
      "dataSamples": 0,
      "maxRequests": 0,
      "maxSeconds": 0,
      "sampleRequests": 0,
      "maxErrors": 0
    }
  },
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：202。

HTTP	error	说明
400	invalid_request	invalid JSON body
422	invalid_request	name and deploymentId are required
422	invalid_profile	profile must be latency or throughput
503	benchmark_unavailable	benchmark target validation is not configured
403	forbidden	write permission required
404	not_found	benchmark or deployment not found
409	active_benchmark	deployment already has an active benchmark
409	invalid_state	operation is not allowed in current state
422	invalid_spec	benchmark specification is too large
500	internal_error	internal server error

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

查询基准测试详情

功能介绍

查询基准测试详情。

访问要求：有效 Token；需要对应资源读权限，并受项目、所有者、公共或共享资源规则限制。

URI

GET /api/v1/benchmarks/{id}

参数	类型	必选	描述
id	string	是	目标资源 ID

请求消息

无请求体。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
projectId	string	所属项目 ID；空值时可能省略
projectName	string	项目名称；空值时可能省略
domainId	string	所属部门 ID；空值时可能省略
domainName	string	部门名称；空值时可能省略
deploymentId	string	目标模型部署 ID
profile	string	测试类型：latency 或 throughput
state	string	任务状态
cancelRequested	boolean	是否已请求停止；空值时可能省略
runnerPodPhase	string	执行 Pod 阶段；空值时可能省略
spec	benchmark.Spec	资源配置快照
result	JSON	基准测试结果；空值时可能省略
errorMessage	string	错误详情；空值时可能省略
startedAt	string(date-time) / null	执行开始时间；空值时可能省略
finishedAt	string(date-time) / null	结束时间；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

GET https://{endpoint}/api/v1/benchmarks/resource-id
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "id-example",
  "name": "示例资源",
  "deploymentId": "deploymentId-example",
  "profile": "latency",
  "state": "pending",
  "spec": {
    "methodologyVersion": "beacon-benchmark/v1",
    "datasetVersion": "beacon-jsonl/v1",
    "seed": 0,
    "profile": {
      "id": "id-example",
      "methodologyVersion": "beacon-benchmark/v1",
      "datasetVersion": "beacon-jsonl/v1",
      "description": "",
      "inputShape": "",
      "outputTokens": 0,
      "runnerProfile": "",
      "warmup": {
        "mode": "",
        "value": 0
      },
      "dataSamples": 0,
      "maxRequests": 0,
      "maxSeconds": 0,
      "sampleRequests": 0,
      "maxErrors": 0
    }
  },
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
404	not_found	benchmark or deployment not found
409	active_benchmark	deployment already has an active benchmark
409	invalid_state	operation is not allowed in current state
422	invalid_spec	benchmark specification is too large
500	internal_error	internal server error

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

查询基准测试日志

功能介绍

查询基准测试日志。

访问要求：有效 Token；需要对应资源读权限，并受项目、所有者、公共或共享资源规则限制。

URI

GET /api/v1/benchmarks/{id}/logs

参数	类型	必选	描述
id	string	是	目标资源 ID

查询参数

参数	类型	必选	描述
tail	integer	否	日志末尾行数；默认 200

请求消息

无请求体。

响应消息

参数	参数类型	描述
logs	string	日志文本
truncated	boolean	日志是否被截断；空值时可能省略

请求示例

GET https://{endpoint}/api/v1/benchmarks/resource-id/logs
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "logs": ""
}

状态码与错误码

成功状态码：200, 202。

HTTP	error	说明
503	logs_unavailable	benchmark logs are not configured
404	not_found	benchmark or deployment not found
409	active_benchmark	deployment already has an active benchmark
409	invalid_state	operation is not allowed in current state
422	invalid_spec	benchmark specification is too large
500	internal_error	internal server error

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

停止基准测试任务

功能介绍

停止基准测试任务。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

POST /api/v1/benchmarks/{id}/stop

参数	类型	必选	描述
id	string	是	目标资源 ID

请求消息

无请求体。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
projectId	string	所属项目 ID；空值时可能省略
projectName	string	项目名称；空值时可能省略
domainId	string	所属部门 ID；空值时可能省略
domainName	string	部门名称；空值时可能省略
deploymentId	string	目标模型部署 ID
profile	string	测试类型：latency 或 throughput
state	string	任务状态
cancelRequested	boolean	是否已请求停止；空值时可能省略
runnerPodPhase	string	执行 Pod 阶段；空值时可能省略
spec	benchmark.Spec	资源配置快照
result	JSON	基准测试结果；空值时可能省略
errorMessage	string	错误详情；空值时可能省略
startedAt	string(date-time) / null	执行开始时间；空值时可能省略
finishedAt	string(date-time) / null	结束时间；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

POST https://{endpoint}/api/v1/benchmarks/resource-id/stop
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 202
Content-Type: application/json

{
  "id": "id-example",
  "name": "示例资源",
  "deploymentId": "deploymentId-example",
  "profile": "latency",
  "state": "pending",
  "spec": {
    "methodologyVersion": "beacon-benchmark/v1",
    "datasetVersion": "beacon-jsonl/v1",
    "seed": 0,
    "profile": {
      "id": "id-example",
      "methodologyVersion": "beacon-benchmark/v1",
      "datasetVersion": "beacon-jsonl/v1",
      "description": "",
      "inputShape": "",
      "outputTokens": 0,
      "runnerProfile": "",
      "warmup": {
        "mode": "",
        "value": 0
      },
      "dataSamples": 0,
      "maxRequests": 0,
      "maxSeconds": 0,
      "sampleRequests": 0,
      "maxErrors": 0
    }
  },
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：202。

HTTP	error	说明
403	forbidden	write permission required
404	not_found	benchmark or deployment not found
409	active_benchmark	deployment already has an active benchmark
409	invalid_state	operation is not allowed in current state
422	invalid_spec	benchmark specification is too large
500	internal_error	internal server error

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

删除基准测试任务

功能介绍

删除基准测试任务。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

DELETE /api/v1/benchmarks/{id}

参数	类型	必选	描述
id	string	是	目标资源 ID

请求消息

无请求体。

响应消息

成功返回 204 No Content，无响应体。

请求示例

DELETE https://{endpoint}/api/v1/benchmarks/resource-id
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 204 No Content

状态码与错误码

成功状态码：204。

HTTP	error	说明
403	forbidden	write permission required
404	not_found	benchmark or deployment not found
409	active_benchmark	deployment already has an active benchmark
409	invalid_state	operation is not allowed in current state
422	invalid_spec	benchmark specification is too large
500	internal_error	internal server error

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。