Python statistics.quantiles 计算 P95 时的 n 参数与方法选择

用 Python 计算 P95 时，先把目标百分位换成 statistics.quantiles 的切点：P95/P99 都应使用 n=100，然后分别读取返回列表的下标 94 和 98。真正容易出错的是 method 的统计语义、小样本量，以及数据里混入 NaN。

官方文档：https://docs.python.org/3/library/statistics.html#statistics.quantiles

n=100 对应百分位切点

statistics.quantiles(data, n=4) 默认返回四分位数的 3 个切点。要计算百分位，n 应设为 100，此时函数返回 99 个切点：第 1 个代表 P1，最后一个代表 P99。因此 P95 读取 cuts[94]，P99 读取 cuts[98]。

这里的 n 是“切成多少个等概率区间”，不是要查询的百分位数。把 n=95 当成 P95 会改变切点网格，得到的并不是通常意义上的第 95 百分位。

from statistics import quantiles

# n=100 生成 P1 到 P99 的 99 个切点。
cuts = quantiles([12, 15, 18, 21, 25, 29, 33, 38, 42, 50], n=100)

# 返回列表从 P1 开始编号，因此 P95 对应下标 94。
p95 = cuts[94]
p99 = cuts[98]
print(p95, p99)

示例样本很少，切点仍然可以按插值规则给出数值，但不应把小样本的 P95 当成稳定的线上基线。参数映射正确，不等于统计结论已经足够可靠。

exclusive 与 inclusive 的选择

method 决定切点如何解释样本两端。默认的 exclusive 适合“从一个更大的总体中抽取的样本”，因为总体可能还有比当前最小值或最大值更极端的数据；inclusive 适合总体数据，或已知样本包含总体两端极值的场景。

两种方法都使用线性插值，但端点的百分位归属不同。不要为了让结果“更高”或“更低”而切换 method；应先回答数据代表什么，再把这个选择固定在指标定义中。

from statistics import quantiles

latencies = [80, 82, 85, 90, 94, 101, 108, 117, 132, 160]

# 同一批数据的两种统计语义不同，不能混用后再比较趋势。
sample_p95 = quantiles(latencies, n=100, method="exclusive")[94]
population_p95 = quantiles(latencies, n=100, method="inclusive")[94]
print(sample_p95, population_p95)

如果文章或监控面板需要跨批次对比，除了记录 P95 数值，还要记录 method、有效样本量和时间窗口。否则同名的 P95 可能来自不同的插值定义。

NaN 与样本数量怎么处理

官方文档特别提醒，quantiles() 会排序数据，NaN 的比较语义会让排序和结果变得异常。因此清理应发生在调用函数之前，而不是算完后再判断结果。

from math import isnan
from statistics import quantiles, StatisticsError

def p95(values, method="exclusive"):
    # 先统一为 float，并过滤 NaN，避免排序阶段出现不确定结果。
    clean = []
    for value in values:
        number = float(value)
        if not isnan(number):
            clean.append(number)

    # 空集合没有可定义的百分位，直接给调用方明确错误。
    if not clean:
        raise ValueError("没有可用的数值样本")

    try:
        # n=100 返回 P1 到 P99，P95 位于下标 94。
        return quantiles(clean, n=100, method=method)[94]
    except StatisticsError as exc:
        # 把统计库异常转换成更容易定位的业务错误。
        raise ValueError("有效样本量不足以支持当前百分位计算") from exc

有效样本量越接近 100，P95 越容易被少数样本和插值放大。工程上至少要把“有效样本量”作为结果旁边的字段保存；当样本不足时，可以延长采样窗口或延后展示指标，而不是静默发布一个看似精确的数字。

把参数封装成稳定的百分位函数

如果还需要 P99，可以把百分位作为受限参数传入，让索引转换只发生在一个地方。这样调用方不会把 P95 错写成 cuts[95]，也能统一校验 method。

from math import isnan
from statistics import quantiles, StatisticsError

def percentile(values, percentile=95, method="exclusive"):
    # 只接受 P1 到 P99，避免 n=100 的返回列表越界。
    if not 1 

落地时建议把 method、有效样本量、采样窗口和指标名称一起写进配置或结果元数据。下一次换实现库时，先对同一批固定输入做回归对照，确认新的百分位定义没有悄悄改变。

常见问题

为什么不是 n=95？ 因为 n 表示区间数量，P95 需要百等分后的第 95 个切点。

什么时候用 inclusive？ 当数据代表总体，或已知样本覆盖总体的最小值和最大值时更合适；普通抽样数据通常保留默认的 exclusive。

只有几十条数据能不能算 P95？ 可以得到插值结果，但样本量不足会让结果不稳定。把它当作探索性信号，并同时展示有效样本数，不要直接当作长期 SLO 基线。