pufferlib

PufferLib

使用 PufferLib 时，应明确指定版本配置。上游目前有两个不兼容的接口：

配置	截至 2026-07-23 的状态	主要用途
pufferlib==3.0.0	PyPI 最新稳定版，发布于 2025-06-23	Python/Gymnasium/PettingZoo 仿真、pufferlib.vector、Torch PuffeRL
source 4.0	上游默认分支；并非 PyPI 最新稳定版	原生 C Ocean 环境、原生 CUDA 训练器、可选 Torch 回退

不要混用 3.0 导入方式与 4.0 配置/CLI 示例。4.0 重新设计后，当前软件包目录树中已移除 3.0 的 emulation、vector 和 pytorch 模块。

安全默认设置

1. 从内置的合成、仅 CPU、无网络工具开始。
2. 不要通过点分路径导入任意环境。内置工具只接受允许列表中的内置项和 slug 标识符。
3. 不要安装或执行未经审查的环境软件包、原生扩展、ROM、地图、检查点或 pickle 文件。
4. 核验官方来源、不可变版本、许可证、校验和或证明材料，以及构建钩子。对原生构建和首次执行进行沙箱隔离。
5. 限制步数、环境数、Agent 数、工作进程数、线程数、缓冲区、内存、磁盘、渲染尺寸和运行时间。
6. 训练环境/种子与评估环境/种子分开。
7. 默认使用本地日志或不记录日志。外部日志记录需要明确选择加入、确认数据披露，并单独批准上传产物。
8. 绝不要通过 CLI、INI、JSON、标签、运行名称或日志记录器配置传递 W&B 或 Neptune 凭据。绝不要打印这些凭据。
9. 绝不要转储所有环境变量，也不要递归搜索 .env。
10. 在受信任的沙箱环境中加载检查点之前，先对其字节计算哈希；检查元数据并不能证明安全。

首次本地检查

所有内置 CLI 均无需依赖，并会输出严格 JSON：

python3 scripts/env_template.py --help
python3 scripts/env_contract_validator.py
python3 scripts/benchmark_vectorization.py --backend serial
python3 scripts/train_template.py
python3 scripts/validate_plan.py
python3 scripts/repro_plan.py

默认设置为合成、确定性、受限、本地、仅 CPU、无网络；若原本会进行训练，则采用空运行模式。

安装与来源证明

已发布的 3.0.0

PyPI 仅提供 pufferlib-3.0.0.tar.gz：

sha256: 7df3a3e3f5f894d78d2a1f5374097890aec01473183e748abefe4f3faa10eaa9
Requires-Python: >=3.9

完成源代码/构建审查后，创建一个固定版本的 uv 项目：

uv venv --python 3.11
uv add --exact --no-sync "pufferlib==3.0.0"
uv lock
uv sync --frozen

提交 pyproject.toml 和 uv.lock；核验归档文件摘要及每个已解析的依赖项。源码构建可能会编译原生代码并获取构建资源，因此应在没有凭据或敏感挂载的沙箱中解析/构建。已上传的元数据没有固定 Torch 或 CUDA 版本；不要声称存在 PyPI 未声明支持的 CUDA 兼容矩阵。

当前 4.0 源码

截至 2026-07-23，经过审查的分支头为：

25647630e1b15330bb3153a5a0d3ff8d234c3acf

固定提交，不要固定分支 4.0：

uv add --no-sync \
  "pufferlib @ git+https://github.com/PufferAI/PufferLib.git@25647630e1b15330bb3153a5a0d3ff8d234c3acf"
uv lock

当前软件包声明 Python >=3.10 和 Torch >=2.9。上游 PufferTank 目前使用 Ubuntu 24.04、Python 3.12，以及带有 cu130 Torch 索引的 NVIDIA CUDA 13.0.2/cuDNN 开发镜像，但没有固定确切的 Torch wheel 或所有系统软件包。应将其视为参考，而非完整锁定配置。绝不要直接从管道执行远程安装程序。

在任何安装或构建之前，先阅读 references/training.md。

环境工作流

1. 验证契约

Gymnasium 的重置会返回 (observation, info)。步骤会返回：

(observation, reward, terminated, truncated, info)

验证空间、形状、数据类型、奖励是否有限、布尔值、先重置再执行步骤、结束后重置、设定种子以及清理。terminated 表示 MDP 终止；truncated 表示时间限制等外部截断。为自举计算和指标保留这一区别。

python3 scripts/env_contract_validator.py \
  --steps 64 --episodes 8 --seed 42

2. 审查后再进行适配

已发布的 3.0 使用显式包装器：

import pufferlib.emulation

wrapped = pufferlib.emulation.GymnasiumPufferEnv(reviewed_gymnasium_instance)

对于经过审查的 PettingZoo Parallel 环境：

wrapped = pufferlib.emulation.PettingZooPufferEnv(reviewed_parallel_instance)

3.0 不支持与旧技能匹配的 pufferlib.emulate(...) 快捷方式。请阅读 references/environments.md 和 references/integration.md。

3. 原生环境

已发布的 3.0 PufferEnv 要求在调用 super().__init__(buf) 前设置 single_observation_space、single_action_space 和 num_agents。它使用原地向量缓冲区，并返回单独的终止/截断数组以及一个信息字典列表。

当前的 4.0 使用 C 绑定。从上游的 ocean/squared（单 Agent） 或 ocean/target（多 Agent）开始，在本地/安全模式下构建一个环境， 并在优化前验证每个缓冲区的大小、类型和索引。

向量化工作流

已发布的 3.0：

import pufferlib.vector

vecenv = pufferlib.vector.make(
    reviewed_creator,
    backend=pufferlib.vector.Serial,
    num_envs=4,
    seed=42,
)

仅在串行跟踪通过后再切换到 Multiprocessing。记录 num_envs、num_workers、batch_size、零拷贝模式、启动方法、Agent 数量、掩码和实际返回的形状。对于多 Agent 环境，批次长度基于 Agent 槽位，不一定等于 num_envs。

当前的 4.0 配置则使用：

[vec]
total_agents = 4096
num_buffers = 2
num_threads = 16

请阅读 references/vectorization.md。使用预热和至少 三次重复，对固定工作量进行基准测试；分别报告模拟 SPS 和端到端训练 SPS。内置基准仅测量其合成测试框架。

策略工作流

已发布的 3.0 策略是根据 single_observation_space/single_action_space 调整大小的 Torch 模块。稳定的循环组合使用 encode_observations 和 decode_actions；结构化仿真使用 pufferlib.pytorch.nativize_dtype 和 nativize_tensor。

当前 4.0 Torch 回退方案组合使用：

pufferlib.models.Policy(encoder=encoder, decoder=decoder, network=network)

它提供 MLP、MinGRU、LSTM 和 GRU 网络选项；--slowly 会选择此回退方案，而非原生后端。检查输出/状态形状、掩码、有限值、梯度以及即时执行与编译执行的行为。请参阅 references/policies.md。

训练与评估

已发布的 3.0 训练器导入方式：

from pufferlib import pufferl

trainer = pufferl.PuffeRL(train_config, vecenv, policy)

当前的 4.0 CLI：

puffer train ENV_NAME
puffer eval ENV_NAME --load-model-path EXACT_TRUSTED_PATH
puffer sweep ENV_NAME

默认生成计划，而不是直接启动：

python3 scripts/train_template.py \
  --profile pypi-3.0.0 \
  --environment synthetic \
  --device cpu \
  --total-timesteps 10000

验证自定义的严格 JSON 计划：

python3 scripts/validate_plan.py --root . --config plan.json

该架构会拒绝包含机密的键、无界资源、带点号的环境路径、无效的向量可整除性、混合版本选项以及耦合的训练/评估种子。请参阅 references/training.md。

日志记录

PufferLib 3.0 提供 W&B 和 Neptune；当前的 4.0 CLI 提供 W&B。两者都是可选的外部服务。它们可能会传输配置、指标、源代码元数据、硬件遥测数据、输出和获准的构件，并涉及隐私、保留期限、访问控制和成本方面的影响。

• W&B 凭据：命名环境变量 WANDB_API_KEY。
• Neptune 凭据：命名环境变量 NEPTUNE_API_TOKEN。
• 切勿在参数/配置/日志中填写值。
• 记录日志前清理配置键。
• 除非明确获准，否则关闭源代码/模型上传。

规划器要求同时具备：

python3 scripts/train_template.py \
  --logger wandb \
  --enable-external-logging \
  --acknowledge-external-disclosure

它只会报告所需变量名，绝不会读取其值。

检查点工作流

PufferLib 3.0 和 4.0 Torch 回退方案使用 Torch 序列化；当前的原生 4.0 会写入不透明的 .bin 权重。PyTorch 警告称，不受信任的模型是程序，而且 torch.load 会使用反序列化。

python3 scripts/inspect_checkpoint.py checkpoint.pt \
  --root . \
  --expected-sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

检查器只会计算哈希并分类。它不会调用 torch.load，不会导入 pickle/Torch，不会检查归档成员，也不会提取文件。在任何沙盒加载前，请验证来源、许可证、架构、环境修订版本、侧文件元数据和校验和。在可复现评估中，切勿使用 latest。

内置文件

脚本

• scripts/env_template.py — 确定性的合成 Gymnasium 风格模板。
• scripts/env_contract_validator.py — 有界契约和种子检查。
• scripts/benchmark_vectorization.py — 受限的串行/生成进程合成基准测试。
• scripts/train_template.py — 不执行训练的 3.0/4.0 训练计划生成器。
• scripts/validate_plan.py — 严格的配置/资源/安全验证器。
• scripts/inspect_checkpoint.py — 不进行反序列化的元数据/哈希检查。
• scripts/repro_plan.py — 使用独立种子的评估和基准测试计划。

参考资料

• references/environments.md — Gymnasium、稳定版 PufferEnv、仿真、原生 C。
• references/vectorization.md — 后端、形状、启动方法、基准测试。
• references/policies.md — 稳定版／当前版策略契约与状态安全性。
• references/training.md — 安装、配置、命令行、PuffeRL、评估、日志、检查点。
• references/integration.md — 迁移矩阵、第三方集成与凭据安全。

上游资料（含日期）

• PyPI pufferlib 3.0.0 — 发布于 2025-06-23；核查于 2026-07-23。
• PyPI 3.0.0 元数据 — 摘要／依赖项；核查于 2026-07-23。
• PufferLib 官方文档 — 当前为 4.0 文档； 核查于 2026-07-23。
• PufferLib 源代码 — 默认分支与实现； 核查于 2026-07-23。
• PufferTank 4.0 Dockerfile — CUDA／Python 参考；核查于 2026-07-23。
• PufferLib 2.0 论文 — 《强化学习期刊》，2025 年；仅用于论文中列明的基准测试。
• PufferLib 兼容性论文 — 提交于 2024-06-18；介绍较早的 API／性能概况。

相关技能

• stable-baselines3：生产就绪的强化学习算法（PPO、SAC、DQN、TD3、DDPG、A2C），提供类似 scikit-learn 的 API。
• evaluating-cosmos-policy：在 LIBERO 和 RoboCasa 仿真环境中评估 NVIDIA Cosmos Policy。
• fine-tuning-serving-openpi：使用 JAX 或 PyTorch 后端微调并部署 Physical Intelligence OpenPI 模型（pi0、pi0-fast、pi0.5），用于机器人策略推理等场景。