跳转到主要内容
Random 工具解决两类稳定性：同一 seed 应复现同一序列；数据集规模变化不应打乱每个已有划分。
当生成的行、样本或向量应在多次运行间保持稳定时，请使用 Random 工具。

​
1. 核心思想

StableRNG 面向测试、demo、基准测试与 LLM 应用 fixture——「随机」数据仍需可调试。若 seed 42 下失败，你应能在之后再生相同的行、向量与样本。 有两种稳定模式：
  • 序列稳定性： 相同 seed 与相同抽取顺序产生相同输出。当一连串抽取应一起推进时，使用 with StableRNG(seed=...) 上下文。
  • 成员稳定性： 增加更多候选项不应改变每个已有项的划分结果。稳定样本与划分请用 hash_sample(...) 与 hash_split(...)。

​
2. 生成可复现序列

用 seed 创建生成器；多次抽取属于同一序列时将其作为上下文使用。 
from heavenbase.utils import StableRNG

with StableRNG(seed=42) as rng:
    row_id = rng.rnd_str(8)
    score = rng.rnd_float(0.0, 1.0)
    label = rng.choice(["open", "closed", "review"])
相同 seed 与抽取顺序产生相同序列： 
from heavenbase.utils import StableRNG

with StableRNG(seed=7) as left:
    left_values = [left.rnd_str(6), left.rnd_int(0, 10)]

with StableRNG(seed=7) as right:
    right_values = [right.rnd_str(6), right.rnd_int(0, 10)]

assert left_values == right_values
在上下文外，单次方法调用对当前 seed 仍稳定。适合只需一个可复现值、又不想与先前抽取耦合的场景。

​
3. 派生子流

用 step(...) 将基础 seed 拆成命名流，而不改变父生成器。 
from heavenbase.utils import StableRNG

base = StableRNG(seed=42)
rows_rng = base.step("rows")
sample_rng = base.step("samples")

rows = rows_rng.rnd_str(6, n=3)
sample = sample_rng.choice(["p1", "p2", "p3", "p4"], k=2, replace=False)
这样某个测试在 workflow 中新增一次随机抽取时，不会牵连无关部分。

​
4. 生成批次与向量

多数生成器接受 n 表示数量或形状。需要一次性生成大量值时很有用。 
from heavenbase.utils import StableRNG

rng = StableRNG(seed=42)

ids = rng.rnd_str(4, n=5)
grid = rng.rnd_int(0, 10, n=(2, 3))
vecs = rng.rnd_vec(dim=8, n=3)
rnd_vec(...) 返回单位长度向量，适合在接入真实 embedding provider 之前需要向量形态的 LLM 与向量检索开发。

​
5. 采样而不打乱全局

稳定样本不应依赖输入顺序或无关新记录时，使用 hash_sample(...) 与 hash_split(...)。 
from heavenbase.utils import StableRNG

items = ["p1", "p2", "p3", "p4"]

sample = StableRNG(seed=11).hash_sample(items, k=2)
selected, remaining = StableRNG(seed=11).hash_split(items, r=0.5)
若之后加入 "p5"，"p1" 到 "p4" 的判定仍基于各项哈希与 seed，而非原始列表位置。
HeavenBase 基准测试使用带 seed 的生成，以便行内容、样本与向量可复现。

​
Further Exploration

相关资源：
  • 哈希 - 稳定采样使用的确定性哈希。
  • 文件系统 - 将生成 fixture 写入本地产物。
  • 查询 - 合成向量 fixture 的常见使用处。