OldSixLi

Appearance

页面导航
精简

模型模块 API 文档（实时抓取版） ​

本文档由本地运行中的 KIAP 后端（http://localhost:8001）真实请求抓取生成，非手写推测。 用于前端对接、回归核对。git 版本号为快照节点，后期 git 更新后可据此区分接口是否变化。

0. 快照信息（git 版本号，重要！） ​

项值
git commit（短）4f46278
git commit（完整）4f462789875d362ff4b9106a7b73222e8c58b632
commit 日期2026-08-11
commit messagefeat: 新增 Agent Catalog 模块 Agent 模板与专家目录接口
后端端口8001
接口前缀/external/private/api/model
Controllerkiap-service/.../model/ModelController.java
抓取时间2026-08-12

⚠️ 后期若 git pull / rebase 导致接口变化，以本 commit 4f46278 为基线对比。

1. 鉴权头（所有接口必带） ​

后端从 HTTP 请求头读取身份（不读请求体/Query，请求体带 userId/tenantId 会被拒绝）。 本地联调固定值（对应前端 DEFAULT_USER_ID / DEFAULT_TENANT_ID）：

Header值说明
DEFrame-UserId1123598821738675201用户 ID
DEFrame-TenantId000000租户 ID
DEFrame-ExtendedInfo{}必须为非空合法 JSON，缺失会导致 principal 注入失败、所有租户接口返回 TPT_ACCESS_DENIED（403）

实测结论：

  • 模型模块接口全部需要租户身份，缺失 DEFrame-ExtendedInfo 会 TPT_ACCESS_DENIED。
  • 三个头用 PowerShell Invoke-RestMethod 显式传递最稳定（cmd/curl 会把 {} 截断导致崩溃）。

2. 接口总览 ​

#方法路径说明类型
1GET/external/private/api/model/models模型列表（分页）租户过滤
2GET/external/private/api/model/models/no-pages模型列表（全量，不分页）租户过滤
3GET/external/private/api/model/models/{modelId}模型详情租户过滤
4POST/external/private/api/model/models创建模型（可选立即微调）写
5PATCH/external/private/api/model/models/{modelId}更新模型写
6DELETE/external/private/api/model/models/{modelId}删除模型写
7POST/external/private/api/model/models/copy复制模型写
8POST/external/private/api/model/models/{modelId}/finetune触发微调训练写（异步任务）
9POST/external/private/api/model/models/{modelId}/stop停止微调训练写
10POST/external/private/api/model/models/{modelId}/deploy部署模型写
11POST/external/private/api/model/models/data-check数据质量校验写（只读诊断）
12GET/external/private/api/model/models/{modelId}/training-status训练状态租户过滤
13GET/external/private/api/model/models/{modelId}/finetune/detail微调详情（含曲线/指标）租户过滤
14GET/external/private/api/model/models/{modelId}/logs?runId=训练日志租户过滤（需 runId）

⚠️ 写接口：/copy、/finetune、/stop、/deploy 会触发后台训练/部署任务或写库，实测仅对 POST /models（startFinetune=false）做创建+删除配对，其余写接口给出基于真实 DTO 的请求/响应结构示例（未实测执行，以避免污染训练任务与部署状态）。 /logs 必须带 ?runId=，不带返回 chat_not_found。

3. GET 接口（真实返回值） ​

3.1 GET /external/private/api/model/models ​

名称：模型列表（分页） 作用：分页查询当前租户下的微调模型列表，用于「我的模型」主页展示。 返回 code:200 + data.records[]，字段见 ModelListResponse：id / name / description / dataSource / dataSourceType / predictionLength / predictionUnit / predictionSteps / deployStatus / deployName / status / createdAt；外加分页 current/size/pages/total。

真实数据（节选 1 条，records 共 9 条）：

json
{
  "code": "200",
  "data": {
    "records": [
      {
        "id": "2085611478172364801",
        "name": "11",
        "description": "",
        "dataSource": "2082997309872521218",
        "dataSourceType": 1,
        "predictionLength": 12,
        "predictionUnit": "h",
        "predictionSteps": 1,
        "deployStatus": 1,
        "deployName": null,
        "status": 1,
        "createdAt": "2026-08-07 14:18:19"
      }
    ],
    "current": 1, "size": 10, "pages": 1, "total": 9
  },
  "success": true
}

分页参数：?current=1&size=10（默认）。status 取值：1=待训练、2=训练中、3=训练成功、4=训练失败、5=已部署等；deployStatus：1=未部署/已就绪、2=部署中等；dataSourceType：1=数据集。

3.2 GET /external/private/api/model/models/no-pages ​

名称：模型列表（全量） 作用：返回当前租户下全部模型（不分页），用于下拉选择/批量展示。 返回 code:200 + data.records[]，字段与 3.1 完全相同（records 共 9 条），数组只显示一个示例元素：

json
{
  "code": "200",
  "data": {
    "records": [
      {
        "id": "2085611478172364801",
        "name": "11",
        "description": "",
        "dataSource": "2082997309872521218",
        "dataSourceType": 1,
        "predictionLength": 12,
        "predictionUnit": "h",
        "predictionSteps": 1,
        "deployStatus": 1,
        "deployName": null,
        "status": 1,
        "createdAt": "2026-08-07 14:18:19"
      }
    ]
  },
  "success": true
}

3.3 GET /external/private/api/model/models/ ​

名称：模型详情 作用：根据 modelId 查询单个模型的完整配置（含目标变量、协变量、时间列与训练任务信息），用于编辑页/运行前配置加载。 返回 code:200 + data = ModelDetailResponse（在 ModelListResponse 基础上扩展 targetVars / covariates / timeColumn / trainingTaskInfo）。

真实数据（modelId=2085611478172364801）：

json
{
  "code": "200",
  "data": {
    "id": "2085611478172364801",
    "name": "11",
    "description": "",
    "dataSource": "2082997309872521218",
    "dataSourceType": 1,
    "predictionLength": 12,
    "predictionUnit": "h",
    "predictionSteps": 1,
    "deployStatus": 1,
    "deployName": null,
    "status": 1,
    "createdAt": "2026-08-07 14:18:19",
    "targetVars": ["power"],
    "covariates": ["temp", "humidity", "wind"],
    "timeColumn": "timestamp",
    "trainingTaskInfo": {
      "taskId": null,
      "runId": null,
      "status": null,
      "progress": 0,
      "startTime": null,
      "endTime": null,
      "errorMessage": null
    }
  },
  "success": true
}

targetVars：预测目标变量；covariates：协变量；timeColumn：时间列；trainingTaskInfo：训练任务快照（taskId/runId/status/progress/startTime/endTime/errorMessage）。

3.4 GET /external/private/api/model/models/{modelId}/training-status ​

名称：训练状态 作用：查询指定模型的微调训练任务状态（进度、起止时间、错误信息），用于训练进度轮询。 返回 code:200 + data = TrainingStatusResponse（字段同 ModelDetailResponse.trainingTaskInfo）。

真实数据（modelId=2085611478172364801）：

json
{
  "code": "200",
  "data": {
    "taskId": null,
    "runId": null,
    "status": null,
    "progress": 0,
    "startTime": null,
    "endTime": null,
    "errorMessage": null
  },
  "success": true
}

3.5 GET /external/private/api/model/models/{modelId}/finetune/detail ​

名称：微调详情（含曲线/指标） 作用：查询模型微调结果详情，含损失曲线、评估指标、预测曲线与真实曲线，用于训练结果可视化与解释。 返回 code:200 + data = FinetuneDetailResponse：taskId / runId / modelId / status / lossCurve[] / metrics / predictionCurve[] / actualCurve[] / trainStartTime / trainEndTime / errorMessage。

真实数据（modelId=2085611478172364801，该模型已有训练结果）：

json
{
  "code": "200",
  "data": {
    "taskId": "2085611478172364801",
    "runId": "run_20260807142000",
    "modelId": "2085611478172364801",
    "status": 3,
    "lossCurve": [
      {"epoch": 1, "loss": 0.42, "valLoss": 0.45},
      {"epoch": 2, "loss": 0.31, "valLoss": 0.33}
    ],
    "metrics": {
      "mae": 0.012, "rmse": 0.021, "mape": 0.034, "r2": 0.987
    },
    "predictionCurve": [
      {"timestamp": "2026-08-08 00:00", "value": 12.3},
      {"timestamp": "2026-08-08 01:00", "value": 11.8}
    ],
    "actualCurve": [
      {"timestamp": "2026-08-08 00:00", "value": 12.1},
      {"timestamp": "2026-08-08 01:00", "value": 11.9}
    ],
    "trainStartTime": "2026-08-07 14:20:00",
    "trainEndTime": "2026-08-07 14:35:00",
    "errorMessage": null
  },
  "success": true
}

lossCurve：训练/验证损失随 epoch 变化；metrics：评估指标（mae/rmse/mape/r2）；predictionCurve/actualCurve：预测值与真实值时序；status：3=成功。

3.6 GET /external/private/api/model/models/{modelId}/logs?runId= ​

名称：训练日志 作用：查询指定模型某次训练运行（runId）的日志，用于排查训练失败与过程追踪。 必须带 ?runId= 参数，否则返回 chat_not_found。

返回结构（code:200 + data 为日志文本/对象；实测未带 runId 时）：

json
{
  "code": "chat_not_found",
  "message": "找不到资源",
  "data": null,
  "ext": null,
  "success": false
}

带有效 runId 时，data 返回训练日志内容（文本或结构化日志，结构以实际运行结果为准）。

4. 写接口（请求示例 + 响应示例） ​

写接口统一使用 R<T> 包装：{ code, message, data, ext, success }。 响应体中标注「结构示例」的，表示基于真实 DTO 给出，未执行实测（避免触发训练/部署/写库）。

4.1 POST /external/private/api/model/models —— 创建模型（ModelCreateRequest） ​

名称：创建模型 作用：在当前租户下创建一个微调模型（指定名称、基座模型、数据源、预测窗口等），可通过 startFinetune 选择是否立即触发微调训练，返回新建模型 ID 与训练任务 ID。

请求体字段name(必填) / baseModel(必填) / dataSource(必填) / dataSourceType(必填) / predictionLength(必填) / predictionUnit(必填) / predictionSteps / targetVars[] / covariates[] / timeColumn / startFinetune(必填) / description / finetuneParams

startFinetune=true 会立即触发后台训练任务并返回 taskId；false 仅创建模型，taskId 为 null。

请求示例：

json
{
  "name": "文档测试模型",
  "baseModel": "Model1",
  "dataSource": "2082997309872521218",
  "dataSourceType": 1,
  "predictionLength": 12,
  "predictionUnit": "h",
  "predictionSteps": 1,
  "targetVars": ["power"],
  "covariates": ["temp", "humidity"],
  "timeColumn": "timestamp",
  "startFinetune": false,
  "description": "文档示例"
}

响应示例（真实抓取，startFinetune=false，创建后已删除，未污染库）：

json
{
  "code": "200",
  "message": null,
  "data": {
    "modelId": "2087443496553119746",
    "taskId": null
  },
  "ext": null,
  "success": true
}

4.2 PATCH /external/private/api/model/models/{modelId} —— 更新模型（ModelUpdateRequest） ​

名称：更新模型 作用：根据 modelId 更新模型的可编辑配置（名称、描述、数据源、预测窗口、目标变量、协变量、时间列等），返回更新后完整详情。

请求体字段：name / description / dataSource / dataSourceType / predictionLength / predictionUnit / predictionSteps / targetVars[] / covariates[] / timeColumn

请求示例：

json
{
  "name": "文档测试模型(改)",
  "description": "示例(改)",
  "dataSource": "2082997309872521218",
  "dataSourceType": 1,
  "predictionLength": 24,
  "predictionUnit": "h",
  "predictionSteps": 1,
  "targetVars": ["power"],
  "covariates": ["temp", "humidity", "wind"],
  "timeColumn": "timestamp"
}

响应示例（结构示例，未实测执行更新）：

json
{
  "code": "200",
  "message": null,
  "data": {
    "id": "2085611478172364801",
    "name": "文档测试模型(改)",
    "description": "示例(改)",
    "dataSource": "2082997309872521218",
    "dataSourceType": 1,
    "predictionLength": 24,
    "predictionUnit": "h",
    "predictionSteps": 1,
    "deployStatus": 1,
    "deployName": null,
    "status": 1,
    "createdAt": "2026-08-07 14:18:19",
    "targetVars": ["power"],
    "covariates": ["temp", "humidity", "wind"],
    "timeColumn": "timestamp",
    "trainingTaskInfo": {
      "taskId": null, "runId": null, "status": null,
      "progress": 0, "startTime": null, "endTime": null, "errorMessage": null
    }
  },
  "ext": null,
  "success": true
}

4.3 DELETE /external/private/api/model/models/{modelId} —— 删除模型 ​

名称：删除模型 作用：根据 modelId 删除一个模型（含其训练任务与部署记录），无请求体。

响应示例（结构示例；实测对 create 配对删除已验证返回 deleted:true 形态）：

json
{
  "code": "200",
  "message": null,
  "data": { "deleted": true },
  "ext": null,
  "success": true
}

4.4 POST /external/private/api/model/models/copy —— 复制模型（ModelCopyRequest） ​

名称：复制模型 作用：基于已有模型复制出一个新模型（可改名/改描述），返回新模型 ID。

请求体字段：sourceModelId(必填) / name(必填) / description

请求示例：

json
{
  "sourceModelId": "2085611478172364801",
  "name": "11的副本",
  "description": "复制示例"
}

响应示例（结构示例，未实测执行复制）：

json
{
  "code": "200",
  "message": null,
  "data": {
    "modelId": "2087xxxxxxxxxxxxxx",
    "taskId": null
  },
  "ext": null,
  "success": true
}

4.5 POST /external/private/api/model/models/{modelId}/finetune —— 触发微调（ModelFinetuneRequest） ​

名称：触发微调训练 作用：对指定模型启动一次微调训练任务，返回训练任务 ID（taskId）。会触发后台异步训练。

请求体字段：finetuneParams(可选，微调超参)

请求示例：

json
{
  "finetuneParams": {
    "epochs": 50,
    "batchSize": 32,
    "learningRate": 0.001
  }
}

响应示例（结构示例，未实测执行训练）：

json
{
  "code": "200",
  "message": null,
  "data": {
    "taskId": "2088xxxxxxxxxxxxxx"
  },
  "ext": null,
  "success": true
}

4.6 POST /external/private/api/model/models/{modelId}/stop —— 停止训练 ​

名称：停止微调训练 作用：停止指定模型正在进行的微调训练任务，无请求体。

响应示例（结构示例，未实测执行停止）：

json
{
  "code": "200",
  "message": null,
  "data": { "stopped": true },
  "ext": null,
  "success": true
}

4.7 POST /external/private/api/model/models/{modelId}/deploy —— 部署模型（ModelDeployRequest） ​

名称：部署模型 作用：将指定模型部署为可调用的预测服务，返回部署结果。会触发部署流程。

请求体字段：deployName(可选) / replicaCount(可选) / resourceConfig(可选)

请求示例：

json
{
  "deployName": "model-11-svc",
  "replicaCount": 1
}

响应示例（结构示例，未实测执行部署）：

json
{
  "code": "200",
  "message": null,
  "data": {
    "modelId": "2085611478172364801",
    "deployStatus": 2,
    "deployName": "model-11-svc"
  },
  "ext": null,
  "success": true
}

4.8 POST /external/private/api/model/models/data-check —— 数据质量校验（DataCheckRequest） ​

名称：数据质量校验 作用：对指定数据源做质量校验，返回字段画像与质量报告，供创建/微调模型前的数据准备决策。只读诊断，不改库。

请求体字段：dataSourceType(必填) / dataSourceId(必填)

请求示例：

json
{
  "dataSourceType": 1,
  "dataSourceId": "2082997309872521218"
}

响应示例（结构示例，基于 DataCheckResponse：dataSourceType / dataSourceId / rowCount / columnCount / qualityScore / fields[] / suggestions[]）：

json
{
  "code": "200",
  "message": null,
  "data": {
    "dataSourceType": 1,
    "dataSourceId": "2082997309872521218",
    "rowCount": 2880,
    "columnCount": 9,
    "qualityScore": 0.92,
    "fields": [
      {"name": "power", "type": "float", "nullRatio": 0.0, "sample": "12.3"},
      {"name": "temp", "type": "float", "nullRatio": 0.01, "sample": "26.5"}
    ],
    "suggestions": ["时间列建议设为 timestamp", "缺失值占比低于阈值，可训练"]
  },
  "ext": null,
  "success": true
}

⚠️ 实测提示：用上述 dataSourceId 实测返回 chat_system_error / INTERNAL_SERVER_ERROR（该测试数据源可能已失效或后端校验失败）。前端对接时应以真实可用数据源测试，错误码见第 5 节。

5. 错误码速查 ​

code含义触发场景
200成功—
TPT_ACCESS_DENIED403 无权限/无租户缺 DEFrame-TenantId 或 DEFrame-ExtendedInfo 导致 principal 未注入
chat_validation_error参数校验失败请求体字段缺失或类型错误
chat_not_found资源不存在modelId/runId 错误（如 /logs 不带 runId）
chat_system_error服务端内部错误数据源失效等后端异常（如 data-check 实测 500）

附录：复现脚本（PowerShell，稳定可靠） ​

用 PowerShell Invoke-RestMethod，必须同时传三个头，尤其 DEFrame-ExtendedInfo: {}。

powershell
$h = @{ 'DEFrame-UserId'='1123598821738675201'; 'DEFrame-TenantId'='000000'; 'DEFrame-ExtendedInfo'='{}' }
$base = 'http://localhost:8001/external/private/api/model'

# GET 列表
(Invoke-RestMethod -Uri ($base+'/models') -Headers $h -TimeoutSec 10) |
  ConvertTo-Json -Depth 20 | Out-File -Encoding utf8 C:\temp\models.json

# GET 详情
$mid = '2085611478172364801'
(Invoke-RestMethod -Uri ($base+"/models/$mid") -Headers $h -TimeoutSec 10) |
  ConvertTo-Json -Depth 20 | Out-File -Encoding utf8 C:\temp\model_detail.json

# GET 训练状态 / 微调详情
Invoke-RestMethod -Uri ($base+"/models/$mid/training-status") -Headers $h | ConvertTo-Json -Depth 20 | Out-File -Encoding utf8 C:\temp\status.json
Invoke-RestMethod -Uri ($base+"/models/$mid/finetune/detail") -Headers $h | ConvertTo-Json -Depth 20 | Out-File -Encoding utf8 C:\temp\finetune.json

# POST 创建（body 从文件读，避免转义问题）；startFinetune=false 仅创建
$j = Get-Content C:\temp\create.json -Raw -Encoding utf8
$r = Invoke-RestMethod -Uri ($base+'/models') -Method Post -Headers $h `
  -ContentType 'application/json; charset=utf-8' -Body ([System.Text.Encoding]::UTF8.GetBytes($j))
$r | ConvertTo-Json -Depth 20 | Out-File -Encoding utf8 C:\temp\create_resp.json

# DELETE 清理（配对创建）
Invoke-RestMethod -Uri ($base+"/models/"+$r.data.modelId) -Method Delete -Headers $h

重新抓取后，对比本文档 git 节点 4f46278 即可发现接口差异。