8.9 KiB

Raw Blame History

API 参数与 Capabilities 映射关系

版本: v1.0
日期: 2026-02-13
目的: 明确前端 API 参数与数据库 capabilities 配置的对应关系

📋 参数分类

1. 简单模式参数（Unified Parameters）

这些参数由前端传递，经过适配器转换为模型特定参数：

前端参数	类型	值域	转换目标	说明
`resolution` (图片)	string	"512", "1024", "2048", "4096"	`width`, `height`, `size`	短边像素值
`resolution` (视频)	string	"480p", "720p", "1080p", "2k", "4k"	`width`, `height`, `size`	分辨率档位
`aspectRatio`	string	"1:1", "4:3", "16:9", "9:16"	`width`, `height`, `aspect_ratio`	宽高比
`quality`	string	"low", "medium", "high"	`quality`, `rendering_speed`	质量档位

检测条件：

图片生成：resolution AND aspectRatio 存在
视频生成：resolution AND aspectRatio 存在

2. 高级模式参数（Model-Specific Parameters）

这些参数直接传递给模型，不经过适配器：

图片模型参数

API 参数	capabilities 字段	类型	说明	示例值
`width`	`size`	integer	宽度（像素）	1024
`height`	`size`	integer	高度（像素）	1024
`style`	-	string	风格（前端自定义）	"realistic"
`outputFormat`	`output_format`	string	输出格式	"png", "jpeg", "webp"
`inputFidelity`	`input_fidelity`	string	输入保真度（OpenAI）	"high", "low"
`moderation`	`moderation`	string	内容审核（OpenAI）	"auto", "low"
`watermark`	`watermark`	boolean	水印（Qwen/Doubao）	true, false
`seed`	`seed`	integer	随机种子	0-2147483647
`numImages`	`n`	integer	生成数量	1-10
`safetyTolerance`	`safety_tolerance`	integer	安全容忍度（Flux）	0-6
`raw`	`raw`	boolean	原始模式（Flux）	true, false
`guidance`	`guidance`	float	引导强度（iRAG）	0.0-10.0
`renderingSpeed`	`rendering_speed`	string	渲染速度（Ideogram）	"QUALITY", "FAST"
`sequentialImageGeneration`	`sequential_image_generation`	string	连续生成（Doubao）	"auto", "disabled"

视频模型参数

API 参数	capabilities 字段	类型	说明	示例值
`width`	`size`	integer	宽度（像素）	1280
`height`	`size`	integer	高度（像素）	720
`duration`	`seconds`	integer	时长（秒）	5, 10
`fps`	-	integer	帧率	30
`videoMode`	`video_mode`	string	视频模式（Wan）	"t2v", "i2v"

3. 通用参数（Common Parameters）

这些参数在所有模式下都存在：

API 参数	说明	是否必传
`model`	模型名称	✅ 是
`prompt`	提示词	图片必传，视频可选
`imageUrl`	参考图片 URL	❌ 否（图生图/图生视频）
`projectId`	项目 ID	❌ 否
`storyboardId`	分镜 ID	❌ 否

🔄 参数流转关系

流程图

graph LR
    A[前端传参] --> B{检测参数类型}
    
    B -->|有 resolution<br/>+ aspectRatio| C[简单模式]
    B -->|仅 width/height<br/>等模型参数| D[高级模式]
    
    C --> E[适配器转换]
    E --> F{模型类型}
    
    F -->|Sora| G[SoraAdapter]
    F -->|Veo| H[VeoAdapter]
    F -->|Flux| I[FluxAdapter]
    F -->|其他| J[对应适配器]
    
    G --> K[转换为模型参数]
    H --> K
    I --> K
    J --> K
    
    D --> L[直接传递]
    K --> M[AIHubMixProvider]
    L --> M
    
    M --> N[读取 capabilities]
    N --> O[capability_transformer]
    O --> P[调用 AIHubMix API]

⚠️ 当前问题

问题 1: 参数检测不完整

现状：

# ai_service.py (第 177 行)
if resolution and aspect_ratio:
    # 简单模式

问题：

仅检测 resolution 和 aspect_ratio
忽略了 quality 参数
无法处理"仅传 resolution"或"仅传 aspectRatio"的情况

建议修正：

# 方案 1: 严格检测（推荐）
if resolution and aspect_ratio:
    # 简单模式（resolution + aspectRatio 必须同时存在）
    
# 方案 2: 宽松检测
if resolution or aspect_ratio or quality:
    # 只要有任一简单模式参数即认为是简单模式
    # 缺失的参数使用默认值

问题 2: 高级参数未传递

现状：

Schema 定义了很多高级参数（watermark, seed, output_format 等）
但这些参数可能没有正确传递到 AIService 或 Provider

检查点：

✅ Schema 是否定义了参数？
❓ API 路由是否正确接收并传递？
❓ AIService 是否在 **kwargs 中接收？
❓ AIHubMixProvider 是否正确使用？

问题 3: Capabilities 参数未验证

现状：

数据库 capabilities 定义了参数的合法值（如 quality: ['low', 'medium', 'high']）
但 API 层可能没有验证用户输入是否符合 capabilities 约束

建议：

# 在 AIService 中验证参数
def validate_params_against_capabilities(model_name: str, params: dict):
    """根据 capabilities 验证参数合法性"""
    model = await get_model(model_name)
    capabilities = model.capabilities
    
    # 验证 quality
    if 'quality' in params:
        allowed = capabilities.get('quality', {}).get('values', [])
        if params['quality'] not in allowed:
            raise ValueError(f"Invalid quality: {params['quality']}, allowed: {allowed}")
    
    # 验证 size
    # 验证 n
    # ...

📝 建议改进方案

方案 1: 完善参数检测（优先级：高）

目标：正确区分简单模式和高级模式

实施：

更新 ai_service.py 中的检测逻辑
明确简单模式触发条件
添加参数日志输出

# 简单模式检测（推荐）
is_simple_mode = bool(kwargs.get('resolution') and kwargs.get('aspect_ratio'))

if is_simple_mode:
    logger.info("🎯 检测到简单模式：resolution=%s, aspectRatio=%s, quality=%s",
                kwargs.get('resolution'),
                kwargs.get('aspect_ratio'),
                kwargs.get('quality', 'default'))
    # 使用适配器
else:
    logger.info("🔧 使用高级模式：width=%s, height=%s, 其他参数=%s",
                kwargs.get('width'),
                kwargs.get('height'),
                {k: v for k, v in kwargs.items() if k not in ['width', 'height']})
    # 直接传递

方案 2: 参数验证层（优先级：中）

目标：确保用户输入符合 capabilities 约束

实施：

创建 param_validator.py
在 API 层或 Service 层调用验证
返回友好的错误提示

class ParamValidator:
    @staticmethod
    async def validate_image_params(model_name: str, params: dict):
        """验证图片生成参数"""
        model = await get_model_by_name(model_name)
        if not model or not model.capabilities:
            raise ValueError(f"Model {model_name} capabilities not found")
        
        caps = model.capabilities
        
        # 验证 quality
        if 'quality' in params:
            allowed = caps.get('quality', {}).get('values', [])
            if params['quality'] not in allowed:
                raise ValueError(
                    f"Invalid quality '{params['quality']}' for {model_name}. "
                    f"Allowed values: {', '.join(allowed)}"
                )
        
        # 验证 size
        # 验证 n
        # ...
        
        return True

方案 3: 完善 Schema 定义（优先级：低）

目标：在 Schema 层添加更多高级参数

示例：

class GenerateImageRequest(BaseModel):
    # ... 现有参数 ...
    
    # 新增高级参数
    output_format: Optional[Literal["png", "jpeg", "webp"]] = Field(
        None,
        description="输出格式（高级模式）",
        alias="outputFormat"
    )
    seed: Optional[int] = Field(
        None,
        description="随机种子（高级模式）",
        ge=0,
        le=2147483647
    )
    watermark: Optional[bool] = Field(
        None,
        description="是否添加水印（Qwen/Doubao）"
    )
    # ...

✅ 总结

参数类别	数量	检测状态	建议
简单模式参数	3	⚠️ 部分检测（仅 2 个）	完善检测逻辑
高级图片参数	12+	❓ 未知	检查传递链路
高级视频参数	6+	❓ 未知	检查传递链路
通用参数	5	✅ 已实现	-

下一步行动：

✅ 明确简单模式参数检测条件（resolution AND aspectRatio）
⚠️ 验证高级参数是否正确传递
⚠️ 实现参数验证层（可选）
⚠️ 补充 Schema 定义（可选）

维护人: Claude
最后更新: 2026-02-13

8.9 KiB Raw Blame History