5.2 KiB

Raw Permalink Blame History

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

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

📋 变更概述

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

🎯 变更目标

问题背景

之前数据库中存储的参考图片能力使用简单整数格式：

{
  "reference_image": 1,    // 图片模型
  "input_reference": 5     // 视频模型
}

这种格式虽然简洁，但存在以下问题：

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

解决方案

统一使用对象格式：

{
  "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}

示例:

# 修改前
'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 处理逻辑，同时支持：

对象格式（推荐）：{"supported": true, "num": 5} → 直接使用
整数格式（向后兼容）：5 → 自动转换为 {"supported": true, "num": 5}

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 响应格式保持一致

✅ 验证结果

数据库验证

-- 图片模型
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 测试脚本验证：

# 图片模型
模型: 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 中的整数格式兼容代码：

# 移除这段代码
elif isinstance(ref_value, int) and ref_value > 0:
    result[field] = {"supported": True, "num": ref_value}

2. 扩展对象字段（未来）

对象格式支持扩展更多元数据：

{
  "reference_image": {
    "supported": true,
    "num": 5,
    "max_size_mb": 10,           // 新增：最大文件大小
    "formats": ["jpg", "png"],   // 新增：支持的格式
    "min_resolution": "512x512"  // 新增：最小分辨率
  }
}

📝 总结

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

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

5.2 KiB Raw Permalink Blame History