10 KiB

Raw Blame History

Changelog: API Schema 高级参数补充

日期: 2026-02-13
类型: API 增强
影响范围: 后端 - API Schema

📋 变更概述

为 GenerateImageRequest 和 GenerateVideoRequest Schema 补充高级参数定义，支持模型特定的精细控制。

🎯 变更目标

问题背景

Schema 定义不完整：仅包含基础参数（width, height, duration）
Capabilities 参数无法使用：数据库配置了丰富的能力参数，但前端无法传递
高级用户需求无法满足：专业用户需要更精细的控制（如 seed、watermark、guidance）

解决方案

在 Schema 中补充所有常用的高级参数，使其与数据库 capabilities 配置保持一致。

🔧 技术实现

文件变更

修改文件: server/app/schemas/ai.py

1. 图片生成 Schema 增强

新增参数（14 个）:

参数分类	参数名	类型	适用模型	说明
输出控制	`outputFormat`	`"png"/"jpeg"/"webp"`	OpenAI, Flux, iRAG	输出格式
	`numImages`	`int (1-10)`	大部分模型	生成数量
控制参数	`seed`	`int (0-2147483647)`	Qwen, Doubao, Flux, iRAG	随机种子
	`watermark`	`bool`	Qwen, Doubao, iRAG	是否添加水印
OpenAI 特有	`inputFidelity`	`"high"/"low"`	OpenAI	输入保真度
	`moderation`	`"auto"/"low"`	DALL-E 3	内容审核级别
Flux 特有	`safetyTolerance`	`int (0-6)`	Flux	安全容忍度
	`raw`	`bool`	Flux 2	原始模式
iRAG 特有	`guidance`	`float (0.0-10.0)`	iRAG 1.0	引导强度
Ideogram 特有	`renderingSpeed`	`"QUALITY"/"FAST"`	Ideogram V3	渲染速度
Doubao 特有	`responseFormat`	`"url"/"base64_json"`	Doubao	响应格式
	`sequentialImageGeneration`	`"auto"/"disabled"`	Doubao	连续生成模式
参考图片	`referenceImages`	`List[str]`	大部分模型	参考图片 URL 列表

示例：

class GenerateImageRequest(BaseModel):
    # ... 原有参数 ...
    
    # 新增高级参数
    output_format: Optional[Literal["png", "jpeg", "webp"]] = Field(
        None,
        description="输出格式（OpenAI/Flux/iRAG）",
        alias="outputFormat"
    )
    num_images: Optional[int] = Field(
        None,
        description="生成数量（1-10，多数模型支持）",
        alias="numImages",
        ge=1,
        le=10
    )
    seed: Optional[int] = Field(
        None,
        description="随机种子（Qwen/Doubao/Flux/iRAG）",
        ge=0,
        le=2147483647
    )
    # ... 更多参数 ...

2. 视频生成 Schema 增强

新增参数（2 个）:

参数名	类型	适用模型	说明
`width`	`int`	所有模型	宽度（像素），高级模式使用
`height`	`int`	所有模型	高度（像素），高级模式使用
`videoMode`	`"t2v"/"i2v"`	Wan	视频模式（文生视频/图生视频）

变更前：

class GenerateVideoRequest(BaseModel):
    # 缺少 width/height 参数
    duration: int = Field(5, description="时长（秒）")
    fps: int = Field(30, description="帧率")

变更后：

class GenerateVideoRequest(BaseModel):
    width: Optional[int] = Field(None, description="宽度（像素）")
    height: Optional[int] = Field(None, description="高度（像素）")
    duration: int = Field(5, description="时长（秒）")
    fps: int = Field(30, description="帧率")
    
    video_mode: Optional[Literal["t2v", "i2v"]] = Field(
        None,
        description="视频模式（Wan，t2v=文生视频, i2v=图生视频）",
        alias="videoMode"
    )

📊 参数覆盖率

变更前后对比

参数类别	变更前	变更后	增加
图片 - 简单模式	3	3	-
图片 - 高级参数	3	17	+14 ✅
视频 - 简单模式	2	2	-
视频 - 高级参数	2	5	+3 ✅
总计	10	27	+17

Capabilities 参数映射

Capabilities 字段	Schema 参数	状态
`size`	`width`, `height`	✅ 已支持
`quality`	`quality`	✅ 已支持
`output_format`	`outputFormat`	✅ 新增
`n`	`numImages`	✅ 新增
`seed`	`seed`	✅ 新增
`watermark`	`watermark`	✅ 新增
`input_fidelity`	`inputFidelity`	✅ 新增
`moderation`	`moderation`	✅ 新增
`safety_tolerance`	`safetyTolerance`	✅ 新增
`raw`	`raw`	✅ 新增
`guidance`	`guidance`	✅ 新增
`rendering_speed`	`renderingSpeed`	✅ 新增
`response_format`	`responseFormat`	✅ 新增
`sequential_image_generation`	`sequentialImageGeneration`	✅ 新增
`reference_image`	`referenceImages`	✅ 新增
`input_reference`	`imageUrl` (视频)	✅ 已支持
`seconds`	`duration`	✅ 已支持
`video_mode`	`videoMode`	✅ 新增

覆盖率: 17/17 = 100% ✅

🔄 参数流转

简单模式（不受影响）

# 前端请求
{
  "model": "dall-e-3",
  "prompt": "一只猫",
  "resolution": "1024",
  "aspectRatio": "1:1"
}

# ↓ 适配器转换
{
  "width": 1024,
  "height": 1024
}

# ↓ Provider 调用 AIHubMix

结论：简单模式流程保持不变。

高级模式（功能增强）

变更前：

# 前端请求（功能受限）
{
  "model": "dall-e-3",
  "prompt": "一只猫",
  "width": 1024,
  "height": 1024
  # ❌ 无法传递 seed, watermark 等参数
}

变更后：

# 前端请求（完整控制）
{
  "model": "dall-e-3",
  "prompt": "一只猫",
  "width": 1024,
  "height": 1024,
  "outputFormat": "png",        # ✅ 新增
  "seed": 42,                    # ✅ 新增
  "inputFidelity": "high",       # ✅ 新增
  "moderation": "low",           # ✅ 新增
  "numImages": 2                 # ✅ 新增
}

# ↓ 直接传递（高级模式）
# ↓ Provider 调用 AIHubMix

结论：高级模式支持完整的模型能力。

✅ 验证

语法检查

$ python -m py_compile app/schemas/ai.py
# 退出码: 0 ✅

类型检查（可选）

$ mypy app/schemas/ai.py
# Success: no issues found

📝 使用示例

示例 1: DALL-E 3 高质量生成

# POST /api/v1/ai/generate/image
{
  "model": "dall-e-3",
  "prompt": "A cat playing piano in cyberpunk style",
  "width": 1792,
  "height": 1024,
  "quality": "high",
  "outputFormat": "png",
  "inputFidelity": "high",
  "moderation": "low"
}

示例 2: Flux 2 Flex 多参考图融合

{
  "model": "flux-2-flex",
  "prompt": "Combine these images into a cohesive scene",
  "resolution": "2048",
  "aspectRatio": "16:9",
  "referenceImages": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg",
    "https://example.com/image3.jpg"
  ],
  "safetyTolerance": 4,
  "raw": true
}

示例 3: Doubao SeedReam 连续生成

{
  "model": "doubao-seedream-4-5",
  "prompt": "A beautiful landscape",
  "resolution": "4096",
  "aspectRatio": "16:9",
  "seed": 12345,
  "watermark": false,
  "sequentialImageGeneration": "auto",
  "numImages": 5
}

示例 4: Wan 2.6 图生视频

# POST /api/v1/ai/generate/video
{
  "model": "wan2.6-i2v",
  "videoType": "img2video",
  "imageUrl": "https://example.com/cat.jpg",
  "prompt": "Make the cat run",
  "width": 1280,
  "height": 720,
  "duration": 10,
  "videoMode": "i2v"
}

🚨 注意事项

1. 参数验证

当前状态：Schema 定义了参数，但未验证是否符合模型 capabilities。

建议：

# 在 AIService 中添加验证
if 'numImages' in kwargs:
    n_config = model.capabilities.get('n', {})
    max_n = n_config.get('max', 10)
    if kwargs['numImages'] > max_n:
        raise ValueError(f"numImages 超出限制: {max_n}")

2. 参数传递

确保链路完整：

✅ API 路由接收参数
✅ Schema 验证参数类型
❓ AIService 是否正确传递到 Provider？（需验证）
❓ Provider 是否正确使用参数？（需验证）

3. 向后兼容

保证：

✅ 所有新参数都是 Optional
✅ 不影响现有简单模式流程
✅ 不影响现有高级模式流程

📊 影响范围

代码变更

文件	变更类型	行数	说明
`app/schemas/ai.py`	修改	+62	GenerateImageRequest 新增 14 个参数
		+3	GenerateVideoRequest 新增 3 个参数
总计		+65

兼容性

✅ 向后兼容: 所有新参数均为可选
✅ API 不变: 现有请求格式保持不变
✅ 零影响: 前端无需修改即可继续使用

🚀 后续工作

优先级 1: 参数传递链路验证（高）

目标：确保新参数能正确传递到 AIHubMix API

检查点：

✅ Schema 定义 → 已完成
⚠️ API Router → 需检查 **kwargs 传递
⚠️ AIService → 需检查参数接收和传递
⚠️ AIHubMixProvider → 需检查参数使用

验证方法：

# 在 AIService 中添加日志
logger.debug("收到的 kwargs: %s", kwargs)

# 在 Provider 中添加日志
logger.debug("传递给 AIHubMix 的参数: %s", params)

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

目标：根据 capabilities 验证参数合法性

实施：参考 docs/server/guides/api-params-capabilities-mapping.md 方案 2

优先级 3: 前端集成（低）

目标：前端 UI 支持高级参数输入

实施：

在"高级设置"面板中添加参数输入框
根据选中模型的 capabilities 动态显示可用参数
提供参数说明和默认值提示

📚 相关文档

维护人: Claude
执行时间: 2026-02-13
审核状态: ✅ 已完成

10 KiB Raw Blame History