j6-plugin-insert-quant-dequant

给任意浮点模型插入 Quant/DeQuant（Horizon 部署边界版）

目标

把任意 浮点 torch.nn.Module 改造成可被 horizon_plugin_pytorch 量化工具链处理的形式：在部署输入边界插入 QuantStub，在部署输出边界插入 DeQuantStub。

这里必须先区分两类逻辑：

• 部署模块 / 部署子图：推理落板时真正需要保留、需要进入量化图的部分，例如 backbone、neck、head、deploy module 等。
• 非部署模块 / 非部署逻辑：只在训练、评估、可视化、日志或 CPU/浮点后处理中使用，不属于最终部署子图，例如 loss 计算、matcher、target assign、NMS 后处理、结果格式整理、metrics、debug print、可视化等。

QuantStub -> ... -> DeQuantStub 中间这段，应该只包含部署模块。凡是部署时不需要的逻辑，都不应该被夹在 quant 和 dequant 中间。

本 Skill 强约束：

• quant/dequant 是部署边界：标记从哪里开始/结束部署（进入/离开量化图）。
• 每个输入和输出都单独创建 quant/dequant：不要复用同一个 stub 处理多个输入或多个输出。
• QuantStub 初始化不要设置 scale：不要传 scale=...，交给量化流程决定。
• QuantStub 只针对浮点 tensor：只有浮点 tensor 输入/输出才需要按部署边界插入 quant/dequant。
• scalar 或非浮点 tensor 不插入 QuantStub：标量（scalar），以及 bool、整数/索引、已是定点语义的 tensor，不要为了“形式统一”强行插 quant。
• quant 和 dequant 之间只放部署逻辑：loss、训练标签处理、评价指标、前后处理、可视化等非部署逻辑必须放在边界之外。
• train/eval 的边界定义必须一致：不要仅因 self.training 为真/假就改变“哪里需要 dequant”的位置；是否 dequant 取决于后续逻辑是否已经离开部署图，而不是取决于当前处于训练还是评估模式。
• 区分“边界输入”和“图内常量输入”：QuantStub/DeQuantStub 负责标注部署边界；但如果部署图内部存在参与算子计算的 tensor 常量输入（例如 x + const_tensor 里的 const_tensor），也必须把它纳入 quant 语义。标量（scalar）可按算子属性处理，不显式插 quant 节点；tensor 形式的常量输入应视为输入参与量化。

第零步：先判断谁属于“部署边界内”

在插入 QuantStub/DeQuantStub 之前，先把目标代码拆成两段：

A. 可以放在 quant 与 dequant 之间的内容

这些通常属于部署模块：

• 主干网络 / backbone
• neck / encoder / decoder / detection head
• 明确要参与板端推理的特征变换
• 明确属于部署图一部分的张量级算子

B. 不能放在 quant 与 dequant 之间的内容

这些通常属于非部署逻辑：

• loss 计算
• matcher / assigner / target builder
• 训练分支专用监督逻辑
• 输入前处理（如果它不属于模型部署图，而是 dataloader / Python 侧处理）
• 输出后处理（如 NMS、阈值过滤、格式整理、映射回原图）
• COCO evaluator / metrics / logger / visualizer
• .cpu() / .numpy() / Python list/dict 整理 / 画图 / dump 文件

如果某段逻辑在板端部署时不会保留，就不要把它塞进 quant/dequant 边界里。

补充说明：

• “输入”不只指 forward(...) 的外部参数，也包括部署图内部某个算子的独立输入。
• 因此，一个由模型内部构造出来的常量 Tensor，只要它作为 add/cat/matmul/attention 等算子的输入参与部署图计算，就不能把它当成“天然 float 附件”忽略量化。
• 但这不意味着要把它误改成新的部署边界：边界 QuantStub 仍只负责模型 I/O 边界；图内常量 Tensor 的重点是“必须进入 quant 语义”，而不是“必须伪装成外部输入”。