np.average()的weights参数必须与数据在指定轴上长度严格一致：一维时等长，二维时沿axis=0需等于行数、axis=1需等于列数；权重须为数值型一维数组，无NaN，且不自动归一化。
np.average() 的 weights 参数必须和数据同长
很多人传入 weights 时发现报错 ValueError: weights must be 1-D 或形状不匹配，其实核心就一条：np.average() 要求 weights 的长度必须严格等于被加权数组的对应轴长度。比如对一维数组计算，weights 就得是一维且长度一致；对二维数组沿 axis=0 计算，weights 长度就得等于行数。
常见错误是拿列名列表、布尔掩码或 DataFrame 的某列直接当 weights 用，没意识到它必须是数值型、无缺失、长度精准匹配的数组。
- 确保
weights是numpy.ndarray或可转为一维数组的序列（如list、pd.Series） - 若从
pd.DataFrame取权重列，先用.to_numpy()或.values提取，避免隐式索引对齐干扰 - 检查是否有
NaN——np.average()遇到NaN权重会直接报错，需提前用np.nan_to_num()或布尔索引过滤
pandas.Series.mean() 不支持直接加权，得用 np.average + apply
Series.mean() 和 DataFrame.mean() 都没有 weights 参数，这是常被误以为“Pandas 更方便”的坑点。真要按行/列加权平均，得绕一层：用 np.average() 手动套进去，再配合 .apply() 或 axis 控制方向。
典型场景是按样本重要性给每行一个权重，算各列的加权均值——这不是 df.mean(weights=...) 能解决的，Pandas 没这个接口。
立即学习“Python免费学习笔记（深入）”；
- 按列加权（每列一个权重）：用
np.average(df, axis=0, weights=w)，其中w长度 = 列数 - 按行加权（每行一个权重）：用
np.average(df, axis=1, weights=w)，其中w长度 = 行数 - 若权重存在 DataFrame 某列（如
'weight'），先提取w = df['weight'].to_numpy()，再删掉该列参与计算，避免维度错乱
权重归一化不是必须的，但影响结果解释性
np.average() 内部不自动归一化权重，它只做分子分母同步加权求和：sum(x_i * w_i) / sum(w_i)。所以 [1, 2, 3] 和 [10, 20, 30] 作为 weights 会给出完全相同的结果。
这意味着：如果你关心的是“相对重要性”，权重是否缩放到和为 1 完全无所谓；但如果你后续要把加权结果和其他未归一化的统计量（比如原始均值）对比，或者要导出权重本身作解释，那手动归一化就很有必要。
- 归一化写法：
w_norm = w / w.sum()，再传给weights=w_norm - 不归一化更省一次除法，在纯计算链路中（比如损失函数内部）反而更高效
- 注意：如果
w.sum() == 0，无论归一与否都会触发ZeroDivisionError，需提前校验
缺失值处理：nan_policy 决定行为，但 pandas 默认跳过
np.average() 默认遇到 NaN 数据就直接报错，而 pd.Series.mean() 默认 skipna=True。两者混合使用时，这个差异极易引发意外中断。
比如你把含 NaN 的 Series 直接喂给 np.average()，不加干预就会崩；但换成 Series.dropna().values 又可能让权重数组长度不匹配——这才是最麻烦的耦合点。
- 安全做法：统一用
np.average(x, weights=w, returned=True)并设nan_policy='omit'（需 NumPy ≥ 1.20） - 老版本 NumPy 只能手动对齐：用
mask = ~np.isnan(x) & ~np.isnan(w)同时过滤数据和权重 - Pandas 用户更自然的做法是：先
df = df.dropna(subset=['data_col', 'weight_col'])，再传值，避免在 numpy 层做 mask 对齐
权重对齐这件事，看着只是长度匹配，实际牵扯索引、缺失、类型、归一化四层对齐逻辑。少检查任何一层，运行时才暴露，debug 成本远高于写的时候多加两行校验。
