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

**日期**：2026-02-13  
**类型**：功能增强  
**影响范围**：后端 AI 服务  
**RFC**：[RFC 144: ai_models 模型参数能力配置规划](../rfcs/144-ai-models-capability-config.md)

## 概述

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

## 核心变更

### 1. 数据库变更

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

```sql
-- 添加 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 模型定义
```python
# 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）

#### 转换逻辑
```python
# 自动检测格式类型并转换（配置驱动）
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
```python
# server/app/schemas/ai.py
capabilities: Dict[str, Any] = Field(
    default_factory=dict, 
    description="模型参数能力配置（RFC 144）"
)
```

#### AIService 改造
```python
# 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` 读取配置的辅助方法

**核心改进**：
```python
# 旧代码（硬编码）
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
```json
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. 执行数据库迁移
```bash
# 进入容器
docker exec -it jointo-server-app bash

# 执行 Alembic 迁移
alembic upgrade head

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

### 2. 重启服务
```bash
docker-compose restart jointo-server-app
```

### 3. 验证
```bash
# 测试模型列表 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 版本对比）

## 参考文档

- [RFC 144: ai_models 模型参数能力配置规划](../rfcs/144-ai-models-capability-config.md)
- [AIHubMix 图片生成 API 文档](https://docs.aihubmix.com/en/api/Image-Gen)
- [AIHubMix 视频生成 API 文档](https://docs.aihubmix.com/cn/api/Video-Gen)

## 作者

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