ZGCM-1 仓库梳理存档 — 各阶段入口脚本与依赖环境

1. 仓库定位与整体链条

ZGCM-1（中关村学院 · 中关村人工智能研究院），7.39B dense 语言模型，从零训练，256K 上下文，主打数学推理 + 工具辅助搜索（agentic search），单一模型同时支持 thinking 与 direct-response 两种模式。MIT License。

对外资产
资产	位置
技术报告	arXiv:2609.13356 — ZGCM-1: A Fully Open and Extremely Efficient Foundation Model for Math and Agentic Search
模型权重	HuggingFace `zgcagi/ZGCM-1-7B`（加载需 `trust_remote_code`）
数据集	HuggingFace `zgcagi/ZGCM-1-Data`
许可	仓库 MIT；各阶段目录内含第三方 bundled license；模型/数据卡另有条款

报告的三阶段配方（仓库对应五个目录）：

Pretraining：约 4.19T tokens，课程式数据混合 + 混合 FP8 精度 + Muon 优化器。
Mid-training：约 600B tokens，上下文 16K → 64K → 256K 渐进扩展；交互轨迹被重构为 MDP 状态-动作转移以监督单步决策。
SFT：通用 + agentic 联合训练，thinking / direct-response 混合样本、执行验证过的轨迹、仅 assistant 计损；报告另探索了数学与代码的 mixed RL。

五个顶层目录 run closure 互相独立（每个 TRAINING_STAGE.md 都显式声明）：外部数据、模型资产、运行时环境全部通过该目录自身的配置声明。

数据流转链条：
data-process(清洗/分桶/混合) ─┐
pretrain_final ──> midtrain 16K ──> 64K ──> 256K ──> SFT(SOURCE_CKPT_ROOT/iter_0008000) ──> RL(GRPO, HF ckpt)

目录清单与文件规模（实测）
目录	领域	运行时文档	文件数	.py	体积
`data-process/`	AI-native 数据治理	`data-process/README.md` (8.3 KB)	—	—	—
`pretrain/`	预训练（含 bundled Megatron-LM）	`pretrain/README.md` · `docs/PRETRAIN_PHASES.md` · `docs/SOURCE_PROVENANCE.md`	2350(Megatron-LM)	927	39.1 MB
`midtrain/`	中期训练（含 bundled Megatron-LM）	`midtrain/README.md` · `docs/MIDTRAIN_STAGES.md` · `docs/SOURCE_PROVENANCE.md`	2350(Megatron-LM)	927	39.1 MB
`sft/`	监督微调（目录本身即 Megatron fork）	`sft/README.md` · `docs/sft/README.md` · `docs/sft/SOURCE_PROVENANCE.md`	2361	928	39.2 MB
`rl/`	强化学习（AReaL GRPO，不捆绑框架）	`rl/README.md` · `rl/ENVIRONMENT.md` · `rl/RUNNING.md` · `rl/TRAINING_STAGE.md`	21	11	~60 KB

全仓文件类型分布（前几）：.py 2856 · .json 2443 · .yaml 852 · .sh 402 · .md 346 · .yml 123 · .png 49 · .txt 9 · .jsonl 7 · .toml 7 —— 绝大多数来自三份重复的 Megatron-LM 树。

报告披露的效果指标（256K SFT checkpoint，thinking 模式；非 agentic 评测 temperature 1.0 / top-p 1.0 / 32 次 pass@1 均值）
Benchmark (%)	ZGCM-1	DeepSeek-R1-0528-Qwen3-8B	MiniCPM4.1-8B	Qwen3-8B	Olmo 3 7B Think
MATH-500	97.13	96.32	95.60	96.20	95.10
AIME 2024	80.62	83.33	83.33	80.00	71.60
AIME 2025	73.33	75.21	73.33	63.33	64.60
AIME 2026	75.00	69.17	71.67	66.67	66.16
HMMT 2025	70.42	61.50	52.50	43.33	43.89
HMMT 2026	59.48	51.52	46.21	45.45	43.94

Agentic search（报告 Table 3–4）
Benchmark	ZGCM-1 (%)	Setting
WebWalkerQA	63.09	Web search and page reading（最多 64 步搜索-阅读）
BrowseComp	19.43	Web search and page reading
GAIA (text-only)	42.52	Web search and page reading
Binary Function Search	62.00	31/50 精确函数入口匹配，Ghidra 工具，10 个 held-out 项目的 50 个任务

报告另称：256K 下 gated sliding-window + global attention 相比 full attention 训练吞吐 3.94×；架构+精度+优化器+归一化综合带来 16K 预训练 time-to-loss 约 4.2× 改善。全部评测覆盖 20 个 benchmark（含 code / knowledge / instruction following），在 14 个推理 benchmark 上于 7 个 7B–8B 对比模型中取得最佳平均排名。

2. 模型结构规格

规格	ZGCM-1
架构	Decoder-only dense Transformer
参数量	7.39B
层数 / hidden size	32 / 4,096
注意力	27 层 gated sliding-window + 5 层 global
局部窗口 / GQA 头	128 tokens（`WINDOW_SIZE="127,0"`）/ 32 query heads，8 KV heads
最大上下文	262,144 tokens (256K)

训练配置中实际使用的完整结构参数

来源：`pretrain/configs/stages/01_pretrain_1t_sequential.env` 与 `sft/training_launchers/stable_candidate/zgcm.conf`
参数	值	备注
`NUM_LAYERS` / `HIDDEN_SIZE` / `FFN_HIDDEN_SIZE`	32 / 4096 / 11008	SwiGLU
`NUM_ATTENTION_HEADS` / `NUM_QUERY_GROUPS` / `KV_CHANNELS`	32 / 8 / 128	`--group-query-attention`
`VOCAB_SIZE`	154,880	`--make-vocab-size-divisible-by 128`
`POSITION_EMBEDDING_TYPE`	rope	`ROTARY_PERCENT=0.334`
`ROTARY_BASE`	预训练/中期 5,000,000；SFT 10,000,000	SFT 阶段才提到 1e7
`NORM_EPSILON`	1e-6	RMSNorm
`WINDOW_SIZE` / `WINDOW_ATTN_SKIP_FREQ`	`127,0` / 6	每 6 层插一层 global → 32 层中 5 层 global、27 层 SWA
`QK_LAYERNORM`	1	`--qk-layernorm`
`ATTENTION_OUTPUT_GATE` / `ATTENTION_OUTPUT_GATE_ONLY_SWA`	1 / 1	输出门控只作用于滑动窗口层（ZGCM 定制）
dropout	attention 0.0 / hidden 0.0	硬编码在 launcher
其他	`--disable-bias-linear`、`--untie-embeddings-and-output-weights`、`--use-mcore-models`
`SEED`	6198	全阶段一致
Tokenizer	GLM5.1（静态目录），默认 `$SHARED_STORAGE_ROOT/models/glm51-tokenizer`	`--tokenizer-type HuggingFaceTokenizer`

3. `data-process/` — AI-native 数据治理本机已实测通过

纯 Python 包，只依赖标准库，本地环境即可运行，不需要集群、私有挂载或厂商 runtime。大规模抽取、分片、tokenize 与 indexed-dataset 写入由目标训练环境提供。

项	内容
依赖	`dependencies = []`；`requires-python >= 3.10`；build 需 `setuptools>=68`；读 `.zst` 输入需另装 `zstandard`
安装	`python3 -m venv .venv && . .venv/bin/activate && pip install -e .`；无 PyPI 访问时可免安装直接 `PYTHONPATH=src` 运行 examples 与 tests
入口（4 个 console script）	`zgcm-clean` → `zgcm_data_pipeline.cli:main` `zgcm-pretrain-clean` → `.stages.pretrain.cli:main` `zgcm-midtrain-clean` → `.stages.midtrain.cli:main` `zgcm-posttrain-clean` → `.stages.posttrain.cli:main`
各 stage 覆盖类别	pretrain: `code` / `pdf_ocr` / `general_text`；midtrain: `code` / `web` / `instruction` / `agentic` / `math` / `reasoning`；posttrain: message / reasoning / tool-call / packing 准备
公共 CLI 参数	`--input --output --dataset --config --manifest --summary --keep-dropped`；stage 入口额外校验 `--source --category --dataset-profile`

目录布局

data-process/
├── pyproject.toml                      # 包元数据 + CLI 入口
├── examples/                           # 最小 JSONL/JSON 输入
│   ├── instruction.jsonl               # 通用 instruction 示例
│   ├── quality-policies.json           # 质量/去重配置示例
│   └── datasets/                       # dataset-profile 示例
├── scripts/smoke_test.py               # 4 个 CLI 的端到端冒烟测试
├── src/zgcm_data_pipeline/
│   ├── common/                         # 共享 schema / quality / dedup / length / manifest
│   ├── steps/                          # code/web/instruction 等类别步骤
│   ├── stages/{pretrain,midtrain,posttrain}/
│   ├── adapters.py                     # 原始字段 → 规范 Sample 适配器
│   ├── core.py                         # Pipeline / Step / PipelineContext
│   ├── models.py                       # Stage / category / decision / Sample 模型
│   └── training.py                     # tokenization/packing/loss-mask 接口
├── tests/
└── docs/{dataset_category_inventory.md, category_cleaning_pipelines.md, category-cleaning-flow.svg}

处理契约

JSONL input
  → DatasetAdapter 字段映射
  → schema 与文本规范化
  → 完整性 / provenance / license / 敏感内容检查
  → AI 生成的 dataset profile
  → stage/category 共享 steps
  → 质量判定 (keep / review / drop)
  → 精确去重 + 可选近似去重
  → token 估算与长度分桶
  → cleaned JSONL + summary + manifest

每条序列化记录至少含：dataset、source_id、stage、category、decision、reasons、flags、buckets、metrics、data、record_sha256。data 保留源记录与规范化字段；reasons 解释 review/drop 决策；flags 记录审计标注。被丢弃记录默认不输出但仍计入 summary，用 --keep-dropped 检视。manifest 从序列化输出重建，因此记录数与下游 loader 实际读到的一致。

AI-native 治理模型

共享流水线提供的是稳定护栏而非一套固定规则：AI 检查某数据集的字段、噪声模式与任务目标后，产出独立的 adapter/profile（修字段、施源特定过滤、记录数据集专属指标），通过 DatasetAdapter 插入 stage 流水线。不同数据集保留各自规则，但共享同一套 decision、审计字段与下游接口。stages/*/datasets/ 与 examples/datasets/ 下是代表性实现，不是全部 cleaner 的完整目录。dataset profile 接受自带命名空间设置，如 finepdfs_*、olmocr_*、web_knowledge_*、dolci_think_*。license review 用 --require-license 或配置里的 require_license 开启。

长度分桶与中期训练混合（与 midtrain 直接对接）

未注入训练 tokenizer 时，共享 step 用可复现的 token 估算；生产集成应提供目标 tokenizer、chat template、indexed writer 与 loader 校验。

midtrain/buckets.py → B16 / B64 / B256 基础桶
midtrain/mix.py     → 稳定哈希构造【不相交】前缀混合：
    mix16  ← B16
    mix64  ← B16 + B64，排除已被 mix16 选中的 ID
    mix256 ← B16 + B64 + B256，排除已被 mix16/mix64 选中的 ID

mix 函数只返回选中 ID；配额策略、物化与 indexed-dataset 写入仍属训练环境集成。采样默认 seed zgcm，prefix_sample_mix 用 zgcm-midtrain；要跨包版本复现同一划分/顺序/采样，必须显式设 seed 并随数据集配置记录。

本地验证命令与实测结果

PYTHONPATH=src python3 -m unittest discover -s tests -v
python3 -m compileall -q src
python3 scripts/smoke_test.py

本机实测记录（2026-09-18，Windows + Python 3.10.10 @ D:\softwares\python\python.exe，set PYTHONPATH=src）

unittest discover -s tests → Ran 32 tests in 0.021s — OK（覆盖共享类别流水线、dataset profile、长度混合、message 转换、代表性 CLI 输入）
compileall -q src → exit 0，无语法错误
scripts/smoke_test.py → exit 0，4 个 CLI 全部产出 manifest：generic 1 条 / pretrain 1 条 / midtrain 2 条 / posttrain 1 条
测试后清理 __pycache__，git status --porcelain 与 --ignored 均为空，clone 保持干净

通用 instruction 示例（无需安装）：

OUTPUT_DIR="${OUTPUT_DIR:-outputs}"; mkdir -p "${OUTPUT_DIR}"
PYTHONPATH=src python3 -m zgcm_data_pipeline \
  --input examples/instruction.jsonl \
  --output "${OUTPUT_DIR}/instruction.cleaned.jsonl" \
  --dataset example_instruction --stage midtrain --category instruction \
  --text-fields instruction,output \
  --config examples/quality-policies.json \
  --manifest "${OUTPUT_DIR}/instruction.manifest.json"

训练前必须补做：在目标环境中验证 token 边界、loss mask、checksum 与全语料分布——这些不在本包范围内。

4. `pretrain/` — 预训练（约 4.19T tokens，16K 上下文）

两个数据阶段：0.99T 课程预训练 + 3.20T 全混合，均用 16K 上下文。配方 = 混合注意力 + Muon + FP8 delayed scaling。目录极简：scripts/launch_train.sh（218 行）+ 2 个 stage env + bundled Megatron-LM/。

阶段
Stage	配置	数据顺序	初始化
1T curriculum（0.99T）	`configs/stages/01_pretrain_1t_sequential.env`	Sequential（确定性顺序）	全新训练
3.2T full mixture	`configs/stages/02_pretrain_3p2t_global_shuffle.env`	离线全局 shuffle，顺序消费	Stage 1 最终 checkpoint

入口

# 在 pretrain/ 下，每台 worker 都要执行
export SHARED_STORAGE_ROOT="${SHARED_STORAGE_ROOT:?set SHARED_STORAGE_ROOT}"
export MASTER_ADDR="${MASTER_ADDR:?set MASTER_ADDR}"
export NODE_RANK="${NODE_RANK:-${RANK:?set NODE_RANK or RANK}}"

# Stage 1：1T 课程数据
bash scripts/launch_train.sh configs/stages/01_pretrain_1t_sequential.env

# Stage 2：若 stage-1 checkpoint 不在默认 run root 下需显式指定
export PRETRAIN_1T_FINAL_CHECKPOINT="${PRETRAIN_1T_FINAL_CHECKPOINT:?...}"
bash scripts/launch_train.sh configs/stages/02_pretrain_3p2t_global_shuffle.env

`scripts/launch_train.sh` 行为（已读源码）

只接受 1 个参数（stage env 路径），否则 exit 2；realpath 解析后 source，并导出 ZGCM_REPO_ROOT 为 pretrain/。
强制校验：MEGATRON_LM_ROOT、MEGATRON_VENV、TORCHRUN_BIN、TOKENIZER_PATH、TRAIN_ROOT、NUM_NODES、GPUS_PER_NODE、NODE_RANK、MASTER_ADDR、MASTER_PORT。
venv 不存在 exit 3；随后 export PYTHONPATH=$TRANSFORMER_ENGINE_HOME:$MEGATRON_LM_ROOT:$FLASH_ATTN_V3_EGG，设 NVTE_FRAMEWORK=pytorch、TOKENIZERS_PARALLELISM=false、PYTHONUNBUFFERED=1、MEGATRON_HOME。
路径存在性校验：MEGATRON_LM_ROOT、TOKENIZER_PATH、可选 PRETRAINED_CHECKPOINT；数据校验——有 DATA_ARGS_PATH 则校验该文件，否则要求 ${REAL_DATA_PREFIX}.idx 与 .bin 同时存在，缺失 exit 3。
NO_DATA_SHUFFLE=1 → export MEGATRON_GPT_DATASET_SEQUENTIAL=1，否则 unset。
默认输出根：SAVE/LOAD_CHECKPOINT_DIR = $TRAIN_ROOT/results/$EXP_NAME/checkpoints（load 默认等于 save）、TENSORBOARD_DIR、DATA_CACHE_DIR、LOG_DIR=$TRAIN_ROOT/logs，全部 mkdir -p。
REQUIRE_LOAD_CHECKPOINT=1 时校验 latest_checkpointed_iteration.txt 存在（缺失 exit 4），并在给了 RESUME_ITER 时断言 marker 迭代号精确相等（不等 exit 4）。
组装 argv：model（含 ZGCM 定制开关：--attention-output-gate、--attention-output-gate-only-swa、--qk-layernorm、--no-rope-fusion、--fp8-param-gather；TP≠1 自动追加 --sequence-parallel）+ training（TRAIN_ITERS 与 TRAIN_SAMPLES 二选一分支）+ parallel + data + logging。
固定项：--bf16、--calculate-per-token-loss、--ckpt-format torch_dist、--distributed-timeout-minutes 120、--log-throughput、--no-create-attention-mask-in-dataloader、attention/hidden dropout 0.0。
cd $MEGATRON_LM_ROOT 后 exec torchrun ... pretrain_gpt.py ... 2>&1 | tee -a $LOG_DIR/${EXP_NAME}_$(date -u +%Y%m%d_%H%M%S).log，并回显 run_tag / env / save / load。

Stage 1 完整配方（`01_pretrain_1t_sequential.env` 实测值）

0.99T 课程阶段
类别	参数	值
并行	TP / PP / CP	2 / 1 / 2，`CP_COMM_TYPE=a2a`，TP≠1 自动 `--sequence-parallel`
并行	分布式优化器	on；`overlap-grad-reduce` on，`overlap-param-gather` off
批与序列	MBS / GBS	2 / 768
批与序列	SEQ_LENGTH / MAX_POSITION_EMBEDDINGS	16384 / 16384
调度	迭代	`TRAIN_ITERS=79473`，`LR_WARMUP_ITERS=667`
调度	学习率	lr 2.0e-4 → min-lr 2.0e-5，`LR_DECAY_STYLE=constant`
优化器	类型	Muon（`OPTIMIZER=muon`）
优化器	Muon 细节	momentum 0.9、scale-mode `spectral`、fp32 matmul prec `medium`、coefficient-type `quintic`、NS steps 5、TP mode `blockwise`、extra scale factor 1.0、scalar optimizer `adam`
Adam/正则	beta / wd / clip	β1 0.9、β2 0.95、weight decay 0.1、clip-grad 1.0
Adam/正则	seed	6198
精度	实现	`TRANSFORMER_IMPL=transformer_engine`，`--bf16`
精度	FP8	format hybrid、recipe delayed、amax algo `max`、history len 1024、`FP8_PARAM_GATHER=1`
数据	顺序	`NO_DATA_SHUFFLE=1` → `MEGATRON_GPT_DATASET_SEQUENTIAL=1`
	切分/加载	`DATA_SPLIT=100,0,0`、`DATA_ARGS_PATH=""`（走 `--data-path $REAL_DATA_PREFIX`）、`num-workers 8`、`num-dataset-builder-threads 8`、`MEGATRON_DATALOADER_PREFETCH_FACTOR=4`
	数据集默认路径	`$SHARED_STORAGE_ROOT/datasets/zgcm7b/pretrain_1t_sequential_text_document`（可被 `PRETRAIN_1T_DATA_PREFIX` 覆盖）
重计算	`ENABLE_RECOMPUTE=0`（关闭）	granularity 默认 `selective`；full 时用 method/num-layers
日志/存档	interval	log 10、save 1000、eval-interval 1000、`eval-iters 0`、`RERUN_MODE=disabled`、`--ckpt-format torch_dist`
集群默认	规模	`NUM_NODES=${WORLD_SIZE:-24}` × `GPUS_PER_NODE=8` = 192 GPU
训练程序	`TRAIN_PROGRAM`	`pretrain_gpt.py`

运行时环境变量（stage env 中的默认值）

变量	默认	说明
`SHARED_STORAGE_ROOT` / `MASTER_ADDR` / `NODE_RANK`(或 `RANK`)	必填	三个硬必需项，调度器提供 `WORLD_SIZE`/`RANK`/`MASTER_ADDR`
`MEGATRON_LM_ROOT`	`${ZGCM_REPO_ROOT}/Megatron-LM`	ZGCM_REPO_ROOT 由 launcher 设置
`MEGATRON_VENV` / `TORCHRUN_BIN`	`$SHARED_STORAGE_ROOT/venvs/megatron` / `$MEGATRON_VENV/bin/torchrun`	必须存在 `bin/activate`
`TRANSFORMER_ENGINE_HOME` / `FLASH_ATTN_V3_EGG`	空	非空时前置进 PYTHONPATH
`TOKENIZER_PATH`	`$SHARED_STORAGE_ROOT/models/glm51-tokenizer`	GLM5.1 静态 tokenizer 目录
`TRAIN_ROOT`	`$SHARED_STORAGE_ROOT/runs/zgcm7b`	run/日志输出根
`MASTER_PORT`	6247	SFT 侧用 29731
`OMP_NUM_THREADS` / `CUDA_DEVICE_MAX_CONNECTIONS`	8 / 1
`PYTORCH_CUDA_ALLOC_CONF`	`expandable_segments:True`
`NCCL_IB_DISABLE` / `NCCL_DEBUG`	0 / WARN	多机需 IB/RDMA
`NVTE_CUDA_ARCHS`	90	sm90 = H100/H800；FP8 的硬性前提
`HF_HUB_OFFLINE` / `TRANSFORMERS_OFFLINE`	1 / 1	离线运行

stage env 顶部注释明确：“Override these defaults in the scheduler or edit this file for the target cluster; no other env file is sourced.” 可覆盖的资产变量还有 PRETRAIN_1T_DATA_PREFIX、PRETRAIN_3P2T_DATA_PREFIX、PRETRAIN_1T_OUTPUT_ROOT / _SAVE_CHECKPOINT_DIR / _LOAD_CHECKPOINT_DIR / _TENSORBOARD_DIR / _DATA_CACHE_DIR、PRETRAIN_LOG_DIR。EXP_NAME=zgcm7b_pretrain_1t_sequential。

5. `midtrain/` — 中期训练（600.51B，16K → 64K → 256K）

三段渐进扩展上下文，分别消耗 180B / 240B / 180.51B tokens；较长的上下文阶段仍保留较短样本。交互轨迹被重构为 MDP 状态-动作转移，与 code、math、knowledge、reasoning、instruction 数据一起进入课程。bundled Megatron-LM 为同一 commit。

入口（比 pretrain 多一步生成 data args）

# 在 midtrain/ 下，每台 worker 都要执行
export SHARED_STORAGE_ROOT=... MASTER_ADDR=... NODE_RANK=...
export ZGCM_REPO_ROOT="$(pwd)"

STAGE_CONFIG=configs/stages/01_seq16k.env
source "$STAGE_CONFIG"
scripts/build_midtrain_data_args.sh "$DATA_ARGS_PATH" \
  "$MIDTRAIN_LONG64K_ROOT" "$MIDTRAIN_SHORT16K_ROOT"
bash scripts/launch_train.sh "$STAGE_CONFIG"

后续阶段把 STAGE_CONFIG 换成 02_seq64k.env / 03_seq256k.env，并在前序输出不在默认 TRAIN_ROOT 布局下时导出 MIDTRAIN_SEQ16K_CHECKPOINT / MIDTRAIN_SEQ64K_CHECKPOINT。

三阶段配方（从三个 stage env 提取的实测值）
项	01_seq16k	02_seq64k	03_seq256k
Token 预算	180B	240B	180.51B
`TRAIN_SAMPLES`	10,986,240	3,662,016	688,560
SEQ_LENGTH / MAX_POS	16,384	65,536	262,144
TP / PP / CP	2 / 1 / 2	2 / 1 / 4	2 / 2 / 4
`CP_COMM_TYPE`	a2a（三段一致）
MBS / GBS	2 / 768	1 / 192	1 / 48
重计算	关闭	`selective`	`full` + method `uniform` + num-layers `1`
`EXP_NAME`	`zgcm7b_midtrain_seq16k_tp2cp2_gbs768_180b`	`zgcm7b_midtrain_seq64k_tp2cp4_gbs192_240b`	`zgcm7b_midtrain_seq256k_tp2pp2cp4_gbs48_180p51b`
初始化 (`PRETRAINED_CHECKPOINT`)	`${PRETRAIN_FINAL_CHECKPOINT}`，默认 `$TRAIN_ROOT/handoff/zgcm7b_pretrain_final`	`${MIDTRAIN_SEQ16K_CHECKPOINT}`，默认 `$TRAIN_ROOT/results/zgcm7b_midtrain_seq16k_tp2cp2_gbs768_180b/checkpoints`	`${MIDTRAIN_SEQ64K_CHECKPOINT}`，默认 `.../zgcm7b_midtrain_seq64k_tp2cp4_gbs192_240b/checkpoints`

三段共用设置
项	值
优化器	Muon，`MUON_SCALAR_OPTIMIZER=adam`，`USE_DISTRIBUTED_OPTIMIZER=1`
学习率	LR=2.0e-5，MIN_LR=2.0e-6（比预训练低一个量级）
结构开关	`WINDOW_SIZE="127,0"`、`WINDOW_ATTN_SKIP_FREQ=6`、RoPE base 仍 5e6（未提到 1e7）
数据	`DATA_SPLIT=9999,1,0`；`NO_DATA_SHUFFLE=0`（允许 shuffle）；`REAL_DATA_PREFIX=""` → 走 `--data-args-path`
数据根	`MIDTRAIN_LONG64K_ROOT` 默认 `$SHARED_STORAGE_ROOT/datasets/zgcm7b/midtrain_mix64_v3_indexed`；`MIDTRAIN_SHORT16K_ROOT` 默认 `.../midtrain_mix16_v4_indexed`
`DATA_ARGS_PATH`	默认 `$TRAIN_ROOT/configs/midtrain_data_args.txt`，由 `build_midtrain_data_args.sh` 生成
加载器	`DATA_NUM_WORKERS=4`、`NUM_DATASET_BUILDER_THREADS=8`、`REQUIRE_LOAD_CHECKPOINT=0`
训练程序	`pretrain_gpt.py`
输出	`$TRAIN_ROOT/results/$EXP_NAME/{checkpoints,tensorboard,data-cache}`，可被 `MIDTRAIN_SEQ{16K,64K,256K}_*_ROOT` 系列变量覆盖

数据混合的桶/前缀混合逻辑来自 data-process 的 midtrain buckets.py + mix.py（B16/B64/B256 → mix16/mix64/mix256 不相交）。

6. `sft/` — 监督微调（目录本身即 Megatron-LM fork）

与 pretrain/midtrain 不同，sft/ 没有 Megatron-LM 子目录：sft/pretrain_gpt.py、sft/megatron/、sft/train_rl.py、sft/uv.lock(1.1 MB) 就是 fork 本体（2361 文件，比另两份多 11 个 = SFT 定制 + docs/sft/ + .gitlab-ci.yml 等）。目录内含完整的 NVIDIA Megatron-LM 上游文档（docs/），ZGCM 专属 SFT 说明在 docs/sft/。另有 CI（.gitlab-ci.yml 8.5 KB）、pre-commit、pylint/flake8/codecov 配置、tests/、docker/、.claude/、CLAUDE.md/AGENTS.md。

包含：GLM5.1 tokenizer/template 契约、packed indexed SFT 数据集支持、FA3 variable-length attention、Muon 优化器、distributed checkpoint 兼容、单一生产 launcher。签入的候选配置基于 256K ThinkMix V1 + Locate run。运行时路径与实验设置刻意分离——换集群或换数据集不需要编辑 launcher。

文件职责四分离

路径	大小	职责
`training_launchers/stable_candidate/runtime.env`	2563 B	机器路径、Python/FA3/TE 环境、NCCL/Gloo 默认值
`training_launchers/stable_candidate/zgcm.conf`	2367 B	模型、数据身份、并行、优化器、调度、epoch 设置
`training_launchers/stable_candidate/launch.sh`	5753 B	校验 metadata、推导迭代数、启动训练
`.../run_sft_thinkmix64k_fa3_tpcomm_formal_20260715.sh`	24998 B	通用的、与序列长度无关的 Megatron 调用主体
`.../pretrain_gpt_force_mcore_save.py`	3267 B	强制 mcore dist-ckpt 保存
`.../pretrain_gpt_rank_cache_mcore_wrapper.sh`	950 B	rank cache / mcore 包装
`.../README.md`	3537 B	launcher 说明
`docs/sft/README.md` · `docs/sft/SOURCE_PROVENANCE.md`	—	实现范围与验证证据 / Megatron 源版本

硬性要求

Linux worker，每 worker 8 张 CUDA GPU。
Python 3.12 环境，含兼容的 PyTorch、Transformer Engine、FA3 overlay 与仓库依赖（PYTHON_SITE_PACKAGES=${ENV_ROOT}/lib/python3.12/site-packages，同时充当 FA3_OVERLAY 与 TRANSFORMER_ENGINE_HOME）。
与所配模型兼容的 Megatron distributed checkpoint。
静态 GLM5.1 tokenizer 目录。
Packed indexed SFT 数据，tokens / targets / cu_seqlens 三套 .bin/.idx 文件必须对齐。
per-split data-args JSON + metadata/ready JSON，其中 train_tokens 必须为正（最好也含 train_records）。
多机需 NCCL/RDMA 连通。
具体集群路径、凭据、cookie、代理地址必须留在仓库之外（runtime.env 注释重复强调）。

三个启动姿势

# 0) 导出五个必需根
export ENV_ROOT="${ENV_ROOT:?path to the Python runtime}"
export PROJECT_ROOT="${PROJECT_ROOT:?shared output root}"
export SOURCE_CKPT_ROOT="${SOURCE_CKPT_ROOT:?source checkpoint root}"
export DATA_ROOT="${DATA_ROOT:?packed indexed SFT data root}"
export TOKENIZER="${TOKENIZER:?tokenizer directory}"

# 命名不同时可覆盖（示例）
export CKPT_LOAD_ITER=8000
export SOURCE_CKPT_ITER="${SOURCE_CKPT_ROOT}/iter_0008000"
export SOURCE_DATA_ARGS="$DATA_ROOT/meta/indexed_per_split_data_args.json"
export INDEXED_DONE="$DATA_ROOT/DATA_READY"
export DATASET_METADATA="$INDEXED_DONE"

# 1) 只校验配置：验证数据集 metadata、身份、推导迭代数，不建 run、不起分布式 worker
VALIDATE_CONFIG_ONLY=1 bash training_launchers/stable_candidate/launch.sh

# 2) 单机 8 卡冒烟（TP=8；DP=1 时自动关闭 DP overlap，TP comm overlap 仍开）
export NNODES=1 NODE_RANK=0 MASTER_ADDR=127.0.0.1 MASTER_PORT=29731
SFT_WORKER_NUM_OVERRIDE=1 SFT_RUN_NAME_OVERRIDE=zgcm-sft-smoke SMOKE_TRAIN_ITERS=2 \
  bash training_launchers/stable_candidate/launch.sh
#    冒烟模式【禁用 checkpoint 保存】，但保留由 metadata 推导的完整 LR decay 视野
#    （限制活跃迭代不会压扁学习率调度）；不验证存盘/续跑

# 3) 多机（调度器 PyTorch-DDP 模式，每 8-GPU 节点一个 worker，启用 RDMA）
export NNODES="${WORLD_SIZE}" NODE_RANK="${RANK}" NPROC_PER_NODE=8
bash training_launchers/stable_candidate/launch.sh

# 4) 正式训练（校验 + 冒烟后，去掉 SMOKE_TRAIN_ITERS）
bash training_launchers/stable_candidate/launch.sh

# 换实验而不复制 launcher：在调度器/私有 shell 里设 SFT_ENV_FILE 与 SFT_CONFIG_FILE，
# 然后在 sft/ 下运行同一个 launch.sh

迭代数推导（数据集 metadata 才是权威输入）

EPOCH_ITERS   = floor(TRAIN_TOKENS / (SEQ_LENGTH * GLOBAL_BATCH_SIZE))
TRAIN_ITERS   = floor(TRAIN_TOKENS * EPOCHS / (SEQ_LENGTH * GLOBAL_BATCH_SIZE))
SAVE_INTERVAL = EPOCH_ITERS * SAVE_EVERY_EPOCHS

有效 epoch 数与请求 epoch 数相差 ≥ 0.01 时 launcher 直接拒绝该计划。
zgcm.conf 里的 EXPECTED_TRAIN_TOKENS=19,462,049,882 与 EXPECTED_TRAIN_RECORDS=76,325 是身份守卫（identity guards），不参与迭代计算。

签入候选 run 的完整配置（`zgcm.conf` 实测值）

类别	参数	值
Run 名	`RUN_NAME`	`zgcm7b-sft-thinkmix-v1-locate-256k-fa3-tpcomm-tp8-g48-lr1e4-cos1e6-nowarmup-wd001-eps1e8-10ep-rope10m-maxpos256k-192g`
上下文	SEQ_LENGTH / MAX_POSITION_EMBEDDINGS	262,144 / 262,144（256K）
上下文	RoPE	base 10,000,000，percent 0.334
并行/批	TP / PP / CP	8 / 1 / 1，`VIRTUAL_PIPELINE_LAYERS=0`
并行/批	MBS / GBS	1 / 48
集群	WORKER_NUM × GPUS_PER_WORKER	24 × 8 = 192 GPU，`NPROC_PER_NODE=8`
优化器	类型	Muon，scalar optimizer `adam`
	Muon 细节	momentum 0.9、`spectral`、fp32 matmul `medium`、`quintic`、NS 5、TP mode `blockwise`、extra scale 1.0
	调度	lr 1e-4 cosine → min-lr 1e-6，warmup 0，wd 0.01，β1 0.9 / β2 0.95 / eps 1e-8，clip-grad 1.0
精度/注意力	精度	BF16 + Transformer Engine FP8 hybrid delayed scaling，`ENABLE_FP8_PARAM_GATHER=1`
	注意力	`ATTENTION_MODE=fa3`，`ATTENTION_BACKEND=flash`（FA3 variable-length flash attention）
	窗口	`WINDOW_SIZE=127,0`，`WINDOW_ATTN_SKIP_FREQ=6`，RMSNorm eps 1e-6
重计算	模式	`RECOMPUTE_MODE=full`，granularity `full`，method `uniform`，num-layers `1`（全量激活重计算）
通信重叠	开启项	grad-reduce overlap、param-gather overlap、TP comm overlap（`TP_COMM_OVERLAP_CFG` 空）、P2P overlap、fully-parallel ckpt load
通信重叠	关闭项	`ENABLE_GRAD_ACCUM_FUSION=0`
数据	Token / 记录	train tokens 19,462,049,882；train records 76,325
数据	混合权重	QCORE 0.9863261526091283（75,242 rec / 19,195,928,782 tok）、THINK 0.01367384739087167（1,083 rec / 266,121,100 tok）、TOOL 0.0（0 rec/0 tok）
epoch / 存档	调度	10 个 token-based epoch，每 epoch 存一次（`EPOCHS=10`，`SAVE_EVERY_EPOCHS=1`，`ENABLE_SAVE=1`）
加载器	配置	`DATALOADER_TYPE=cyclic`，`DATASET_BUILDER_THREADS=64`，`NUM_WORKERS=0`
评估/日志	配置	`EVAL_ITERS=20`，`ENABLE_SWANLAB=0`（project `zgcm-s4-sft`），`DISTRIBUTED_TIMEOUT_MINUTES=120`，seed 6198

`runtime.env` 关键环境（实测内容）

五个必填根：ENV_ROOT / PROJECT_ROOT / SOURCE_CKPT_ROOT / DATA_ROOT / TOKENIZER；任一为空则 return 2（或 exit 2）。
路径推导：PYTHON_BIN=${ENV_ROOT}/bin/python；CKPT_LOAD_ITER=8000 → SOURCE_CKPT_ITER=${SOURCE_CKPT_ROOT}/iter_0008000（用 printf 'iter_%07d'）；SOURCE_DATA_ARGS 默认 ${DATA_ROOT}/meta/indexed_per_split_data_args.modelware.json；INDEXED_DONE=${DATA_ROOT}/MODELWARE_READY；DATASET_METADATA=$INDEXED_DONE；QCORE_ROOT / THINK_ROOT / TOOL_ROOT 都默认 $DATA_ROOT。
Python/库：PYTHON_SITE_PACKAGES=${ENV_ROOT}/lib/python3.12/site-packages，并令 FA3_OVERLAY、FA3_TRANSFORMER_ENGINE_HOME、TRANSFORMER_ENGINE_HOME 全指向它。
网络：NCCL_SOCKET_IFNAME=eth0、GLOO_SOCKET_IFNAME=eth0、NCCL_IB_GID_INDEX=7、NCCL_IB_DISABLE=0、NCCL_DEBUG=WARN、MASTER_PORT=29731。
CUDA：CUDA_VISIBLE_DEVICES=0..7、CUDA_DEVICE_MAX_CONNECTIONS=1、PYTORCH_ALLOC_CONF 与 PYTORCH_CUDA_ALLOC_CONF 均 expandable_segments:True、OMP_NUM_THREADS=8。
NCCL 监控：TORCH_NCCL_ENABLE_MONITORING=0、TORCH_NCCL_HEARTBEAT_TIMEOUT_SEC=1800。
torch.compile 全关：TORCHDYNAMO_DISABLE=1、TORCH_COMPILE_DISABLE=1、TORCHDYNAMO_SUPPRESS_ERRORS=1。
TE 后端选择：NVTE_FRAMEWORK=pytorch、NVTE_CUDA_ARCHS=90、NVTE_FLASH_ATTN=1、NVTE_FUSED_ATTN=0、NVTE_UNFUSED_ATTN=0。

输出目录结构

$PROJECT_ROOT/megatron_runs/$RUN_NAME/
├── checkpoints/
├── configs/run_manifest.json     # 记录生效的启动配置
├── data/per_split_data_args.json
├── data-cache/
├── logs/                         # rank-local：已解析的 ckpt/数据输入、并行、优化器、overlap、GPU 遥测
├── status/train.done
└── tensorboard/

已验证配置与实测性能

规模	配置	结果
单节点 8×H100	TP8/DP1，256K，FA3，Muon，full recompute	1 个优化步 + validation/test，成功完成
8 节点 64×H100	TP8/DP8，256K，FA3，Muon，DP/TP overlap	2 个优化步 + 20 val + 20 test，无 NaN / OOM / NCCL 错误 / traceback / 跳步
64 GPU 稳态	GBS48	≈33.32 s/step ≈ 377.6K tokens/s（集群）；GPU 活跃利用率均值 98.05%；单卡峰值显存 ≈69.75 GiB

注意：这些短跑验证的是运行时行为与分布式通信，不是收敛性或模型质量评估。GBS=48 + MBS=1 → 每 DP rank 每优化步 6 个 microbatch。

运维注意事项（README 原文归纳）

dist-ckpt 被重分片进不同 TP/PP 布局时，TP/PP mismatch 警告是预期的——判断标准是参数加载是否仍报成功。
通用 flash-attention 版本告警可能不认 FA3 overlay。需验证 flash_attn_interface.py 导出了 flash_attn_varlen_func，且 run manifest 标识的是 FA3 路径。
DP grad-reduce 与 param-gather overlap 要求 DP > 1。
迭代数由 launch.sh 从「数据集 metadata × seq length × GBS × epoch」推导。
冒烟跑刻意禁用 ckpt 保存，因此不验证保存/续跑。
调度器入口只应包含运行时 export 与对 launch.sh 的调用；模型与优化器参数属于 zgcm.conf。

7. `rl/` — AReaL GRPO 最精简：21 个文件，不捆绑框架

探索数学、代码、通用能力三域的 mixed RL，算法为 Group Relative Policy Optimization (GRPO)，对应技术报告 §4.2。目录含发布模型最终 math GRPO 阶段所用的确切配置、奖励实现与训练入口，外加 mixed-RL 实验中 code 与 instruction-following 两阶段的配置/奖励/入口。

术语澄清（仓库专门强调，最近一次提交就在改这里）：本仓库的 “mixed RL” 指跨三个任务域的 RL 计划，不是混合域 batch。发布的各阶段每个都只训单一域，代表我们找到的每域可用配置；它们共享同一套 GRPO 配方骨架。混合域 batch 可以用同一批组件自行组合——逐行路由器 rewards/rewards.py 在标准 AReaL workflow 下把每行分派给其所属域的 reward。

框架与精确依赖钉版

训练框架：AReaL v2.0.0（commit fee938e），需从源码在该 commit 安装。Python 3.12。以下为发布 run 验证过的确切栈：

Package	Version
torch	2.11.0+cu129
vllm	0.25.1+cu129
transformers	5.14.1
ray	2.56.0
math-verify	0.8.0
flashinfer-python	0.6.13
antlr4-python3-runtime	4.13.2

三个训练入口

export ZGCM_MODEL_PATH=/path/to/zgcm1_checkpoint   # HF checkpoint（带 tokenizer）
export ZGCM_TRAIN_JSONL=/path/to/train.jsonl
export ZGCM_VALID_JSONL=/path/to/valid.jsonl
export AREAL_ADMIN_API_KEY=local-key               # 本地任意非空串即可
export ZGCM_RL_STATUS_ROOT=./status                # eval marker 落点

cd rl
PYTHONPATH=. python train/length_shaped_math_grpo.py configs/math_grpo_length_shaped.yaml  # 最终 math 阶段
PYTHONPATH=. python train/code_grpo.py configs/code_grpo.yaml                              # 需沙箱服务
PYTHONPATH=. python train/if_grpo.py   configs/if_grpo.yaml                                # 需 IFEvalG 注册表

可选闸门：ZGCM_EXPECTED_TRAIN_ROWS / ZGCM_EXPECTED_VALID_ROWS 强制精确行数；ZGCM_N_NODES / ZGCM_N_GPUS_PER_NODE 指定集群规模。

目录布局

rl/
├── configs/
│   ├── math_grpo_length_shaped.yaml   # 最终 math 阶段（env 参数化）
│   ├── code_grpo.yaml                 # mixed-RL code 阶段
│   └── if_grpo.yaml                   # mixed-RL instruction-following 阶段
├── rewards/                           # 11 个 .py
│   ├── completion.py                  # 抽取 </think> 之后的可见答案 + Python 代码块
│   ├── math_reward.py                 # math-verify 等价性奖励
│   ├── ifeval_reward.py               # Open-Instruct IFEvalG 约束奖励
│   ├── sandbox_client.py              # code 奖励：HTTP 沙箱客户端 + 资产哈希
│   ├── sandbox_server.py              # 参考沙箱服务（namespace 隔离）
│   ├── sandbox_runner.py              # chroot 内的受信内层 runner
│   ├── sandbox_rootfs.py              # 最小只读 rootfs 构建器（tmpfs）
│   ├── rewards.py                     # 域路由（math/code/if）+ async 入口
│   └── __init__.py
└── train/
    ├── length_shaped_math_grpo.py     # math 入口：workflow + 组过滤 + 版本锚定 eval
    ├── code_grpo.py                   # code 入口：沙箱重试 + dump 审计式 eval
    ├── if_grpo.py                     # if 入口：注册表 preflight + 版本锚定 eval
    └── __init__.py

数据与奖励设计

用初始策略的 rollout 估计 prompt 难度，剔除已被频繁解出的题目，把训练集中到有用学习信号上。

数学：二值答案正确性奖励。可见答案在闭合的 </think> 之后抽取（completion.py），与 gold label 用 math-verify worker 比对（precision=6，timeout=8s，双向等价），返回严格二值 r_raw ∈ {0,1}。
代码：可执行测试通过比例。取可见答案中最后一个 fenced Python 块，针对内容哈希的测试资产在隔离沙箱中验证，永远走 HTTP；task_type 为 code（函数调用测试）或 code_stdio（stdin/stdout 比较）。参考沙箱服务（sandbox_server.py/sandbox_runner.py/sandbox_rootfs.py）= loopback HTTP server，在 user/network/PID namespace + tmpfs 只读 chroot 中执行每个候选，带每测 CPU/内存/进程/文件 rlimits、无网络出口、nonce 匹配结果，启动时自我 attestation，任一隔离属性缺失则 fail closed。需 root。
指令跟随：满足的显式约束比例。每条 prompt 带 ifeval_spec（instruction id + kwargs），用 Open-Instruct 的 IFEvalG checker 注册表评估；checker 自身抛异常按基础设施故障处理，而不是按答错。
无效或被截断的响应拿不到正奖励。
内部流水线的 general-domain judge 依赖内部服务，未随仓库重新分发；路由器对未知域直接 raise，让不支持的混合响亮失败而不是静默给 0 分。
测试资产布局：<root>/<hash[:2]>/<hash>.json.gz，每个文件是 JSON 测试列表且其 SHA-256 等于自身文件名，另有顶层 manifest.json。

Correct-only 长度惩罚（仅 math）

penalty = 0.05 * clip((n_out - 16384) / (65536 - 16384), 0, 1)
r       = r_raw * (1 - penalty)

惩罚从 16,384 生成 token 线性爬升到 65,536 上限，且只在 r_raw = 1 时生效：满长度且完全正确的答案得 0.95 而非 1.0；答错恒为 0。
被长度上限截断（stop_reason = length）的响应直接 0 分。
评估运行关闭惩罚（apply_length_penalty = False），只按原始正确率打分。

Dynamic sampling（组过滤）

按原始二值正确率而非 shaped reward 过滤（accept_math_group）：一组 8 条响应在下列情况整组丢弃——全对或全错（正确率零方差）、任一 reward 落在 [0,1] 之外或非有限、组内最长轨迹超过 69,632 token 的 learner 侧上限。code 与 if 阶段对各自的分数型奖励套用同一组过滤（accept_code_group / accept_if_group）；if 过滤额外拒绝任何 [0,1] 之外的 reward。

训练设置

最终 math GRPO 阶段（`configs/math_grpo_length_shaped.yaml`）
设置	值
优化目标	GRPO（无 critic、无 reference policy、`kl_ctl = 0`）
Actor 优化器	Adam，lr 1e-6 constant（3% warmup），weight decay 0.01，grad clip 1.0
裁剪	`eps_clip = 0.2`，token 级重要性采样
奖励归一化	组内 mean/std，8 条响应（unbiased）
优势归一化	batch 级
每次更新 minibatch	12；序列打包上限 69,632 tokens（FFD 装箱）
拒绝掩码	token 级 ratio 上界 5.0
每步采样	384 prompts × 8 responses = 3,072 trajectories
采样参数	temperature 1.0，top-p 1.0
生成上限	65,536 tokens；prompt+response 总上下文 98,304；prompt ≤ 4,096
步数 / epoch	177 / 3
评估	每 10 步（另含 step 0 与最终步），每 prompt 8 样本，raw 正确率

三个阶段差异（共享同一 recipe 骨架：同优化器、裁剪、归一化、token 预算、采样参数）
维度	math（发布）	code	instruction-following
配置文件	`math_grpo_length_shaped.yaml`	`code_grpo.yaml`	`if_grpo.yaml`
训练入口	`train/length_shaped_math_grpo.py`	`train/code_grpo.py`	`train/if_grpo.py`
长度惩罚	有（correct-only，最多扣 0.05）	无——奖励为原始通过测试比例	无——奖励为原始满足约束比例
截断响应	0 分	仍为 0 分	仍为 0 分
步数 / epoch	177 / 3	153 / 3	219 / 3
评估频率 / 样本数	每 10 步，8 样本/prompt	baseline + 最终 + 每 51 步，1 样本/prompt	每 10 步，8 样本/prompt
评估指标	raw 正确率	二值 all-tests-pass@1（每题最多 64 个测试）	满足约束比例
特有机制	版本锚定 eval marker	训练后审计 dump 的 eval rollout（完整性、版本钉定、二值奖励），再写 marker；沙箱瞬时故障重试最多 3 次（1s / 3s 退避）后才让 run 失败	启动前注册表 preflight 校验每个 instruction id
Checkpoint / recovery	周期存 ckpt（math 与 if 每 10 步，code 每 51 步），recovery state 每步写（`recover.mode: auto`）

报告 §4.2 描述的更早变体还探索过更大的 response-group 规模（actor lr 2e-6）与 reference-policy KL 变体；发布配置采用上表数值。

评估与恢复

math 与 if 入口每 10 步（以及 step 0 与最终步）用每 prompt 8 样本、raw 奖励打分，结果写成版本锚定 marker $ZGCM_RL_STATUS_ROOT/evaluations/version_XXX.json，这同时让周期性评估跨重启幂等。code 入口在 baseline 步、最终步与每 51 步评估（1 样本/prompt，二值 all-tests-pass@1），训练后审计 dump 出的 rollout 并在 $ZGCM_RL_STATUS_ROOT 写 code_eval_baseline.json / code_eval_stepXXX.json / code_eval_final.json。

额外依赖与环境变量

阶段	需要的额外组件	环境变量
math（发布最终阶段）	只需 `rewards/` 自带的数学验证器	`ZGCM_MODEL_PATH`、`ZGCM_TRAIN_JSONL`、`ZGCM_VALID_JSONL`、`AREAL_ADMIN_API_KEY`、`ZGCM_RL_STATUS_ROOT`
code	`requests`（沙箱 HTTP 客户端）；代码沙箱服务——参考的 namespace 隔离 server（需 root），或任意 Open-Instruct 兼容的 `test_program` HTTP 端点；内容哈希的测试资产根	服务端：`ZGCM_CODE_SANDBOX_TOKEN`（随机串，≥32 字符）启动：`python -m rewards.sandbox_server --port 8090 --asset-root /path/to/code_assets --rootfs /dev/shm/zgcm-code-rootfs --build-rootfs`
code	客户端配置	`ZGCM_CODE_SANDBOX_MODE=attested-http`（或 `namespace-http` / `open-instruct-http`）、`ZGCM_CODE_SANDBOX_URL=http://127.0.0.1:8090`、`ZGCM_CODE_SANDBOX_TOKEN`、`ZGCM_CODE_ASSET_ROOT`、`ZGCM_CODE_EXPECTED_IDENTITY_FILE`（attested 模式：启动后拉一次 `/health` 并把身份字段写入该 JSON 以钉定服务身份）、`ZGCM_CODE_MAX_TESTS`（默认 8）、`ZGCM_CODE_TEST_TIMEOUT_SECONDS`（默认 2）
instruction-following	Open-Instruct checkout（提供 `open_instruct.IFEvalG`）及其依赖所在 site-packages；NLTK `punkt` 与 `punkt_tab/english`	`ZGCM_OPEN_INSTRUCT_ROOT`、`ZGCM_OPEN_INSTRUCT_SITE_PACKAGES`、`NLTK_DATA` 预检 API：`rewards.ifeval_reward.validate_ifeval_registry` / `ifeval_preflight`

训练绝不在进程内执行模型输出——代码奖励一律由隔离服务经 HTTP 计算。

Prompt JSONL schema

// math（通用形状）：sample_id / domain / task_type / messages / answers 必填
//   domain 必须为 "math"，answers 非空；benchmark 可选，仅用于拆分 eval 统计
//   prompt 渲染后不得超过 4,096 tokens
{"sample_id":"math-000155d909841838fb9e67c7","domain":"math","task_type":"math",
 "messages":[{"role":"user","content":"..."}],"answers":["28"],"benchmark":"aime24"}

// code：task_type = "code"(函数调用测试) 或 "code_stdio"(stdin/stdout 比较)
{"sample_id":"code-...","domain":"code","task_type":"code",
 "messages":[...],"answers":[""],"code_asset_hash":"<64 hex>","prompt_hash":"<64 hex>"}

// if：ifeval_spec 列出对可见答案检查的 instruction id 与 kwargs
{"sample_id":"if-...","domain":"if","task_type":"if",
 "messages":[...],"answers":[""],"ifeval_spec":[
   {"instruction_id":"language:response_language","kwargs":{"language":"en"}}]}

发布的三个训练入口各自只训单一域；因路由器逐行分派，自定义 run 可用标准 AReaL workflow 在同一个 JSONL 里混合这些行形状。

实验流程（`RUNNING.md` 五步）

用初始策略的 rollout 估计 prompt 难度，剔除已被频繁解出的题。
每训练步为 384 个 prompt 各采 8 条响应（temperature 1.0，top-p 1.0）。
用 rewards/ 的二值数学验证器打分，再施 correct-only 线性长度惩罚（16,384 → 65,536 token，最多 0.05）；截断响应奖励 0。
按原始二值正确率过滤零方差组（dynamic sampling），另过滤奖励越界/非有限的组与轨迹超过 69,632 token learner 上限的组。
构造组相对优势（组内奖励归一化 + batch 级优势归一化），以 actor lr 1e-6 做 GRPO 优化（eps_clip = 0.2，无 reference policy，kl_ctl = 0）。

响应/总上下文预算分别为 65,536 与 98,304 tokens，prompt 上限 4,096。训练数据不随仓库分发，需先按上述 schema 自备 prompt JSONL。

8. 上游来源与 ZGCM 定制点

阶段	基线	commit / 版本
pretrain	NVIDIA Megatron-LM（bundled 在 `pretrain/Megatron-LM/`）	`eba2eaf71d34274c1ca0a59ac5e57a6bf53eb732`（2026-04-07）
midtrain	NVIDIA Megatron-LM（bundled 在 `midtrain/Megatron-LM/`）	同上 commit
sft	NVIDIA Megatron-LM + Megatron Core（`sft/` 目录本体即 fork）	同上 commit
rl	AReaL（外部，不随仓库分发，需从源码装）	v2.0.0，commit `fee938e`
data-process	ZGCM 自有包 `zgcm-data-pipeline` v0.1.0（无上游）	requires-python ≥ 3.10，零依赖

实测发现：pretrain/Megatron-LM 与 midtrain/Megatron-LM 是逐文件 MD5 完全一致的两份拷贝（同名但内容不同 = 0，仅 midtrain 独有 = 0，共 2350 文件 / 39.1 MB 各）。sft/ 是第三份（2361 文件 / 928 个 .py / 39.2 MB）。三树合计约占仓库体积的绝大部分。

ZGCM 相对上游 Megatron-LM 的定制（`docs/SOURCE_PROVENANCE.md` + 源码核实）

预训练侧 ZGCM-1 训练源提供：

ZGCM-1 attention output gating on sliding-window layers — 核实落点：megatron/core/transformer/transformer_config.py 的 attention_output_gate / attention_output_gate_only_swa（另有 attention_output_gate_only_global）；megatron/training/training.py L517、L613–636 用其计算 gate projection 参数量（按 gated 层数与是否 only-SWA 分别统计）。
Muon QKV splitting，支持同时含 gated 与 ungated 层的栈 — 核实落点：megatron/core/optimizer/muon.py、emerging_optimizers.py（L145–150 依 attention_output_gate* 分支）、optimizer_config.py、layer_wise_optimizer.py、transformer_config.py、optimizer_param_scheduler.py、multi_latent_attention.py、absorbed_mla.py、language_module.py。
确定性顺序 GPT 数据集顺序（早期 Pretrain 用）— 由 MEGATRON_GPT_DATASET_SEQUENTIAL=1 触发。
全局 shuffle 的顺序数据 + consumed-sample offset。
dataloader 预取控制（MEGATRON_DATALOADER_PREFETCH_FACTOR）。
eval_iters=0 时跳过 validation/test dataloader。

SFT 分支在此之上再加：GLM5.1 SFT 数据集与 tokenizer 契约、packed-sequence 训练输入、variable-length FA3、attention output gating、TP-aware Muon 行为、distributed checkpoint 兼容、stable SFT launcher。

额外核实到的自定义命令行参数（megatron/training/arguments.py）：--window-attn-skip-freq(L2029)、--muon-scalar-optimizer(L2259，默认 adam)、--num-dataset-builder-threads(L2906，默认 1)。Muon 专属参数族：--muon-momentum、--muon-scale-mode、--muon-fp32-matmul-prec、--muon-coefficient-type、--muon-num-ns-steps、--muon-tp-mode、--muon-extra-scale-factor。

参考运行时（pretrain / midtrain）

组件	版本
Python	3.12.3
PyTorch	2.7.0a0+79aa17489c.nv25.04（CUDA 12.9）
Transformer Engine	2.15.0.dev0+5f9550ff
FlashAttention 2	2.7.3
FlashAttention-3	3.0.0

注意 pretrain/midtrain（torch 2.7.0a0 nv25.04 / CUDA 12.9）与 rl（torch 2.11.0+cu129 / vLLM 0.25.1）是两套不同的运行时栈，不要混用同一个 env。

9. 本机可运行性结论 Windows / 无 NVIDIA GPU

阶段	可运行性	阻塞原因 / 最小前提
`data-process`	✅ 可以，已实测通过	零依赖纯标准库；Python ≥3.10 即可（本机 3.10.10 验证：32 tests OK + compileall OK + smoke test exit 0）
`pretrain`	❌ 不行	Linux + 每机 8 张 sm90 (H100/H800) GPU（FP8 hybrid 硬要求，`NVTE_CUDA_ARCHS=90`）；默认 24 节点 = 192 GPU；启动脚本假定 Linux venv 布局（`$VENV/bin/activate`、`bin/torchrun`）；需 TE/FA3 overlay、GLM5.1 tokenizer、indexed `.bin/.idx` 数据
`midtrain`	❌ 不行	同上；另需前序 checkpoint 链（pretrain_final → 16K → 64K）与 `midtrain_mix{16,64}_*_indexed` 数据集
`sft`	❌ 不行	Linux + 每 worker 8 GPU；最少 8 卡才能跑 TP8 单机冒烟（256K seq + full recompute）；Python 3.12 + FA3 overlay + TE；需 packed indexed SFT 数据 + dataset metadata；正式配置 24 worker = 192 GPU
`rl`	❌ 不行	Linux + GPU 集群；需先从源码装 AReaL@`fee938e`、vLLM 0.25.1+cu129、Ray 2.56.0、flashinfer 0.6.13；code 奖励的沙箱服务需 root 与 namespace/tmpfs 支持；if 奖励需 Open-Instruct checkout + NLTK 数据

结论：Windows 侧现实可做的是读代码 / 改配置 / 跑数据治理流水线 / 离线单测纯函数逻辑。真要起训必须在 Linux GPU 集群上，并且先从 HuggingFace 取三件资产：GLM5.1 tokenizer、数据集 zgcagi/ZGCM-1-Data、权重 zgcagi/ZGCM-1-7B（加载需 trust_remote_code）。

各阶段 GPU 规模速查

阶段	默认规模	来源变量
pretrain	24 节点 × 8 = 192 GPU	`NUM_NODES=${WORLD_SIZE:-24}`、`GPUS_PER_NODE=8`
midtrain	同上骨架（调度器注入 `WORLD_SIZE`/`RANK`）	`NUM_NODES`、`GPUS_PER_NODE`
sft	24 worker × 8 = 192 GPU（已验证 64 GPU 布局：8 worker TP8/PP1/CP1 → DP8）	`WORKER_NUM=24`、`GPUS_PER_WORKER=8`、`NPROC_PER_NODE=8`
rl	由使用方指定	`ZGCM_N_NODES`、`ZGCM_N_GPUS_PER_NODE`

10. 配套资产与已知缺口

跑通各阶段需要自备的外部资产
资产	用在哪	默认/期望位置	状态
GLM5.1 静态 tokenizer 目录	pretrain / midtrain / sft	`$SHARED_STORAGE_ROOT/models/glm51-tokenizer`；SFT 用 `$TOKENIZER`	需自备
indexed 预训练数据 `*.bin/.idx`	pretrain stage 1	`$SHARED_STORAGE_ROOT/datasets/zgcm7b/pretrain_1t_sequential_text_document`	需自备（HF `ZGCM-1-Data`）
`midtrain_mix16_v4_indexed` / `midtrain_mix64_v3_indexed`	midtrain 三段	`$SHARED_STORAGE_ROOT/datasets/zgcm7b/`	需自备
packed indexed SFT 数据（`tokens`/`targets`/`cu_seqlens`）+ per-split data-args JSON + metadata/ready JSON	sft	`$DATA_ROOT`；`meta/indexed_per_split_data_args.modelware.json`；`$DATA_ROOT/MODELWARE_READY`	需自备；`train_tokens` 必须为正
Megatron distributed checkpoint（`iter_0008000`）	sft 初始化	`$SOURCE_CKPT_ROOT/iter_0008000`	需自备
Python venv（Megatron 栈）	pretrain / midtrain	`$SHARED_STORAGE_ROOT/venvs/megatron`，须含 `bin/activate` 与 `bin/torchrun`	需自建（Python 3.12.3 + torch 2.7.0a0 nv25.04 + TE + FA2/FA3）
AReaL v2.0.0 @`fee938e`	rl	从源码安装	不随仓库分发
RL prompt JSONL（train/valid）	rl	`ZGCM_TRAIN_JSONL` / `ZGCM_VALID_JSONL`	训练数据不随仓库分发，需按 schema 自备
代码沙箱测试资产（内容寻址 `<hash[:2]>/<hash>.json.gz` + `manifest.json`）	rl code 阶段	`ZGCM_CODE_ASSET_ROOT`	需自备
Open-Instruct checkout（IFEvalG）+ NLTK `punkt`/`punkt_tab/english`	rl if 阶段	`ZGCM_OPEN_INSTRUCT_ROOT` / `_SITE_PACKAGES` / `NLTK_DATA`	需自备
general-domain judge	内部 RL 流水线的通用域判分	—	❌ 依赖内部服务，未重新分发；路由器对未知域 raise

安全/合规约定（仓库显式要求）：sft 的 runtime.env 与 README 均声明——具体集群路径、凭据、cookie、代理地址必须保留在仓库之外，不得提交内部挂载路径。rl 的 AREAL_ADMIN_API_KEY 本地填任意非空串，ZGCM_CODE_SANDBOX_TOKEN 需≥32 字符随机串。代码奖励永远不在训练进程内执行模型输出，一律经 HTTP 打到隔离沙箱，沙箱无网络出口且缺任一隔离属性即 fail closed。

11. 后续可选动作

深挖某阶段的 Megatron 定制代码：Muon（muon.py、emerging_optimizers.py 的 gate 层 QKV 拆分）、attention output gate（transformer_config.py + training.py 参数量统计）、--window-attn-skip-freq 的实际层排布实现，并与 upstream eba2eaf7 做 diff。
用 data-process 跑通自有 JSONL：写一个 dataset profile + adapter，走 midtrain 的 buckets.py/mix.py 生成 mix16/mix64/mix256 划分（显式钉 seed）。
离线单测 rl/rewards/ 的纯函数部分：按 RUNNING.md schema 造小样本 prompt JSONL，在无 GPU 环境测 completion.py（</think> 后抽答案与 Python 块）、长度惩罚公式、accept_math_group/accept_code_group/accept_if_group 组过滤逻辑、以及 ifeval_reward.validate_ifeval_registry 的注册表校验路径。
配置对账：核对 02_pretrain_3p2t_global_shuffle.env 与 stage 1 的差异（3.2T 的 tokens/iters/GBS/lr schedule），以及 pretrain/docs/PRETRAIN_PHASES.md、midtrain/docs/MIDTRAIN_STAGES.md 中与报告一致的数据课程细节。

1. 仓库定位与整体链条

2. 模型结构规格

训练配置中实际使用的完整结构参数

3. data-process/ — AI-native 数据治理 本机已实测通过

目录布局

处理契约

AI-native 治理模型

长度分桶与中期训练混合（与 midtrain 直接对接）

本地验证命令与实测结果

4. pretrain/ — 预训练（约 4.19T tokens，16K 上下文）

入口

scripts/launch_train.sh 行为（已读源码）

Stage 1 完整配方（01_pretrain_1t_sequential.env 实测值）

运行时环境变量（stage env 中的默认值）

5. midtrain/ — 中期训练（600.51B，16K → 64K → 256K）

入口（比 pretrain 多一步生成 data args）

6. sft/ — 监督微调（目录本身即 Megatron-LM fork）

文件职责四分离

硬性要求

三个启动姿势

迭代数推导（数据集 metadata 才是权威输入）

签入候选 run 的完整配置（zgcm.conf 实测值）

runtime.env 关键环境（实测内容）

输出目录结构

已验证配置与实测性能

运维注意事项（README 原文归纳）

7. rl/ — AReaL GRPO 最精简：21 个文件，不捆绑框架

框架与精确依赖钉版

三个训练入口

目录布局

数据与奖励设计

Correct-only 长度惩罚（仅 math）

Dynamic sampling（组过滤）

训练设置

评估与恢复

额外依赖与环境变量

Prompt JSONL schema

实验流程（RUNNING.md 五步）

8. 上游来源与 ZGCM 定制点

ZGCM 相对上游 Megatron-LM 的定制（docs/SOURCE_PROVENANCE.md + 源码核实）

参考运行时（pretrain / midtrain）

9. 本机可运行性结论 Windows / 无 NVIDIA GPU

各阶段 GPU 规模速查

10. 配套资产与已知缺口

11. 后续可选动作

3. `data-process/` — AI-native 数据治理本机已实测通过

4. `pretrain/` — 预训练（约 4.19T tokens，16K 上下文）

`scripts/launch_train.sh` 行为（已读源码）

Stage 1 完整配方（`01_pretrain_1t_sequential.env` 实测值）

5. `midtrain/` — 中期训练（600.51B，16K → 64K → 256K）

6. `sft/` — 监督微调（目录本身即 Megatron-LM fork）

签入候选 run 的完整配置（`zgcm.conf` 实测值）

`runtime.env` 关键环境（实测内容）

7. `rl/` — AReaL GRPO 最精简：21 个文件，不捆绑框架

实验流程（`RUNNING.md` 五步）

ZGCM 相对上游 Megatron-LM 的定制（`docs/SOURCE_PROVENANCE.md` + 源码核实）