"""模型能力契约与动态 Fallback 候选解析。 本模块只负责“某模型是否满足本次调用”与“失败后候选如何排序”，不执行 Provider 请求、重试、日志或账务。业务入口后续只声明 :class:`ModelRequirements`，不得按模型名 复制能力判断。 """ from __future__ import annotations from dataclasses import dataclass, field from datetime import datetime from typing import Any from apps.ai.generation_errors import provider_error_rule_errors from apps.ai.models import ModelConfig, ModelProvider from apps.ai.routing_policy import load_model_routing_policy @dataclass(frozen=True, slots=True) class ModelRequirements: """一次模型调用的最小能力需求；未使用的字段保持空值。""" capability: str operation: str features: frozenset[str] = field(default_factory=frozenset) reference_mode: str | None = None reference_images: int = 0 reference_videos: int = 0 reference_audios: int = 0 aspect_ratio: str | None = None resolution: str | None = None duration: int | None = None language: str | None = None public_voice: str | None = None char_count: int | None = None speed_ratio: float | None = None output_format: str | None = None def __post_init__(self) -> None: if not self.capability or not self.operation: raise ValueError("模型能力需求必须包含 capability 和 operation") for name in ("reference_images", "reference_videos", "reference_audios"): if getattr(self, name) < 0: raise ValueError(f"{name} 不能为负数") if self.reference_mode not in {None, "none", "single", "multiple"}: raise ValueError("reference_mode 只能是 none、single 或 multiple") if self.reference_mode == "single" and self.reference_images != 1: raise ValueError("reference_mode=single 时 reference_images 必须等于 1") if self.reference_mode == "multiple" and self.reference_images < 2: raise ValueError("reference_mode=multiple 时 reference_images 必须至少为 2") # Seedance 的视频编辑模式用 -1 表示“跟随参考视频时长”。 if self.duration is not None and self.duration <= 0 and self.duration != -1: raise ValueError("duration 必须大于 0，或为 -1（跟随参考视频）") if self.char_count is not None and self.char_count < 0: raise ValueError("char_count 不能为负数") if self.speed_ratio is not None and self.speed_ratio <= 0: raise ValueError("speed_ratio 必须大于 0") @dataclass(frozen=True, slots=True) class CapabilityMatch: matched: bool reasons: tuple[str, ...] = () def _dict(value: Any) -> dict[str, Any]: return value if isinstance(value, dict) else {} def _set(value: Any) -> set[str]: if not isinstance(value, (list, tuple, set, frozenset)): return set() return {str(item) for item in value if str(item)} def _positive_int(value: Any) -> int | None: if isinstance(value, bool): return None try: result = int(value) except (TypeError, ValueError): return None return result if result >= 0 else None def routing_metadata(model: ModelConfig) -> dict[str, Any]: return _dict(_dict(model.metadata).get("routing")) def capability_metadata(model: ModelConfig) -> dict[str, Any]: return _dict(_dict(model.metadata).get("capabilities")) def model_allows_fallback(model: ModelConfig) -> bool: """该模型失败后是否允许向外切换；缺失配置时保守关闭。""" return routing_metadata(model).get("fallback_on_failure") is True def model_is_fallback_candidate(model: ModelConfig) -> bool: """该模型是否允许被其他失败任务选中；缺失配置时保守关闭。""" return routing_metadata(model).get("fallback_candidate") is True def provider_fallback_priority(provider: ModelProvider) -> int: """读取供应商候选优先级；数字越小越优先，缺失或非法值统一排到普通供应商层。""" value = _dict(_dict(provider.metadata).get("routing")).get("fallback_priority", 100) if isinstance(value, bool): return 100 try: return int(value) except (TypeError, ValueError): return 100 def provider_metadata_errors(metadata: Any) -> tuple[str, ...]: """校验供应商路由与错误展示配置；供后台写入校验和运行前诊断共同复用。""" routing = _dict(_dict(metadata).get("routing")) errors = list(provider_error_rule_errors(metadata)) if "fallback_priority" in routing: value = routing["fallback_priority"] if isinstance(value, bool) or not isinstance(value, int) or not 0 <= value <= 1000: errors.append("routing.fallback_priority 必须是 0 到 1000 的整数，数字越小越优先") return tuple(errors) def model_metadata_errors(capability: str, metadata: Any) -> tuple[str, ...]: """校验模型路由开关与最小能力契约，缺少候选开关时允许保存。""" root = _dict(metadata) routing = _dict(root.get("routing")) errors: list[str] = [] for name in ("fallback_on_failure", "fallback_candidate"): if name in routing and not isinstance(routing[name], bool): errors.append(f"routing.{name} 必须是 true 或 false") if routing.get("fallback_candidate") is not True: return tuple(errors) capabilities = _dict(root.get("capabilities")) if not _set(capabilities.get("operations")): errors.append("capabilities.operations 至少配置一个操作") if capability == ModelConfig.Capability.IMAGE: modes = _set(capabilities.get("reference_modes")) if modes - {"none", "single", "multiple"}: errors.append("capabilities.reference_modes 只能包含 none、single、multiple") if capability == ModelConfig.Capability.VIDEO: if not _set(capabilities.get("resolutions")): errors.append("视频候选必须配置 capabilities.resolutions") durations = capabilities.get("durations") if not isinstance(durations, (list, tuple)) or not durations: errors.append("视频候选必须配置 capabilities.durations") if capability == ModelConfig.Capability.AUDIO: voice_map = capabilities.get("voice_map") if voice_map is not None and not isinstance(voice_map, dict): errors.append("配音 capabilities.voice_map 必须是公开音色到供应商音色 ID 的对象") return tuple(errors) def capability_metadata_errors(model: ModelConfig) -> tuple[str, ...]: """返回会导致模型无法安全进入候选池的中文配置问题。""" return model_metadata_errors(model.capability, model.metadata) def _check_limit( reasons: list[str], capabilities: dict[str, Any], field_name: str, required: int, label: str, ) -> None: if required <= 0: return maximum = _positive_int(capabilities.get(field_name)) if maximum is None or maximum < required: reasons.append(f"{label}上限不足：需要 {required}，配置为 {maximum if maximum is not None else '缺失'}") def _video_pricing_available(model: ModelConfig, resolution: str | None) -> bool: if not resolution: return True pricing = _dict(_dict(model.metadata).get("pricing")) if not pricing: return False # 1080p/4k 必须有精确价格档；480p/720p 可使用现有 default 档。 tier = pricing.get(resolution) if resolution in {"1080p", "4k"} else pricing.get(resolution) or pricing.get("default") return isinstance(tier, dict) and bool(tier) def match_model_requirements(model: ModelConfig, requirements: ModelRequirements) -> CapabilityMatch: """纯函数式能力匹配；缺失配置一律保守排除，不按模型名猜测。""" reasons: list[str] = [] if model.capability != requirements.capability: reasons.append(f"能力大类不匹配：需要 {requirements.capability}，模型为 {model.capability}") return CapabilityMatch(False, tuple(reasons)) capabilities = capability_metadata(model) operations = _set(capabilities.get("operations")) if requirements.operation not in operations: reasons.append(f"不支持操作 {requirements.operation}") missing_features = sorted(set(requirements.features) - _set(capabilities.get("features"))) if missing_features: reasons.append(f"缺少特性：{', '.join(missing_features)}") if requirements.reference_mode and requirements.reference_mode != "none": if requirements.reference_mode not in _set(capabilities.get("reference_modes")): reasons.append(f"不支持 {requirements.reference_mode} 参考图模式") _check_limit(reasons, capabilities, "max_reference_images", requirements.reference_images, "参考图片") _check_limit(reasons, capabilities, "max_reference_videos", requirements.reference_videos, "参考视频") _check_limit(reasons, capabilities, "max_reference_audios", requirements.reference_audios, "参考音频") for field_name, required, label in ( ("aspect_ratios", requirements.aspect_ratio, "画面比例"), ("resolutions", requirements.resolution, "分辨率"), ("languages", requirements.language, "语言"), ("output_formats", requirements.output_format, "输出格式"), ): # 视频编辑的 adaptive 比例由火山按输入视频决定，不是模型静态能力表中的比例档。 if required and required != "adaptive" and required not in _set(capabilities.get(field_name)): reasons.append(f"不支持{label} {required}") if requirements.duration is not None and requirements.duration != -1: durations = capabilities.get("durations") supported = set(durations) if isinstance(durations, (list, tuple, set, frozenset)) else set() if requirements.duration not in supported: reasons.append(f"不支持时长 {requirements.duration} 秒") if requirements.public_voice: voice_map = capabilities.get("voice_map") if not isinstance(voice_map, dict) or not voice_map.get(requirements.public_voice): reasons.append(f"缺少公开音色 {requirements.public_voice} 的供应商映射") if requirements.char_count is not None: max_chars = _positive_int(capabilities.get("max_chars")) if max_chars is None or requirements.char_count > max_chars: reasons.append( f"字符上限不足：需要 {requirements.char_count}，配置为 {max_chars if max_chars is not None else '缺失'}" ) if requirements.speed_ratio is not None: speed_range = capabilities.get("speed_range") if not isinstance(speed_range, (list, tuple)) or len(speed_range) != 2: reasons.append("缺少合法的语速范围配置") else: try: minimum, maximum = float(speed_range[0]), float(speed_range[1]) except (TypeError, ValueError): reasons.append("语速范围配置不是数字") else: if not minimum <= requirements.speed_ratio <= maximum: reasons.append(f"不支持语速 {requirements.speed_ratio:g}") if requirements.capability == ModelConfig.Capability.VIDEO and not _video_pricing_available( model, requirements.resolution ): reasons.append(f"缺少分辨率 {requirements.resolution} 的视频价格配置") return CapabilityMatch(not reasons, tuple(reasons)) def _timestamp(value: datetime | None) -> float: return value.timestamp() if value is not None else 0.0 def _candidate_sort_key(model: ModelConfig) -> tuple[int, float, float, str]: return ( provider_fallback_priority(model.provider), -_timestamp(model.updated_at), -_timestamp(model.created_at), str(model.id), ) def resolve_fallback_candidates( *, primary_model: ModelConfig, requirements: ModelRequirements, attempted_model_ids: set[Any] | frozenset[Any] = frozenset(), excluded_provider_ids: set[Any] | frozenset[Any] = frozenset(), ) -> list[ModelConfig]: """在主模型明确失败后解析候选；不会替换或重排用户传入的主模型。""" if not model_allows_fallback(primary_model): return [] attempted = {str(value) for value in attempted_model_ids} attempted.add(str(primary_model.id)) excluded_providers = {str(value) for value in excluded_provider_ids} policy = load_model_routing_policy() remaining_model_slots = max(0, policy.max_models - len(attempted)) if remaining_model_slots == 0: return [] candidates = [] queryset = ModelConfig.objects.select_related("provider").filter( capability=requirements.capability, status=ModelConfig.Status.ACTIVE, provider__status=ModelProvider.Status.ACTIVE, ) for model in queryset: if str(model.id) in attempted or str(model.provider_id) in excluded_providers: continue if not model_is_fallback_candidate(model) or capability_metadata_errors(model): continue if match_model_requirements(model, requirements).matched: candidates.append(model) candidates.sort(key=_candidate_sort_key) return candidates[:remaining_model_slots] __all__ = [ "CapabilityMatch", "ModelRequirements", "capability_metadata", "capability_metadata_errors", "match_model_requirements", "model_allows_fallback", "model_is_fallback_candidate", "model_metadata_errors", "provider_fallback_priority", "provider_metadata_errors", "resolve_fallback_candidates", "routing_metadata", ]