tysgydk/DeepSeek-V2-Lite-LoopIntervention

English summary. This is a work-in-progress research repository that ports a "loop intervention" idea from a dense model to a Mixture-of-Experts trunk: a frozen DeepSeek-V2-Lite-Chat (16B MoE, MLA, hidden 2048) loaded in 4-bit with manually int8-quantized experts, plus a small trainable intervention network (per-loop full-rank projection + gate, about 8.41M parameters). It ships 3 intervention checkpoints (~33.6 MB each) and 12 training / quantization / evaluation scripts — but no trunk weights, no config, no tokenizer, so nothing here can be loaded with from_pretrained. The author marks it as a half-finished prototype whose checkpoints are not usable models: generation collapses.

这是什么

• 主干固定：DeepSeek-V2-Lite-Chat（作者卡片描述为 16B MoE、MLA 注意力、hidden 2048），全程冻结，只训练外挂干预网络。
• 干预网络（scripts/train_dsv2.py 的 ResidualLoop，loop 模式）：圈间 Proj 翻译（每圈一份 LayerNorm + Linear(2048→2048)，满秩）+ 门控（把 [h; fh] 拼接后预测逐 token 的 z，用凸组合 h = (1-z)·h + z·fh 混合），每圈重新 forward 主干（真循环）。作者卡片给出的总参数量约 841 万。
• 仓库性质：训练/量化/评测的胶水代码 + 少量中间检查点，不是成品模型。作者在原卡片顶部明确标注「⚠️ 半成品 / Work in Progress …… 干预网络 ckpt 均为实验中间产物，不是可用于正式场景的成品模型」。
• 两个代码世代混在同一目录里：早期 loop 模式用每圈一个标量 loop_gate（对应 ckpt/intervdsv2_r2_step3000.pt，作者卡片称"残差循环 R=2（无 GRU 门控）"），后期改成 **GRU 式 gate_proj**（对应两个 intervdsv2_gru_r2_*）。这直接决定了哪些脚本还能跑，见「已知限制」。

不含完整权重（重要澄清）

• 三个 .pt 都是 loop 模式的 checkpoint，字典形态为 {'step', 'r', 'loop_sd'}（见 train_dsv2.py:592），loop_sd 内含 proj.{i}.*、门控（loop_gate.{i} 或 gate_proj.{i}.*），可选 interv_loop.*、v_tokens.{i}。
• 仓库内没有主干权重、config.json、tokenizer 或任何 HF 格式权重文件；AutoModelForCausalLM.from_pretrained("<本仓库>") 不能工作。复现需要自行下载主干（脚本里的路径是魔搭/本地 snapshot 形式：/root/autodl-tmp/models/models/deepseek-ai--DeepSeek-V2-Lite-Chat/snapshots/master）。

仓库内容

DeepSeek-V2-Lite-LoopIntervention/
├── README.md          # 原卡片（无 license 字段）
├── .gitattributes     # 标准模板，声明 *.pt 走 LFS（实际 0 个 LFS 对象）
├── ckpt/              # 3 个干预网络检查点
└── scripts/           # 12 个脚本

ckpt/：3 个检查点

ckpt（大小）	结构（引自原卡片）	状态（引自原卡片）
intervdsv2_r2_step3000.pt (33.6 MB)	残差循环 R=2（无 GRU 门控，即每圈标量 loop_gate）	早期版
intervdsv2_gru_r2_step2500.pt (33.6 MB)	GRU 门控 R=2	首轮
intervdsv2_gru_r2_resume_step1000.pt (33.6 MB)	GRU 门控 R=2，续训累计 3500 步	最终（生成崩坍，待改进）

• 文件名遵循 train_dsv2.py:593 的命名规则 interv{--tag}_step{step}.pt：因此 intervdsv2_r2_* 对应 --tag dsv2_r2，..._resume_step1000 对应续训那一段的 tag（用 --init-ckpt 从上一段继承）。仓库没有附带训练日志，步数之外的训练细节只能从文件名读出。
• 三个文件大小几乎一致，与"每圈一份满秩 2048×2048 Proj"的量级相符；GRU 版比无门控版略大（多出两个 gate_proj）。

scripts/：12 个脚本

训练

• train_dsv2.py（620 行，最核心）：4-bit（bitsandbytes nf4 + double quant）加载主干，再用 quantize_all_experts() 手动把 MoE 专家权重转 int8；ResidualLoop 同时提供 5 种前向——forward_residual（残差堆叠，主干只 forward 一次）、forward_blockwise（中间层 hook 分块残差）、forward_loop（真循环：Proj 翻译 + 门控混合，圈间用 torch.utils.checkpoint 手动梯度检查点省显存）、forward_vtok（每圈在输入端拼 k 个可学习虚拟 token + 真循环），以及对应的 4 个 generate_*。loop 模式的损失是只逼末圈 CE（loss = ls[-1]，train_dsv2.py:529 注释写作 "C-ablation: 只逼末圈 CE，中间圈完全自由"），并带 val_ce 早停；非 loop 模式另有 MATH 小样本早停与最优快照回滚。
• 关键默认超参（argparse 默认值）：--steps 2000 --bs 2 --lr 1e-3 --weight-decay 0.01 --r 2 --rank 32 --margin 0.01 --lam 1.0 --eval-every 500 --eval-n 8 --patience 2 --val-ratio 0.08 --ce-every 200 --tag res --data /root/autodl-tmp/data/cot_mix_v1.jsonl，序列 MAX_LEN = 512。

量化

• quantize_dsv2.py（107 行）：手工 int8 分组量化（GROUP_SIZE = 128）MoE 专家的 gate_up_proj / down_proj，monkey-patch DeepseekV2Experts.forward，并用自定义 autograd Function（QuantLinear）在前向时反量化、反向时重新反量化以省显存；可直接运行，打印量化前后显存。
• verify_quant.py：对同一 prompt 比较量化前后的 logits（max/mean |diff|、cosine 相似度、top-5 一致性）。

探针 / 冒烟 / 显存

• probe_dsv2.py：结构探针——tokenizer vocab/eos、Q4 加载是否成功、顶层与 layer0/mlp 的模块树、显存占用。
• smoke_dsv2.py：forward_loop + CE 的冒烟测试（含短生成）。
• smoke_gru.py：GRU 门控版冒烟——gate_proj 结构、z 均值是否落在 [0,1]、gate_proj 梯度是否非零、短生成。
• diag_mem.py：逐步打印显存（embedding / 第一圈 / proj / 第二圈 / 残差 / loss / backward），定位 R=2 训练的峰值来源。
• mem_test.py：给定序列长度（默认 L=2048）实测训练显存峰值，并按 32 GB 显存算余量。

评测

• eval_dsv2.py：加载 loop ckpt，用 generate_loop 跑 MATH 正确率（位置参数 ckpt，--r 2 --n 30 --offset 0 --cap 4096 --rank 32），并打印每题输出。
• eval_dsv2_base.py：基线对照——无循环，主干直接 generate（--n 5 --cap 4096，eos_token_id=100001）。
• gate_eval.py / gate_scan.py：固定/扫描门控值（gate_eval 默认 0.3 跑 5 题；gate_scan 扫 1.0 / 0.3 / 0.1 各跑第 1 题）看崩坍是否随 gate 单调变化。

脚本用法（脚本内取证的真实命令）

# 训练：真循环 R=2（GRU 门控）。默认即 steps=2000, bs=2, lr=1e-3, rank=32
python scripts/train_dsv2.py --loop --r 2 --rank 32 --tag dsv2_gru_r2

# 续训：从上一段的点继承，用新 tag（对应 ckpt/intervdsv2_gru_r2_resume_step1000.pt）
python scripts/train_dsv2.py --loop --r 2 --rank 32 --tag dsv2_gru_r2_resume \
    --init-ckpt <intervdsv2_gru_r2_step2500.pt>

# 其它前向模式（同一脚本）：残差堆叠 / 中间层分块 / 虚拟 token
python scripts/train_dsv2.py --r 2 --rank 32 --tag dsv2_r2
python scripts/train_dsv2.py --n-blocks 6 --rank 8 --tag dsv2_blk
python scripts/train_dsv2.py --loop --vtok 8 --tag dsv2_vtok

# 量化与验证（可直接运行，路径常量指向本地主干）
python scripts/quantize_dsv2.py
python scripts/verify_quant.py

# 探针 / 冒烟
python scripts/probe_dsv2.py
python scripts/smoke_gru.py
python scripts/mem_test.py 2048

# 评测
python scripts/eval_dsv2.py <intervdsv2_gru_r2_resume_step1000.pt> --r 2 --n 30 --cap 4096 --rank 32
python scripts/eval_dsv2_base.py --n 5 --cap 4096

运行前必须处理的两件事：① 脚本里 MODEL 是硬编码的本地 snapshot 路径；② train_dsv2.py 第一行 import 就依赖外部文件（见下）。数据侧同样硬编码：/root/autodl-tmp/data/cot_mix_v1.jsonl、/root/autodl-tmp/data/math500/test.jsonl。

技术要点

• 迁移目标：把"循环干预"从稠密 Qwen 模型搬到 MoE 架构上做实验（同作者的 tysgydk/Qwen3-4B-LoopIntervention 对应稠密版）。
• 显存工程是这个仓库的主要工作量：4-bit 主干 + 手动 int8 专家量化 + 圈间手动梯度检查点 + logits 分块计算，mem_test.py 用以按 32 GB 卡算余量。
• 门控设计：从早期"每圈一个标量 loop_gate"演进到"GRU 式 gate_proj（Linear(2D→1)，逐 token 从 [h; fh] 预测 z）"，h = (1-z)·h + z·fh 的凸组合形式在 train_dsv2.py 与 Qwen 仓库的变换循环中一致。
• 损失取舍：loop 模式只用末圈 CE（作者注释称在 dense 上最稳）；非 loop 模式用"各圈 CE 均值 + margin 单调约束"（train_dsv2.py:1-4 的注释给出了残差循环的完整定义与损失）。
• 作者给出的结论（原卡片「当前结论（首轮）」）：
  • 训练侧正常、生成侧崩坍——val_ce 1.1312、gate 正常、圈间差异为正，但生成 2/2 题崩坍（ok=0、顶帽 100%）。
  • 崩坍根因判为周期吸引子（limit cycle）：hidden 进入 5-token 周期循环，不是门控失配、不是不动点。
  • dense vs MoE 的关键区分：Qwen dense 上真循环失败是"分数低但生成正常"，DeepSeek MoE 上失败是"直接生成崩坍"；根因指向 MoE 离散 Top-K 路由 + 循环收缩映射。
  • 待定修复方向：软路由（专家加权平均替代硬 Top-K）、训练侧 free-run 采样。

已知限制

• 许可：上游采用自定义的 DeepSeek License v1.0（非 OSI 开源许可），本仓库已随附许可全文（根目录 LICENSE）并逐条落实该许可 §4 的四项义务；详见文末「许可」一节。
• 生成崩坍：按作者自述，最终 checkpoint 在生成侧 2/2 题崩坍、顶帽 100%，不可用于任何生成或生产用途；作者给出的定位是"半成品 / Work in Progress"。
• 不是成品模型：无主干权重、无 config、无 tokenizer，不能 from_pretrained，不能直接接 HF pipeline。
• 代码代际不一致（会导致脚本跑不起来）：gate_eval.py、gate_scan.py、smoke_dsv2.py、diag_mem.py 都引用 lm.loop_gate，而当前 train_dsv2.py 的 loop 模式用的是 gate_proj（GRU 门控），ResidualLoop 里已经没有 loop_gate 属性；同时 gate_eval.py / gate_scan.py 硬编码从 intervdsv2_r2_step3000.pt 读 loop_gate.*。因此这些探针与最新训练代码不匹配。
• 缺失依赖：train_dsv2.py:10 是 from train_interv import load_docs, batchify，而 train_interv.py 不在本仓库（它属于 tysgydk/Qwen3-4B-LoopIntervention）；复现训练需要同时取那个仓库的脚本。另外被复用的 batchify 用 151643 作 padding id（Qwen 的 pad token），并不是 DeepSeek-V2-Lite 的（其 eos/pad 为 100001，见 eval_dsv2_base.py 与 train_dsv2.py:16），属代码复用残留。
• 所有脚本硬编码绝对路径；数据文件（cot_mix_v1.jsonl、math500/test.jsonl）与量化/评测结果都不在仓库内。
• 作者卡片中的 val_ce 1.1312、2/2 崩坍 等结论没有附带日志或结果文件，无法在本仓库内复核；仓库也没有说明训练总耗时、硬件环境。
• .gitattributes 声明 *.pt 走 LFS，但仓库内当前 0 个 LFS 对象（.pt 为普通文件），迁移到 HF 时需自行决定 LFS 策略。

未说明的信息：训练数据 cot_mix_v1.jsonl 的来源、规模与 token 总量；续训累计 3500 步对应的 epoch 数；每轮实验的硬件与耗时；量化误差的实际数值（verify_quant.py 会打印，但仓库内没有结果）；仓库的上传/最后更新时间。

许可

可以公开，但不能标成 Apache-2.0。 上游主干 deepseek-ai/DeepSeek-V2-Lite-Chat 用的是自定义的 DeepSeek License Agreement v1.0（2023-10-23），不在 OSI 认可的开源许可列表内。因此 front matter 采用 license: other + license_name: deepseek-license + license_link: LICENSE，并把许可全文随仓库提供（本仓库根目录的 LICENSE，13,759 字节，取自上游官方仓库）。

允许分发：该许可第 2 条授予「永久、全球、非独占、免费、免版税、不可撤销」的版权许可，明确包含 reproduce / prepare / publicly display / sublicense / distribute；第 4 条进一步允许以任意介质分发 Model 与 Derivatives of the Model（含修改版）。所以本仓库公开是合规的。

但第 4 条的四项义务必须同时满足——本仓库已逐项落实：

DeepSeek License §4 的要求	本仓库的处理
a. 管辖使用的条款中必须保留 Attachment A 的使用限制并可执行，且须告知下游	见下方「使用限制」，逐条转载
b. 必须向接收方提供本许可的副本	根目录 LICENSE = 许可全文
c. 修改过的文件须带显著改动声明	本仓库全部文件（干预模块 + 脚本）均为作者新增，不含上游文件
d. 保留版权、专利、商标与署名声明	保留许可全文中的 Copyright (c) 2023 DeepSeek，未作删改

许可第 4.e 条允许作者为自己的修改另附条款，但前提是仍保留上述使用限制；本仓库选择了最简单稳妥的做法：整仓按 DeepSeek License 发布。

使用限制（转载自 Attachment A，具有约束力）：不得将本模型或其衍生物用于——违反任何适用法律法规或侵害第三方合法权益；任何军事用途；剥削、伤害或试图伤害未成年人；为伤害他人而生成或传播可证伪的虚假信息；生成或传播受监管的不当内容；未经授权生成或传播个人身份信息；诽谤、贬损或骚扰他人；对个人法律权利产生不利影响或创设约束性义务的全自动决策；基于线上/线下社会行为或人格特征歧视、伤害个人或群体；利用特定群体的年龄、社会、身体或心理特征实质性扭曲其行为并造成身心伤害；基于受法律保护的特征或类别歧视个人或群体。

关于「本仓库不含主干权重」：本仓库只分发约 841 万参数的干预模块与脚本，不含 DeepSeek-V2-Lite-Chat 的任何权重文件。但这类「基于上游模型激活/输出训练」的产物在许可定义下仍可能落入 §1 的 Derivatives of the Model，故上面四项义务按最谨慎口径一并履行。主干权重请自行从上游仓库获取，其许可独立适用。

输出：许可第 6 条声明 DeepSeek 不对你生成的输出主张权利，但你需要对输出及其后续使用负责。

引用

• 本仓库（ModelScope）：https://modelscope.cn/models/tysgydk/DeepSeek-V2-Lite-LoopIntervention
• 本仓库（Hugging Face）：
• 基座：deepseek-ai/DeepSeek-V2-Lite-Chat（作者卡片声明的仓库名；脚本中为本地 snapshot 路径）
• 同作者的稠密版相关仓库：tysgydk/Qwen3-4B-LoopIntervention（本仓库的 train_dsv2.py 从它的 train_interv.py 导入工具函数）
• 本仓库未附带论文、arXiv 编号或 BibTeX 条目；如引用请引用上面的仓库地址。