Configuration¶

本文件只说明配置文件和配置字段含义，不写运行命令。操作步骤见 STEP_BY_STEP_GUIDE.md。

配置是硬件差异、模型规模和运行策略的唯一入口。不要把机器相关参数、GPU 编号、worker 数量、模型降级逻辑或路径硬编码到实现里。

配置文件¶

项目只使用现有配置文件：

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 或第二套配置目录。

统一 Schema¶

configs/default.toml 是完整 schema 和通用默认值的唯一来源。其他环境配置文件只写覆盖项，避免重复维护同一批字段。

加载语义：

configs/default.toml + 环境 override TOML

merge 后的最终配置必须符合统一 schema。环境差异只能改变值，不能另起一套配置格式。

核心分组：

[run]
[python]
[rules]
[runtime]
[training]
[training.gpu]
[evaluation]
[model]
[mcts]
[self_play]
[data]
[checkpoint]
[metrics]
[games]

`configs/default.toml`¶

默认配置定义完整字段集合和主线默认值：

15x15 棋盘。
ruleset_version = "area15_v1"。
residual CNN 主线模型。
checkpoint 三槽：latest、previous、best。
棋谱格式：jsonl.zst。
棋谱索引：SQLite。
mcts.batch_inference = true，Python evaluator 会把 Rust worker 的模型推理请求按短窗口合批，默认 inference_batch_size = 64、 inference_batch_timeout_ms = 2。
evaluation.games 控制每次 checkpoint 周期的 latest-vs-previous 模型对战评估局数；evaluation.simulations_per_move 和 evaluation.cpuct 控制评估 MCTS 参数。

`configs/m2-ultra.toml`¶

Apple Silicon 开发机覆盖项：

Python 解释器统一使用项目内 .local/venv 中的 python。
训练 device 为 mps。
Rust worker 不绑 socket。
单 socket/MPS 情况下 Rust worker 使用 single_socket_cpu_fraction = 0.80。

`configs/linux-cpu.toml`¶

Linux 单 CPU/socket、无 CUDA/MPS 覆盖项：

训练 device 为 CPU。
Rust worker 策略为 all_available。
worker affinity 关闭。
没有 GPU/MPS/CUDA 时由 no_gpu_cpu_fraction = 0.50 控制 Rust worker 比例。

`configs/linux-gpu.toml`¶

Linux 单 CPU/socket、带 CUDA GPU 覆盖项：

训练 device 为 CUDA。
Rust worker 策略为 all_available。
worker affinity 关闭。
有 CUDA 训练时 Rust worker 使用 single_socket_cpu_fraction = 0.80。
CUDA 候选 GPU 来自 candidate_ids。
默认 min_free_memory_gb = 0，靠真实 probe 判定 GPU 是否可用。

`configs/linux-dual-cpu-gpu.toml`¶

Linux 双 CPU/socket、带 CUDA GPU server 覆盖项：

训练 device 为 CUDA。
Rust worker 默认使用一个 socket。
CUDA 候选 GPU 来自 candidate_ids。
默认 min_free_memory_gb = 0，靠真实 probe 判定 GPU 是否可用。
默认 mode = "auto_single"，从候选 GPU 中选择空闲显存最多且 probe 通过的一张。
多 GPU 只能通过 TOML 显式启用 auto_multi、allow_multi_gpu 和 max_gpus。

Python 与项目内工具链¶

默认训练入口使用项目内工具链和 Python 环境，避免污染客户机器：

Rust/cargo 安装到 .local/cargo 和 .local/rustup。
uv 安装到 .local/bin。
uv 管理的 Python 安装到 .local/uv-python。
Python 环境安装到 .local/venv。
pip/uv/cache/tmp/home 都指向 .local/...。
不写客户 HOME，不改系统 Python，不改系统 Rust。
configs/default.toml 中的 python.create_virtualenv = true 表示默认入口必须统一创建并复用项目内 .local/venv；环境自举只由 tmux_train.sh 统一负责。
python.version、python.venv_dir 和 python.uv_python_install_dir 是 Python 环境路径和版本的唯一配置来源；启动脚本只读取这些值。

CPU 策略¶

单 CPU/socket 且训练 device 为 CPU：Rust worker 默认使用 runtime.no_gpu_cpu_fraction = 0.50。
单 CPU/socket 且训练 device 为 MPS/CUDA：Rust worker 默认使用 runtime.single_socket_cpu_fraction = 0.80。
多 CPU/socket server：Rust worker 默认用满一个 CPU/socket，Python 自由调度。

这两个比例必须来自配置文件，不允许在实现中硬编码：

[runtime]
single_socket_cpu_fraction = 0.80
no_gpu_cpu_fraction = 0.50

GPU 策略¶

GPU 只服务 Python/PyTorch residual CNN 训练和可选 batch inference。

默认 server 策略是 auto_single：

只从配置的候选 GPU 中选择。
按空闲显存排序。
probe 通过后使用一张 GPU。
probe 失败则尝试下一张。

多 GPU 是配置能力，不是默认路径。

模型规模¶

默认模型是 15x15 棋盘专用 residual CNN：

[model]
channels = 128
residual_blocks = 8

不要根据硬件自动降级。如果某台机器需要更小模型，必须在对应 configs/*.toml 中显式覆盖。

数据与 checkpoint¶

运行产物必须写入：

data/runs/<run_id>/

关键字段：

data.root
checkpoint.keep_slots
metrics.format
metrics.flush_every_steps
games.format
games.index
games.shard_max_games
games.shard_max_compressed_mib

checkpoint 默认是 PyTorch .pt，不额外压缩。棋谱默认是 JSONL.zst，索引默认是 SQLite。