项目生成配置与模型快照
本文属于“当前架构”文档,描述 P2 / C3 已落地的项目生成配置。 风格锁定见 项目风格快照与锁定。
两层配置
全局层(ModelSettings / Provider / Model)
供应商凭据、Base URL、模型目录、全局默认模型
↓ 仅作为兜底
项目层(projects.default_*_model_id + 生成参数)
本项目确认使用的图片 / 视频 / 音频模型与输出规格解析顺序:
- 项目显式配置的模型 ID;
- 项目未配置时,回退
ModelSettings.default_{image,video,audio}_model_id; - 两边都为空 → 配置检查失败,生成准备度返回未就绪。
项目显式配置指向不存在的模型或类别不匹配时不回退,直接返回 503。 这样不会出现「预览一个模型、实际跑另一个」的静默切换。
项目字段
| 字段 | 说明 |
|---|---|
default_image_model_id | 项目图片模型;为空回退全局 |
default_video_model_id | 项目视频模型;为空回退全局 |
default_audio_model_id | 项目音频模型;为空回退全局 |
default_image_ratio | 项目默认图片比例;为空回退视频比例 |
image_ratio_defaults | 按用途的图片比例:character_card 默认 16:9、prop 默认 1:1;scene / costume 为空跟随默认图片比例 |
default_reference_mode | 默认参考模式;P2 固定 reference |
shot_duration_preference_enabled | 是否启用人工时长偏好;默认 false = AI 逐镜智能规划 |
default_shot_duration | 镜头时长参考值(秒);仅在偏好开启或 AI 缺失时长时兜底 |
video_duration_min / video_duration_max | 项目业务时长范围;默认 4–15 |
video_concurrency | 批量并发数;默认 4 |
use_dialog_audio_as_reference | 音频参考开关;新项目默认关闭 |
generation_config_version | 配置版本;再次确认时递增 |
generation_config_confirmed_at | 确认时间;为空表示未确认 |
generation_config_updated_at | 最近保存时间 |
generation_config_snapshot | 确认时的只读快照(JSON) |
快照只保存模型 ID、名称、供应商 ID / 名称、能力参数与输出策略, 不保存 API Key、Base URL 或任何凭据。
生成任务同样不在 GenerationTask.payload 中保存 API Key:
任务只记录 provider_id,worker 执行时按该 ID 从服务端解析凭据。
历史任务里已有的 api_key 字段仍可被旧任务读取,但新任务不再写入。
业务时长与供应商能力
- 供应商能力:优云智算 H3 API 为 4–30 秒、480P/768P/1080P/2K/4K;适配器已对齐;
- 内部业务约束:P2 固定 4–15 秒;
- 保存时校验
4 <= min <= max <= 15;启用时长偏好时再校验min <= default <= max; - 配置面板显示两者交集,例如 H3 下为 4–15 秒;
- P6 的生成准备度与提交逻辑继续执行同一交集,不在页面里散落硬编码。
镜头时长:智能规划与人工偏好
三个概念必须分开:
| 概念 | 来源 | 是否等于视频请求参数 |
|---|---|---|
| 规划时长 | AI 根据对白、动作、运镜和节奏为每个镜头给出的 duration_seconds | 确认后写入 ShotDetail.duration |
| 请求时长 | 发送给视频模型的实际 seconds;当前取 ShotDetail.duration | 是 |
| 实际时长 | 模型产出视频的媒体探针结果 | 由媒体文件决定,不能反推请求值 |
规则:
- 默认
shot_duration_preference_enabled=false,AI 逐镜规划,不把项目值强写成统一时长; - 开启后,
default_shot_duration只作为规划参考值和 AI 缺失时长时的兜底; - AI 已返回时长时永远优先使用 AI 值;
- 历史项目新增列默认
false,不修改任何已有default_shot_duration值; - 镜头可执行性检查会提示「对白超出目标时长、对白密度过高、动作拍点过多、短镜头塞入多叙事事件」,默认是 warning,不擅自拦截历史镜头;
- 准备度、生成预览与镜头详情保存(
PATCH /studio/shot-details/{id})统一用「项目业务范围 ∩ 供应商能力」校验请求时长;超出则阻塞生成,新增/修改越界值返回 400。 - 历史越界值在未修改时允许保留:保存其他字段不会失败,也不会被静默改写;修改为该值之外仍按统一范围校验。
- 分镜规划确认阶段同样按交集校验,避免先写入一个到生成时才失败的时长。
PlannedShot.duration_seconds 允许为空;Schema 不再用默认 5 秒伪装成 AI 已做判断。
API
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /api/v1/studio/projects/{id}/generation-options | 模型清单、能力、全局默认与业务约束 |
GET | /api/v1/studio/projects/{id}/generation-config | 当前生效值、检查项与快照 |
PUT | /api/v1/studio/projects/{id}/generation-config | 保存草稿或保存并确认 |
PUT 的 confirm=false 只保存草稿;confirm=true 会在服务端重新跑完整检查,
失败返回 400 且不写入任何字段。草稿可以保留不完整配置,确认前必须修复所有阻塞项;
前端只提前拦截已声明的本地字段错误,最终仍以服务端检查为准。
配置检查中的 style_locked 只影响 initialized,不阻塞配置本身的确认:
用户可以先确认模型与参数,再到「风格圣经」完成锁定。配置页把失败项分为「阻塞确认」与
「初始化前置条件」,并逐项展示失败原因、可选值与跳转入口;模型检查会标明来源是项目显式配置、
全局默认还是未配置,避免用户误改范围。
资产图比例
资产图不再统一使用 default_image_ratio,而是按用途解析:
请求显式比例
→ 首帧:镜头有效视频比例(请求 → 镜头 override → 项目默认)
→ 项目 image_ratio_defaults[用途]
→ project.default_image_ratio
→ project.default_video_ratio
→ 模型能力默认值character_card默认16:9,角色补充视角也跟随该比例,避免同角色画幅跳变;prop默认1:1;scene/costume未配置时跟随项目默认图片比例;- 首帧不单独配置:它始终跟随镜头有效视频比例;视频比例未配置时才回退
9:16并提示; - 比例必须受当前图片模型能力约束,不支持时配置检查或创建任务返回可执行错误。
配置检查新增 image_ratio_defaults_ready:只要角色卡/道具/场景/服装任一比例不在当前图片模型能力内,就阻塞配置确认;草稿仍可保存,便于先切换模型再确认。
生成链路接入
- 视频:
build_run_args通过镜头反查项目,优先取项目视频模型; - 图片:显式
model_id→ 项目模型 → 全局默认;角色图与分镜帧可从关联实体唯一反查项目, 全局资产(演员/场景/道具/服装)可能跨项目复用,继续回退全局默认; - 音频:显式
model_id→ 项目模型 → 全局默认;可从project_id/ 镜头反查项目; - 视频准备度与项目开工预检同样优先读项目配置。
默认值修正
use_dialog_audio_as_reference 的 ORM、Pydantic 与数据库新行默认值统一为 False。
迁移只执行 ALTER COLUMN ... SET DEFAULT 0,不回填存量项目,已有项目保持自己的设置。
当前边界
- 项目配置面板不负责编辑全局供应商与 API Key;这些仍在模型管理页;
- 不自动创建未经核实的供应商/模型;
- 并发数只是项目配置,P2 不实现真实批量队列(P6);
- 配置面板的检查项与
shot.status、任务状态、视频准备度是四套独立语义。