用途:该技能用于在 FlashDreams 中新增视频后处理器,或修改 runner 的后处理流接线。参考实现为 integrations_v2/flashvsr/impl/postprocess.py。
主要结构:一个后处理器通常由三个类组成,而非单一继承类。VideoPostProcessorConfig 负责可序列化配置与 CLI 界面,设置 _target 指向处理器工厂,并声明字段、output_spec()、requires_all_ranks() 与 validate_execution()。VideoPostProcessor 是由配置创建的轻量工厂,职责是 start(spec) -> VideoPostProcessorSession。VideoPostProcessorSession 是每个流的可变运行时,持有缓冲区、缓存、惰性模型实例与计数器,并实现 process() / flush()。流状态应放在会话中,不要放在配置或工厂上。
实现位置:通用可复用后处理放在 flashdreams/flashdreams/infra/postprocess/;模型专属处理器放在对应集成的 postprocess.py 中。
关键约定:当空间尺寸、通道或时序变化时重写 output_spec();需要非零 rank 在 torchrun 下运行时重写 requires_all_ranks();用 validate_execution() 提前拒绝不支持的分布式或形状模式。配置继承 device 字段,消费者复制缓存的 preset 配置,在 setup() 前赋值 device 并保持不变,不得修改注册表返回的 preset 对象。
流处理:process() 是同步的,但可能返回 [],表示已消费输入块并在缓冲帧,等待后续块或 flush() 才能输出完整窗口。在边界处处理布局:接受 chunk.layout 中的 VideoChunk.tensor,仅在通用边界使用 to_bvtchw(),转换一次到处理器原生布局,内部缓冲保持该布局。返回值应保持 [-1, 1] 值域并设置正确布局。
预设注册:通过项目入口点注册,如 [project.entry-points."flashdreams.postprocess_presets"] 下注册 "my-postprocessor-v1" = "my_pkg.postprocess:POSTPROCESS_PRESET_MY_V1",导出对象须为 VideoPostProcessorConfig。用户用 --postprocess.preset my-postprocessor-v1 选择。V2 应用可通过 VideoPostprocessChainConfig.from_preset(args.postprocess_preset, device=args.postprocess_device) 在启动时解析设备。
Runner 交互:Runner 通过 create_runner_postprocess_stream() 创建 VideoPostprocessStream,为整条流创建一个链式会话,或在 postprocess_per_view=True 时每个视图一个会话;对每个 AR 输出调用 session.process();将 [] 转为零帧张量;在流末尾调用一次 flush()。
测试:新增 CPU 安全测试,除非行为确实需要 GPU。相关测试文件包括 test_postprocess_presets.py、test_postprocess_stream.py、test_runner_postprocess.py 以及集成内的 test_postprocess.py。每个 pytest 测试必须使用 ci_cpu、ci_gpu 或 manual 中的一个标记。可使用 uv run pytest 运行上述文件进行聚焦验证。限制:资料未提供具体功能效果、收费或平台支持信息。