# 火山引擎视频模型配置流程说明

## 📊 数据流程图

```
┌─────────────────────────────────────────────────────────────────┐
│  步骤1：管理员在UI中配置模型                                     │
├─────────────────────────────────────────────────────────────────┤
│  - 选择"火山引擎视频"Provider                                    │
│  - 看到4个模型配置表单（动态从预设加载）                        │
│  - 可以修改：                                                    │
│    ✏️  模型ID（例如：doubao-seedance-1-0-pro-250528）          │
│    ✏️  显示名称（例如：豆包 Seedance Pro 250528）              │
│    ✏️  描述（例如：全功能专业版...）                            │
│  - 点击"保存"                                                    │
└─────────────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────────┐
│  步骤2：API处理并保存到数据库                                   │
├─────────────────────────────────────────────────────────────────┤
│  API: POST /api/admin/volcano-video-models                      │
│                                                                  │
│  1️⃣ 接收管理员输入的模型配置                                   │
│     { modelId, displayName, description }                       │
│                                                                  │
│  2️⃣ 智能匹配预设配置（从 volcano-video-models.ts）            │
│     - 精确匹配：直接使用预设的 capabilities                     │
│     - 模糊匹配：如果模型ID是新版本，匹配相似配置                │
│     - 兜底方案：使用Pro版本的默认配置                           │
│                                                                  │
│  3️⃣ 合并配置并保存到数据库 AiModel 表：                       │
│     INSERT INTO "AiModel" (                                     │
│       providerId,              -- 火山引擎视频Provider ID       │
│       modelId,                 -- ✅ 管理员输入                 │
│       displayName,             -- ✅ 管理员输入                 │
│       description,             -- ✅ 管理员输入                 │
│       capabilities,            -- 🔧 从预设自动填充            │
│       defaultParams,           -- 🔧 从预设自动填充            │
│       supportsVision,          -- 🔧 从预设自动填充            │
│       supportsImageGen,        -- 🔧 从预设自动填充            │
│       isEnabled,               -- ✅ 默认 true                  │
│       sortOrder                -- 🔧 从预设自动填充            │
│     )                                                            │
│                                                                  │
│  ✅ 保存成功！数据库现在包含完整的模型配置                     │
└─────────────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────────┐
│  步骤3：前端功能从数据库读取模型配置                            │
├─────────────────────────────────────────────────────────────────┤
│  场景1：聊天界面 - 选择模型                                     │
│    GET /api/models                                               │
│    → 返回所有启用的模型（包含 capabilities）                   │
│    → 前端显示模型列表供用户选择                                 │
│                                                                  │
│  场景2：视频生成 - 参数验证                                     │
│    用户选择：分辨率 1080p、比例 16:9、时长 8秒                  │
│    ↓                                                             │
│    从数据库读取模型的 capabilities：                            │
│    {                                                             │
│      supportedResolutions: ['480p', '720p', '1080p'],          │
│      supportedRatios: ['16:9', '4:3', '1:1', ...],            │
│      durationRange: { min: 2, max: 12 }                        │
│    }                                                             │
│    ↓                                                             │
│    ✅ 验证通过：1080p ∈ supportedResolutions                   │
│    ✅ 验证通过：16:9 ∈ supportedRatios                         │
│    ✅ 验证通过：8秒 在 [2, 12] 范围内                          │
│    ↓                                                             │
│    调用视频生成API                                               │
│                                                                  │
│  场景3：智能模型选择                                             │
│    用户选择"首尾帧过渡"模式                                     │
│    ↓                                                             │
│    查询数据库：WHERE capabilities->'supportedModes' @> '["first-last-frame"]' │
│    ↓                                                             │
│    返回支持该模式的模型列表：                                   │
│    - doubao-seedance-1-0-pro-250528 ✅                         │
│    - doubao-seedance-1-0-lite-i2v-250428 ✅                    │
│    ↓                                                             │
│    自动选择优先级最高的模型                                     │
└─────────────────────────────────────────────────────────────────┘
```

## 🔄 模型名称更新场景

### 场景：火山引擎发布新版本模型

```
旧模型：doubao-seedance-1-0-pro-250528
新模型：doubao-seedance-1-0-pro-260115  ← 新版本
```

**管理员操作：**
1. 在系统设置中，打开"添加模型"对话框
2. 选择"火山引擎视频"Provider
3. 修改第一个模型的 `模型ID` 为 `doubao-seedance-1-0-pro-260115`
4. 显示名称自动变为：`豆包 Seedance Pro 260115`
5. 点击"保存"

**系统处理：**
```javascript
// API智能匹配逻辑
const preset = VOLCANO_VIDEO_MODEL_PRESETS.find(p => 
  p.modelId === 'doubao-seedance-1-0-pro-260115'
);
// ❌ 找不到精确匹配

// 尝试模糊匹配
const baseModelId = 'doubao-seedance-1-0';  // 提取基础名称
const preset = VOLCANO_VIDEO_MODEL_PRESETS.find(p => 
  p.modelId.startsWith(baseModelId)
);
// ✅ 找到：doubao-seedance-1-0-pro-250528

// 使用旧版本的 capabilities 作为模板
return {
  ...preset,  // 继承 capabilities、defaultParams
  modelId: 'doubao-seedance-1-0-pro-260115',  // 使用新版本ID
  displayName: '豆包 Seedance Pro 260115',    // 管理员输入
  description: '全功能专业版（2025年1月新版）' // 管理员输入
};

// ✅ 保存到数据库，前端功能正常使用
```

## 📝 后续维护步骤

### 当火山引擎更新模型名称时：

#### 方式1：管理员直接在UI中修改（推荐）
1. 打开系统设置 → AI 模型
2. 找到旧模型，点击"编辑"
3. 修改模型ID和显示名称
4. 保存即可

#### 方式2：开发者更新预设配置（适用于批量更新）
1. 修改 `lib/ai/volcano-video-models.ts` 文件
2. 更新 `VOLCANO_VIDEO_MODEL_PRESETS` 数组中的模型配置
3. 部署代码
4. 管理员在UI中删除旧模型，重新添加（会自动使用新预设）

## 🎯 关键优势

✅ **灵活性**：管理员可以随时更新模型名称，无需代码改动  
✅ **智能性**：API能自动匹配相似配置，避免配置丢失  
✅ **一致性**：所有功能都从数据库读取，保证数据统一  
✅ **可维护性**：预设配置集中管理，易于批量更新  

## ⚠️ 注意事项

1. **首次添加模型时**，必须选择火山引擎视频Provider，系统才会显示4个模型配置表单
2. **模型ID必须唯一**，不能重复添加相同的模型
3. **capabilities字段很重要**，决定了视频生成的参数验证逻辑
4. **如果预设配置不匹配**，系统会使用Pro版本的默认配置作为兜底