Kornia 立体视差指标半精度修复：float16/bfloat16 下的累加溢出与精度损失问题解析

计算机视觉人工智能深度学习图像处理【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址https://gitcode.com/gh_mirrors/ko/kornia点击查看免费下载本篇技术指南围绕 Kornia 仓库 changelog.d/3931.fixed.md 记录的一项修复展开kornia.metrics模块中的视差disparity指标在float16/bfloat16输入下因归约累加发生在半精度 dtype 中导致mean_absolute_disparity_error、root_mean_squared_disparity_error、mean_bad_pixel_error在图像尺度的误差图上返回inf。本文将从问题成因、修复实现float32 累加器 dtype 提升、测试验证到实际使用注意事项给出完整解析读者可据此理解 Kornia 立体视觉指标在混合精度训练 / 推理场景下的数值行为并掌握安全使用这些指标的正确姿势。一、背景kornia.metrics 中的立体视差指标Kornia 的 kornia/metrics/init.py 明确说明该模块提供 PSNR、SSIM、endpoint error 与 stereo disparity error 等指标。其中视差disparity子模块位于 kornia/metrics/disparity.py对外导出四个指标函数函数定义说明mean_absolute_disparity_errorMAE (1/V)·ΣD_p − D^gt_p预测视差图与真值之间的平均绝对误差root_mean_squared_disparity_errorRMSE √((1/V)·Σ(D_p − D^gt_p)²)均方根误差对大幅误差更敏感mean_bad_pixel_errorBad_τ (1/V)·Σ[|D_p − D^gt_p| τ]超过绝对阈值 τ默认 3.0 px的坏像素占比对应 Middlebury 基准的坏像素百分比以 [0,1] 分数而非百分比表达kitti_d1_error绝对误差 τ_abs且相对误差 τ_rel 的离群点占比KITTI 2015 立体基准的 D1 指标额外引入相对判据见 changelog.d/3931.added.md关闭 issue #3758这些函数共享同一套输入约定input预测视差图、target真值视差图形状与input一致、可选的valid_mask可广播到input形状、非零值标记参与评估的像素、以及reductionnone|mean|sum。对应的 API 文档页为 docs/source/metrics.stereo.rst。二、缺陷本质为什么半精度下指标会返回 inf本次修复针对的问题核心是归约reduction累加发生在输入张量的半精度 dtype 中。这在图像尺度的误差图上会造成两类数值灾难1. float16 求和饱和上限 65504float16可表示的最大有限值为65504。对视差误差图例如 320×240 的稠密图数万个像素项求和时只要项数足够多、误差足够大累加值一旦越过 65504 便饱和为inf最终mean归约也返回inf。这正是原变更记录所指的 no longer returninfon an image-sized map。2. bfloat16 求和精度损失约 0.5% / 10 万项bfloat16虽然指数范围与 float32 相同但只有 8 位尾数。对 10 万项求和时累积舍入误差约丢失 0.5%。肉眼看似微小但在 3D 重建、自动驾驶立体匹配的误差统计中会让 MAE / 坏像素率出现系统性偏差。3. RMSE 平方先行溢出300 px 误差即饱和root_mean_squared_disparity_error的病灶比单纯累加更隐蔽——它在修复前先以输入 dtype 计算平方。300 px 的视差误差平方后是 90000已经超过 float16 上限 65504于是逐像素误差图在归约尚未开始前就整体饱和成inf。测试 tests/metrics/test_disparity.py 中的test_large_error_does_not_saturate_the_square注释精确记录了这个边界300² 90000 is past the float16 ceiling。4. 混合 dtype 行为不一致当input与target是不同 dtype如 float32 与 float64 混合时修复前各指标返回 dtype 不一致mean_absolute_disparity_error已按提升promoteddtype 返回而其余指标跟随input的 dtype破坏了一致性约定见测试注释 tests/metrics/test_disparity.py。三、修复实现float32 累加器与 dtype 提升修复的核心是 kornia/metrics/disparity.py 中的两个内部函数_check_disparity_inputs与_reduce_disparity_error。1. 统一的 float32 累加路径_reduce_disparity_errorkornia/metrics/disparity.py实现了统一的修复策略out_dtype error.dtype acc_dtype torch.promote_types(out_dtype, torch.float32) if valid_mask is not None: # Zeroing the invalid pixels keeps the shape static. Indexing with the mask would make the # output shape depend on the mask values, which torch.compile cannot trace in a full graph. error torch.where(valid_mask, error, 0) if reduction mean: count error.numel() if valid_mask is None else valid_mask.sum() error (error.sum(dtypeacc_dtype) / count).to(out_dtype) elif reduction sum: error error.sum(dtypeacc_dtype).to(out_dtype) elif reduction none: pass要点拆解累加 dtype 提升通过torch.promote_types(out_dtype, torch.float32)计算累加器 dtype。对float16/bfloat16输入提升为float32对 float32/float64 输入则保持原 dtype不改变原有精度行为。显式指定sum(dtype...)强制累加发生在acc_dtype避免 torch 内部按输入 dtype 做缩减求和。结果回写输入 dtype归约完成后用.to(out_dtype)转回误差图的 dtype保证指标返回输入 dtype的既有约定对mean而言这是准确的对sum则有下述边界。torch.where而非索引对掩码像素置零而非用布尔索引收缩形状保持张量形状静态化使得整条计算图可被torch.compile追踪测试中均有test_dynamo验证编译等价性。2. RMSE 的平方前移修复root_mean_squared_disparity_errorkornia/metrics/disparity.py在进入归约前就先把输入提升到累加 dtype 再平方out_dtype torch.promote_types(input.dtype, target.dtype) acc_dtype torch.promote_types(out_dtype, torch.float32) error (input.to(acc_dtype) - target.to(acc_dtype)) ** 2 return _reduce_disparity_error(error, mask, reduction).sqrt().to(out_dtype)这样 300 px 的平方90000在 float32 中毫无压力平方根在回写前把数值拉回原范围。注意这里out_dtype是对input与target做提升的结果为混合 dtype 一致性修复打好了基础。3. 输出 dtype 的统一规则修复后模块内每个指标对混合 dtype 输入对都返回torch.promote_types(input.dtype, target.dtype)float32×float64 → float64float16×float32 → float32统一了此前mean_absolute_disparity_error独树一帜的局面。这条约定被固化在测试test_convention_result_dtype_is_the_promoted_onetests/metrics/test_disparity.py中。4. 整数视差图拒绝与 dtype 修复配套_check_disparity_inputskornia/metrics/disparity.py新增了对整数输入的显式校验由于归约在 float32 累加后回写会截断整数如 0.5 被截断为 0整数视差图会返回貌似合理实则错误的结果因此现在直接抛出异常并提示先.float()。注释特别指出 KITTI 以 uint16 PNG 形式分发视差图torch.from_numpy(imread(...))拿到整数张量是真实场景。测试test_convention_integer_disparity_maps_are_rejectedtests/metrics/test_disparity.py逐指标验证了该守卫及浮点路径的正确值。四、测试验证大图、大误差与混合 dtype测试/metrics/test_disparity.py 为本修复提供了系统性证据关键用例包括图像尺度掩码归约test_large_masked_reductionL238-L243_large_masked_inputs构造了 10 万有效像素 2 万无效像素的掩码对L39-L55其中 3/4 的有效像素偏离 100 px、掩码外的尾部像素离谱地偏离 10000 px——足以压爆半精度累加器同时检验掩码像素绝不会泄漏进归约。MAE 期望值恰为 75.0RMSE 期望值为 √(0.75·100²) ≈ 86.60且断言actual.dtype dtype返回值仍保持输入 dtype。平方不饱和test_large_error_does_not_saturate_the_squareL318-L327300 px 误差在修复前必然饱和修复后mean与none均精确返回 300.0。空掩码语义L207-L216valid_mask全为 False 时mean返回nansum返回 0.0——这是文档化的边界行为。混合 dtypetest_convention_result_dtype_is_the_promoted_onefloat16×float32 → float32、float32×float64 → float64后端不支持 float64 时跳过如 MPS通过运行时探测_can_hold而非硬编码设备名。torch.compile 兼容每个指标均有test_dynamo用例验证优化前后结果一致。五、实战注意事项与边界基于源码注释与测试使用这些指标时有几个关键边界需要留意sum归约在半精度下仍可能饱和修复保证mean在图像尺度上准确但sum结果会回写输入 dtype——float16 的求和总数超过 65504 依旧得到inf。若需要超大总量文档建议改用reductionnone取回逐像素误差图在更宽的 dtype 中自行求和见 kornia/metrics/disparity.py 的 docstring 注释。坏像素与 D1 是指标型指标二者由比较运算构成无有效梯度输出不携带requires_grad不能当作损失函数使用而mean_absolute_disparity_error可正常回传梯度。测试 L133-L144 明确固化了这一差异。KITTI D1 的数值语义D1 要求绝对误差 3.0且相对误差 0.05 同时成立真值视差为 0 的像素相对误差非有限会退化为仅按绝对阈值判定KITTI 官方将这些像素标记为无效因此应通过valid_mask排除。此外nan会因比较恒为假而被计为内点非有限像素应显式掩码。mean_bad_pixel_error与 KITTI D1 不同前者是 Middlebury 风格的纯绝对阈值坏像素率后者才是 KITTI 排行榜口径两者不要混用。输入必须是浮点整数视差图如 KITTI 的 uint16 PNG 直接读入会直接抛错请先转换例如.float()。批量是池化而非逐图平均mean归约把批内所有图像的全部有效像素合并成一个比率与 KITTI devkit 的累加口径一致而非逐图 D1 再取平均各图有效像素数不等时两者结果不同。六、总结本次修复changelog.d/3931.fixed.md以float32 累加器 dtype 提升 平方前移三管齐下解决了kornia.metrics视差指标在float16/bfloat16下的三类问题float16 求和饱和为inf、bfloat16 累加精度损失、RMSE 平方先行溢出同时统一了混合 dtype 输入的返回类型。修复过程在 kornia/metrics/disparity.py 中落地由 tests/metrics/test_disparity.py 以 10 万像素大图、300 px 大误差、混合 dtype 及 torch.compile 等价性等用例全面验证。对在混合精度AMP/bf16训练或部署中评估立体匹配模型的开发者而言理解这套累加器语义是避免拿到inf/失真指标的关键。赞分享计算机视觉人工智能深度学习图像处理【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址https://gitcode.com/gh_mirrors/ko/kornia点击查看免费下载相关推荐Kornia 修复 ConvQuadInterp3d 半精度梯度溢出Cramer 求解器在 float16 下的精度提升方案Kornia 修复 ConvQuadInterp3d 半精度梯度溢出Cramer 求解器在 float16 下的精度提升方案 导读 ConvQuadInter计算机视觉深度学习人工智能图像处理DocsGPT 开源贡献指南仓库结构、前后端编码规范与测试验证工作流DocsGPT 开源贡献指南仓库结构、前后端编码规范与测试验证工作流 本文为 DocsGPT一个集 Agent 构建、深度研究、文档分析与企业搜索于一体的私计算机视觉深度学习人工智能图像处理Kornia 修复 bbox_to_mask 半精度精度问题float16/bfloat16 大图掩码像素网格坍缩与 float32 网格方案Kornia 修复 bbox_to_mask 半精度精度问题float16/bfloat16 大图掩码像素网格坍缩与 float32 网格方案 导读 本文围绕计算机视觉深度学习人工智能图像处理上一篇Linux用户的终极梦想在桌面原生运行Android应用的完整指南下一篇Linux桌面运行Android应用的终极指南Waydroid完整解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考