KBEngine 内嵌 Python 的 random 模块指南:伪随机数生成、分布与可复现采样
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() 并避免多线程并发推进同一个生成器。