KBEngine 内嵌 Python 的 random 模块指南:伪随机数生成、分布与可复现采样

原创2026-10-17 19:32:382,326 阅读
文章标签:游戏开发后端

KBEngine 内嵌 Python 的 random 模块指南:伪随机数生成、分布与可复现采样

导读:KBEngine 在 kbe/src/lib/python 下内置了完整的 Python 3.7.3 运行时(见 Include/patchlevel.h 中 PY_VERSION "3.7.3"),本文以其标准库文档 kbe/src/lib/python/Doc/library/random.rst 为骨架,系统讲解 random 模块的完整能力:从 Mersenne Twister 核心生成器、种子与状态管理,到整数/序列函数、13 种实数分布、SystemRandom,再到可复现性与统计模拟配方。读完你可以在 KBEngine 的服务器脚本(基于内嵌 Python 编写,SDK 模板见 kbe/res/sdk_templates/server/python_assets)中正确使用 import random 完成掉落抽奖、均匀/加权采样、正态分布属性生成等游戏逻辑,同时避开"伪随机数不可用于安全场景"的常见陷阱。

模块总览:伪随机数生成器的能力边界

random 模块实现了各种分布的伪随机数生成器(pseudo-random number generators)。从功能面看:

  • 整数:从某个区间内做均匀选择;
  • 序列:均匀选取一个随机元素、原地生成列表的随机排列(permutation)、以及无放回(without replacement)的随机抽样;
  • 实数轴:提供均匀(uniform)、正态(Gaussian)、对数正态(lognormal)、负指数(negative exponential)、伽马(gamma)、贝塔(beta)等分布;
  • 角度分布:提供 von Mises 分布。

几乎所有模块函数都依赖基础函数 random(),它生成半开区间 <a href="https://link.gitcode.com/i/f2ee3363c940e99b3c9ccdc7e7740666" target="_blank">0.0, 1.0) 内的均匀随机浮点数。Python 使用 Mersenne Twister 作为核心生成器:产生 53 位精度浮点数,周期为 2**19937-1;其 C 底层实现(仓库内位于 [kbe/src/lib/python/Modules/_randommodule.c,基于 MT19937,核心例程 random_random() 即原作者代码中的 genrand_res53(),种子扩展函数为 init_by_array())既快又线程安全。Mersenne Twister 是现存被测试最充分的随机数生成器之一。然而,由于它完全确定性(deterministic),并不适合所有用途,尤其完全不适用于密码学用途。

模块导出的函数实际上是隐藏的 random.Random 类实例(源码见 kbe/src/lib/python/Lib/random.py 末尾 _inst = Random() 与后续 seed = _inst.seed、random = _inst.random 等批量绑定)的绑定方法。你可以自行实例化 Random 来获得不共享状态的独立生成器;也可以子类化 Random 以接入自研的生成器,此时需重写 random、seed、getstate、setstate 四个方法,可选地提供 getrandbits——有了它,randrange 就能在任意大的区间上做选择。

安全警告(原文档明确给出):本模块的伪随机生成器不得用于安全用途。安全或密码学用途请改用 secrets 模块(仓库内置实现见 kbe/src/lib/python/Lib/secrets.py,它内部正是从 random 导入 SystemRandom)。

记账函数(Bookkeeping):seed / getstate / setstate / getrandbits

seed(a=None, version=2)

初始化随机数生成器:

  • 省略参数或传 None:使用当前系统时间;如果操作系统提供了随机性来源,则优先使用系统来源(详见 os.urandom,仓库实现见 kbe/src/lib/python/Lib/os.py)。
  • 参数为 int:直接使用该整数作为种子。
  • version 2(默认):str、bytes、bytearray 会被转换为 int 且使用其全部比特位。从 Lib/random.py 的实现看,version 2 会先将字符串编码后拼接 SHA-512 摘要再按大端转为整数,保证种子充分分散。
  • version 1:为复现旧版本 Python 的随机序列而保留,对 str/bytes 生成更窄范围的种子(见 Lib/random.py,其算法为 x = ((1000003 * x) ^ c) & 0xFFFFFFFFFFFFFFFF 式迭代)。
  • 该函数自 Python 3.2 起升级为 version 2 方案。

getstate() / setstate(state)

getstate() 返回一个捕获生成器当前内部状态的对象;该对象可传给 setstate() 以将生成器状态恢复到调用 getstate() 时的样子。这常用于保存/恢复随机序列,例如回放(replay)一局随机过程。

getrandbits(k)

返回一个包含 k 个随机比特的 Python 整数。Mersenne Twister 生成器提供该方法,其他生成器也可作为可选 API 提供。getrandbits 可用时,randrange 能处理任意大的区间(无需依赖浮点数精度)。

整数函数:randrange 与 randint

randrange(start, stop[, step]) / randrange(stop)

从 range(start, stop, step) 中随机选取一个元素,等价于 choice(range(start, stop, step)),但不会真的构建 range 对象,因此内存开销更小。位置参数的语义与 range 完全一致;原文档特别提醒:不要使用关键字参数,因为函数可能以意料之外的方式使用它们。Python 3.2 起 randrange 对等概率分布的处理更精细——旧式 int(random()*n) 写法可能产生轻微的不均匀分布。

randint(a, b)

返回满足 a <= N <= b 的随机整数 N,是 randrange(a, b+1) 的别名。注意与 randrange 不同,randint 的右端点 b 是闭区间包含的。

序列函数:choice / choices / shuffle / sample

choice(seq)

从非空序列 seq 中返回一个随机元素;若 seq 为空则抛出 IndexError。

choices(population, weights=None, *, cum_weights=None, k=1)

返回从 population 中有放回抽取的 k 个元素组成的列表;空 population 抛出 IndexError。支持相对权重 weights 与累计权重 cum_weights 两种加权方式:

  • 例如相对权重 [10, 5, 30, 5] 等价于累计权重 [10, 15, 45, 50]。
  • 内部实现上,相对权重会先被转换为累计权重再采样(源码见 Lib/random.py,等权重分支直接用 population[int(random() * total)],加权分支则用 bisect 在累计权重序列上二分定位),所以直接提供 cum_weights 可以省去转换开销;cum_weights 也可用 itertools.accumulate 现算。
  • 都不指定时按等概率选取;weights 必须与 population 等长;同时指定 weights 和 cum_weights 会抛出 TypeError。
  • 权重可以是能与 random() 返回的 float 互操作的任意数值类型(整数、浮点数、fractions,不含 decimals)。
  • 细节差异:相同种子下,等权重的 choices 通常与反复调用 choice 产生不同序列——choices 用浮点运算保证内部一致性与速度,而 choice 默认用整数运算并重复选取以避免舍入误差带来的微小偏差。
  • 该函数自 Python 3.6 加入。

shuffle(x[, random])

原地打乱序列 x。可选参数 random 是一个返回 [0.0, 1.0) 随机浮点数的零参函数,默认即 random()。若想打乱不可变序列并返回新的打乱列表,改用 sample(x, k=len(x))。一个容易忽略的边界:即使 len(x) 很小,x 的排列总数也可能很快超过大多数随机数生成器的周期——比如长度 2080 的序列已经是 Mersenne Twister 周期内能容纳的最大排列数,更长的序列必然无法穷尽所有排列。

sample(population, k)

从 population(序列或集合)中无放回抽取 k 个不重复元素组成新列表,原 population 不被修改。返回列表保持选取顺序,因此任意子切片依然是合法的随机样本——这允许把抽奖结果(sample)继续切分为头奖、二等奖等子集。population 成员无需可哈希(hashable)也无需唯一,重复出现的元素每次出现都是独立可选项。

  • 从大整数区间采样时,直接传 range 对象最省内存和最快:sample(range(10000000), k=60)。
  • 若 k 大于 population 大小,抛出 ValueError。

实数分布(Real-valued distributions)

以下函数生成特定实值分布,参数命名遵循统计教材中分布方程的惯用记号。全部实现位于 Lib/random.py:

函数 分布 关键参数与语义
random() 均匀 返回 [0.0, 1.0) 内的下一个随机浮点数
uniform(a, b) 均匀 a <= N <= b(当 a <= b 时);b < a 时反之;端点 b 是否包含取决于 a + (b-a) * random() 的浮点舍入
triangular(low, high, mode) 三角 low <= N <= high;low/high 默认为 0/1,mode 默认取区间中点(对称分布)
betavariate(alpha, beta) 贝塔 要求 alpha > 0、beta > 0;返回值介于 0 与 1 之间
expovariate(lambd) 负指数 lambd 是期望均值的倒数(取 1 除以期望均值),须非零;参数本应叫 "lambda",但那是 Python 保留字;lambd > 0 时返回值从 0 到正无穷,反之从负无穷到 0
gammavariate(alpha, beta) 伽马 要求 alpha > 0、beta > 0(注意不是伽马函数);PDF 为 x ** (alpha-1) * math.exp(-x/beta) / (math.gamma(alpha) * beta ** alpha)
gauss(mu, sigma) 高斯 mu 为均值、sigma 为标准差;比下面的 normalvariate 略快
lognormvariate(mu, sigma) 对数正态 对其取自然对数后服从均值 mu、标准差 sigma 的正态分布;mu 任意,sigma > 0
normalvariate(mu, sigma) 正态 mu 均值、sigma 标准差
vonmisesvariate(mu, kappa) von Mises(圆上角度) mu 为平均角(弧度,0 到 2π),kappa 为集中度参数(>= 0);kappa == 0 时退化为 0 到 2π 的均匀随机角
paretovariate(alpha) Pareto alpha 为形状参数
weibullvariate(alpha, beta) Weibull alpha 为尺度参数,beta 为形状参数

备选生成器:SystemRandom

SystemRandom 类使用操作系统的 os.urandom 从操作系统提供的随机性来源生成随机数:

  • 并非所有系统都可用;
  • 不依赖软件状态,序列不可复现(reproducible);
  • 因此 seed() 方法无效且会被忽略;
  • 调用 getstate()/setstate() 会抛出 NotImplementedError。

适用场景:当你在 KBEngine 服务器脚本中需要一次性、不可预测的随机值(如临时 token、防重复的短随机串),又不想引入密码学级方案时,SystemRandom 是比默认 Random 更合适的"安全取向"选择;但要明确它仍不是 secrets 那样的正式安全模块。

可复现性(Reproducibility)注意事项

有时我们希望伪随机数生成器给出的序列可复现:只要复用同一个种子值,并且没有多线程并发运行,每次运行应产生相同序列。原文档明确两点:

  • random 模块的大部分算法与播种函数会随 Python 版本变化;
  • 但两件事保证不变:① 若新增播种方法,会提供向后兼容的播种器;② 用兼容播种器配合相同种子时,生成器的 random() 方法将持续产出相同的序列。

实现层面还有两个容易被忽视的细节(见 Lib/random.py):模块检测到 os.fork 时会在子进程中注册 _inst.seed() 重新播种,避免 fork 后父子进程共享同一随机状态;同时文档也提示"只要多线程不在运行,同种子即可复现"——多线程环境下随机状态会被并发推进,复现性无法保证,需自行加锁或为各线程创建独立 Random 实例。

示例与配方(Examples and Recipes)

基础示例

>>> random()                             # Random float:  0.0 <= x < 1.0
0.37444887175646646

>>> uniform(2.5, 10.0)                   # Random float:  2.5 <= x < 10.0
3.1800146073117523

>>> expovariate(1 / 5)                   # Interval between arrivals averaging 5 seconds
5.148957571865031

>>> randrange(10)                        # Integer from 0 to 9 inclusive
7

>>> randrange(0, 101, 2)                 # Even integer from 0 to 100 inclusive
26

>>> choice(['win', 'lose', 'draw'])      # Single random element from a sequence
'draw'

>>> deck = 'ace two three four'.split()
>>> shuffle(deck)                        # Shuffle a list
>>> deck
['four', 'two', 'ace', 'three']

>>> sample([10, 20, 30, 40, 50], k=4)    # Four samples without replacement
[40, 10, 50, 30]

模拟实验

>>> # 六次轮盘旋转(有放回的加权采样)
>>> choices(['red', 'black', 'green'], [18, 18, 2], k=6)
['red', 'green', 'black', 'black', 'red', 'black']

>>> # 从 52 张扑克牌中无放回发 20 张,统计 10 点牌(10/J/Q/K)占比
>>> deck = collections.Counter(tens=16, low_cards=36)
>>> seen = sample(list(deck.elements()), k=20)
>>> seen.count('tens') / 20
0.15

>>> # 估计一个 60% 概率落正面的有偏硬币,7 次抛出出现 5 次及以上正面的概率
>>> def trial():
...     return choices('HT', cum_weights=(0.60, 1.00), k=7).count('H') >= 5
...
>>> sum(trial() for i in range(10000)) / 10000
0.4169

>>> # 5 个样本的中位数落在中间两个四分位数之间的概率
>>> def trial():
...     return 2500 <= sorted(choices(range(10000), k=5))[2] < 7500
...
>>> sum(trial() for i in range(10000)) / 10000
0.7958

统计自助法(bootstrap):用有放回重采样估计均值置信区间

from statistics import mean
from random import choices

data = 1, 2, 4, 4, 10
means = sorted(mean(choices(data, k=5)) for i in range(20))
print(f'The sample mean of {mean(data):.1f} has a 90% confidence '
      f'interval from {means[1]:.1f} to {means[-2]:.1f}')

重采样置换检验(permutation test):估计药物 vs 安慰剂的 p 值

from statistics import mean
from random import shuffle

drug = [54, 73, 53, 70, 73, 68, 52, 65, 65]
placebo = [54, 51, 58, 44, 55, 52, 42, 47, 58, 46]
observed_diff = mean(drug) - mean(placebo)

n = 10000
count = 0
combined = drug + placebo
for i in range(n):
    shuffle(combined)
    new_diff = mean(combined[:len(drug)]) - mean(combined[len(drug):])
    count += (new_diff >= observed_diff)

print(f'{n} label reshufflings produced only {count} instances with a difference')
print(f'at least as extreme as the observed difference of {observed_diff:.1f}.')
print(f'The one-sided p-value of {count / n:.4f} leads us to reject the null')
print(f'hypothesis that there is no difference between the drug and the placebo.')

单服务器队列:到达时间与服务交付模拟

from random import expovariate, gauss
from statistics import mean, median, stdev

average_arrival_interval = 5.6
average_service_time = 5.0
stdev_service_time = 0.5

num_waiting = 0
arrivals = []
starts = []
arrival = service_end = 0.0
for i in range(20000):
    if arrival <= service_end:
        num_waiting += 1
        arrival += expovariate(1.0 / average_arrival_interval)
        arrivals.append(arrival)
    else:
        num_waiting -= 1
        service_start = service_end if num_waiting else arrival
        service_time = gauss(average_service_time, stdev_service_time)
        service_end = service_start + service_time
        starts.append(service_start)

waits = [start - arrival for arrival, start in zip(arrivals, starts)]
print(f'Mean wait: {mean(waits):.1f}.  Stdev wait: {stdev(waits):.1f}.')
print(f'Median wait: {median(waits):.1f}.  Max wait: {max(waits):.1f}.')

该队列模拟是理解"指数到达 + 高斯服务时间"这类经典排队模型的极佳起点,也展示了 expovariate(间隔均值取倒数)与 gauss 的实战组合。

在仓库中核对实现与测试

如果你想在 KBEngine 内核对本篇文章所述内容,可直接查阅以下文件:

  • 文档原文:kbe/src/lib/python/Doc/library/random.rst(全文约 490 行,本文即以其为骨架)。
  • 纯 Python 层实现:kbe/src/lib/python/Lib/random.py——Random 类(第 72 行起)、seed(97 行)、randrange(174 行)、choice(256 行)、shuffle(264 行)、sample(286 行)、choices(344 行)、各实数分布(372–667 行)、SystemRandom(669 行)、模块级绑定实例 _inst = Random()(748 行)。
  • C 核心生成器:kbe/src/lib/python/Modules/_randommodule.c——MT19937 的实现,random_random() 对应原始 genrand_res53(),init_by_array() 负责按种子数组初始化,模块 docstring 明确写着 "Module implements the Mersenne Twister random number generator"。
  • 测试套件:kbe/src/lib/python/Lib/test/test_random.py——覆盖自动播种(test_autoseed)、状态保存恢复(test_saverestore)、种子参数(test_seedargs)、shuffle/choice/sample/choices(含分布与输入校验)、gauss、pickle 序列化以及 SystemRandom_TestBasicOps 等一系列行为验证。
  • 内嵌运行时的实际依赖方:仓库内置标准库中 crypt.py、email/generator.py、email/utils.py、tempfile.py 均 import random,secrets.py 使用 SystemRandom,可作为"模块在本运行时内被真实使用"的佐证。

最后提醒:KBEngine 的服务器逻辑脚本运行于上述内嵌 Python 之上,你在自己资产的 scripts 目录(模板可参考 kbe/res/sdk_templates/server/python_assets)中直接 import random 即可使用本模块全部能力;涉及安全场景时务必转向 secrets,而需要可复现的随机流程(如确定性的关卡生成、公平抽奖审计)时,请固定 seed() 并避免多线程并发推进同一个生成器。

登录后查看全文
kbengine