1. 项目起点：为什么 Agent 里需要 VSR 模型路由器

1.1 单模型方案的三个死穴

"VSR 模型路由器 -08"说到底是我在 Agent 项目里做的第八版迭代，编号里的 -08 不是版本号凑数，而是代表这条线已经从 -01 一路改过来了。VSR 是视频超分辨率（Video Super Resolution），模型路由器解决的是"一段视频该交给哪个超分模型处理"的决策问题。之所以坚持做路由器而不是直接调模型，是因为我在实际项目里被单模型方案坑了太多回。

最初团队的做法非常朴素：所有视频超分需求统一调一个效果最好的大模型。演示阶段一切完美，一进生产环境立刻露馅。第一个死穴是效果不通用。监控视频噪声大、运动剧烈，需要去噪和运动补偿；动漫番剧线条分明、色块锐利，跟写实画面的特征完全不同；老照片修复衍生出来的视频任务又涉及人脸细节和胶片颗粒。这些内容用一个模型硬扛，总有一半任务效果不合格。

第二个死穴是延迟。1080p 转 4K 的重型模型单帧推理耗时经常超过 800ms，一段 30 秒的视频抽出来差不多几千帧，跑完要四十多分钟。用户在 Agent 对话框里等一个"视频已超分完成"的回复，等到怀疑人生。第三个死穴是资源。重型模型显存占用起步就是 10GB 上下，一旦几个任务并发，GPU 直接 OOM，连带 Agent 框架里其他推理服务一起崩。

一个特别典型的案例让我彻底下定决心：同一段视频，按内容切成几个场景段，片头字幕给轻量模型、动态画面给中等级模型、静态背景给快速模型，总耗时压到原来的四分之一，而人工盲测几乎看不出视觉差异。这个结果说明，问题从来不是"模型不够强"，而是"模型没用对地方"。

1.2 从负载均衡到决策分发：先把概念分清

做路由器之前先把概念理清楚，不然设计方向会跑偏。"负载均衡"是把同一类请求分到多个同质服务上，核心是流量调度和故障转移；"模型路由器"面对的是异构模型，每个模型能力不同、成本不同、适合的场景不同，核心是"根据请求特征做决策"。这俩不是一回事。

我在 -08 版里把路由决策拆成四层，每层只干一件事，避免规则膨胀成意大利面条。

• 任务层：用户到底想干什么。超分倍率是 2x 还是 4x，目标分辨率多少，需不需要去噪、插帧，是老视频修复还是新视频增强。这些信息主要来自 Agent（LLM）对用户意图的解析。
• 内容层：视频本身长什么样。清晰度如何、噪声水平高低、运动强度大不大、画面里有没有大量字幕文字。这些靠预分析模块在正式超分前做一次快速抽帧采样，用统计特征打标签。
• 资源层：当前的环境状态。GPU 空闲显存多少、推理服务排队长度、API 额度还剩多少、任务的硬性延迟预算是多少。
• 策略层：把前三层的结果汇总，结合用户"质量优先还是速度优先"的偏好，算出最终选择。

这个分层结构帮我挡掉了大量"加一个需求就要改路由主体代码"的尴尬。新场景进来基本只需要在某一个层次追加规则，其他层根本不用动。

1.3 插件化不是喜好问题，是被场景逼出来的

-01 到 -03 版本，路由表是写死的： if scale == 4 and motion_high: use_model_b 。看起来直白，但每接入一个新模型就要改核心代码，每改一次核心代码就要重新跑一遍回归，Agent 框架那边的工具定义还要跟着升级。模型从 3 个涨到 10 个的时候，这套玩法彻底撑不住了。

插件化带来的核心收益是"模型接入"和"路由逻辑"解耦。模型提供方只需要实现一个固定接口，把插件包丢进目录，路由器启动时自动发现并参与评分。新增模型不碰路由引擎，下线模型也不影响其他功能。

还有一个意外收获：插件化让团队协作模式变了。负责基础超分模型的组维护自己的插件包，负责人脸修复的组维护另一个插件包，两边各自迭代，只有路由主体由我统一维护，互不阻塞。这种模块间的并行推进，在 monolith 时代完全不敢想。所以如果你也在做 Agent 里的工具编排或者模型分发，我建议从一开始就把插件边界划清楚，别等代码烂了再重构。

2. 插件协议与路由引擎的关键设计

2.1 接口契约：薄接口，厚实现

插件接口是整个系统的契约，设计原则只有一条：接口尽量薄，约定尽量少。模型方接入成本越低，生态越容易长出来。

VSR 模型插件接口的核心部分大致是这样：

class VSRPlugin(ABC):
    name: str
    version: str

    @abstractmethod
    def describe(self) -> PluginProfile:
        """返回模型能力画像，路由引擎依赖它做评分。"""

    @abstractmethod
    def process(self, clips: list[Clip], params: ProcessParams) -> list[Clip]:
        """对输入视频片段执行超分，返回处理后的片段。"""

    def health_check(self) -> bool:
        """可选：探活接口，默认返回 True。"""

    def shutdown(self) -> None:
        """可选：优雅退出，处理完手头批次再停。"""

这里最关键的是 describe() 返回的 PluginProfile ，路由引擎完全靠它做判断。它包含这些字段：

• 显存占用（模型跑起来需要的最低显存）
• 单帧耗时（在标准 1080p→4K 输入上的实测均值）
• 推荐输入尺寸和最大放大倍率（比如支持 2x/4x，不支持 3x）
• 擅长场景标签（噪声处理、动漫线条、人脸修复、文字增强、通用细节）
• 质量评分（离线测试集上的 PSNR/SSIM 或主观平均意见分）
• 运行成本（如果是调用远端推理服务，填单次调用价格）

路由引擎根本不关心插件内部是 Real-ESRGAN、BasicVSR 还是某个私有模型，它只读 Profile 里的数字。这就是解耦的意义：模型本身的实现细节被完全封装在插件内部，路由侧永远面对的是统一的 Profile 契约。

2.2 插件注册机制：扫描、验证、登记

插件加载我采用"目录扫描 + 声明式注册"结合的方式。模型方把插件打包成标准 Python 包，放进配置指定的插件目录，路由器启动时扫描目录逐个加载。

注册流程是：发现 -> 加载 -> 验证 -> 登记。验证环节非常关键，它会检查接口实现完整性，然后跑一次最小推理样例，确认输出张量尺寸和像素范围正确，插件才会被标记为 active。验证不通过的插件只记日志、不进路由候选池，绝不阻断主流程启动。

这里藏着一个被我们坑过两次的细节：依赖冲突。插件 A 强依赖某个特定版本的推理算子库，装完以后插件 B 直接 import 失败。后来我把插件改成隔离加载，每个插件在自己的虚拟环境里注册资源，主进程通过 IPC 调用而不是直接 import。代价是进程间通信有一点性能损耗，但换来的是"一个插件装挂不会拖垮整个路由器"的稳定性，这笔账非常划算。

另外，插件目录里的包要做好版本管理。我见过同事直接覆盖共享目录里的同名包，结果另一个插件干活的时候突然行为异常。每个插件包带独立版本号、独立目录、独立依赖声明，这是最基本的要求。

2.3 路由评分：把主观需求变成数字

路由决策不是一堆 if-else 硬编码，而是一个加权的多维度评分。每个候选模型对一个任务会得到一个适配度分数：

score = w1 * quality_fit + w2 * resource_fit + w3 * speed_fit + w4 * cost_fit

每一项都归一化到 0~1，然后加权求和。不满足硬性条件的模型直接淘汰，不参与评分，比如显存不够、最大倍率不满足需求、预测耗时超过预算两倍。

• quality_fit：用 Profile 的场景标签跟任务场景标签做匹配度计算。任务检测出"动漫 + 高噪"，那动漫场景得分高的模型这部分就高。
• resource_fit：当前 GPU 显存余量与模型最小显存要求的比值，越富余分越高。
• speed_fit：预测耗时与任务延迟预算的比值，越快分越高。
• cost_fit：成本预算内的模型得高分，超出预算降权。

权重一开始也是拍脑袋定的，但从 -04 版本开始我用历史任务日志做了简单回归拟合。当时发现速度项的权重偏低，导致一些任务被分到慢模型上，用户抱怨量明显上升。调整权重之后整体满意率好了一大截。我的经验是：别老觉得规则能解决一切，线上数据反馈比直觉可靠得多。权重参数定期用最近一个月的任务日志重新拟合一遍，效果比手工调参稳定。

2.4 熔断、降级与兜底

模型是外部依赖，它一定会出问题。我在生产里遇到过的故障包括：远端推理服务挂了、显存不足导致 OOM、API 额度用完、插件进程卡死。这些问题如果不处理，路由器会把所有流量都送进一个坏掉的模型，超分质量变成灾难现场。

-08 版加了熔断机制：每个插件维护一个健康计数器，连续失败超过阈值就进入熔断状态，路由评分直接跳过；熔断有冷却时间，冷却结束后进入半开状态，用少量探活请求验证恢复情况，成功率达标才恢复全量流量。这个机制跟微服务里的熔断是同一个思路，用在这里刚好合适。

另外还有一条硬性兜底：无论如何都保留一个"最保守模型"插件。它效果可能不是最好的，但足够稳定、跨场景适用，吃资源也少。当所有前置路由条件都满足不了时，流量落它身上，保证请求一定有输出。Router 可以追求最优，但不能为了最优放弃"永远有结果"这条底线。

3. 从零搭一个可用的 VSR 模型路由器

3.1 项目结构与配置

整个项目的目录结构大致是这样：

vsr-router/
├── core/
│   ├── registry.py        # 插件注册中心
│   ├── router.py          # 路由决策引擎
│   ├── context.py         # 任务上下文构建
│   └── circuit.py         # 熔断状态管理
├── plugins/               # 各模型插件目录
│   ├── plugin_a_esr/
│   ├── plugin_b_basicvsr/
│   └── plugin_c_fast/
├── tools/
│   ├── analyze_video.py   # 视频内容预分析
│   └── bench.py           # 插件性能基准
├── agent_integration/
│   └── vsr_tool.py        # Agent 工具封装
└── config/
    └── routing.yaml       # 权重与阈值配置

配置方面把权重、阈值、插件目录、熔断参数都放到 routing.yaml ：

router:
  plugin_dir: ./plugins
  score_weights:
    quality: 0.4
    resource: 0.2
    speed: 0.25
    cost: 0.15
  hard_limits:
    max_scale_mismatch_ratio: 2.0
    min_gpu_free_gb: 2
circuit_breaker:
  fail_threshold: 5
  cooldown_seconds: 120
  half_open_probe_count: 3
fallback_plugin: plugin_c_fast

配置和代码分离的好处是调权重不需要改代码重新发布，运营同学也能安全操作。熔断参数这种跟环境强相关的东西，放配置里比写死在代码里合理得多。

3.2 视频预分析：路由决策的第一手材料

路由要基于内容决策，就得先知道视频内容长什么样。预分析模块做三件事：抽帧、特征提取、场景切分。

抽帧策略我踩过大坑。一开始均匀抽帧，每 N 帧取一帧，结果面对一段前半部分是静态字幕、后半部分是剧烈运动的视频，均匀抽样把静态部分的样本大量浪费掉，动态部分的特征反而采样不足。后来改成"基于场景切分的自适应抽帧"：先用场景检测算法把视频切成若干镜头段，再从每个段内抽代表帧。这样每个镜头都能分到合理的采样配额。

特征提取主要算几个指标：平均清晰度（用梯度统计量近似）、噪声水平（高频能量占比）、运动强度（帧间差分）、色彩分布（判断动漫还是写实，动漫画面通常有更极端的饱和度分布）。这些指标不依赖深度学习，纯 OpenCV 就能算，速度非常快，一个 1080p 视频的全片预分析控制在几秒内。

场景切分之后，每个片段带着自己的特征标签进入路由评分。一段视频里不同片段可能被分给不同模型处理，最后按时间轴拼回去。拼接这里有一个隐蔽的坑：不同模型的色彩空间处理方式可能不一致，如果各插件在输出端没有统一约定，拼接处会出现肉眼可见的边界闪烁。我们后来统一约定所有插件的输入输出都是 RGB 且保持同一亮度分布，这个问题才彻底消失。

3.3 路由引擎核心实现要点

路由引擎的核心循环并不复杂，但有三个实现细节值得单独说。

一是"决策"和"执行"分离。路由引擎只输出一个 RoutePlan ，包含每个片段的模型选择、处理顺序和预估资源占用，不直接调用模型。执行器拿到 plan 之后再真正调度。原因在于决策时点的资源状态和执行时点的资源状态可能不一致，分离之后，执行器可以在真正调度前做最后一刻的资源复核，避免"plan 里写的是 11GB 显存，实际执行时 GPU 已经被别的任务占走大半"这种尴尬。

二是批量合并。同一个模型被选中处理多个连续片段时，执行器会做 frame batching，把多个片段的帧合并成一个 batch 推理，而不是逐段调用。实测下来，在 GPU 上 batch=4 相比单帧推理吞吐提升约 2.5 倍，这是整个系统里性价比最高的一项优化。batch 大小不是越大越好，超过 8 以后显存占用曲线变陡、收益递减，我们一般卡在 4~8 之间。

三是幂等性与可追溯性。每次生成 plan 都会分配一个唯一 plan_id ，关键决策依据会记录成结构化日志，比如"camera_02.h264 场景3：高分噪 + 运动强 -> 模型B，quality_fit=0.82, speed_fit=0.31"。问题排查时直接按 plan_id 拉取决策记录，定位效率比对着模型输出瞎猜高一个档次。

3.4 Agent 工具层对接：让 LLM 会"用"路由器

路由器本身是一个独立服务，Agent 框架通过工具调用协议访问它。我做的 Agent 集成是一个标准 tool 定义，暴露给 LLM 的参数包括：

• input_path ：输入视频路径或 URL
• target_scale ：目标放大倍率（2x/4x 等）
• priority ：质量优先 / 速度优先 / 平衡
• extra_requirements ：附加需求，比如"注意人脸区域不要过度锐化"

LLM 解析用户需求后，把用户意图映射成参数。比如用户说"把这个老视频弄清晰一点，尽量快"，Agent 会设置 target_scale=2x, priority=speed ；如果用户说"我要画面细节再多一些，后期做特效用"，则可能是 target_scale=4x, priority=quality 。

这里有两个非常现实的坑。第一个是 LLM 生成的参数经常不合法，比如超分倍率给了 3x ，而模型集只支持 2x 和 4x。tool 层必须做严格的 schema 校验，不合法就返回带纠错提示的错误信息，让 Agent 重新生成参数，而不是直接报 500。值得高兴的是，现在主流 Agent 框架对工具错误返回的处理已经比较成熟，只要错误信息足够结构化，LLM 基本能自我纠正。

第二个坑是长视频超时。Agent 调用工具的默认超时往往只有几十秒，而一个 10 分钟视频即使路由优化过也可能要跑十几分钟。直接同步调用必挂无疑。我最终的方案是做异步任务化：tool 调用立即返回一个 task_id ，Agent 通过轮询或 webhook 获取任务状态。这个改动对用户体验的提升非常明显，用户不用死等一个同步响应，Agent 也能腾出上下文窗口做别的事。

3.5 一个完整案例：五个插件怎么分一段演唱会视频

拿真实场景走一遍流程。用户提交一段 1920x1080 的演唱会现场视频，目标分辨率 4K，模型集里有五个插件：

插件	类型	显存占用	单帧耗时(1080p→4K)	场景标签
plugin_a_esr	通用增强	6GB	420ms	通用 / 细节增强
plugin_b_basicvsr	时序超分	11GB	860ms	低噪 / 连续运动
plugin_c_fast	轻量快速	2GB	90ms	通用 / 快速预览
plugin_d_anime	动漫专用	4GB	350ms	动漫 / 线条
plugin_e_face	人脸增强	5GB	520ms	人脸 / 细节

预分析把视频切成 8 个场景段：5 段是舞台灯光下的运动镜头，噪声偏高；2 段是大远景固定机位，画面相对干净；1 段是字幕特写。任务要求质量优先，延迟预算 30 分钟。

资源层先过滤：当前 GPU 可用显存 24GB，plugin_b 需要 11GB，能放但会让其他服务吃紧。速度项一算，plugin_b 全场跑完大约 75 分钟，超过预算两倍，被硬性降权；plugin_a 全场约 37 分钟，接近预算，速度分偏低；plugin_c 全场只要 8 分钟，速度满分但质量分不高。

最终评分结果是：5 个运动镜头分给 plugin_a，2 个静态镜头分给 plugin_c，字幕特写分给 plugin_a。整个任务实际耗时约 31 分钟，人工抽查时运动画面的细节增强到位、静态画面干净、字幕清晰。这个案例最能说明路由器的价值：同样一个预算，通过差异化分配把可感知的质量拉满，而不是让所有片段共享同一个"最安全的模型"。

4. 常见问题与排查技巧实录

4.1 高频问题速查表

现象	可能原因	处理思路
部分插件加载后一直 inactive	插件依赖冲突或验证样例推理失败	查看插件日志，用隔离环境重装依赖，单独跑验证脚本
路由结果不符合预期	内容预分析特征判定错误	用 plan_id 拉取决策日志，检查该片段的特征标签
拼接处出现颜色闪烁	不同插件的色彩空间处理不一致	统一约定各插件输入输出都为 RGB 且保持同一亮度分布
Agent 工具调用报参数错误	LLM 生成参数不合 schema	返回结构化错误信息，提示正确枚举值，让 Agent 重新生成
长视频任务超时	同步调用超时配置不匹配	改为异步 task_id + 轮询/回调模式
某个插件频繁熔断	推理服务不稳定或显存不足	检查熔断日志，确认偶发还是持续，必要时降低其并发数
显存 OOM	多个插件 batch 推理并发过大	执行器增加并发控制和显存预留检查

4.2 排查决策异常的标准动作

路由器出问题，我第一反应从来不是看模型，而是看路由决策日志。绝大多数"超分效果诡异"的问题，根源都是"模型选错了"，而不是"模型跑坏了"。

标准排查流程是四步。第一步，拿任务的 plan_id 拉出结构化决策日志，看每个片段分给了哪个插件、评分各项数值、淘汰原因。第二步，对比人工复盘结论。如果人工判断"这个片段应该给动漫模型"，而系统给了通用模型，多半是内容预分析把场景标签判错了。这时候单独跑一遍预分析脚本，确认特征提取环节有没有问题。第三步，如果特征没问题但评分权重不对，把历史同类任务的评分分布拉出来，检查权重配置是不是需要调整。第四步，如果模型选择正确但输出质量差，再去检查插件内部参数，比如目标尺寸、去噪强度是不是在预处理阶段被覆盖了。

这套流程的核心思想是：路由器已经把业务逻辑的关键决策暴露成结构化数据了，排查就该从数据切入，而不是对着黑盒输出猜。你先把"选型对不对"这个问题回答掉，剩下的事通常都好办。

4.3 性能优化三板斧

-08 版在性能上做了三轮优化，都值得记录。

第一板斧是预分析阶段的并行化。视频抽帧、特征提取可以按场景段并行跑，只要控制好线程数，能把预分析时间从十几秒压到两三秒。这一步在长视频上收益尤其明显。

第二板斧是推理批处理。前面提过的 frame batching 收益最大，实现也简单：执行器维护一个"同模型待处理帧队列"，攒够 batch 大小再统一送推理。注意 queue 里要处理优先级，不能让一个大片段的帧一直占用队列导致小任务饿死。

第三板斧是结果缓存。对重复出现的视频片段特征（比如同一个视频被多次请求不同超分倍率），命中缓存的片段直接跳过推理。缓存键要包含文件标识、片段起始时间、目标倍率和处理参数，不能只录文件 hash，否则容易把不同需求的输出搞混。这个缓存真正起作用是在运营侧反复跑测试集做效果对比时，命中率能到 40% 以上，省下大量 GPU 时间。

4.4 给插件开发者的避坑清单

最后留一份给模型插件开发者的避坑清单，都是我这边被真实坑过之后总结出来的。

• describe() 的数据必须真实。报价 50ms 实际跑 400ms 的模型会带偏整个路由评分，最后背锅的一定是插件方。
• 输入输出色彩空间必须跟协议一致。超分模型内部习惯各异，有的走 YCbCr，有的走 RGB，插件层统一转换，别让路由引擎处理这些杂事。
• 插件要有优雅退出逻辑。被熔断时先处理完手头这批帧再停，不要直接中断，否则上游会拿到残缺片段。
• 独立插件不要动公共配置。有一次插件 A 为了调自己的参数改写了共享缓存目录的结构，结果插件 B 的缓存全部失效，排查了大半天。
• 处理完做一次输出校验。尺寸、帧数、像素范围这些基础指标，几行代码就能搞定，能挡住大部分低级 bug。

5. 个人复盘与下一步打算

写到这，我复盘一下 -08 整个迭代的过程。最初这个项目被质疑过"多此一举"，理由是"有模型不就够了吗"。但真实跑数据之后这种声音基本消失了。一个 VSR 模型路由器解决的问题，本质上不是技术问题，而是资源分配问题——把最合适的计算资源给最合适的画面需求。这和 Agent 领域里把复杂任务拆给不同工具去完成是同一个思路：路由是智能系统里比"蛮力执行"更高级的一层。

我个人的体会是，插件化设计最大的价值不是第一天的灵活，而是半年后的可持续。当模型数量从 3 个涨到 10 个，路由规则从 20 条涨到 100 条的时候，如果当初没有把接口和实现切开，整个系统早就被改崩了。接口契约、隔离加载、决策日志这三件事，是支撑这个系统活过八轮迭代的顶梁柱。

下一步我打算做三件事。一是把视频预分析接入 Agent 的视觉理解能力，让 LLM 直接描述视频特征，替代部分 OpenCV 的统计判断，场景标签应该会更准。二是把人工反馈和客观指标回灌到权重拟合里，让路由越用越准。三是把插件协议标准化成描述文件加钩子脚本的热插拔方案，让新模型上线只需要丢一个配置，不用写任何 Python。

如果你也在做 Agent 里的模型分发或者工具编排，希望这篇对你有参考价值。我踩过的坑你可能也会踩，提前写出来，能省一点是一点。