# Changelog: AI 模型能力数据格式统一

**日期**: 2026-02-13  
**类型**: 数据格式优化  
**影响范围**: 后端 - AI 模型配置

---

## 📋 变更概述

将 `ai_models` 表中 `capabilities` JSONB 字段的 `reference_image` 和 `input_reference` 数据格式从简单整数统一为规范对象格式，提升数据可读性和可扩展性。

---

## 🎯 变更目标

### 问题背景
之前数据库中存储的参考图片能力使用简单整数格式：
```json
{
  "reference_image": 1,    // 图片模型
  "input_reference": 5     // 视频模型
}
```

这种格式虽然简洁，但存在以下问题：
- **语义不明确**：仅靠整数无法区分"不支持"（0）和"支持但数量为0"
- **扩展性差**：无法表达更多元数据（如格式要求、尺寸限制等）
- **API 不一致**：`capability_transformer` 需要将整数转换为对象，增加维护成本

### 解决方案
统一使用对象格式：
```json
{
  "reference_image": {
    "supported": true,
    "num": 5
  },
  "input_reference": {
    "supported": false  // 不支持时省略 num
  }
}
```

---

## 🔧 技术实现

### 1. 数据库迁移脚本更新

**文件**: `server/scripts/migrate_model_capabilities.py`

**变更内容**:
- 将所有模型的 `reference_image` 和 `input_reference` 从整数格式改为对象格式
- 支持能力统一表示为 `{"supported": true, "num": <数量>}`
- 不支持能力表示为 `{"supported": false}`

**示例**:
```python
# 修改前
'dall-e-3': {
    'reference_image': 1
}

# 修改后
'dall-e-3': {
    'reference_image': {'supported': True, 'num': 1}
}
```

**涉及模型**:
- **图片模型**: OpenAI (DALL-E), Google Imagen, Qwen, Doubao, Flux, iRAG, Ideogram, Gemini
- **视频模型**: Sora, Veo, Wan, Jimeng

---

### 2. 转换器向后兼容

**文件**: `server/app/utils/capability_transformer.py`

**变更内容**:
更新 `transform_capabilities_to_api` 函数的 `referenceImage` 处理逻辑，同时支持：
1. **对象格式**（推荐）：`{"supported": true, "num": 5}` → 直接使用
2. **整数格式**（向后兼容）：`5` → 自动转换为 `{"supported": true, "num": 5}`

```python
if isinstance(ref_value, dict):
    # 已经是对象格式，直接使用
    result[field] = ref_value
elif isinstance(ref_value, int) and ref_value > 0:
    # 整数格式，转换为对象
    result[field] = {
        "supported": True,
        "num": ref_value
    }
```

**优势**:
- ✅ 保证数据库迁移后系统正常运行
- ✅ 未来可安全移除整数格式支持
- ✅ API 响应格式保持一致

---

## ✅ 验证结果

### 数据库验证
```sql
-- 图片模型
SELECT model_name, capabilities->'reference_image' 
FROM ai_models 
WHERE model_type = 2 LIMIT 3;

-- 结果：
-- dall-e-3              | {"num": 1, "supported": true}
-- gemini-2.5-flash-image | {"num": 1, "supported": true}
-- flux-1-1-ultra         | {"num": 1, "supported": true}

-- 视频模型
SELECT model_name, capabilities->'input_reference' 
FROM ai_models 
WHERE model_type = 3 LIMIT 3;

-- 结果：
-- sora-2                 | {"num": 1, "supported": true}
-- veo-3.1-generate-001   | {"num": 1, "supported": true}
-- wan2.6-t2v             | {"supported": false}
```

### API 响应验证
使用 Python 测试脚本验证：
```python
# 图片模型
模型: dall-e-3
数据库: {'num': 1, 'supported': True}
API:    {'num': 1, 'supported': True}  ✅

# 视频模型
模型: sora-2
数据库: {'num': 1, 'supported': True}
API:    {'num': 1, 'supported': True}  ✅
```

**结论**: 数据库存储格式与 API 响应格式完全一致。

---

## 📊 影响范围

### 数据变更
- **已更新**: 12 个模型（图片 3 个 + 视频 9 个）
- **已跳过**: 10 个模型（无 capabilities 配置）

### 代码变更
| 文件 | 变更类型 | 说明 |
|------|---------|------|
| `migrate_model_capabilities.py` | 修改 | 所有 `reference_image`/`input_reference` 改为对象格式 |
| `capability_transformer.py` | 增强 | 新增对象格式支持，保持整数格式向后兼容 |

### 兼容性
- ✅ **向后兼容**: 转换器同时支持旧格式（整数）和新格式（对象）
- ✅ **API 不变**: 前端接口响应格式保持不变
- ✅ **零影响**: 现有功能无需任何修改

---

## 🚀 后续工作

### 1. 清理旧格式支持（可选）
当确认所有数据已迁移后，可移除 `capability_transformer.py` 中的整数格式兼容代码：
```python
# 移除这段代码
elif isinstance(ref_value, int) and ref_value > 0:
    result[field] = {"supported": True, "num": ref_value}
```

### 2. 扩展对象字段（未来）
对象格式支持扩展更多元数据：
```json
{
  "reference_image": {
    "supported": true,
    "num": 5,
    "max_size_mb": 10,           // 新增：最大文件大小
    "formats": ["jpg", "png"],   // 新增：支持的格式
    "min_resolution": "512x512"  // 新增：最小分辨率
  }
}
```

---

## 📝 总结

✅ **数据格式统一**: 所有模型使用对象格式存储参考图片能力  
✅ **向后兼容**: 转换器同时支持新旧格式  
✅ **零影响部署**: 现有 API 和前端无需修改  
✅ **可扩展性**: 为未来增加更多元数据预留空间

**执行时间**: 2026-02-13 03:25:36  
**迁移结果**: 成功更新 12 个模型