跳转至

Step-by-step Guide

本文件是唯一操作入口。配置字段含义只看 CONFIGURATION.md；这里只写怎么安装、检查、启动、恢复、可视化和清理。

【主线】从零开始到启动训练

Step 1：进入仓库根目录

cd mcts-cpu-validate

后续命令都默认从仓库根目录执行。

Step 2：确认系统有 tmux 和 curl

训练入口只依赖系统已有 tmux 和 curl。Rust、uv、Python 环境和缓存都由 项目安装到仓库内 .local/。

tmux -V
curl --version

不要手工安装到客户 HOME，也不要改系统 Python/Rust。

Step 3：一键自举并启动训练

./tmux_train.sh

tmux_train.sh 会在进入 tmux 前完成：

  • 安装 uv 到 .local/bin。
  • 安装 Rust/cargo 到 .local/cargo 和 .local/rustup。
  • 由 uv 安装/管理 Python 到 .local/uv-python，并创建 Python 环境 .local/venv。
  • 安装 Python 依赖和本地包。
  • 构建 Rust Python extension。
  • 启动 tmux 训练会话，并在该 session 内设置项目内环境变量。

所有这些产物都在仓库内 .local/，不会写客户 HOME 或系统目录。tmux 里发送的训练命令是 python dl.py，不会把仓库路径、venv 路径、GPU 配置或 run id 放进命令行。

Step 4：查看训练会话

tmux attach -t train

训练主入口不接收命令行参数，不在进程列表里暴露 GPU id、run id 或配置路径。它会从现有 configs/*.toml 中按当前机器能力选择配置：

  • CUDA 可用且机器有多个 CPU/socket：configs/linux-dual-cpu-gpu.toml
  • CUDA 可用且机器是单 CPU/socket：configs/linux-gpu.toml
  • Apple MPS 可用：configs/m2-ultra.toml
  • Linux CPU 且无 CUDA/MPS：configs/linux-cpu.toml
  • 其他情况：configs/default.toml

【支线】手工检查项目内环境

自举完成后可以检查：

.local/venv/bin/python --version
.local/cargo/bin/cargo --version
PYTHONPATH=python .local/venv/bin/python -c "import rust_engine.rust_engine as e; print(e.version())"

【支线】运行测试

PYTHONPATH=python .local/venv/bin/python -m unittest discover -s python/tests -p 'test_*.py'
.local/cargo/bin/cargo test --manifest-path rust-engine/Cargo.toml --features python

【支线】前台运行训练

不用 tmux 时可以前台运行：

PYTHONPATH=python .local/venv/bin/python dl.py

【支线】配置文件怎么选

配置文件只用现有这一套：

configs/default.toml
configs/m2-ultra.toml
configs/linux-cpu.toml
configs/linux-gpu.toml
configs/linux-dual-cpu-gpu.toml

不要新增 local.toml、active.toml 或另一套配置目录。GPU 编号、worker 策略、模型规模都写在现有 TOML 里，不写到命令行参数里。

【支线】单步训练入口

python/mcts_cpu_validate/train.py 不是完整长期训练入口。它只做“已有棋谱分片上的单次训练更新”。

只有已经存在 self-play 生成的 JSONL.zst 时，才可以直接调用它：

PYTHONPATH=python .local/venv/bin/python python/mcts_cpu_validate/train.py \
  --config configs/linux-dual-cpu-gpu.toml \
  --run-dir data/runs/<run_id> \
  --games-shard data/runs/<run_id>/games/games-000000.jsonl.zst

正常训练不要手动调用这个文件，直接用 ./tmux_train.sh 或 PYTHONPATH=python .local/venv/bin/python dl.py。

【支线】检查 checkpoint

.local/venv/bin/python tools/inspect_checkpoint.py \
  --checkpoint data/runs/<run_id>/checkpoints/latest.pt

也可以检查：

data/runs/<run_id>/checkpoints/previous.pt
data/runs/<run_id>/checkpoints/best.pt

恢复粒度是 checkpoint 周期边界。中断后从 checkpoint 中的 training_step + 1 继续。

【支线】校验 run 数据

.local/venv/bin/python tools/validate_run_data.py \
  --run-dir data/runs/<run_id>

这个工具会检查 checkpoint、metrics、JSONL.zst 和 SQLite 索引是否可读且互相一致。

【支线】渲染棋谱

按 SQLite 索引渲染：

.local/venv/bin/python tools/render_game.py \
  --index data/runs/<run_id>/games/games.index.sqlite \
  --game-id <game_id> \
  --output data/runs/<run_id>/plots/game-<game_id>.png

渲染某一步：

.local/venv/bin/python tools/render_game.py \
  --index data/runs/<run_id>/games/games.index.sqlite \
  --game-id <game_id> \
  --step <move_count> \
  --output data/runs/<run_id>/plots/game-<game_id>-step-<move_count>.png

输出是 15x15 棋盘 PNG，包含当前棋子、最后一步、当步移除点、分数、胜者和终局原因。

【支线】画 metrics 图

.local/venv/bin/python tools/plot_metrics.py \
  --metrics data/runs/<run_id>/metrics/metrics.parquet \
  --output-dir data/runs/<run_id>/plots

输出：

loss.png
win_rate.png
self_play_throughput.png
checkpoints.png

【支线】运行数据目录

所有运行产物必须集中在：

data/runs/<run_id>/

典型结构：

data/runs/<run_id>/manifest.json
data/runs/<run_id>/config.snapshot.toml
data/runs/<run_id>/checkpoints/latest.pt
data/runs/<run_id>/checkpoints/previous.pt
data/runs/<run_id>/checkpoints/best.pt
data/runs/<run_id>/metrics/
data/runs/<run_id>/games/
data/runs/<run_id>/plots/

不要在顶层 data/ 创建长期使用的 checkpoints/、games/、metrics/ 或 plots/。

【支线】清理策略

可以重新生成：

data/runs/<run_id>/plots/*.png
data/runs/<run_id>/validation.json

不要删除：

data/runs/<run_id>/manifest.json
data/runs/<run_id>/config.snapshot.toml
data/runs/<run_id>/checkpoints/latest.pt
data/runs/<run_id>/checkpoints/previous.pt
data/runs/<run_id>/checkpoints/best.pt
data/runs/<run_id>/metrics/
data/runs/<run_id>/games/games.index.sqlite
data/runs/<run_id>/games/*.jsonl.zst

如果数据量过大，改 configs/*.toml 中的保存频率和分片策略。不要手工修改 run 内部数据一致性；清理时只删除可再生的图表/校验摘要，或完整删除整个废弃 run 目录。

【支线】提交前检查

git status --short

改 Python 后至少跑：

PYTHONPATH=python .local/venv/bin/python -m unittest discover -s python/tests -p 'test_*.py'

改 Rust 后至少跑：

.local/cargo/bin/cargo test --manifest-path rust-engine/Cargo.toml --features python