nex_animation/backend/app/services/preflight.py

332 lines
20 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

"""检查素材与参数(业务流程「检查素材与参数」节点)。
逐镜头给出可执行性清单:关键帧/尾帧、提示词、时长与模型上限、人物定妆图、
场景图、配音可用性、参考图数量上限、模型能力与限流配置等,并区分 error / warning。
"""
from __future__ import annotations
from dataclasses import asdict, dataclass, field
from sqlalchemy.orm import Session
from app.config import settings
from app.constants import ASPECT_RATIOS, RESOLUTIONS, AssetKind, ShotStatus
from app.models import Character, Project, Shot, VoiceAsset
from app.providers import registry as model_registry
from app.services import audio
from app.services import prompt as prompt_service
from app.services import storage
@dataclass
class Issue:
code: str
field: str
message: str
severity: str = "error" # error / warning
@dataclass
class ShotReadiness:
shot_id: int
order_index: int
title: str
status: str
ok: bool = True
issues: list[Issue] = field(default_factory=list)
def add(self, issue: Issue) -> None:
self.issues.append(issue)
if issue.severity == "error":
self.ok = False
def as_dict(self) -> dict:
d = asdict(self)
d["issues"] = [asdict(i) for i in self.issues]
return d
def _availability_reason(adapter, config: dict) -> str:
"""不可用时向适配器要一句能照着修的话:没配地址 / 配了但连不上,修法完全不同。"""
if adapter is None:
return "没有注册这个适配器,请在模型管理里换用可用适配器"
probe = getattr(adapter, "availability_reason", None)
if callable(probe):
try:
return str(probe(config) or "")
except Exception: # noqa: BLE001 - 诊断信息不能把预检打挂
return ""
return ""
def _resolve_voice(db: Session, project: Project, shot: Shot) -> VoiceAsset | None:
if shot.voice_asset_id:
voice = db.get(VoiceAsset, shot.voice_asset_id)
if voice:
return voice
if shot.speaker_character_id:
char = db.get(Character, shot.speaker_character_id)
if char and char.default_voice_id:
return db.get(VoiceAsset, char.default_voice_id)
for char in shot.characters or []:
if char.default_voice_id:
return db.get(VoiceAsset, char.default_voice_id)
default = db.query(VoiceAsset).filter(VoiceAsset.project_id == project.id,
VoiceAsset.is_default.is_(True)).first()
return default or db.query(VoiceAsset).filter(VoiceAsset.project_id == project.id).first()
def check_shot(db: Session, project: Project, shot: Shot, *, strict: bool = True) -> ShotReadiness:
res = ShotReadiness(shot_id=shot.id, order_index=shot.order_index,
title=shot.title or f"镜头 {shot.order_index}", status=shot.status)
spec, adapter = model_registry.resolve_video(db, shot.provider or project.default_provider, shot.model or None)
caps = model_registry.capabilities_of(spec)
# 预检必须看「真正交给适配器的配置」:api_key 存在加密字段里,
# 直接读 spec.config_json 会把已配好密钥的模型判成「未配置」(SB-1)。
try:
spec_cfg = model_registry.runtime_config(db, spec)
except Exception: # noqa: BLE001 - 预检不能被配置读取打挂
spec_cfg = getattr(spec, "config_json", None) or {}
# 1. 脚本与提示词
if not (shot.description or "").strip():
res.add(Issue("missing_description", "description", "缺少镜头描述(画面内容)"))
elif len((shot.description or "").strip()) < 8:
res.add(Issue("short_description", "description", "镜头描述过短,模型容易漂移,建议补充主体/动作/情绪", "warning"))
# 2. 时长与模型能力
dur = float(shot.duration or 0)
if dur <= 0:
res.add(Issue("invalid_duration", "duration", "镜头时长必须大于 0"))
else:
# 联合音视频模型的可用下限另算:它的音轨和画面一样长,台词短就必须让镜头短,
# 拿通用 min_duration(H3 那个值来自节点 tooltip 的**训练建议区间** 5s)来挡,
# 等于把「贴住台词出片」这条正解判成非法,而超出的部分模型会拿念提示词补满。
low = float(caps.min_duration or 0)
joint_low = float(getattr(caps, "joint_min_duration", 0.0) or 0.0)
if caps.joint_av and 0 < joint_low < low:
low = joint_low
if dur < low - 1e-6:
res.add(Issue("duration_below_min", "duration",
f"时长 {dur:.1f}s 低于模型下限 {low:.1f}s(模型 {spec.provider}/{spec.model})"))
if dur > caps.max_duration + 1e-6:
res.add(Issue("duration_above_max", "duration",
f"时长 {dur:.1f}s 超过模型上限 {caps.max_duration:.1f}s,请拆分镜头或换模型"))
if project.resolution not in caps.delivery_resolutions:
res.add(Issue("resolution_unsupported", "resolution",
f"模型不支持 {project.resolution},可用:"
f"{', '.join(caps.delivery_resolutions)}", "warning"))
if project.aspect_ratio not in caps.aspect_ratios:
res.add(Issue("aspect_unsupported", "aspect_ratio",
f"模型不支持画幅 {project.aspect_ratio},可用:{', '.join(caps.aspect_ratios)}", "warning"))
# 档位声明通过 ≠ 配置真的跟得上档位:本地模型按像素数换算画布,
# 画布只由 model_specs 配置决定(平台不改写外部进程维护的分辨率),
# 所以 megapixels 低于交付档位时不会自动抬升,而是原样生成、由合成端放大。
# 这里在预检里说明「配置与档位不匹配」及其后果,让人自己决定提速还是保画质。
canvas = None
if adapter is not None:
try:
canvas = adapter.effective_canvas(spec_cfg, project.aspect_ratio)
except Exception: # noqa: BLE001 - 预检不能被适配器实现细节打挂
canvas = None
if canvas:
_w, _h = int(canvas[0]), int(canvas[1])
need = RESOLUTIONS.get(str(project.resolution or ""), (0, 0))[1]
if need and min(_w, _h) < need - 1:
_ratio = ASPECT_RATIOS.get(str(project.aspect_ratio or "16:9"), 16 / 9)
target_mp = (_ratio * need * need) if _ratio >= 1 else (need * need / _ratio)
cfgj = spec_cfg
cur_mp = float(cfgj.get("megapixels") or 0) if isinstance(cfgj, dict) else 0.0
policy = str((cfgj.get("resolution_policy") if isinstance(cfgj, dict) else "")
or settings.comfyui_resolution_policy).strip().lower()
# 原生画布够不够是一回事,能不能交付是另一回事。声明了 upscale_to 的模型
# (MiniMax H3 原生 768p)按设计就是「原生像素出片 + 合成端放大交付」,
# 这时候报 warning「细节偏软、确认是草案档」等于把正常链路说成事故,
# 用户会去动 megapixels,白付一倍卡时。
need_edge = int(round(need / min(_ratio, 1 / _ratio)))
cap_edge = int((cfgj.get("max_edge") or 0) if isinstance(cfgj, dict) else 0)
if str(project.resolution or "") in tuple(getattr(caps, "upscale_to", ()) or ()):
res.add(Issue("resolution_upscaled_delivery", "resolution",
f"{project.resolution} 是放大交付档:模型按原生 {_w}x{_h} 出片,"
f"合成端用 lanczos 放大到 {project.resolution} 交付。"
f"卡时与该模型的原生档完全一致,画质介于原生 "
f"{min(_w, _h)}p 与原生 {project.resolution} 之间。"
f"要模型真的按 {project.resolution} 出像素,把 megapixels 提到 "
f"{target_mp / 1_000_000:.2f} 以上并把 max_edge 提到 ≥{need_edge}"
f"(实测 H3 的 2MP 画布卡时约 ×2.3,官方未训这一档,需先 A/B)",
"info"))
elif policy == "budget":
res.add(Issue("resolution_effective_lower", "resolution",
f"模型声明支持 {project.resolution},当前像素预算只够 {_w}x{_h}"
f"(短边 {min(_w, _h)} < {need});配置为 budget(预算封顶),"
f"生成后由合成端放大到 {project.resolution}:速度优先、细节偏软,"
f"适合草案迭代。定稿请把 resolution_policy 改回 tier "
f"或把 megapixels 提到 {target_mp / 1_000_000:.2f} 以上",
"info"))
elif policy == "tier":
res.add(Issue("resolution_effective_lower", "resolution",
f"模型声明支持 {project.resolution},但当前像素预算只够 {_w}x{_h}"
f"(短边 {min(_w, _h)} < {need});配置为 tier(档位作下限),"
f"出片会按档位抬到不低于 {need} 的真实画布,画面不会糊,"
f"但耗时高于按 {cur_mp:.2f} MP 预估的值"
+ (f"(注意:max_edge={cap_edge} 会把长边钳回 {max(_w, _h)},"
f"必须同时提到 ≥{need_edge} 才真的抬到档位)"
if cap_edge and cap_edge < need_edge else "") + "。"
f"想真提速请把模型像素数(megapixels)保持 {cur_mp:.2f} "
f"并把 resolution_policy 设成 config/budget,或把项目档位调低到 "
f"{int(min(_w, _h) // 16 * 16)}p",
"warning"))
else:
res.add(Issue("resolution_effective_lower", "resolution",
f"模型声明支持 {project.resolution},但模型配置只够 {_w}x{_h}"
f"(megapixels={cur_mp:.2f},短边 {min(_w, _h)} < {need});"
f"平台按配置原样生成(不偷偷改外部设定的分辨率),"
f"成片由合成端放大到 {project.resolution},细节会偏软。"
f"要按档位出真实像素就把 megapixels 提到 "
f"{target_mp / 1_000_000:.2f} 以上或把 resolution_policy 设成 tier;"
f"确认这是草案档(约快 2 倍)就保持现状",
"warning"))
if shot.mode not in caps.modes:
res.add(Issue("mode_unsupported", "mode",
f"模型不支持生成模式 {shot.mode},可用:{', '.join(caps.modes)}"))
if not spec.enabled:
res.add(Issue("model_disabled", "model", f"模型 {spec.provider}/{spec.model} 已停用"))
if adapter is None or not adapter.is_available(spec_cfg):
# 「没配置」和「配置了但连不上」修法完全不同,别用一句话糊过去
why = _availability_reason(adapter, spec_cfg)
res.add(Issue("provider_unavailable", "provider",
f"适配器 {spec.adapter}:{why or '未配置(缺少 API 地址或密钥)'}"))
# 3. 关键帧 / 参考素材
keyframe = storage.first_asset_path(db, "shot", shot.id, "keyframe")
last_frame = storage.first_asset_path(db, "shot", shot.id, "last_frame")
if shot.mode in ("i2v",) and not keyframe:
res.add(Issue("missing_keyframe", "keyframe", "图生视频模式缺少关键帧,请上传分镜关键帧"))
if shot.mode == "fl" and (not keyframe or not last_frame):
res.add(Issue("missing_frames", "keyframe", "首尾帧模式需要同时上传首帧与尾帧"))
if not keyframe and shot.mode == "t2v":
res.add(Issue("no_keyframe_text_mode", "keyframe", "纯文生视频可不上传关键帧", "warning"))
# 参考图上限是「按优先级取前 N 张」,不是超限就失败:超出部分由
# prompt.collect_references 截断,这里只在可能影响一致性时给出提醒。
_refs, _explicit, ref_total = prompt_service.collect_references(
db, shot, limit=int(caps.max_reference_images or 0))
if caps.max_reference_images and ref_total > caps.max_reference_images:
res.add(Issue("references_truncated", "characters",
f"绑定素材 {ref_total} 张,超过模型参考上限 {caps.max_reference_images} 张,"
f"生成时只取优先级最高的 {caps.max_reference_images} 张(参考图 > 定妆图 > 场景图)",
"warning"))
if caps.max_reference_images and not _explicit and ref_total > caps.max_reference_images:
res.add(Issue("reference_priority_hint", "reference_image",
"如需固定人物或场景,请给该镜头上传参考图,确保它优先入模", "warning"))
ref_count = ref_total
if getattr(adapter, "capabilities", None) and adapter.capabilities(spec_cfg).needs_public_media \
and (keyframe or ref_count) and not spec_cfg.get("upload_url"):
res.add(Issue("media_not_public", "keyframe",
"该供应商无法读取本地路径,请在模型 config_json 中配置 upload_url 以自动上传素材", "warning"))
# 4. 角色与声音一致性
if not (shot.characters or []):
res.add(Issue("no_character_bound", "characters", "未绑定人物资产,人物造型可能不一致", "warning"))
for char in shot.characters or []:
if not storage.first_asset_path(db, "human", char.id, "portrait"):
res.add(Issue("character_no_reference", "characters",
f"人物「{char.name}」还没有定妆图:关键帧与视频只能凭文字描述画脸,"
f"前后镜头很容易变成另一个人。可执行「补齐人物/场景定妆素材」让图像模型补一张"
"(会同时作为该人物所有镜头的参考图入模)", "warning"))
if not (char.persona_prompt or char.appearance):
res.add(Issue("character_no_profile", "characters",
f"人物「{char.name}」缺少角色设定/一致性提示词", "warning"))
for scene in shot.scenes or []:
if not storage.first_asset_path(db, "scene", scene.id, AssetKind.SCENE_IMAGE):
res.add(Issue("scene_no_reference", "scenes",
f"场景「{scene.name}」缺少母图:同一房间在不同镜头里可能是两个空间,"
f"陈设与光线都不稳定", "warning"))
if str(spec_cfg.get("reference_mode") or "").strip().lower() == "frame_only" \
and (shot.characters or shot.scenes):
res.add(Issue("reference_mode_frame_only", "characters",
"该视频模型的 reference_mode 是 frame_only:定妆图与场景母图不会进入模型,"
"一致性完全依赖关键帧本身;要用人物母版做参考请把模型配置改成 auto", "warning"))
dialogue = (shot.dialogue or "").strip()
if dialogue:
# 台词由视频模型直出(默认)时,声线只是「音色参考」而不是必需品:
# 缺声线最多让模型自己挑一把嗓子,口型照样对,绝不能把它当成派发失败。
# 只有显式选择「平台配音(dub)」时,没有可用声线才是真错误。
from app.services import timeline as timeline_service
native_voice = timeline_service.native_voice_wanted(db, project, shot)
voice, info = audio.resolve_voice(db, project, shot)
if voice is None:
res.add(Issue("no_voice_for_dialogue", "dialogue",
"台词将由模型直出原声,本镜头未绑定角色声线:音色由模型即兴,"
"跨镜头的同一个角色可能不是同一个嗓子(在时间线切到平台配音可强制 TTS)"
if native_voice else "有台词但没有可用声线,配音环节会失败",
"warning" if native_voice else "error"))
else:
# 「有声线记录」不等于「这个角色有自己的音色」:IndexTTS2 缺参考音频时
# 会静默改用模型自带的通用参考音频,全片听起来都是同一个陌生人。
# H3 的 ref_audios 同理——没有克隆样本就退化成模型随机音色。
hint = audio.voice_selection_hint(info)
if hint:
res.add(Issue("voice_identity_risk", "voice_asset_id",
(f"模型原声会以「{voice.name}」做音色参考,但{hint}" if native_voice
else f"配音将用「{voice.name}」,但{hint}"), "warning"))
if shot.speaker_character_id is None:
res.add(Issue("no_speaker", "speaker_character_id", "台词未指定说话人,字幕与配音音色可能不准确", "warning"))
# 联合音视频模型按句绑音色(<Audio n> 指向第 n 条参考音频)。某句台词的说话人
# 没绑上自己的声线时不会报错,只是那句没有标签——模型自己从参考池里挑嗓子,
# 于是同一个角色在下一个镜头里换了个人说话。这里必须提前点名。
if native_voice and getattr(caps, "joint_av", False):
unbound = prompt_service.joint_unvoiced_speakers(db, project, shot)
if unbound:
res.add(Issue("joint_speaker_unbound", "dialogue",
"、".join(f"「{n}」" for n in unbound)
+ "的台词拿不到自己的参考音色(角色未设默认声线、声线缺少克隆样本"
"或超出参考音频条数上限):模型会为这几句自己挑嗓子,"
"跨镜头很容易变成另一个人的声音。请到人物资产里为该角色绑定默认声线",
"warning"))
return res
def project_readiness(db: Session, project: Project, *, strict: bool = True) -> dict:
shots = list(project.shots or [])
results = [check_shot(db, project, s, strict=strict) for s in shots]
ready = [r for r in results if r.ok]
blocking = [r for r in results if not r.ok]
summary = {
"project_id": project.id,
"total": len(results),
"ready": len(ready),
"blocked": len(blocking),
"warnings": sum(1 for r in results for i in r.issues if i.severity == "warning"),
"errors": sum(1 for r in results for i in r.issues if i.severity == "error"),
"can_generate": bool(results) and not blocking,
"checks": [r.as_dict() for r in results],
}
# 项目级前置条件
project_issues = []
if not shots:
project_issues.append("尚未导入分镜与脚本")
if not project.characters:
project_issues.append("人物与声音资产库为空,建议先建立角色设定与定妆图")
if summary["can_generate"] is False and not blocking:
project_issues.append("没有可执行的分镜")
summary["project_issues"] = project_issues
return summary
def apply_status(db: Session, project: Project, readiness: dict | None = None) -> dict:
"""把检查结果回写到镜头状态(draft ↔ ready),供任务清单生成使用。"""
readiness = readiness or project_readiness(db, project)
by_id = {c["shot_id"]: c for c in readiness["checks"]}
for shot in project.shots or []:
info = by_id.get(shot.id)
if not info:
continue
if shot.status in (ShotStatus.DRAFT, ShotStatus.READY):
shot.status = ShotStatus.READY if info["ok"] else ShotStatus.DRAFT
shot.stage = "preflight_passed" if info["ok"] else "preflight_failed"
db.flush()
return readiness