在 Numba 中，不能在 @njit 函数内用 isinstance 进行运行时类型判断；正确方式是通过 @nb.extending.overload 在编译期为不同参数类型生成专用函数，从而实现高性能、类型安全的分发逻辑。
在 numba 中，不能在 `@njit` 函数内用 `isinstance` 进行运行时类型判断；正确方式是通过 `@nb.extending.overload` 在编译期为不同参数类型生成专用函数，从而实现高性能、类型安全的分发逻辑。
Numba 的 JIT 编译模型要求类型信息在编译期（而非运行时）确定。因此，像 isinstance(indices, nb.int64[:]) 这类运行时检查不仅不被支持，还会触发警告甚至编译失败——因为 nb.int64[:] 是 Numba 的类型对象（如 nb.types.Array(dtype=nb.int64, ndim=1, layout='C')），而非 Python 运行时实例类型。isinstance 在 @njit 函数中属于实验性功能，且语义与纯 Python 不同，应严格避免。
✅ 正确做法：使用 @nb.extending.overload 实现编译期类型分发
该机制允许你为同一 Python 函数名注册多个底层实现，Numba 会根据调用时的实际参数类型（在编译阶段推断）自动选择最匹配的实现，真正实现“零开销多态”。
以下是一个完整、可直接运行的示例（适配 Numba ≥ 0.59）：
import numba as nb
import numpy as np
# 纯 Python 回退实现（仅用于类型推断和文档）
def test_dispatch(X, indices):
if isinstance(indices, (int, np.integer)):
return test_dispatch_scalar(X, indices)
elif (isinstance(indices, np.ndarray) and
indices.ndim == 1 and
np.issubdtype(indices.dtype, np.integer)):
return test_dispatch_vector(X, indices)
else:
raise TypeError(f"Unsupported indices type: {type(indices)}")
# 标量索引分支：返回 shape=(3,) 向量
def test_dispatch_scalar(X, indices):
ref_pos = np.empty(3, dtype=np.float64)
ref_pos[:] = X[:, indices]
return ref_pos
# 向量索引分支：返回 shape=(3, len(indices)) 矩阵
def test_dispatch_vector(X, indices):
ref_pos = np.empty((3, len(indices)), dtype=np.float64)
ref_pos[:, :] = X[:, indices]
return ref_pos
# 关键：Numba 类型重载注册
@nb.extending.overload(test_dispatch)
def test_dispatch_overload(X, indices):
# 编译期类型检查：indices 是整数标量类型？
if isinstance(indices, nb.types.Integer):
return test_dispatch_scalar
# indices 是一维整数数组类型？
elif (isinstance(indices, nb.types.Array) and
indices.ndim == 1 and
isinstance(indices.dtype, nb.types.Integer)):
return test_dispatch_vector
# 其他类型不支持（编译时报错，而非运行时）
else:
raise TypeError("test_dispatch only supports scalar int or 1D integer array indices")
# 用户调用入口：保持简洁、类型透明
@nb.njit
def example_usage():
X = np.random.rand(3, 100) # shape=(3,100)
# 自动分发到 scalar 版本
result1 = test_dispatch(X, 42)
# 自动分发到 vector 版本
result2 = test_dispatch(X, np.array([10, 20, 30], dtype=np.int64))
return result1, result2
? 关键注意事项：
- ✅ @overload 函数本身不执行任何计算，它只在编译期返回对应实现函数（如 test_dispatch_scalar），因此必须确保返回的是已定义的、@njit 兼容的函数。
- ✅ 类型检查必须使用 nb.types.*（如 nb.types.Integer, nb.types.Array），而非 nb.int64 等实例类型别名——后者是类型构造器，不是类型对象。
- ⚠️ 避免过度约束具体位宽（如硬编码 nb.types.int64）：使用 nb.types.Integer 可兼容 int32/int64/uint32 等所有整数类型，提升泛化能力。
- ⚠️ np.ndarray 的 dtype 和 ndim 在 Numba 类型系统中需通过 indices.dtype 和 indices.ndim 访问，而非 .dtype 属性本身（后者是 NumPy 对象，在编译期不可用）。
- ❌ 不要尝试在 @njit 内部用 isinstance(..., nb.types.X) —— 这些类型对象无法在运行时实例化或比较。
? 总结：Numba 的类型分发本质是编译期代码生成，而非运行时分支。@overload 是官方推荐、稳定且高性能的解决方案；而 isinstance + @njit 属于误用模式，应彻底摒弃。合理利用 @overload，既能保持接口简洁，又能获得接近手写 C 的执行效率。
