` 形状校验修复：以 ValueError 确立数组规约 API 的输入契约)
Warp 中wp.utils.array_inner()形状校验修复以 ValueError 确立数组规约 API 的输入契约【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp本篇围绕 NVIDIA WarpGPU 加速仿真与机器学习框架在 1.17.0 发布周期中针对wp.utils.array_inner()的一项行为修复展开该函数现在会对形状不一致的输入数组抛出ValueError取代此前“接受等大小输入、或让形状不匹配的数组流入轴规约逻辑”的隐患行为。读完本文你将掌握array_inner()的完整签名与参数语义、修复前后的行为差异、底层校验顺序与错误信息格式以及仓库测试用例所固化的边界条件能够在自己的 Warp 代码中安全使用这一规约 API 并规避类似缺陷。变更来源与修复背景本修复记录在 changelog/1903.fixed.md原文为Makewp.utils.array_inner()reject input arrays with different shapes usingValueErrorinstead of accepting equal-size inputs or allowing mismatched arrays into axis-reduction logic.这是 Warp 采用的 Towncrier 变更片段fragment格式按 changelog/README.md 的约定1903对应 GitHub issue 编号fixed表示缺陷修复类别。同一发布周期内还包含与之配套的 changelog/1893.fixed.mdarray_sum()与array_inner()对负轴的一致性处理二者共同完善了数组规约 API 的输入语义。该修复属于用户可见的 API 行为变化调用方从“可能静默得到错误结果”变为“立即收到明确异常”。array_inner()的 Python 入口实现在 warp/_src/utils.py测试覆盖在 warp/tests/test_utils.py。array_inner()API 全貌签名、参数与返回值wp.utils.array_inner()计算两个数组的内积点积支持整数组扁平化求和或沿指定轴归约。其完整签名如下def array_inner( a: wp.array, b: wp.array, out: wp.array | None None, count: int | None None, axis: int | None None, ) - wp.array | float:各参数语义依据 warp/_src/utils.py 的 docstring 与实现参数含义默认行为 / 约束a第一个输入数组必须为float32/float64标量或向量如wp.vec3dtypeint32等整型会抛出RuntimeErrorb第二个输入数组必须与a形状、dtype、存储设备完全一致out输出数组为None时在设备上新建数组否则其 dtype 必须是a的标量类型向量 dtype 会取分量类型形状须与规约输出形状一致count参与规约的元素个数为None时取整数组元素数axisNone或a.shape[axis]axis规约轴负数从最后一个维度倒数如-1表示最后一维为None时对扁平化后的数组求单个内积返回值遵循以下规则axisNone且outNone返回 Pythonfloat标量其余情况返回out数组规约结果写入其中。典型的等形状标量/向量用法如下取自 warp/tests/test_utils.py 的验证逻辑import warp as wp a wp.array((1.0, 2.0, 3.0), dtypewp.float32, devicedevice) b wp.array((1.0, 2.0, 3.0), dtypewp.float32, devicedevice) print(wp.utils.array_inner(a, b)) # 14.0 # 显式输出数组out 的 dtype 必须是输入标量类型 result wp.empty(shape(1,), dtypewp.float32, devicedevice) wp.utils.array_inner(a, b, outresult) print(result.numpy()[0]) # 14.0 # 向量 dtypewp.vec3按分量逐维内积后求和 a wp.array((1.0, 2.0, 3.0), dtypewp.vec3, devicedevice) b wp.array((1.0, 2.0, 3.0), dtypewp.types.vector(3, float), devicedevice) print(wp.utils.array_inner(a, b)) # 14.0从底层实现看CPU 与 CUDA 路径分别派发到原生函数wp_array_inner_float_host/device与wp_array_inner_double_host/devicewarp/_src/utils.py轴规约时按a.strides[axis]/b.strides[axis]计算步长并逐元素累加warp/_src/utils.py。修复前的缺陷等大小输入与轴规约逻辑的隐患变更说明明确指出旧实现存在两类问题接受等大小输入旧逻辑可能仅按“元素总数相等”放行例如shape(2,)与shape(2,)之外(2, 3)与(6,)这类元素总数相同但维度结构不同的数组也会被当作合法输入。允许形状不匹配的数组进入轴规约逻辑当指定axis时规约需要按各维度 stride 寻址若两个数组形状不同如(2, 3)与(6,)轴索引含义、步长与输出形状推断都会错位可能产生越界访问、错误结果或难以定位的异常。这类缺陷的典型特征是“不报错但结果不可信”属于数值计算中最隐蔽的一类故障。修复的核心思路是在入口处强制形状一致把错误提前到 API 边界暴露。修复后的校验顺序与错误语义现在array_inner()在进入任何规约逻辑之前先执行形状一致性检查warp/_src/utils.pyif a.shape ! b.shape: raise ValueError(farray_inner() arguments must have the same shape, got {a.shape} and {b.shape})形状校验成功后后续校验按固定顺序执行形成完整的输入契约形状一致a.shape ! b.shape→ValueError本修复引入设备一致a.device ! b.device→RuntimeErrorA and b array storage devices do not matchdtype 一致types_equal(a.dtype, b.dtype)失败 →RuntimeError如float32 vs float64轴范围axis越界 →IndexErrorf{operation}() axis {axis} is out of bounds for an array with {ndim} dimensions由_normalize_array_reduction_axis()统一处理负轴warp/_src/utils.pycount 合法性与 APIC 捕获约束捕获期间count 0→RuntimeErrorcount _APIC_REDUCTION_INT_MAX→RuntimeError非空调用缺out或存在负 stride →NotImplementedError输出数组校验out的设备、dtype须为输入标量类型、形状逐一核对 → 不匹配抛出RuntimeError。需要特别说明的是形状检查发生在设备与 dtype 检查之前因此两个形状不同、其他属性也可能不同的数组会优先以ValueError暴露形状问题错误信息可读性最好。空数组边界形状相同时空数组合法count 0时axisNone且outNone返回0.0否则对out执行zero_()warp/_src/utils.py。注意测试覆盖了((0, 3), (3, 0), {})这种双方形状不同的空数组组合同样触发ValueError——形状不一致的判定不因元素数为 0 而放宽。测试固化异常路径的完整验证仓库测试 warp/tests/test_utils.py 中test_array_inner_error_shapes_mismatch直接验证本修复覆盖以下组合cases ( ((2,), (3,), {}), # 一维不同长度 ((2, 3), (6,), {}), # 元素总数相同但维度不同 ((2, 3), (6,), {axis: 1}), # 显式轴规约下的形状不匹配 ((2, 3), (6,), {count: 0}), # 即使 count0 也拒绝 ((0, 3), (3, 0), {}), # 空数组但形状不同 )每个用例断言抛出ValueError且消息精确匹配array_inner() arguments must have the same shape, got {a_shape} and {b_shape}这些用例的价值在于锁死了修复契约的边界元素总数相同(2, 3)vs(6,)不再被视为合法count0不会绕过校验空数组之间也必须形状一致。配套测试还覆盖了 dtype 不匹配float32 vs float64、outdtype 不匹配、out形状不匹配以及整型 dtype 不支持Unsupported data type: int32等相邻错误路径warp/tests/test_utils.py。与相邻变更的关系负轴处理与图捕获约束本修复与同一周期的两项变更共同构成array_inner()语义的完整闭环负轴一致性changelog/1893.fixed.mdarray_sum()与array_inner()对负轴如axis-1统一按axis % ndim归一化且越界时抛出IndexError由_normalize_array_reduction_axis()集中实现warp/_src/utils.py。CPU / CUDA 图捕获约束在 CPU 图捕获或apicTrue的 CUDA 图捕获下array_inner()的非空调用必须显式传入out否则抛出NotImplementedError负 stride、负 count、超 32 位整数上限的 count 以及未按标量类型对齐的地址/步长均被拒绝warp/_src/utils.py 与 docs/user_guide/runtime.rst。形状校验在捕获路径中同样最先执行保证捕获前后的行为一致。升级实践与排查建议如果你的代码在升级 Warp 1.17.0 后遇到ValueError: array_inner() arguments must have the same shape, got ...可按以下顺序排查核对a与b的shape属性不仅元素总数要相同维度结构与各维长度都必须一致(2, 3)与(6,)不再合法请用reshape或flatten显式统一形状。检查axis用法形状校验先于轴归一化执行形状修复后再确认axis在[-ndim, ndim)范围内。检查out约定out的 dtype 必须取输入 dtype 的标量类型向量 dtype 取其分量类型形状必须与规约输出形状axis对应维变为 1一致。图捕获场景若在ScopedCapture中使用确保非空调用显式传入out。将这类校验内置于 API 入口而非依赖规约内核是 Warp 提升数值健壮性的典型模式warp/tests/test_utils.py 中成体系的错误路径测试也为后续新增数组规约 API 提供了可复用的验证模板。【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
