AI_Painting_V2.0/docs/模型参数后端化方案.md

模型参数后端化方案

一、当前架构（平台重构后）

平台重构已采用 Platform Descriptor 模式，Painting 和 Video 统一走扁平 modelParams：

src/platforms/
├── registry.js              # 注册表：registerPlatform() + createPlatform()
├── painting/
│   ├── index.js             # Painting descriptor（controls, state, loadConfig 等）
│   ├── modelSelector.vue
│   ├── imageUploader.vue
│   ├── models/              # 模型参数 schema（本地 JS 文件，待后端化）
│   │   ├── index.js         # getModelConfig(modelName) → 查找本地 config
│   │   └── flux-2.js        # 单个模型的 params 定义
│   └── controls/
│       ├── proportion.vue
│       ├── dimension.vue
│       ├── quality.vue
│       └── quantity.vue
└── video/
    ├── index.js             # Video descriptor（仍用 fetchModelConfig 拉远程 JSON）
    ├── modelSelector.vue
    ├── imageUploader.vue
    └── controls/
        ├── pattern.vue
        ├── proportion.vue
        └── time.vue

核心数据流（两个平台统一）：

1. 用户选择模型 → dialogBox 调用 platform.loadConfig(modelName, modelType)
2. loadConfig 获取参数 schema → 驱动 controls 数组渲染对应 UI 控件
3. 用户点击发送 → platform.buildTaskBody({ prompt, referenceImages }) 返回扁平 modelParams
4. createTask.js 透传 data.body（不再做任何转换）
5. POST /suanli/v1/tasks，携带 X-Session-Id header

当前参数配置来源（待统一）：

平台	参数配置来源	位置
Painting	本地 JS 文件（硬编码）	src/platforms/painting/models/*.js
Video	远程静态 JSON（每日 localStorage 缓存）	fetchModelConfig() → resources.xueai.art/AIGC/static/public/Platform/Video/workflows/...

两个平台的 buildTaskBody() 均已返回扁平 modelParams，不再构造 { workflowId, nodeInfoList } 格式。

---

二、目标架构

将模型参数配置从前端代码迁移到后端 API，实现：

• 新增模型/修改参数无需前端发版
• Painting 和 Video 使用统一的 API 获取配置
• 前端只保留 UI 控件库，参数 schema 完全由后端驱动

后端 API
├── GET /api/v1/platforms/:code/models          # 模型列表（已有）
│   └── 响应: [{ id, display_name, tags, config? }]
├── GET /api/v1/models/:id/config               # 模型参数配置（新增）
│   └── 响应: { params: [...], inputType, maxImages, ... }
└── POST /api/v1/tasks                          # 创建任务（已有）
    └── 请求体: 扁平 modelParams（与 RunningHub API 格式对齐）

改造后的数据流：

用户选择模型
  → platform.loadConfig(modelName)
    → GET /api/v1/models/:id/config
      → 返回 { params: [{ name, ui, default, options, ... }] }
        → 前端根据 ui 字段渲染对应控件
          → 用户填写参数
            → buildTaskBody() 返回扁平 { aspectRatio, resolution, ... }
              → POST /api/v1/tasks

---

三、模型配置 API 格式

3.1 请求

GET /api/v1/models/:modelId/config

modelId 来自模型列表接口返回的 id 字段（UUID）。

3.2 响应格式

{
  "code": 0,
  "data": {
    "inputType": "text",
    "maxImages": 4,
    "promptPlaceholder": "描述你想生成的画面和动作。",
    "params": [
      {
        "name": "prompt",
        "ui": "textarea",
        "label": "提示词",
        "required": true,
        "default": ""
      },
      {
        "name": "aspectRatio",
        "ui": "proportion",
        "label": "比例",
        "default": "1:1",
        "options": ["1:1", "3:4", "4:3", "9:16", "16:9", "custom"]
      },
      {
        "name": "resolution",
        "ui": "resolution",
        "label": "分辨率",
        "default": "2k",
        "options": ["1k", "2k", "4k"]
      },
      {
        "name": "size",
        "ui": "dimension",
        "label": "尺寸",
        "default": "1024*1024",
        "dimension": {
          "width":  { "min": 256, "max": 6197 },
          "height": { "min": 256, "max": 4096 }
        }
      },
      {
        "name": "quality",
        "ui": "select",
        "label": "画质",
        "default": "medium",
        "options": ["low", "medium", "high"]
      },
      {
        "name": "quantity",
        "ui": "quantity",
        "label": "生成数量",
        "default": 1,
        "options": [1, 2, 3, 4]
      },
      {
        "name": "imageUrl",
        "ui": "imageUpload",
        "label": "参考图",
        "maxCount": 4
      }
    ]
  }
}

3.3 ui 字段与前端控件映射

ui 值	前端控件	说明
textarea	Sender 内置 textarea	提示词输入框，不需要额外渲染控件
proportion	PaintingProportion / VideoProportion	比例选择 Popover，options 含 custom 时允许自定义宽高
resolution	proportion 控件内部	分辨率子选项，与 proportion 共用 Popover
dimension	DimensionInput	组合模式：单字段 "W*H" 格式，通过 dimension.parse/format 序列化
dimensionWidth + dimensionHeight	DimensionInput	拆分模式：两个独立字段，共享同一个 Popover 和比例锁
select	Select	通用下拉选择（如 quality）
quantity	Quantity	生成数量，上限由 options 最大值派生
imageUpload	ImageUploader	参考图上传，maxCount 控制数量上限
hidden	无	静默写入默认值，不渲染控件

3.4 条件显示

{
  "name": "customWidth",
  "ui": "dimensionWidth",
  "showWhen": { "aspectRatio": "custom" }
}

showWhen 字段使参数仅在指定条件满足时显示。当前支持的条件：aspectRatio 值为 custom。

---

四、迁移步骤

阶段一：后端实现模型配置 API

• 设计并实现 GET /api/v1/models/:id/config 接口
• 将 Painting 的 9 个模型配置（src/platforms/painting/models/*.js）迁移到数据库/配置文件
• 将 Video 的 workflow 配置（resources.xueai.art/AIGC/static/public/Platform/Video/workflows/...）迁移到同一接口
• 响应格式对齐 3.2 节的 schema

阶段二：前端适配

• src/platforms/painting/models/ 目录删除，getModelConfig() 改为调用 API
• src/utils/modelConfig.js（Video 旧架构遗留）删除，Video descriptor 改为调用同一 API
• src/utils/createTask.js（当前仅透传）删除，dialogBox 直接使用 buildTaskBody() 返回值
• Painting descriptor 的 loadConfig() 改为 fetch API + 本地缓存（30s TTL，与模型列表一致）

阶段三：清理

• 删除 src/utils/modelConfig.js
• 删除 src/utils/createTask.js
• 确认前端不再包含任何硬编码的模型参数

---

五、与 RunningHub API 的关系

后端创建任务的请求体格式应直接对齐 RunningHub 标准模型 API，前端 buildTaskBody() 返回的扁平 modelParams 即是 API body：

{
  "prompt": "...",
  "resolution": "720p",
  "aspectRatio": "16:9",
  "duration": 5
}

不再需要中间层转换（旧架构的 src/config/runninghub/ 已删除）。

---

附录：RunningHub API 参考

以下为 RunningHub 标准模型 API 的原始文档，作为后端任务创建接口的设计参考。

A.1 提交任务

curl --location --request POST 'https://www.runninghub.cn/openapi/v2/rhart-video/ltx-2.3/text-to-video' \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${RUNNINGHUB_API_KEY}" \
--data-raw '{
  "prompt": "...",
  "resolution": "720p",
  "aspectRatio": "16:9",
  "duration": 5
}'

参数	类型	必填/可选	说明
prompt	String	必填	提示词
resolution	String	必填	枚举值: [1080p, 720p, 480p]
aspectRatio	String	必填	枚举值: [16:9, 9:16]
duration	Int	必填	输入范围值: 5 - 15

A.2 查询结果

curl --location --request POST 'https://www.runninghub.cn/openapi/v2/query' \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${RUNNINGHUB_API_KEY}" \
--data-raw '{"taskId": "${RUNNINGHUB_TASKID}"}'

响应字段：

字段	类型	说明
taskId	String	任务 ID
status	String	QUEUED / RUNNING / SUCCESS / FAILED
results	List	生成结果列表
results[].url	String	结果 URL（24 小时有效）
results[].nodeId	String	工作流节点 ID
results[].outputType	String	文件扩展名 (png, mp4, txt)
results[].text	String	纯文本输出内容

A.3 文件上传

上传接口: POST https://www.runninghub.cn/openapi/v2/media/upload/binary

支持 imageUrls（公共 URL）、Base64 Data URI、RH 上传接口三种方式传入图片。