不能直接用scipy.spatial.distance.pdist的自定义度量，因其要求函数仅接收两个一维数组并返回标量，无法支持带参数（如权重、掩码）或需向量化批量计算的实际需求；硬套lambda会导致纯Python循环、性能骤降。
为什么不能直接用 scipy.spatial.distance.pdist 的自定义度量？
因为 pdist 要求自定义函数必须接收两个一维数组并返回标量，但很多实际场景（比如加权欧氏、带掩码的余弦）需要额外参数或结构化输入。硬塞进 lambda 容易出错，且无法向量化——每次调用都是纯 Python 循环，性能断崖式下跌。
正确做法是：用 NumPy 写一个支持广播的向量化函数，不依赖 scipy 的回调机制。
- 避免用
lambda x, y: np.linalg.norm(x - y * weight)这类写法——它无法处理批量点对计算 - 输入应为二维数组
X（shape(m, d)）和Y（shape(n, d)），输出为(m, n)距离矩阵 - 所有运算必须基于 NumPy 原生广播，禁用
for循环或np.apply_along_axis
如何实现带权重的欧氏距离（weighted_euclidean）？
核心是把权重向量融入差值平方的逐元素计算中，再沿特征轴求和。不能先算普通欧氏再乘权重——那不是加权距离。
def weighted_euclidean(X, Y, weight=None):
if weight is None:
weight = np.ones(X.shape[1])
# 确保 weight 是列向量，以便广播到 (m, d) 和 (n, d)
weight = np.asarray(weight).reshape(1, -1)
diff = X[:, None, :] - Y[None, :, :]
return np.sqrt(np.sum((diff * weight) ** 2, axis=2))注意：X[:, None, :] 和 Y[None, :, :] 触发广播，生成 shape (m, n, d) 的差值张量；weight 必须 reshape 成 (1, d) 才能正确广播相乘。
立即学习“Python免费学习笔记（深入）”；
- 如果
weight是标量，要显式转成np.full(d, weight)，否则广播会出错 - 若
X和Y维度不一致（d不同），NumPy 会直接报ValueError，别指望它自动截断 - 内存敏感场景下，可改用
np.einsum替代np.sum(... ** 2)，减少临时数组
如何安全实现带缺失值掩码的余弦距离（masked_cosine）？
标准余弦相似度在含 NaN 时会传播错误结果。必须显式忽略无效维度，且分母不能为零——这是最容易被忽略的崩溃点。
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
def masked_cosine(X, Y, mask=None):
# mask shape: (d,)，True 表示该维度参与计算
if mask is None:
mask = np.ones(X.shape[1], dtype=bool)
X_masked = X[:, mask]
Y_masked = Y[:, mask]
# 分子：点积（仅有效维度）
dot = X_masked @ Y_masked.T
# 分母：各自 L2 范数（仅有效维度）
norm_X = np.linalg.norm(X_masked, axis=1, keepdims=True)
norm_Y = np.linalg.norm(Y_masked, axis=1, keepdims=True)
# 防除零：将零范数对应位置设为 1，使 cos=0（正交）
norm_X = np.where(norm_X == 0, 1.0, norm_X)
norm_Y = np.where(norm_Y == 0, 1.0, norm_Y)
cos_sim = dot / (norm_X * norm_Y.T)
return 1 - cos_sim关键点在于：不使用 np.nan_to_num 或 np.ma，因为它们无法控制“按维度掩码”，而真实业务中往往是某些特征列整体失效（如传感器离线），不是随机缺失。
-
mask必须是布尔数组，传入int或float会静默失败 - 若
X或Y中某样本在所有掩码维度上全为零，norm_X为 0，此时余弦无定义——我们主动设为 0 相似度（即距离为 1），而非让nan污染后续聚类 - 该函数不处理
X或Y内部含NaN的情况；如有，需前置用np.nanmean填充或剔除
何时必须用 numba.jit 加速？
当距离函数含条件逻辑（如分段权重、阈值截断）或非标准范数（如 L1.5）导致无法用纯广播表达时，NumPy 向量化失效，numba 是唯一实用选择。
例如实现“超阈值惩罚欧氏”：差值绝对值超过 thresh 时，平方项额外乘 penalty：
from numba import jit
@jit(nopython=True)
def penalized_euclidean(X, Y, thresh=1.0, penalty=2.0):
m, d = X.shape
n = Y.shape[0]
dist = np.empty((m, n))
for i in range(m):
for j in range(n):
s = 0.0
for k in range(d):
diff = abs(X[i, k] - Y[j, k])
if diff > thresh:
s += (diff ** 2) * penalty
else:
s += diff ** 2
dist[i, j] = np.sqrt(s)
return dist注意：@jit(nopython=True) 是硬性要求，否则退化为 Python 解释执行；所有变量类型必须可推导（不能用 list 或 dict）；输入必须是 np.ndarray，不能是 pd.Series。
- 首次调用会编译，后续才快；小规模数据（
m,n ）可能比纯 NumPy 还慢 - 无法调试（
print无效），出错信息晦涩，建议先写 Python 版本验证逻辑 - 不支持
np.einsum、np.where复杂用法，循环展开是唯一可控手段
实际项目里，90% 的定制距离需求靠前三个技巧就能覆盖。真正卡住的，往往不是算法，而是没意识到 mask 该用布尔数组，或者把 weight 当标量传却忘了 reshape。
