YG_FT/docs/backend-api-design.md

模型微调平台后端接口设计

后端建议使用 FastAPI，统一挂载 /modelTF 前缀。本文根据当前 Vue 前端路由、API 模块、mock 数据和页面交互反推接口，并补充完整微调平台必须具备的用户中心、权限控制、审计、异步任务、文件版本与监控能力。

1. 通用约定

1.1 统一响应

{
  "code": 0,
  "message": "ok",
  "data": {}
}

• code=0 成功；非 0 为业务错误。
• HTTP 状态码仍用于认证失败、权限不足、参数错误、系统异常。
• 前端当前 axios 已按 { code, data, message } 解包。

1.2 认证与权限

• 登录成功返回 JWT access token，前端后续请求增加 Authorization: Bearer <token>。
• 当前前端权限码：dashboard、fine-tune、model-eval、model-inference、model-manage、dataset、data-process、data-convert、hardware、logs、user-settings。
• 后端 RBAC 建议按 permission.code + role_permission + user_permission_override 实现。
• 所有写操作记录审计日志。

1.3 分页、排序、筛选

当前前端大多直接取数组，后端建议同时支持分页，便于数据量增长：

page=1&page_size=20&keyword=xxx&sort=-created_at

分页响应：

{
  "items": [],
  "total": 0,
  "page": 1,
  "page_size": 20
}

1.4 异步任务

训练、评测、模型加载、数据处理、文件转换都应落为异步任务：

• 创建任务：返回 task_id。
• 查询详情：返回状态、进度、错误信息、运行统计。
• 实时进度：优先 SSE，必要时 WebSocket。

通用状态建议：pending、running、completed、failed、stopped。

2. 用户中心与系统权限

2.1 登录

POST /modelTF/login

请求：

{
  "username": "admin",
  "password": "password"
}

响应：

{
  "token": "jwt-token",
  "user": {
    "id": "uuid",
    "username": "admin",
    "display_name": "系统管理员",
    "role": "admin",
    "status": "active",
    "permissions": ["dashboard", "fine-tune"],
    "create_time": "2026-07-16T10:00:00+08:00",
    "last_login": "2026-07-16T10:00:00+08:00",
    "protected": true
  }
}

说明：前端当前登录接口已经要求返回 user，mock 里只返回 token，正式后端必须返回完整用户信息。

2.2 当前用户

GET /modelTF/me

用于刷新页面后恢复用户信息和权限，避免完全依赖 localStorage。

2.3 用户管理

方法	路径	说明	权限
GET	/modelTF/users	用户列表	user-settings
POST	/modelTF/users	创建用户	user-settings
PUT	/modelTF/users/{id}	更新角色、状态、页面权限	user-settings
DELETE	/modelTF/users/{id}	删除用户	user-settings
PUT	/modelTF/users/{id}/password	重置密码	user-settings

创建用户请求：

{
  "username": "zhangsan",
  "display_name": "张三",
  "password": "InitialPass123",
  "role": "operator",
  "status": "active",
  "permissions": ["dashboard", "fine-tune", "dataset"]
}

更新权限请求：

{
  "role": "viewer",
  "status": "active",
  "permissions": ["dashboard", "logs"]
}

3. 服务看板与系统监控

3.1 首页看板

GET /modelTF/dashboard/overview?period=7d

返回：

{
  "health": {
    "state": "normal",
    "online_services": 12,
    "running_tasks": 5,
    "pending_alerts": 2
  },
  "service_statuses": [
    { "name": "模型推理", "state": "normal", "instances_online": 6, "instances_total": 6 }
  ],
  "training_stats": [
    { "date": "2026-07-16", "train_count": 11, "gpu_count": 5, "avg_score": 89.0 }
  ],
  "recent_tasks": [],
  "operation_distribution": [],
  "login_duration_rank": [],
  "recent_login_users": []
}

说明：首页当前完全使用前端 mock，后端应提供聚合接口，避免前端拼多接口导致加载慢。

3.2 健康指标

GET /modelTF/health

响应字段兼容前端 HealthMetrics：

{
  "cpu_percent": 32,
  "memory_percent": 58,
  "disk_percent": 45
}

3.3 平台性能

GET /modelTF/system-info

返回 CPU、内存、磁盘、GPU、网络、系统运行时间。GPU 进程字段建议包含 pid、name、memory_used_gb、task_name、user。

3.4 日志

方法	路径	说明
GET	/modelTF/log-files?date=2026-07-16	系统日志文件列表
GET	/modelTF/log-content?file=system.log	系统日志内容
GET	/modelTF/training-log-files	训练日志文件列表
GET	/modelTF/training-log-content?file=xxx.log	训练日志内容
POST	/modelTF/web-log	前端错误/行为日志

日志内容应支持 tail、offset、limit 参数，避免一次返回超大文件。

4. 模型管理

4.1 模型登记

方法	路径	说明
GET	/modelTF/model-manage	模型列表
GET	/modelTF/model-manage/{id}	模型详情
GET	/modelTF/model-manage/name/{name}	按名称查询
POST	/modelTF/model-manage	创建模型
PUT	/modelTF/model-manage/{id}	编辑模型
DELETE	/modelTF/model-manage/{id}	删除模型
PUT	/modelTF/model-manage/{id}/purpose	修改用途
GET	/modelTF/model-manage/local-models	扫描本地模型目录

创建/编辑请求：

{
  "name": "Qwen2.5-7B-Instruct",
  "type": "LLM",
  "purpose": "training",
  "model_source": "local",
  "description": "训练基座",
  "path": "/data/models/qwen2.5-7b",
  "api_url": null,
  "api_key": null,
  "online_model_name": null
}

字段说明：

• type: LLM、CV、NLP、Embedding、Other。
• purpose: training、inference、evaluation。
• model_source: local、api。
• api_key 后端加密存储，列表接口只返回脱敏值。

4.2 已训练模型与权重合并

方法	路径	说明
GET	/modelTF/model-manage/trained-models	已训练模型列表
DELETE	/modelTF/model-manage/trained-models/{id}?type=merged|lora	删除训练产物
POST	/modelTF/model-manage/merge	合并 LoRA 权重
GET	/modelTF/model-manage/trained-models/{model_name}/export	导出模型文件

合并请求：

{
  "model_name": "qwen-ft-finance-001",
  "train_method": "lora",
  "base_model_path": "/data/models/qwen2.5-7b"
}

响应：

{
  "merge_task_id": "uuid",
  "status": "pending"
}

5. 数据集管理

5.1 数据集

方法	路径	说明
GET	/modelTF/dataset-manage	数据集列表
GET	/modelTF/dataset-manage/{id}	数据集详情
POST	/modelTF/dataset-manage	创建数据集
PUT	/modelTF/dataset-manage/{id}	更新数据集
DELETE	/modelTF/dataset-manage/{id}	删除数据集
POST	/modelTF/dataset-manage/upload/{dataset_id}	上传文件，字段名 files
GET	/modelTF/dataset-manage/download/{dataset_id}	打包下载数据集
GET	/modelTF/dataset-manage/download/{dataset_id}/{file_id}	下载单文件

创建数据集：

{
  "name": "金融问答-训练集",
  "type": "train",
  "storage_type": "local",
  "source": "upload",
  "description": "金融领域问答",
  "task_id": null
}

数据集类型：

• type: train、test、eval、val、other。
• storage_type: local、minio、cloud。
• source: upload、task。

5.2 文件预览与版本

方法	路径	说明
GET	/modelTF/dataset-manage/preview/{file_id}	当前版本内容预览
GET	/modelTF/dataset-manage/versions/{file_id}	文件版本列表
GET	/modelTF/dataset-manage/versions/{file_id}/{version_id}	读取历史版本
POST	/modelTF/dataset-manage/versions/{file_id}	保存为新版本
PUT	/modelTF/dataset-manage/versions/{file_id}/active	切换当前版本
DELETE	/modelTF/dataset-manage/versions/{file_id}/{version_id}	删除非当前、非初始版本

创建新版本：

{
  "content": "{\"instruction\":\"...\"}\n",
  "description": "在线编辑",
  "base_version_id": "uuid",
  "expected_current_version_id": "uuid"
}

说明：expected_current_version_id 用于乐观锁，防止多人编辑覆盖。

6. 数据处理

当前数据处理页面为本地模拟，正式后端建议实现以下接口。

6.1 任务列表与详情

方法	路径	说明
GET	/modelTF/data-process	数据处理任务列表
POST	/modelTF/data-process	创建草稿任务
GET	/modelTF/data-process/{id}	任务详情
PUT	/modelTF/data-process/{id}	更新任务配置
DELETE	/modelTF/data-process/{id}	删除任务
POST	/modelTF/data-process/{id}/start	启动处理
POST	/modelTF/data-process/{id}/stop	停止处理
GET	/modelTF/data-process/{id}/progress	查询进度
GET	/modelTF/data-process/{id}/events	SSE 实时进度

创建任务：

{
  "name": "客服问答数据清洗",
  "description": "清洗并生成 SFT 数据",
  "process_type": "structured",
  "config": {
    "preprocess_options": ["clean_invalid", "detect_structure", "deduplicate"],
    "dataset_split": { "train": 80, "validation": 10, "test": 10 },
    "generation_model_id": "uuid",
    "generation_prompt": "请生成训练数据",
    "temperature": 0.7,
    "max_tokens": 1024,
    "json_mode": false,
    "quality_filter_enabled": true
  }
}

6.2 源文件与外部数据源

方法	路径	说明
POST	/modelTF/data-process/{id}/source-files	上传源文件，字段名 files
DELETE	/modelTF/data-process/{id}/source-files/{file_id}	移除源文件
POST	/modelTF/data-process/{id}/external/test	测试外部数据源连接
POST	/modelTF/data-process/{id}/external/pull	拉取外部数据并生成源文件

外部数据源请求：

{
  "type": "mysql",
  "url": "mysql://host:3306/db",
  "auth_mode": "password",
  "username": "user",
  "password": "secret",
  "token": null,
  "limit": 1000
}

安全要求：连接密码/token 不落明文，任务详情只回显脱敏配置。

6.3 预览切片

方法	路径	说明
POST	/modelTF/data-process/{id}/preview/build	根据源文件和配置生成预览切片
GET	/modelTF/data-process/{id}/preview	查询预览切片
PUT	/modelTF/data-process/{id}/preview/{preview_id}	编辑切片内容
POST	/modelTF/data-process/{id}/preview	手动新增切片
DELETE	/modelTF/data-process/{id}/preview/{preview_id}	删除切片

预览切片字段：

{
  "id": "uuid",
  "source_file_id": "uuid",
  "original_content": "...",
  "edited_content": "...",
  "source_start": 0,
  "source_end": 100,
  "source_start_line": 1,
  "source_end_line": 5,
  "token_count": 50,
  "status": "original"
}

6.4 生成结果与发布数据集

方法	路径	说明
POST	/modelTF/data-process/{id}/generate	启动 LLM 生成
GET	/modelTF/data-process/{id}/results	查询结果明细
PUT	/modelTF/data-process/{id}/results/{result_id}	编辑结果
POST	/modelTF/data-process/{id}/results/{result_id}/restore	恢复原始结果
POST	/modelTF/data-process/{id}/publish	发布为数据集

结果字段：

{
  "instruction": "生成简洁客服回复",
  "input": "用户反馈页面加载慢",
  "output": "已收到反馈，我们正在排查。",
  "status": "valid"
}

发布请求：

{
  "dataset_name": "客服问答清洗集",
  "dataset_type": "train",
  "storage_type": "local",
  "split": { "train": 80, "validation": 10, "test": 10 },
  "format": "alpaca_jsonl"
}

7. 模型微调

7.1 训练任务

方法	路径	说明
GET	/modelTF/fine-tune	训练任务列表
GET	/modelTF/fine-tune/{id}	训练任务详情
GET	/modelTF/fine-tune/check-name?name=xxx	任务名查重
POST	/modelTF/fine-tune	创建训练任务记录
POST	/modelTF/fine-tune/start	启动训练
PUT	/modelTF/fine-tune/{id}	更新任务
POST	/modelTF/fine-tune/stop/{id}	停止任务
DELETE	/modelTF/fine-tune/{id}	删除任务
GET	/modelTF/fine-tune/progress/{id}	获取训练进度
GET	/modelTF/fine-tune/{id}/events	SSE 训练日志/进度
POST	/modelTF/fine-tune/tensorboard/start	启动 TensorBoard

启动训练请求兼容前端 FineTuneStartPayload：

{
  "task_id": "uuid",
  "name": "finance-sft-001",
  "description": "金融 SFT",
  "train_type": "SFT",
  "train_method": "lora",
  "template": "qwen",
  "base_model": "uuid",
  "train_dataset_id": "uuid",
  "auto_merge": true,
  "output_model_name": "qwen-finance-sft-v1",
  "gpus": [0, 1],
  "batch_size": 1,
  "learning_rate": 0.0001,
  "n_epochs": 1,
  "save_steps": 100,
  "lr_scheduler_type": "cosine",
  "max_length": 512,
  "warmup_ratio": 0.05,
  "weight_decay": 0.01,
  "lora_alpha": 16,
  "lora_dropout": 0.1,
  "lora_rank": 8,
  "quantization_bit": 4,
  "export_quantized": false,
  "quant_method": "",
  "quant_bits": 0,
  "quant_group_size": 0,
  "export_format": ""
}

7.2 训练日志详情页

训练日志页还会联合调用：

• GET /modelTF/fine-tune/{id} 获取任务参数。
• GET /modelTF/dataset-manage/{id} 获取训练集信息。
• GET /modelTF/system-info 获取 GPU 状态。
• GET /modelTF/training-log-files、GET /modelTF/training-log-content 获取日志。

建议新增：

GET /modelTF/fine-tune/{id}/overview

一次返回任务、数据集、GPU、日志摘要、指标曲线，减少页面聚合复杂度。

8. 模型评测

8.1 评测任务

方法	路径	说明
GET	/modelTF/model-eval	评测任务列表
GET	/modelTF/model-eval/{id}	评测详情
POST	/modelTF/model-eval/start	启动评测
DELETE	/modelTF/model-eval/{id}	删除评测
GET	/modelTF/model-eval/{id}/events	SSE 评测进度

启动评测：

{
  "eval_task_name": "金融模型评测-v1",
  "eval_type": "custom",
  "model_id": "uuid",
  "gpu_id": 0,
  "dataset_id": "uuid",
  "dimension_id": "uuid",
  "data_source": "dataset",
  "leaderboard": true,
  "basic_metrics": {
    "bleu": { "enabled": true, "ngram": 4 },
    "rouge": { "enabled": true, "methods": ["rouge-1", "rouge-l"] },
    "cosine": { "enabled": false },
    "output_precision": 3
  }
}

详情响应应包含：

• 综合分数、最大分、总体评价、改进建议。
• 维度汇总。
• 样本级输入、参考答案、模型输出、评分、原因、错误类型。

8.2 评测维度

方法	路径	说明
GET	/modelTF/dimension	维度列表
GET	/modelTF/dimension/{id}	维度详情
POST	/modelTF/dimension	创建维度
PUT	/modelTF/dimension/{id}	编辑维度
DELETE	/modelTF/dimension/{id}	删除维度

维度请求：

{
  "name": "回答准确性",
  "type": "classification",
  "description": "评估回答是否准确",
  "eval_model": "uuid",
  "eval_method": "standard",
  "eval_prompt": "你是专业评测专家...",
  "is_active": true,
  "bleu_n": null,
  "output_precision": 3,
  "score_min": 0,
  "score_max": 100,
  "pass_threshold": 70
}

9. 模型推理与对比

前端将“推理”和“模型对比”共用 model-compare 接口。

9.1 推理/对比任务

方法	路径	说明
GET	/modelTF/model-compare	推理/对比任务列表
GET	/modelTF/model-compare/{id}	任务详情
POST	/modelTF/model-compare	创建任务
DELETE	/modelTF/model-compare/{id}	删除任务
POST	/modelTF/model-compare/{id}/load	加载任务内模型
POST	/modelTF/model-compare/{id}/unload	卸载任务内模型
GET	/modelTF/model-compare/{id}/load-status	查询加载状态
POST	/modelTF/model-compare/{id}/load-status	更新加载状态
POST	/modelTF/model-compare/{id}/start-model	启动单个模型服务
POST	/modelTF/model-compare/stop-by-pid	按 PID 停止模型
POST	/modelTF/model-compare/all/stop-all	停止全部旧模型服务

创建任务：

{
  "name": "金融模型对比",
  "description": "对比基座与微调模型",
  "models": [
    {
      "model_id": "uuid",
      "model_name": "Qwen2.5-7B-Instruct",
      "model_path": "/data/models/qwen2.5-7b",
      "gpu_id": 0,
      "source": "database"
    }
  ]
}

9.2 对话接口

方法	路径	说明
POST	/modelTF/model-compare/stream-chat	流式对话，建议 SSE/chunked
POST	/modelTF/model-compare/chat-with-port	指定端口非流式对话
POST	/modelTF/model-chat/batch	API 模型批量对话
POST	/modelTF/model-chat/local/chat	本地模型对话
POST	/modelTF/model-chat/local/preload	预加载本地模型
POST	/modelTF/model-chat/trained/preload	预加载已训练模型

流式请求：

{
  "task_id": "uuid",
  "model_id": "uuid",
  "messages": [
    { "role": "user", "content": "解释什么是 ROE" }
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": true
}

建议落库会话与消息，便于对比结果页查看历史。

10. 数据转换与工具中心

10.1 数据转换

当前 JSON 转 JSONL 页面是 UI 原型，建议接口：

方法	路径	说明
POST	/modelTF/data-convert/jobs	创建转换任务，multipart 上传源文件
GET	/modelTF/data-convert/jobs/{id}	转换任务详情
GET	/modelTF/data-convert/jobs/{id}/download	下载转换结果
DELETE	/modelTF/data-convert/jobs/{id}	删除转换任务

请求字段：

• source_file: .json 文件。
• output_name: 输出文件名。
• encoding: 默认 UTF-8。
• convert_type: json_to_jsonl。

10.2 自定义工具

当前自定义工具仅 localStorage，若要多用户共享，建议接口：

方法	路径	说明
GET	/modelTF/tools	工具列表
POST	/modelTF/tools	创建工具
GET	/modelTF/tools/{id}	工具详情
PUT	/modelTF/tools/{id}	编辑工具
DELETE	/modelTF/tools/{id}	删除工具

字段：name、description、url、icon、visibility、owner_id。

11. 后端开发需要补齐的关键点

1. 前端路由已有 user-settings、user-create、user-permission、permission-denied，但当前仓库缺少对应 Vue 文件；后端仍应先实现用户中心和权限接口。
2. 数据处理主流程目前全在浏览器本地模拟，后端需要正式实现上传、切片、LLM 生成、结果编辑、发布数据集。
3. 训练、评测、数据处理、模型加载都不应同步阻塞 HTTP；建议接 Celery/RQ/Arq 或 FastAPI BackgroundTasks + 独立 worker。
4. 文件内容不要全部入库；数据库保存元数据、版本、校验和、对象存储路径，内容放本地 NAS/MinIO。
5. API Key、外部数据源密码必须加密存储，接口只回显脱敏。
6. 日志和监控数据增长快，需要分区或保留策略。
7. 建议实现 OpenAPI schema，并用 Pydantic enum 与数据库 enum 对齐。

12. 仍需确认的问题

1. 部署形态已确认：多算力节点仍按“单机多 GPU 节点”管理，不引入 K8s；每台 GPU 服务器独立部署 Compute API/Agent/File Gateway/LLaMA-Factory。
2. 文件存储：使用本地磁盘、NAS、MinIO，还是对象存储？是否需要断点续传？
3. 训练框架：是否固定使用 LLaMA-Factory？是否还要支持 Transformers 原生、DeepSpeed、Accelerate？
4. 权限粒度：页面级权限是否足够，还是需要到数据集/模型/任务的所有者与项目空间级权限？
5. 多租户/项目空间：是否需要组织、项目、团队隔离？
6. 审批流程：模型发布、数据集删除、停止训练等危险操作是否需要审批？
7. 评测方式：只支持规则指标 + LLM Judge，还是需要人工标注/复核闭环？
8. 推理服务：是否需要长驻服务、自动端口管理、并发限流、会话历史长期保存？
9. 合规安全：数据脱敏、敏感词检测、审计留存周期、模型 API Key 管理是否有公司规范？
10. 数据库规模预期：数据集样本量、日志保留周期、监控采样频率，会影响分区和索引策略。

13. 企业治理与算力平台补充接口

根据 system-development-plan.md，以下能力已从待确认项升级为第一版设计范围：单机多 GPU、本地磁盘、应用平台/算力平台分离、多租户、项目级资源隔离、审批流、审计留存、LLaMA-Factory 引擎插件化。原有业务接口需要统一增加 tenant_id、project_id 上下文，列表接口默认只返回当前用户可访问项目内资源。

13.1 租户管理

方法	路径	说明	权限
GET	/modelTF/tenants	租户列表	平台管理员
POST	/modelTF/tenants	创建租户	平台管理员
GET	/modelTF/tenants/{id}	租户详情	租户管理员
PUT	/modelTF/tenants/{id}	更新租户	平台管理员
PUT	/modelTF/tenants/{id}/quota	设置租户配额	平台管理员
PUT	/modelTF/tenants/{id}/retention-policy	设置租户留存策略	平台管理员

创建租户：

{
  "name": "研发一部",
  "code": "rd-1",
  "status": "active",
  "quota": {
    "gpu_concurrency": 4,
    "storage_bytes": 10995116277760,
    "max_projects": 20
  },
  "retention_policy": {
    "audit_days": 180,
    "training_log_days": 90,
    "metric_days": 30,
    "temp_file_days": 1
  }
}

13.2 项目空间

方法	路径	说明
GET	/modelTF/projects	当前用户可访问项目列表
POST	/modelTF/projects	创建项目
GET	/modelTF/projects/{id}	项目详情
PUT	/modelTF/projects/{id}	更新项目
POST	/modelTF/projects/{id}/archive	归档项目
GET	/modelTF/projects/{id}/members	项目成员
POST	/modelTF/projects/{id}/members	添加成员
PUT	/modelTF/projects/{id}/members/{user_id}	修改项目角色
DELETE	/modelTF/projects/{id}/members/{user_id}	移除成员

创建项目：

{
  "tenant_id": "uuid",
  "name": "金融模型微调",
  "code": "finance-ft",
  "description": "金融问答模型训练与评测",
  "quota": {
    "gpu_concurrency": 2,
    "storage_bytes": 2199023255552,
    "max_running_jobs": 3
  }
}

项目角色建议：owner、maintainer、developer、reviewer、viewer。

13.3 资源级授权

模型、数据集、训练任务、评测任务、推理任务、数据处理任务都必须支持资源级 ACL。

方法	路径	说明
GET	/modelTF/resources/{resource_type}/{resource_id}/acl	查询资源授权
PUT	/modelTF/resources/{resource_type}/{resource_id}/acl	覆盖资源授权
POST	/modelTF/resources/{resource_type}/{resource_id}/share	快速分享给用户/项目角色

授权请求：

{
  "entries": [
    {
      "subject_type": "user",
      "subject_id": "uuid",
      "permissions": ["read", "execute", "download"]
    },
    {
      "subject_type": "project_role",
      "subject_id": "developer",
      "permissions": ["read", "write", "execute"]
    }
  ]
}

权限码：read、write、execute、download、delete、manage_acl。

13.4 审批中心

方法	路径	说明
GET	/modelTF/approvals	审批列表，支持 type=pending/mine/done
POST	/modelTF/approvals	发起审批
GET	/modelTF/approvals/{id}	审批详情
POST	/modelTF/approvals/{id}/approve	通过
POST	/modelTF/approvals/{id}/reject	驳回
POST	/modelTF/approvals/{id}/cancel	撤回
GET	/modelTF/approval-templates	审批模板列表
PUT	/modelTF/approval-templates/{id}	更新审批模板

发起审批：

{
  "action": "model_publish",
  "resource_type": "trained_model",
  "resource_id": "uuid",
  "project_id": "uuid",
  "reason": "发布金融问答模型测试服务",
  "payload": {
    "service_level": "production",
    "gpu_id": 0,
    "max_concurrency": 8
  }
}

第一版建议触发审批的动作：删除数据集、删除模型、生产服务发布、导出模型、下载敏感数据集、提高 GPU 配额、停止他人任务。

13.5 算力资源与队列

应用平台对前端暴露 /modelTF/compute/*，实际由 Compute Gateway 调用算力平台内部接口。

方法	路径	说明
GET	/modelTF/compute/nodes	算力节点列表
POST	/modelTF/compute/nodes	新增算力节点
GET	/modelTF/compute/nodes/{id}	算力节点详情
PUT	/modelTF/compute/nodes/{id}	编辑节点地址、权重、标签、路径和启用状态
POST	/modelTF/compute/nodes/{id}/test-connection	测试 Compute API/File Gateway 连通性
POST	/modelTF/compute/nodes/{id}/enable	启用节点
POST	/modelTF/compute/nodes/{id}/disable	禁用节点，不接收新任务
POST	/modelTF/compute/nodes/{id}/drain	进入维护模式，已有任务跑完后下线
POST	/modelTF/compute/nodes/{id}/health-check	主动触发节点健康检查
GET	/modelTF/compute/nodes/{id}/engines	节点训练引擎和版本
GET	/modelTF/compute/nodes/{id}/replicas	节点本地资源副本
GET	/modelTF/compute/gpus	GPU 状态
GET	/modelTF/compute/queue	任务队列
GET	/modelTF/compute/jobs/{id}	算力任务详情
POST	/modelTF/compute/jobs/{id}/retry	重试任务
POST	/modelTF/compute/jobs/{id}/priority	调整优先级
POST	/modelTF/internal/compute-sync/jobs/poll	应用平台主动轮询并同步算力任务状态
POST	/modelTF/internal/compute-sync/resources	调度前同步数据集/模型到目标节点

算力节点设计说明：

• 多算力节点仍按“单机多 GPU 节点”管理，每台 GPU 服务器是一条 compute_nodes 记录。
• 每个可执行训练的节点都需要部署 Compute API、Compute Agent、File Gateway 和宿主机挂载的 LLaMA-Factory。
• 节点之间默认不互相访问，应用平台主动访问所有节点的 Compute API/File Gateway。
• 调度支持 auto 和 manual：普通用户默认自动调度，管理员或高级用户可手动指定节点。

算力节点响应字段：

{
  "id": "uuid",
  "code": "gpu-node-01",
  "name": "A800 Node 01",
  "api_base_url": "http://10.10.20.31:19100",
  "file_gateway_url": "http://10.10.20.31:19101",
  "enabled": true,
  "scheduler_status": "online",
  "scheduler_weight": 100,
  "tags": ["A800", "80GB", "llama_factory"],
  "gpu_count": 8,
  "current_running_jobs": 2,
  "max_parallel_jobs": 8,
  "data_root": "/data/yg-ft",
  "model_root": "/data/yg-ft/models",
  "log_root": "/opt/yg-ft/logs/compute",
  "last_health_check_at": "2026-07-20T12:00:00+08:00",
  "health_detail": {
    "compute_api": "ok",
    "file_gateway": "ok",
    "llama_factory": "ok"
  }
}

GPU 响应字段：

{
  "node_id": "uuid",
  "gpu_index": 0,
  "uuid": "GPU-xxx",
  "name": "NVIDIA A800",
  "status": "running",
  "memory_total_mb": 81920,
  "memory_used_mb": 40960,
  "utilization_percent": 72,
  "temperature": 61,
  "current_job_id": "uuid",
  "current_project_id": "uuid"
}

13.6 算力平台内部接口

以下接口只允许应用平台调用，不直接暴露给浏览器。

方法	路径	说明
POST	/modelTF/compute/jobs	创建训练/评测/数据处理/推理任务
GET	/modelTF/compute/jobs/{id}	查询任务
POST	/modelTF/compute/jobs/{id}/stop	停止任务
GET	/modelTF/compute/jobs/{id}/logs	拉取日志
GET	/modelTF/compute/resources/gpus	查询 GPU
POST	/modelTF/compute/files/upload	上传到算力本地磁盘
GET	/modelTF/compute/files/{id}/download	下载文件

创建算力任务：

{
  "tenant_id": "uuid",
  "project_id": "uuid",
  "job_type": "fine_tune",
  "engine": "llama_factory",
  "priority": "normal",
  "scheduler": {
    "mode": "auto",
    "requested_node_id": null,
    "required_tags": ["A800"],
    "preferred_tags": ["llama_factory"],
    "min_gpu_memory_mb": 40960
  },
  "resource_request": {
    "gpu_count": 1,
    "gpu_ids": [0],
    "memory_gb": 64
  },
  "workspace": {
    "root": "/data/ft-platform/tenants/{tenant_id}/projects/{project_id}/jobs/{job_id}"
  },
  "payload": {
    "model_path": "/data/ft-platform/.../models/base/qwen",
    "dataset_path": "/data/ft-platform/.../datasets/train.jsonl",
    "training_args": {}
  },
  "status_sync_mode": "polling",
  "poll_interval_seconds": 10
}

手动指定节点时：

{
  "scheduler": {
    "mode": "manual",
    "requested_node_id": "uuid",
    "gpu_ids": [0, 1]
  }
}

调度前资源副本检查：

{
  "target_compute_node_id": "uuid",
  "resources": [
    {
      "resource_type": "model",
      "resource_id": "uuid",
      "required": true
    },
    {
      "resource_type": "dataset",
      "resource_id": "uuid",
      "required": true
    }
  ],
  "sync_if_missing": true
}

如果目标节点缺少数据集或模型副本，应用平台通过 File Gateway 创建 resource_sync_jobs，同步完成后再提交训练任务。

13.7 文件网关与离线导入

方法	路径	说明
POST	/modelTF/files/upload-session	创建分片上传会话
PUT	/modelTF/files/upload-session/{id}/parts/{part_no}	上传分片
POST	/modelTF/files/upload-session/{id}/complete	完成上传
GET	/modelTF/files/{id}/preview	文件预览
GET	/modelTF/files/{id}/download-url	获取短时下载链接
POST	/modelTF/import/local-model	从算力节点本地路径导入模型
POST	/modelTF/import/local-dataset	从算力节点本地路径导入数据集

离线导入模型：

{
  "tenant_id": "uuid",
  "project_id": "uuid",
  "compute_node_id": "uuid",
  "path": "/data/models/qwen2.5-7b",
  "name": "Qwen2.5-7B-Instruct",
  "purpose": "training"
}

13.8 训练引擎管理

方法	路径	说明
GET	/modelTF/training-engines	训练引擎列表
GET	/modelTF/training-engines/{id}	引擎详情
GET	/modelTF/training-engines/{id}/schema	参数 schema
POST	/modelTF/training-engines/{id}/health-check	健康检查

LLaMA-Factory 引擎声明：

{
  "code": "llama_factory",
  "name": "LLaMA-Factory",
  "version": "0.9.x",
  "supported_task_types": ["SFT", "DPO", "CPT"],
  "supported_methods": ["lora", "qlora", "full"],
  "supported_formats": ["alpaca", "sharegpt", "dpo_pair", "pretrain_text"],
  "schema": {}
}

13.9 Checkpoint 与恢复训练

方法	路径	说明
GET	/modelTF/fine-tune/{id}/checkpoints	checkpoint 列表
POST	/modelTF/fine-tune/{id}/retry	失败任务重试
POST	/modelTF/fine-tune/{id}/resume	从 checkpoint 恢复训练
DELETE	/modelTF/fine-tune/{id}/checkpoints/{checkpoint_id}	删除 checkpoint，可能触发审批
PUT	/modelTF/fine-tune/{id}/checkpoint-retention	设置 checkpoint 保留策略

默认保留策略：最近 3 个、最优 2 个、已发布模型关联 checkpoint 不自动删除、失败任务保留 14 天。

13.10 审计、留存、配额和成本统计

方法	路径	说明
GET	/modelTF/audit-logs	操作审计
GET	/modelTF/login-logs	登录审计
GET	/modelTF/download-logs	下载审计
GET	/modelTF/retention-policies	留存策略
PUT	/modelTF/retention-policies/{id}	更新留存策略
GET	/modelTF/quotas/usage	配额使用
GET	/modelTF/usage/summary	GPU 小时、磁盘、推理调用统计

第一版只做用量统计，不做账单计费；第二期可扩展成本核算。

14. 接口与页面功能模块映射

本节用于接口开发和前后端联调。后端开发人员可按页面模块确认接口覆盖范围；前端开发人员可按页面查找需要调用的 API。

14.1 认证、用户和权限

页面模块	路由/入口	接口	说明
登录页	/login	POST /modelTF/login、GET /modelTF/me、POST /modelTF/logout	登录、恢复用户、退出
用户中心	/user-settings	GET /modelTF/users	用户列表、搜索、状态筛选
创建用户	/user-settings/create	POST /modelTF/users	创建本地用户
用户权限	/user-settings/:id/permission	PUT /modelTF/users/{id}、PUT /modelTF/users/{id}/password	用户角色、状态、页面权限、重置密码
无权限页	/permission-denied	无专属接口，可调用 GET /modelTF/me	展示当前用户权限和返回入口

14.2 租户、项目和资源授权

页面模块	路由/入口	接口	说明
租户管理	/tenants	GET /modelTF/tenants、POST /modelTF/tenants	租户列表、创建租户
租户详情	/tenants/:id	GET /modelTF/tenants/{id}、PUT /modelTF/tenants/{id}、PUT /modelTF/tenants/{id}/quota、PUT /modelTF/tenants/{id}/retention-policy	租户配置、配额、留存
项目列表	/projects	GET /modelTF/projects、POST /modelTF/projects	项目列表、创建项目
项目详情	/projects/:id	GET /modelTF/projects/{id}、PUT /modelTF/projects/{id}、POST /modelTF/projects/{id}/archive	项目概览、归档
项目成员	/projects/:id/members	GET /modelTF/projects/{id}/members、POST /modelTF/projects/{id}/members、PUT /modelTF/projects/{id}/members/{user_id}、DELETE /modelTF/projects/{id}/members/{user_id}	成员和项目角色
资源授权	资源详情弹窗或 /projects/:id/permissions	GET /modelTF/resources/{resource_type}/{resource_id}/acl、PUT /modelTF/resources/{resource_type}/{resource_id}/acl、POST /modelTF/resources/{resource_type}/{resource_id}/share	模型/数据集/任务级 ACL

14.3 看板、监控和日志

页面模块	路由/入口	接口	说明
服务看板	/dashboard	GET /modelTF/dashboard/overview、GET /modelTF/health	首页聚合、轻量健康指标
平台性能	/hardware	GET /modelTF/system-info、GET /modelTF/compute/gpus	CPU、内存、磁盘、GPU、任务占用
系统日志	/logs	GET /modelTF/log-files、GET /modelTF/log-content	系统日志列表和内容
训练日志页	/training-log/:id	GET /modelTF/fine-tune/{id}/overview、GET /modelTF/training-log-files、GET /modelTF/training-log-content	训练日志、指标、GPU 状态

14.4 模型管理

页面模块	路由/入口	接口	说明
模型列表	/model-manage	GET /modelTF/model-manage、DELETE /modelTF/model-manage/{id}、PUT /modelTF/model-manage/{id}/purpose	模型列表、删除审批入口、用途变更
模型创建/编辑	/model-manage/create、/model-manage/:id/edit	GET /modelTF/model-manage/{id}、POST /modelTF/model-manage、PUT /modelTF/model-manage/{id}、GET /modelTF/model-manage/local-models	本地/API 模型登记
离线导入模型	模型创建页或导入弹窗	POST /modelTF/import/local-model	从算力节点本地路径导入
已训练模型	模型列表/选择弹窗	GET /modelTF/model-manage/trained-models、DELETE /modelTF/model-manage/trained-models/{id}	训练产物列表和删除
权重合并	/model-manage/merge	POST /modelTF/model-manage/merge	LoRA 合并任务
模型导出	模型列表/详情	GET /modelTF/model-manage/trained-models/{model_name}/export	导出下载，必要时触发审批

14.5 数据集与数据处理

页面模块	路由/入口	接口	说明
数据集列表	/dataset	GET /modelTF/dataset-manage、DELETE /modelTF/dataset-manage/{id}、GET /modelTF/dataset-manage/download/{id}	数据集列表、删除、打包下载
数据集创建/编辑	/dataset/create、/dataset/:id/edit	POST /modelTF/dataset-manage、PUT /modelTF/dataset-manage/{id}、POST /modelTF/dataset-manage/upload/{dataset_id}	数据集元数据和文件上传
离线导入数据集	数据集创建页或导入弹窗	POST /modelTF/import/local-dataset	从算力节点目录导入
数据集预览	/dataset/:id/preview	GET /modelTF/dataset-manage/preview/{file_id}、GET /modelTF/dataset-manage/versions/{file_id}、POST /modelTF/dataset-manage/versions/{file_id}、PUT /modelTF/dataset-manage/versions/{file_id}/active、DELETE /modelTF/dataset-manage/versions/{file_id}/{version_id}	文件预览、版本、在线编辑
数据处理列表	/data-process	GET /modelTF/data-process、DELETE /modelTF/data-process/{id}	处理任务列表
数据处理创建向导	/data-process/create	POST /modelTF/data-process、POST /modelTF/data-process/{id}/source-files、POST /modelTF/data-process/{id}/preview/build、POST /modelTF/data-process/{id}/generate、POST /modelTF/data-process/{id}/publish	创建、上传、预览、生成、发布
数据处理详情	/data-process/:id	GET /modelTF/data-process/{id}、GET /modelTF/data-process/{id}/results、GET /modelTF/data-process/{id}/progress、GET /modelTF/data-process/{id}/events	详情、结果、进度
数据转换	/data-convert	POST /modelTF/data-convert/jobs、GET /modelTF/data-convert/jobs/{id}、GET /modelTF/data-convert/jobs/{id}/download	JSON/JSONL 转换

14.6 微调训练

页面模块	路由/入口	接口	说明
微调列表	/fine-tune	GET /modelTF/fine-tune、POST /modelTF/fine-tune/stop/{id}、DELETE /modelTF/fine-tune/{id}	训练任务列表、停止、删除
微调创建	/fine-tune/create	GET /modelTF/fine-tune/check-name、POST /modelTF/fine-tune、POST /modelTF/fine-tune/start、GET /modelTF/model-manage、GET /modelTF/dataset-manage、GET /modelTF/compute/gpus	参数配置、GPU 选择、启动训练
训练详情/日志	/training-log/:id	GET /modelTF/fine-tune/{id}、GET /modelTF/fine-tune/progress/{id}、GET /modelTF/fine-tune/{id}/events、GET /modelTF/fine-tune/{id}/checkpoints	日志、进度、checkpoint
恢复/重试训练	训练详情页	POST /modelTF/fine-tune/{id}/retry、POST /modelTF/fine-tune/{id}/resume	从 checkpoint 重试或恢复
Checkpoint 管理	训练详情页、存储管理页	DELETE /modelTF/fine-tune/{id}/checkpoints/{checkpoint_id}、PUT /modelTF/fine-tune/{id}/checkpoint-retention	清理策略和删除
TensorBoard	训练详情页	POST /modelTF/fine-tune/tensorboard/start	启动 TensorBoard

14.7 评测、推理、对比和服务发布

页面模块	路由/入口	接口	说明
评测列表	/model-eval	GET /modelTF/model-eval、DELETE /modelTF/model-eval/{id}	评测任务列表
评测创建	/model-eval/create	POST /modelTF/model-eval/start、GET /modelTF/dimension、GET /modelTF/model-manage/trained-models、GET /modelTF/dataset-manage、GET /modelTF/compute/gpus	选择模型、数据集、维度、GPU
评测详情	/model-eval/:id	GET /modelTF/model-eval/{id}、GET /modelTF/model-eval/{id}/events	综合结果、样本评分
评测维度	/model-eval/dimension/:id/edit	GET /modelTF/dimension/{id}、POST /modelTF/dimension、PUT /modelTF/dimension/{id}、DELETE /modelTF/dimension/{id}	维度和 Prompt 管理
推理列表	/model-inference	GET /modelTF/model-compare、POST /modelTF/model-compare/{id}/load、POST /modelTF/model-compare/{id}/unload	推理任务和加载状态
推理创建	/model-inference/create	POST /modelTF/model-compare、GET /modelTF/model-manage、GET /modelTF/model-manage/trained-models、GET /modelTF/compute/gpus	选择模型和 GPU
推理对话	/model-inference/chat/:id	GET /modelTF/model-compare/{id}、POST /modelTF/model-compare/stream-chat、POST /modelTF/model-compare/chat-with-port	单模型对话
模型对比	/model-compare/chat/:id、/model-compare/result	POST /modelTF/model-chat/batch、POST /modelTF/model-chat/local/chat、POST /modelTF/model-chat/local/preload、POST /modelTF/model-chat/trained/preload	多模型对比和预加载
模型服务治理	/model-services、/model-services/:id	POST /modelTF/approvals、GET /modelTF/compute/jobs/{id}、GET /modelTF/usage/summary	测试/生产服务发布、调用统计、下线审批

14.8 审批、审计、算力和存储运维

页面模块	路由/入口	接口	说明
审批中心	/approvals、/approvals/pending、/approvals/mine、/approvals/:id	GET /modelTF/approvals、POST /modelTF/approvals、GET /modelTF/approvals/{id}、POST /modelTF/approvals/{id}/approve、POST /modelTF/approvals/{id}/reject、POST /modelTF/approvals/{id}/cancel	审批列表和审批动作
审批设置	/approval-settings	GET /modelTF/approval-templates、PUT /modelTF/approval-templates/{id}	审批模板
算力资源	/compute、/compute/gpus、/compute/queue、/compute/nodes	GET/POST/PUT /modelTF/compute/nodes、POST /modelTF/compute/nodes/{id}/test-connection、POST /modelTF/compute/nodes/{id}/enable、POST /modelTF/compute/nodes/{id}/disable、POST /modelTF/compute/nodes/{id}/drain、GET /modelTF/compute/gpus、GET /modelTF/compute/queue、POST /modelTF/compute/jobs/{id}/retry、POST /modelTF/compute/jobs/{id}/priority	GPU、节点、队列、节点权重、标签、维护状态、资源副本
存储管理	/storage	GET /modelTF/quotas/usage、GET /modelTF/files/{id}/download-url、GET /modelTF/retention-policies、PUT /modelTF/retention-policies/{id}	磁盘占用、下载、留存
审计中心	/audit-logs、/login-logs、/download-logs	GET /modelTF/audit-logs、GET /modelTF/login-logs、GET /modelTF/download-logs	操作、登录、下载审计
训练引擎管理	/training-engines	GET /modelTF/training-engines、GET /modelTF/training-engines/{id}、GET /modelTF/training-engines/{id}/schema、POST /modelTF/training-engines/{id}/health-check	引擎能力和健康