model-eval-site/API.md

# 模型评测网站 API 文档

Base: `http://<IP>:16066`（端口 16066）。后台管理接口需先登录（session cookie）。

## 1. 接收提交（llm-speed-tester 一键发送）

`POST /api/submit`

Header: `Content-Type: application/json`，`X-Token: meval16066`

```bash
curl -X POST http://127.0.0.1:16066/api/submit \
  -H "Content-Type: application/json" \
  -H "X-Token: meval16066" \
  -d '{
    "account": "性能评测组",            # 账号，不存在自动创建
    "source_test_id": 25,
    "source_site": "llm-speed-tester",
    "provider": "openai",
    "model": "nvidia/Qwen3.6-35B-A3B-NVFP4",
    "hardware": "NVIDIA A100 80G x8",   # 硬件/GPU 描述（随提交展示）
    "test_name": "我的测试",
    "summary": { "samples_ok":2, "samples_total":2, "avg_ttft_ms":180,
                 "avg_prefill_speed":320.5, "avg_decode_speed":88.2,
                 "avg_output_tokens":128, "avg_total_ms":2500,
                 "concurrency_levels":[1],
                 "by_length": {...}, "by_concurrency": {} },
    "gen": {"context_lengths":[2048,8192], "max_tokens":128, "samples":2, "concurrency_levels":[1]},
    "runs": []
  }'
```

响应：

```json
{ "ok": true, "id": 22, "account_id": 2, "account": "性能评测组",
  "model": "nvidia/Qwen3.6-35B-A3B-NVFP4",
  "url": "/model.html?provider=openai&model=nvidia/Qwen3.6-35B-A3B-NVFP4" }
```

## 2. 后台登录

```bash
POST /api/admin/login  {"username":"admin","password":"admin123"}   # 成功后下发 session cookie
GET  /api/admin/session                                             # {"admin":true}
POST /api/admin/logout
```

## 3. 排行 / 统计 / 对比

```bash
# 模型速度排行（含硬件）；models 可指定对比哪些（provider|model 逗号分隔）
GET /api/leaderboard?sort=avg_decode_speed&order=desc&limit=200
GET /api/leaderboard?models=openai|qwen3.5-plus,autodl|glm-5.3-flash
# sort 可选: avg_decode_speed / avg_prefill_speed / avg_ttft_ms / best_decode / cnt / accounts / last_tested

# 模型对比（默认全部模型）；chart_metric: avg_decode_speed|avg_prefill_speed|avg_ttft_ms|best_decode；chart_type: bar|line
GET /api/compare?models=openai|qwen3.5-plus,google|gemini-2.0-flash&chart_metric=avg_ttft_ms&chart_type=bar

GET /api/stats        # 统计（模型/提交/账号/采样/能力测试数）
GET /api/health
```

## 4. 模型详情

```bash
GET /api/model?provider=openai&model=nvidia/Qwen3.6-35B-A3B-NVFP4
```

返回该模型全部提交（含账号、硬件）+ 按上下文长度聚合 + 折线图数据。

## 5. 提交（前台只读；增删改走后端）

```bash
GET    /api/submissions?page=1&page_size=20&q=关键词&account_id=2&model=xxx&provider=xxx
GET    /api/submissions/<id>
DELETE /api/submissions/<id>                       # 后台
PUT    /api/submissions/<id>/hardware {"hardware":"NVIDIA A100"}   # 后台，改硬件
GET    /api/submissions/<id>/chart                 # 长度→速度折线图 PNG
```

## 6. 账号管理（后台）

```bash
GET    /api/accounts
POST   /api/accounts    {"name":"xxx","remark":"yyy"}
PUT    /api/accounts/<id>  {"name":"xxx","remark":"yyy"}
DELETE /api/accounts/<id>
```

## 7. 模型能力测试（前台只读；内容后台编辑）

```bash
# 前台：只返回 status=1 启用的能力测试
GET /api/capabilities

# 后台：全部（含停用）+ 增删改
GET    /api/admin/capabilities
POST   /api/admin/capabilities
PUT    /api/admin/capabilities/<id>
DELETE /api/admin/capabilities/<id>

# 能力测试对象：{name, category, icon, description, sort, status,
#   items: [ {title, prompt, expect}, ... ]}
```

## 8. 演示数据（后台）

```bash
POST /api/seed-demo           # 🎲 评测演示数据（含硬件）
POST /api/seed-capabilities   # 🎲 能力测试演示数据
```

## 9. 其他

```bash
POST /api/chart              # 图表代理（转发 data-chart-tool 16016，返回 PNG，自动叠加水印）
GET  /api/settings           # 前台设置（watermark/top_n）
```

## 10. 速度项管理（后台，热度/个数/配置简介）

```bash
GET    /api/admin/speed-items
POST   /api/admin/speed-items            # {provider, model, heat, count, intro, remark}
PUT    /api/admin/speed-items/<id>
DELETE /api/admin/speed-items/<id>
POST   /api/admin/speed-items/sync       # 从提交自动同步（默认热度=提交数）
```

排行榜默认按 **热度(heat)** 显示前 N 个（N 后台设置 top_n 可改）；搜索框热门5个取热度前5。

## 11. 站点设置（后台，图片水印/默认条数/排行榜列）

```bash
GET /api/admin/settings
PUT /api/admin/settings  {
  "watermark_text":"...", "watermark_style":"corner",   # 风格: corner/diagonal/bottom/corners/diag-big
  "top_n":10,
  "lb_show_ttft":"0", "lb_show_hardware":"1", "lb_show_framework":"1",
  "lb_merge_decode":"1", "lb_merge_hwfw":"1"
}
```

生成图表时自动叠加水印（默认首页网址，5 种预置风格，浅底深字/深底浅字自适应）；排行榜列显示/合并可配。

## 错误

所有接口失败返回 `{"ok": false, "error": "..."}` + 对应 HTTP 状态码；
后台接口未登录返回 401。