Kornia GuidedBlur 半精度修复多通道引导下 float16/bfloat16 引导滤波的求解器适配【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址: https://gitcode.com/gh_mirrors/ko/kornia本篇文章聚焦 Kornia 图像滤波模块中guided_blur/GuidedBlur引导滤波的一次关键修复当引导图guidance包含多个通道时算子此前在float16/bfloat16半精度下会因torch.linalg.solve缺乏半精度 LU 分解 kernel 而直接报错甚至中止进程。文章将完整还原问题根因、修复策略、源码级实现细节与回归测试验证帮助读者理解如何在自己的项目中安全地以半精度运行多通道引导滤波并给出可复制的函数式与模块式调用示例。背景引导滤波在 Kornia 中的实现引导滤波Guided Image Filtering是一种经典的保边平滑算子由 He 等人于 2010 年提出对应仓库 docs/source/references.bib 中的he2010guided其后 He 与 Sun 又提出加速版本 Fast Guided Filterhe2015fast。其核心假设是在每个局部窗口内输出可以被表示为引导图的一个线性变换因此平坦区域被平滑平均而引导图中较强的结构被保留下来。Kornia 在 kornia/filters/guided.py 中实现了完整的引导滤波逻辑并通过 kornia/filters/init.py 对外导出两个 API函数式guided_blur(guidance, input, kernel_size, eps, ...)模块式GuidedBlur(kernel_size, eps, ...)继承nn.Module两者支持引导图与输入图通道数不一致如 3 通道 RGB 引导 4 通道输入参数包括border_type、subsampleFast Guided Filter 下采样与separable可分离盒式滤波。根据输入guidance.shape[1]是否为 1实现会分流到两条路径见 kornia/filters/guided.py单通道引导_guided_blur_grayscale_guidance纯盒式滤波与逐元素运算不涉及矩阵求解多通道引导_guided_blur_multichannel_guidance每个像素需要求解一个C x C的线性系统这是本次修复的核心对象。问题现场半精度下的两类崩溃在修复之前当引导图通道数C 1即进入_guided_blur_multichannel_guidance且输入为float16或bfloat16时每次调用torch.linalg.solve都会失败且不同后端表现不同见 changelog.d/migration-116.fixed.mdCPU 后端抛出NotImplementedError: lu_cpu not implemented for Half即 PyTorch 的 LU 分解在 CPU 上没有半精度实现MPS 后端直接触发硬断言Only MPSDataTypeFloat32 is supported这不是普通异常而是会直接中止进程危害更大。值得注意的是单通道引导路径灰度引导永远不会进入求解器因此完全不受影响——崩溃仅出现在guide_dim 1的场景这一结论在 tests/filters/test_guided.py 的回归测试文档字符串中有明确说明。隐藏的第二个 Bug张量 eps 参与 dtype 提升除了求解器本身缺乏半精度 kernel还存在一个容易被忽视的 dtype 提升陷阱。eps正则化参数既可以是普通 Python 浮点数也可以是torch.Tensor。当用户传入常见的epstorch.tensor(0.1)时该张量默认是float32构造系数矩阵A var_I _eps时float32的_eps会把float16的var_I提升promote为 float32而右侧项cov_Ip仍保持float16结果就是交给solve的一对操作数 dtype 不一致矩阵比右端项更宽torch.linalg.solve会拒绝这对不匹配的输入。也就是说即便先绕过半精度 LU kernel 的问题eps的 dtype 提升也会让求解器直接报错。这是多通道 半精度场景下同一崩溃的两个叠加根因。修复方案统一求解 dtypefloat32 求解后转回修复的核心思路非常克制在进入torch.linalg.solve之前把两个操作数统一到一个求解 dtype半精度一律提升到 float32求解完成后把结果 cast 回原 dtype。对应源码位于 kornia/filters/guided.pyif isinstance(eps, torch.Tensor): _eps torch.eye(C, deviceguidance.device, dtypeguidance.dtype).view(1, 1, 1, C, C) * eps.view(-1, 1, 1, 1, 1) else: _eps guidance.new_full((C,), eps).diag().view(1, 1, 1, C, C) A var_I _eps solve_dtype torch.promote_types(A.dtype, cov_Ip.dtype) if solve_dtype in (torch.float16, torch.bfloat16): solve_dtype torch.float32 a torch.linalg.solve(A.to(solve_dtype), cov_Ip.to(solve_dtype)).to(cov_Ip.dtype)关键设计决策源码注释中均有明确交代先提升、再判半精度先通过torch.promote_types求出两个操作数的共同 dtype若恰好是float16或bfloat16再抬升到float32。这样既覆盖了半精度输入也天然解决了eps为 float32 张量导致的 dtype 分裂——两个操作数最终被统一到同一个 dtype。刻意不使用_torch_solve_cast这类工具因为那类封装会把float32也提升到float64不仅改变默认路径的数值结果还会让每个像素都付出一次 float64 求解的代价。本次修复只在半精度时抬升float32/float64输入完全走原来的路径。Tensor.to在 dtype 已匹配时是 no-op因此全部输入均为 float32 或 float64 的调用求解前后不做任何转换行为与修复前逐位一致bit-identical。兼容性保证默认路径数值不变、编译路径不受影响修复对既有用户是透明的changelog 明确给出了三项兼容性保证见 changelog.d/migration-116.fixed.mdfloat32与float64结果与修复前逐位一致因为统一 dtype 的逻辑对非半精度是 no-op单通道引导不受影响该路径从不进入求解器算子仍可在fullgraphTrue下以单图single graph编译Tensor.to与条件提升均不破坏 TorchScript /torch.compile的图结构。这一点在 tests/filters/test_guided.py 的test_dynamo中有直接验证该测试对GuidedBlur含float与torch.Tensor两种eps形态使用torch_optimizer优化后与 eager 模式结果对比覆盖kernel_size为5/(5, 7)、subsample为1/2、separable为False/True的组合。回归测试失败率从 98 到 0本次修复配套了专门的回归测试test_multichannel_guidance_in_half_precision见 tests/filters/test_guided.py其测试策略值得借鉴仅在float16/bfloat16下运行其他 dtype 直接pytest.skip是纯粹针对求解器路径的回归测试使用border_typeconstant而非默认reflect因为默认反射边界需要半精度的reflection_pad2d而 CPU PyTorch 2.5.1 对 float16 没有该实现用constant可以确保测试真正落在求解器上排除边界填充的干扰同时覆盖eps0.1float与epstorch.tensor(0.1)tensor两种形态恰好对应上述两个根因断言输出 dtype 保持为原半精度、所有值有限torch.isfinite并以 float32 版本结果为基准用8 * torch.finfo(dtype).eps的容差做数值对比——注释说明由于求解在 float32 中进行结果误差应受周围半精度算术累积误差支配而非求解器自身精度。整体效果在 changelog 中有量化数据tests/filters/test_guided.py在--dtypefloat16,bfloat16下从98 失败 / 67 通过提升到169 全部通过。API 参考与实战用法函数式接口guided_blur完整签名见 kornia/filters/guided.py参数类型默认值说明guidanceTensor—引导图形状(B, C, H, W)通道数可为 1 或多通道inputTensor—待滤波输入形状(B, C, H, W)通道数可与 guidance 不同kernel_sizeint/tuple[int, int]—滤波核大小epsfloat/Tensor—正则化参数值越小保留的边缘越多可以是逐 batch 的张量border_typestrreflect边界填充模式constant、reflect、replicate、circularsubsampleint1Fast Guided Filter 下采样因子1表示不采样separableboolFalse用两次一维盒式滤波代替二维大窗口下可减少计算量函数内部会校验 guidance/input 的 batch 与空间维度一致KORNIA_CHECK系列断言见 kornia/filters/guided.py并根据 guidance 通道数自动分派到灰度或矩阵求解路径。最小可运行示例import torch import kornia # 函数式3 通道引导、4 通道输入直接在半精度下运行 guidance torch.rand(2, 3, 5, 5, dtypetorch.float16) input torch.rand(2, 4, 5, 5, dtypetorch.float16) output kornia.filters.guided_blur(guidance, input, kernel_size3, eps0.1) print(output.shape, output.dtype) # torch.Size([2, 4, 5, 5]) torch.float16 # bfloat16 同样支持 output_bf kornia.filters.guided_blur( guidance.to(torch.bfloat16), input.to(torch.bfloat16), 5, torch.tensor(0.1) ) # 模块式与 nn.Module 生态无缝集成 from kornia.filters import GuidedBlur blur GuidedBlur(kernel_size5, eps0.1, border_typereflect, subsample1, separableFalse) out_module blur(guidance, input)值得注意的细节张量 eps 现在安全修复后epstorch.tensor(0.1)float32与float16/bfloat16输入混用不会再触发 dtype 不匹配因为两个操作数会被统一到 float32 再求解参见 kornia/filters/guided.py 的注释。默认reflect边界在半精度下的边界情况回归测试特意改用constant以隔离求解器行为如果你的运行时如 CPU PyTorch 2.5.x缺少半精度reflection_pad2d遇到 float16 与reflect组合报错时可考虑更换border_type或升级 PyTorch 版本。数值精度参考多通道路径链式执行多次盒式滤波、一次C x C求解和一次einsum误差通常在几个 eps 量级bfloat16 因输入表示精度本身有限误差预算会略宽测试中为 bfloat16 放宽到4 * eps容差见 tests/filters/test_guided.py。小结changelog.d/migration-116.fixed.md记录的这次修复本质上是算子级半精度适配的一个范本先精确定位崩溃发生的 kerneltorch.linalg.solve无半精度 LU再排查 dtype 提升这类隐性问题最终用最小侵入的方式求解阶段统一到 float32、完成后转回同时解决两者并保证非半精度路径逐位不变、编译兼容、单通道路径零改动。修复后guided_blur/GuidedBlur在float16/bfloat16下配合多通道引导图即可稳定运行为移动端、MPS 等偏好半精度算力的部署场景扫清了障碍。【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址: https://gitcode.com/gh_mirrors/ko/kornia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
