一个文件都不用装,python 就能跑通「环境 → 智能体 → 训练 → 评估 → 报告」的完整闭环。
tinyrl 是一个零运行时依赖、纯标准库实现的经典强化学习(Reinforcement Learning)工具箱:内置多臂老虎机、网格世界、冰湖行走、悬崖行走等经典环境,并配套 ε-Greedy、UCB1、Thompson Sampling、Q-Learning、Sarsa、Expected Sarsa、价值迭代、策略迭代等开箱即用的算法。
- 主流 RL 环境栈(
gymnasium+numpy+mujoco……)安装重、编译难,在离线机器、受限 CI、嵌入式 Python、教学机房里经常第一步就卡在环境配置; - 机器人/物理仿真环境依赖显示与原生二进制,想快速验证一个算法想法却跑不起来;
- 框架封装层太厚,初学者看不清「一次交互」内部到底发生了什么;
- 实验随机源散落各处,结果不可复现,教学演示与回归测试都很痛苦。
- 真·零依赖:只用 Python 3.8+ 标准库,不需要编译任何东西,拷贝整个目录即可运行;
- 种子级可复现:所有随机性都来自显式
random.Random,同种子逐位复现实验轨迹; - 环境与算法双覆盖:既有「无模型」的 TD 控制,也有「基于模型」的动态规划,可以对照学习;
- 教科书级对照实验:悬崖行走环境中可稳定复现「Q-Learning 走最短险路(-13)、Sarsa 走安全远路(-17)、Expected Sarsa 居中(-15)」的经典结论;
- 双形态使用:既是可
import的算法库,也提供tinyrl命令行,一行命令出对比报告; - 工程完备:71 个标准库单元测试、类型注解、ASCII 渲染、学习曲线、JSON/CSV 报告导出。
💡 灵感来源:本项目在 GitHub Trending 上关注到绑定 MuJoCo 物理引擎的机器人 RL 训练环境项目(需要重型原生依赖与显示环境)。我们没有复制其任何代码,而是反向思考其痛点,独立自研了一个在任何机器上秒级跑通的轻量替代形态,专注于经典表格型 RL 的学习、教学与快速实验。
| 环境 | 说明 | 可配置点 |
|---|---|---|
| MultiArmedBandit | 多臂老虎机,单状态探索-利用问题 | 臂数量、伯努利/高斯/确定性分布 |
| GridWorld | 通用网格世界,到达目标即胜利 | 尺寸、墙体、起点终点、步惩罚、随机打滑 |
| FrozenLake | 冰湖行走(4×4 / 8×8 / 自定义地图) | 地图、是否打滑、最大步数 |
| CliffWalking | Sutton 教科书悬崖行走 | 尺寸、悬崖惩罚、步惩罚 |
- 多臂老虎机:
EpsilonGreedy(支持乐观初始值 Q0 与固定学习率)、UCB1、ThompsonBernoulli - 时序差分控制:
QLearningAgent(异策略)、SarsaAgent(同策略)、ExpectedSarsaAgent(低方差) - 动态规划:
value_iteration(价值迭代)、policy_iteration(策略迭代),并可把策略渲染成箭头地图
- ⚙️ 实验引擎:
train/evaluate/run_bandit,训练与评估严格分离 - 📊 报告系统:指标汇总、Unicode 迷你学习曲线(
▁▂▃▄▅▆▇█)、JSON / CSV 导出 - 🖥️ 命令行工具:4 个子命令覆盖算法对比、训练演示、规划演示
- 🔁 统一接口:接近 Gymnasium 风格的
reset / step,学到的概念可无缝迁移到主流框架 - 🧪 零依赖测试:测试同样只用标准库
unittest,python -m unittest discover即可
tinyrl/
├── tinyrl/ # 核心包
│ ├── core.py # 环境抽象、离散空间、随机源、贪心工具
│ ├── envs/ # 环境:老虎机 / 网格世界 / 冰湖 / 悬崖
│ ├── agents/ # 智能体:老虎机算法 / TD 控制 / 动态规划
│ ├── engine.py # 训练、评估、老虎机实验引擎
│ ├── report.py # 指标统计、迷你曲线、JSON/CSV 导出
│ └── cli.py # tinyrl 命令行入口
├── examples/ # 4 个可直接运行的示例
├── tests/ # 71 个单元测试(标准库 unittest)
├── docs/ # 繁體中文 / English 文档
├── pyproject.toml # 打包配置(零运行时依赖)
└── LICENSE # MIT
- Python 3.8 及以上(3.8 / 3.9 / 3.10 / 3.11 / 3.12 均验证通过)
- 无需任何第三方运行时依赖,不联网、不编译
git clone https://github.com/gitstq/tinyrl.git
cd tinyrl
python -m tinyrl.cli demo-bandits
# 从源码安装(会注册 tinyrl 命令)
pip install .
# 之后在任意目录使用
tinyrl demo-grid --env frozenlake --agent q --episodes 4000
python examples/01_bandits.py
python examples/02_frozenlake_qlearning.py
python examples/03_cliff_comparison.py
python examples/04_value_iteration.py
from tinyrl.envs import FrozenLake
from tinyrl.agents import QLearningAgent
from tinyrl.engine import train, evaluate
env = FrozenLake() # 打滑的 4×4 冰湖
agent = QLearningAgent(
n_states=env.observation_space.n,
n_actions=env.action_space.n,
alpha=0.25, gamma=0.99, epsilon=0.1, seed=42,
)
train(env, agent, episodes=4000, seed=42) # 训练
print(evaluate(FrozenLake(), agent, 500, 9999)) # 贪心评估
# {'episodes': 500, 'avg_return': 0.796, 'avg_steps': 49.8, 'success_rate': 0.796, ...}
| 子命令 | 作用 |
|---|---|
tinyrl demo-bandits |
三种老虎机算法同台对比(平均奖励、最优臂选择率、累计遗憾) |
tinyrl demo-grid |
在指定网格环境训练一个 TD 智能体,输出学习曲线、评估指标与贪心轨迹 |
tinyrl demo-plan |
价值迭代 / 策略迭代求解,并打印最优策略箭头地图 |
tinyrl compare |
Q-Learning / Sarsa / Expected Sarsa 横向对比,可导出 JSON、CSV |
常用参数:
# 选择环境与算法、调节超参
tinyrl demo-grid --env cliff --agent sarsa --episodes 2000 \
--alpha 0.3 --gamma 0.99 --epsilon 0.1 --seed 7
# 三算法对比并落盘报告(便于 CI 或写实验报告)
tinyrl compare --env frozenlake --episodes 4000 \
--json report.json --csv report.csv
| 参数 | 含义 | 默认值 |
|---|---|---|
--env |
网格环境:gridworld / frozenlake / cliff |
frozenlake |
--agent |
算法:q / sarsa / expected |
q |
--episodes |
训练回合数 | 4000 |
--alpha |
学习率 | 0.25 |
--gamma |
折扣因子 | 0.99 |
--epsilon |
ε-贪心探索率 | 0.1 |
--seed |
随机种子(保证可复现) | 42 |
真实运行输出(悬崖环境三算法对比):
$ tinyrl compare --env cliff --episodes 2000 --seed 7
agent tail_return tail_succ% eval_return eval_succ%
--------------------------------------------------------------
q -52.610 100.0% -13.000 100.0%
sarsa -22.485 100.0% -17.000 100.0%
expected -21.020 100.0% -15.000 100.0%
📌 输出解读:训练期(tail)因为 ε 随机探索会偶尔坠崖,回报偏低;评估期切换为纯贪心策略后,三种算法全部 100% 到达终点。Q-Learning 学到贴悬崖的最短路径(-13),Sarsa 因惧怕探索期坠崖而主动绕行(-17),Expected Sarsa 居中(-15)。
1)自定义网格世界(墙体 + 随机打滑):
from tinyrl.envs import GridWorld
env = GridWorld(
rows=5, cols=5,
start=(0, 0), goal=(4, 4),
walls=frozenset({(1, 1), (2, 3)}),
step_reward=-0.04, # 时间惩罚,鼓励短路径
slip_prob=0.1, # 10% 概率滑向侧向
)
2)自定义冰湖地图:
from tinyrl.envs import FrozenLake
env = FrozenLake([
"SFFF",
"FHFH",
"FFFH",
"HFFG",
], slippery=True) # slippery=False 可关闭打滑
3)多臂老虎机实验并查看遗憾曲线:
from tinyrl.envs import MultiArmedBandit
from tinyrl.agents import ThompsonBernoulli
from tinyrl.engine import run_bandit
from tinyrl.report import sparkline, summarize_bandit
env = MultiArmedBandit.bernoulli([0.2, 0.5, 0.8, 0.35, 0.6])
record = run_bandit(env, ThompsonBernoulli(5, seed=42), pulls=2000, seed=42)
print(summarize_bandit(record))
print(sparkline(record.cumulative_regret)) # ▁▄▅▆▇█████
4)已知模型时直接动态规划,无需采样:
from tinyrl.envs import FrozenLake
from tinyrl.agents import value_iteration, policy_as_arrows
env = FrozenLake()
V, policy, sweeps = value_iteration(env, gamma=0.99)
print(policy_as_arrows(env, policy))
终端演示动图将在后续版本补充,可先用下面命令复现全部效果:
tinyrl demo-bandits # 算法对比表 + 遗憾曲线
tinyrl demo-plan --env gridworld # 箭头形式的最优策略
- 🎓 课堂教学 / 自学:从老虎机到 TD 控制,每个算法都能在 1 秒内看到结果
- 🧪 算法原型验证:先在表格环境验证想法,再迁移到大规模深度 RL
- 🤖 编码 Agent 基准:确定性、零依赖,适合作为 AI 编程智能体的可复现评测沙盒
- 🔬 实验报告:
compare --json/--csv直接产出可画图的原始数据
- 可读即文档:每个模块控制在单文件可通读的规模,算法实现贴近 Sutton & Barto《Reinforcement Learning: An Introduction》的符号体系(Q、α、γ、ε)。
- 显式随机源:环境与智能体各自持有独立的
random.Random,由种子派生,杜绝全局随机状态带来的不可复现。 - 模型/无模型对照:网格环境同时提供
step()(交互)与model()(转移概率),让「Q-Learning 学出来的策略」和「价值迭代算出来的最优策略」可以直接对照。 - 零依赖是特性而非妥协:标准库足以清晰表达全部经典表格型算法,也因此获得跨平台、秒级启动、永久可运行的稳定性。
- v1.1:新增 Blackjack、Windy Gridworld、Shortcut MDP 等经典环境
- v1.1:TD(λ)、n-step Sarsa、Double Q-Learning 算法
- v1.2:策略评估的自包含 SVG 学习曲线导出(仍保持零依赖)
- v1.2:Gymnasium 适配层(可选导入,不破坏零依赖核心)
- v1.3:简单函数逼近接口(线性函数近似,纯 Python)
- 持续补充多语言文档与教学 Notebook(不引入运行时依赖)
欢迎认领 Roadmap 条目,或贡献新的经典环境、算法、教学示例;提交前请阅读 CONTRIBUTING.md。
本项目属于工具库 / CLI 类项目(纯 Python、跨平台、无原生产物),无需下载可执行文件,按以下方式集成分发:
# 需要构建工具(仅构建期使用,不是运行时依赖)
python -m pip install build
python -m build # 产出 dist/*.whl 与 dist/*.tar.gz
构建出的 wheel 为 py3-none-any,一份包通用于 Windows / macOS / Linux。
# 在有网机器下载 wheel,拷贝到目标机器后
pip install tinyrl_lab-1.0.0-py3-none-any.whl
| 项 | 支持范围 |
|---|---|
| 操作系统 | Windows / macOS / Linux(纯 Python,与平台无关) |
| Python 版本 | 3.8 – 3.12 |
| 运行时依赖 | 无 |
| 安装方式 | 源码目录直接运行 / pip 安装 / wheel 离线安装 |
测试同样零第三方依赖,使用标准库 unittest:
# 运行全部 71 个测试
python -m unittest discover -s tests -v
# 语法编译检查
python -m compileall tinyrl examples
测试覆盖:环境转移正确性与概率闭合、奖励语义、算法收敛性(含多种子稳健性)、 动态规划 Bellman 残差、同种子可复现/异种子不同、报告导出往返、CLI 端到端。
- 🐛 问题反馈请附最小复现代码 + 随机种子;
- 🔀 PR 提交信息遵循 Angular 规范:
feat:/fix:/docs:/test:/refactor:; - 📐 新功能必须附带单元测试,且不得引入第三方运行时依赖;
- 🌐 改动公开 API 时,请同步更新三份语言文档。
完整约定见 CONTRIBUTING.md。
本项目基于 MIT License 开源,可自由用于学习、教学、科研与商业项目,保留版权声明即可。
如果这个项目对你有帮助,欢迎 ⭐ Star 支持!
Happy Learning, Happy Reinforcement! 🦞🎰