7.8 KiB

Raw Blame History

RFC 144 实施：AI 模型能力配置系统

日期：2026-02-13
类型：功能增强
影响范围：后端 AI 服务
RFC：RFC 144: ai_models 模型参数能力配置规划

概述

实现了 AI 模型能力配置系统（RFC 144），通过数据库 JSONB 列存储模型参数能力，完全移除 AIHubMixProvider 中的硬编码逻辑，改为配置驱动的动态系统。

核心变更

1. 数据库变更

新增字段

表：ai_models
字段：capabilities (JSONB)
用途：存储模型参数能力配置（尺寸、质量、时长等可选值与约束）

-- 添加 capabilities 列
ALTER TABLE ai_models ADD COLUMN capabilities JSONB NOT NULL DEFAULT '{}';

-- 创建 GIN 索引
CREATE INDEX idx_ai_models_capabilities_gin ON ai_models USING gin (capabilities);

数据迁移

脚本：server/scripts/migrate_model_capabilities.py
运行方式：docker exec jointo-server-app python scripts/migrate_model_capabilities.py
覆盖模型：18 个图片/视频模型（DALL-E, Flux, Qwen, Doubao, Imagen, Sora, Veo, Wan 系列）

2. 模型层变更

AIModel 模型定义

# server/app/models/ai_model.py
capabilities: dict = Field(
    default_factory=dict,
    sa_column=Column(
        JSONB,
        nullable=False,
        server_default='{}',
        comment='模型参数能力配置（尺寸、质量、时长等可选值与约束）'
    )
)

3. API 层变更

新增工具类

文件：server/app/utils/capability_transformer.py
功能：
- 定义全量能力字段枚举（图片 14 个、视频 3 个字段）
- 实现 DB capabilities (snake_case) → API (camelCase) 转换
- 补全不支持的字段为 { "supported": false }
- 提供配置驱动的 size 格式转换器（无 if/elif）

转换逻辑

# 自动检测格式类型并转换（配置驱动）
convert_size_for_provider(width, height, size_capability)

# 支持 4 种格式：
# - 档位格式：720P, 1080P (Veo)
# - K 格式：1K, 2K, 4K (Flux, Imagen)
# - 星号格式：512*1024 (Qwen)
# - 标准格式：1024x1024 (OpenAI, Sora, Wan)

AIModelResponse Schema

# server/app/schemas/ai.py
capabilities: Dict[str, Any] = Field(
    default_factory=dict, 
    description="模型参数能力配置（RFC 144）"
)

AIService 改造

# server/app/services/ai_service.py
async def get_available_models(self, model_type: Optional[int] = None):
    models = await self.model_repository.get_visible_models(model_type)
    return [
        {
            ...
            'capabilities': transform_capabilities_to_api(m.capabilities, m.model_type)
        }
        for m in models
    ]

4. Provider 层变更

AIHubMixProvider 改造

移除：所有基于 model_name 的硬编码 if/elif 判断（~40 行代码）
新增：从 capabilities 读取配置的辅助方法

核心改进：

# 旧代码（硬编码）
if 'sora' in self.model_name.lower():
    if duration <= 4:
        seconds = '4'
    elif duration <= 8:
        seconds = '8'
    else:
        seconds = '12'
elif 'veo' in self.model_name.lower():
    ...

# 新代码（配置驱动）
def _get_video_duration(self, duration: int) -> str:
    seconds_cap = self.capabilities.get('seconds', {})
    values = seconds_cap.get('values', [])
    
    int_values = [int(v) for v in values]
    for v in int_values:
        if v >= duration:
            return str(v)
    return str(int_values[-1])

5. 测试覆盖

单元测试

文件：server/tests/unit/test_capability_transformer.py
覆盖：
- camelCase ↔ snake_case 转换
- DB capabilities → API 转换（图片/视频）
- 参数值校验（枚举/整数范围/布尔/参考图数量）
- Size 格式转换器（4 种格式）
- 端到端转换测试

API 响应格式

模型列表 API

GET /api/v1/ai/models?modelType=2

{
  "code": 200,
  "data": [
    {
      "modelId": "xxx",
      "modelName": "flux-2-pro",
      "modelType": 2,
      "capabilities": {
        "size": {
          "supported": true,
          "values": ["1K", "2K", "4K", "auto"],
          "default": "auto"
        },
        "quality": { "supported": false },
        "aspectRatio": {
          "supported": true,
          "values": ["16:9", "1:1", "4:3"],
          "default": "16:9"
        },
        "referenceImage": {
          "supported": true,
          "num": 1
        },
        "watermark": { "supported": false },
        "seed": { "supported": true }
      }
    }
  ]
}

向后兼容性

降级逻辑

触发条件：模型 capabilities 为空 {}
降级行为：
- API 返回全量字段，均为 { "supported": false }
- Provider 回退到原有硬编码逻辑（保留 DALL-E 特殊处理）

现有功能不受影响

旧的 AI 生成接口保持不变
不依赖 capabilities 的功能正常运行

技术债务清理

已移除

❌ AIHubMixProvider.generate_image() 中的 DALL-E 尺寸判断（8 行）
❌ AIHubMixProvider.generate_video() 中的时长判断（32 行）
❌ AIHubMixProvider.generate_video() 中的分辨率判断（12 行）

新增优势

✅ 新增模型仅需配置，无需修改代码
✅ 配置驱动的 size 转换器（支持 4 种格式，可扩展）
✅ 参数校验逻辑统一化
✅ 前端可动态获取模型能力

部署步骤

1. 执行数据库迁移

# 进入容器
docker exec -it jointo-server-app bash

# 执行 Alembic 迁移
alembic upgrade head

# 执行数据迁移（写入 capabilities）
python scripts/migrate_model_capabilities.py

2. 重启服务

docker-compose restart jointo-server-app

3. 验证

# 测试模型列表 API
curl http://localhost:6170/api/v1/ai/models?modelType=2

# 运行单元测试
docker exec jointo-server-app pytest tests/unit/test_capability_transformer.py -v

涉及文件

创建（5 个）

server/alembic/versions/20260213_1000_add_capabilities_to_ai_models.py - Alembic 迁移
server/scripts/migrate_model_capabilities.py - 数据迁移脚本
server/app/utils/capability_transformer.py - 能力转换工具
server/tests/unit/test_capability_transformer.py - 单元测试
docs/server/changelogs/2026-02-13-rfc-144-capabilities-implementation.md - 本文档

修改（5 个）

server/app/models/ai_model.py - 添加 capabilities 字段
server/app/schemas/ai.py - 更新 AIModelResponse Schema
server/app/services/ai_service.py - 返回 capabilities
server/app/services/ai_providers/aihubmix_provider.py - 移除硬编码逻辑
server/app/services/ai_providers/factory.py - 传递 capabilities 参数
server/app/tasks/ai_tasks.py - 查询并传递 capabilities

后续优化

短期（1-2 周）

前端实现动态参数表单（基于 capabilities）
添加 constraints 支持（参数依赖关系，如 duration ← size）
补充集成测试（AIService + AIHubMixProvider）

中期（1 个月）

支持更多模型类型（音频模型 capabilities）
实现参数校验中间件（API 层自动校验）
添加 capabilities 版本管理

长期（2-3 个月）

构建 Admin 后台 capabilities 配置界面
支持运行时热更新 capabilities（无需重启服务）
实现 A/B 测试支持（不同 capabilities 版本对比）

参考文档

作者

实施者：Claude (Cursor AI Agent)
审核者：待审核
提交时间：2026-02-13

7.8 KiB Raw Blame History