• 计算机视觉
• 深度学习
• 图像处理

本篇技术指南聚焦 kornia 几何求解器模块中solve_quartic的一次关键缺陷修复：当输入为纯双二次方程（如x^4 - 16）时，旧实现对torch.clamp(..., min=0.0).sqrt()的依赖会让反向传播在sqrt(0)处产生inf进而污染为nan。读完本文，你将理解该 bug 的完整成因链、clamp边界梯度在 PyTorch 2.14 前后的行为差异、源码中"安全被开方数替换"（safe radicand substitution）的修复手法，以及对应的回归测试与同一系列的相邻修复。

背景：kornia 的多项式求根模块

kornia 在 kornia/geometry/solvers/polynomial_solver.py 中提供了面向几何估计的实根多项式求解器，包括：

• solve_quadratic：求解coeffs[0]x² + coeffs[1]x + coeffs[2] = 0，输入形状(B, 3)，输出(B, 2)；
• solve_cubic：求解coeffs[0]x³ + coeffs[1]x² + coeffs[2]x + coeffs[3] = 0，输入形状(B, 4)，输出(B, 3)；
• solve_quartic：求解coeffs[0]x⁴ + coeffs[1]x³ + coeffs[2]x² + coeffs[3]x + coeffs[4] = 0，输入形状(B, 5)，输出(B, 4)。

这三个函数在 kornia/geometry/solvers/init.py 中被导出，是 docs/source/geometry.solvers.rst 中 "Polynomial Solvers" 一节所收录的公开 API。solve_quartic基于 Ferrari 方法实现：先构造预解三次方程（resolvent cubic），调用solve_cubic求根，再用得到的y组合出R²与E，最终把四次的求根拆成两个二次方程分别交给solve_quadratic完成。

值得注意的是，这些求解器全程使用可微的张量运算，系数张量可以带requires_grad=True，梯度可以穿过整个求根流程——这正是本修复的意义所在：几何求解链路（例如通过预解方程、五点法本质矩阵求解等场景）可以在反向传播中把损失梯度回传到系数上。

问题：纯双二次方程的梯度爆炸

本次修复的触发案例是形如x⁴ - 16的纯双二次方程——即x³、x²、x项系数全部为零的四次方程。它有两个实根±2和两个复根±2i。

在 Ferrari 方法中，x⁴ - 16会让关键中间量R²精确落在 0 上（因为A = B = 0，R² = A²/4 - B + y = y，而对纯双二次方程取到使R²恰好为 0 的预解根）。旧代码随后执行：

R = torch.clamp(R_sq, min=0.0).sqrt()

这段代码看似在保护sqrt的输入不为负，但 changelog.d/+migration-044.fixed.md 明确指出：clamp(min=0).sqrt()并不保护它看起来在保护的梯度。原因有两层：

1. d(sqrt)/dx在 0 处无界：sqrt(x)在x = 0处的导数趋于+inf。即使输入恰好是 0，sqrt的反向也会产生inf梯度；
2. PyTorch 2.14 之前clamp的边界行为：在 torch < 2.14 上，clamp在边界处（输入等于min的取值）会把传入的梯度原样透传，而不是将其归零。

两者叠加，在 kornia 所支持的较老一半 torch 版本范围内（项目要求torch>=2.5.1，见 pyproject.toml），backward 会先得到inf，随后在后续计算中退化为nan（对应 issue #4229）。

为什么 clamp 的"保护"是假象

这里值得展开：torch.clamp(x, min=0.0)在数值上把负值截断到 0，确实保证了传入sqrt的值非负——前向是正确的。问题出在反向：

• 对x > 0的内部点，梯度正常；
• 对x = 0的边界点，sqrt自身的导数是inf；
• 在旧版 torch 上，clamp在边界处不抑制上游梯度，于是inf会直接穿过clamp到达R_sq，最终污染系数梯度。

也就是说，clamp修复的是"值域"问题，而梯度问题出在"定义域边界上的导数发散"，二者不是同一件事。仅靠clamp永远无法让sqrt(0)的梯度有限——必须让 autograd根本不曾在 0 处对sqrt求导。

值得一提的是，solve_quartic的文档字符串（kornia/geometry/solvers/polynomial_solver.py）明确记录了这种约定：在零被开方数边界处，backward 会抑制发散的sqrt导数以保证梯度有限，这个结果"有限但并非根的雅可比矩阵"（is not the root Jacobian），且前向值不受影响。

修复方案：安全被开方数替换

修复思路在文档中一句话点破："Both sites now substitute a safe radicand under thesqrt, assolve_quadraticin the same module already did."（两个位置现在都在sqrt下替换安全被开方数，同一模块中的solve_quadratic早已如此。）前向值保持不变（Forward values are unchanged）——这是该修复的重要约束：只修梯度，不改变求根结果。

模式原型：solve_quadratic 的既有做法

solve_quadratic在计算判别式delta的平方根时已经采用了这一模式（kornia/geometry/solvers/polynomial_solver.py）：

zero = torch.zeros_like(delta) mask_nonpositive = mask_negative | mask_zero sqrt_delta = torch.where( mask_nonpositive, zero, torch.sqrt(torch.where(mask_nonpositive, torch.ones_like(delta), delta)) )

其技巧在于：对非正判别式的通道，torch.where在取值上返回 0（等价于旧行为），但传给sqrt的实参被替换成1。于是sqrt的输入在所有通道上都 > 0，autograd 永远不会在 0 处对sqrt求导；那些不需要的通道上的梯度被torch.where的掩码自然截断。这样既保持了前向数值不变，又让梯度在边界处有限。

solve_quartic 的两处修复点

solve_quartic中有两处相同的隐患，本次一并修复：

第一处：R的计算（kornia/geometry/solvers/polynomial_solver.py）：

mask_R_sq_positive = R_sq > 0 R = torch.where( mask_R_sq_positive, torch.sqrt(torch.where(mask_R_sq_positive, R_sq, torch.ones_like(R_sq))), torch.zeros_like(R_sq), )

这正是x⁴ - 16这类纯双二次方程命中的位置：R_sq == 0时，旧代码的clamp(R_sq, min=0.0).sqrt()让梯度爆炸；新代码把 0 通道的实参替换为1，同时取值仍为 0。

第二处：E的模长计算（kornia/geometry/solvers/polynomial_solver.py）：

E_radicand = 0.25 * y * y - D mask_E_radicand_positive = E_radicand > 0 E_magnitude = torch.where( mask_E_radicand_positive, torch.sqrt(torch.where(mask_E_radicand_positive, E_radicand, torch.ones_like(E_radicand))), torch.zeros_like(E_radicand), )

这里通过常数项恒等式E² = y²/4 - D计算|E|，当被开方数精确为 0（例如(x²+1)(x²+4)这类无实根双二次方程的路径）时，同样需要安全替换。

代码注释还补充了版本相关的细节（kornia/geometry/solvers/polynomial_solver.py）：在 torch >= 2.14 上clamp已经会把边界梯度归零，因此这些梯度保护断言在基线 torch 上也能通过；真正承担判别任务的是2.5.1 与 2.9.1 的 CI 测试腿。

回归测试：不仅断言有限，还钉死数值

针对本次修复的测试位于 tests/geometry/solvers/test_polynomial_solver.py 的test_convention_gradient_is_finite_for_a_pure_biquadratic_4229。它用参数化方式覆盖了三个案例：

测试的关键设计有三点：

1. 断言梯度全有限：assert bool(torch.isfinite(c.grad).all())，这是修复的直接验收标准；
2. 钉死梯度数值：注释明确指出"只断言有限还不够——一个detach everything的伪修复同样能让梯度有限，但复现不出这些数字"。因此测试用assert_close精确比对c.grad[0]与expected_grad，防止"用切断图的方式掩盖问题"；
3. 钉死前向值：测试同时断言求根结果不变（例如±2、±1），确保"前向值不变"这一约束不被违反——如果一个修复靠改动数值来"绕开"梯度问题，这里会被抓住。

此外，同文件中的test_convention_gradient_does_not_leak_across_batch_rows_4334（tests/geometry/solvers/test_polynomial_solver.py）验证了批处理场景：四实根四次方程与x⁴ - 16混合成 batch 时，行间梯度不会互相污染，且混合 batch 中正常行的梯度与单独求解时完全一致。

同一模式修复的家族脉络

"clamp(min=0).sqrt()不保护梯度"在 kornia 中并非孤例，changelog 片段（changelog.d）记录了同一模式的系列修复，理解这条脉络有助于把握 kornia 对梯度数值稳定性的整体态度：

• +migration-044.fixed.md（本文主题）：solve_quartic的R与E两处sqrt边界，对应 issue #4229、PR #4339；
• +migration-075.fixed.md：solve_cubic在D <= 0分支对acos边界（x = ±1）的处理——d(acos)/dx = -1/sqrt(1-x²)同样在边界无界，通过"在 detached 副本上求值、在安全实参上求梯度"的方式绕开，solve_quartic经由预解三次方程继承该约定；该片段还披露了量化数据：在 20000 个随机实根四次方程上，10.7% 出现过非有限梯度或断开的计算图；
• +migration-049.fixed.md：solve_cubic/solve_quartic在混合 batch 中因D < 0行上的sqrt(D)参与计算图导致行间梯度污染（#4334、#4338）；
• +migration-059.fixed.md：_cdist用掩码实参替换dm.clamp(min=0.0).sqrt()，规避 PyTorch 2.5.1 与 2.9.1 上精确零距离对的NaN梯度；
• +migration-132.fixed.md：SIFTDescriptor等对sqrt(gx² + gy² + eps)的同类防护。

可以看出，kornia 的维护者在处理这类问题时形成了统一范式：用torch.where把"安全实参"喂给边界上导数发散的算子（sqrt、acos），同时用掩码保持前向取值不变——既保证梯度有限，又绝不改动前向数值契约。

结语

本次solve_quartic修复（changelog 片段 changelog.d/+migration-044.fixed.md）表面上只是两处几行的改动，背后却是对 PyTorch autograd 边界语义的细致把握：clamp保护值域、不保护导数，sqrt在 0 处的导数无界，而clamp在 torch 2.14 前后对边界梯度的处理存在行为差异。修复通过"安全被开方数替换"让 autograd 完全避开 0 点求导，同时用精确数值断言防止退化为"断图式"伪修复。对于在几何求解链路中需要反向传播的开发者，这一模式——以及配套的 gradcheck、数值钉死测试——是值得直接复用的工程范本。

• 计算机视觉
• 深度学习
• 图像处理