llm infewr 的 vibe coding 经验全汇总

xxx 文档中的框架/模块架构图、设计图、函数流程图等尽量不要用 mermaid 图，尽量复用论文、博客中的图片、或者自行生成直接图片形式！！！

优化文档，更清晰易懂，描述自然流畅，表达严谨，、衔接过渡自然通顺，多结合实例理解，可视化结构图理清执行流程和模块架构。移除过时描述、冗余描述。加载 skill: skills/de-ai-editing/​SKILL.md,去除 ai 味！

针对当前会话修改，提交精简、清晰的 commit 到远程仓库。

add ​parallel_state.py​(vllm) 和 ​srt/distributed/parallel_state.py(sglang)​，深度解析 vllm sglang 的并行组管理模块，作用/特性、设计原理、核心流程解析，并通过 debug 来理解模型推理的数据流（shape/dtype），必须有实例可视化理解，总结区别。

深度解析 benchmark 模块，作用/特性、设计原理、核心流程解析，必须有实例可视化理解。

xxx 文档优化表达，更清晰易懂，去除 AI 味！不要换行啊！！行宽度限制了，影响阅读体验！

create_per_token_group_quant_fp8_output_scale 派生出的 5 种物理布局形态的可视化，以及如何让其在对应硬件与 kernel 发挥出性能，布局如何影响内存访问模式的可视化解析，以及为啥内存访问模式能影响性能的，及算子实现代码深度解析，执行过程总结。

它自己发明了一个和你项目里已有工具函数功能重复的新函数;
它把一个只该在事务里做的操作放在了事务外面;
它处理了九种边界情况,唯独漏了你们业务里最常见那种;
它引了一个你们从来没用过的库,就为了做一件三行代码能搞定的事；
过渡注释，改一行代码写10行以上注释，一个类设计能完成的功能拆成多个类、多个函数；
这叫"合理的错误"。

rapid_llm 仓库的 ​README.md​ 及版本发布的 RELEASE ​docs​ 

​README 和 RELEASE 文档记得更新新增优化、功能特性的实例动态可视化结果，方便用户理解新优化特性的原理和使用。

​quantization​ 量化模块代码质量和可读性治理：
**代码质量提升**：所有代码在可读性上必须是干净、整洁清爽的实现，代码易懂性提高，移除冗余、无效、过时代码。
**注释重构**：清晰易懂、精简严谨！解决改几行代码就加数行注释的问题！（写入底层记忆系统、确保后续会话不会出现同类问题！！）

重构 benchmarks 模块，可以参考开源框架 vLLM benchmarks/ 与 SGLang benchmark/ 的目录结构、脚本划分和指标定义，统一 benchmark 的目录组织、命名和公共能力。

目标：
- 代码干净、易读，删除冗余、无效、过时设计和死代码。
- 注释精简、准确，解释关键逻辑和约束，不复述代码。
- 统一文件命名，合并功能重复的文件。
- 抽象公共模块：参数解析、数据集与请求构造、服务启动与健康检查、指标计算、结果汇总、日志输出。
- 各 benchmark 入口清晰，能直接看出测什么、怎么跑、输出哪些指标。

benchmark 类型至少覆盖：
offline throughput、online serving、latency（TTFT TPOT等）、长上下文、prefix caching、并行场景（TP/EP/DP/PP 等）。

命名和目录可参考：
bench_serving.py、bench_offline_throughput.py、bench_latency.py、bench_parallel.py、common/、utils/。
公共逻辑放 common/ 或 utils/，不要把 serving、offline、latency 的逻辑混在一个文件里。

验收标准：
- 目录结构清晰，文件职责单一。
- 重复逻辑已合并，公共代码有明确入口。
- 注释只保留必要信息。
- 每个 benchmark 有 README 或等价说明：用途、环境、负载、命令、指标、结果示例。
- 指标定义与 vLLM/SGLang 对齐，避免同名指标口径不一致。

benchmark 工作要求（后续所有 benchmark 工作必须提供）：
1. 环境说明：rapid_llm 版本、commit、CUDA/驱动、硬件、模型、并行配置、启动参数。
2. 推理工作负载：数据集、输入/输出长度、请求数、并发、采样参数。
3. 运行脚本命令：完整可复现命令。
4. 运行结果日志：原始日志或关键日志。
5. 全部测试指标：TTFT、TPOT、TPS、TGS（有并行时），以及吞吐、延迟分位（P50/P90/P99）、错误率、显存/GPU 利用率等。
6. 对比结果总结：与基线或不同配置的对比，说明结论和异常。

任务：补充模型在全部量化模式下的 benchmark 结果，汇总到 benchmark_quantization_models.md。

A. 基线
| bf16 | 所有 bf16 权重模型必测 |

B. 权重量化（bf16 权重加载后在线量化）
| FP8 Per Tensor  | 权重 FP8，整层共享一个 scale |
| FP8 Block Scaling | 权重 FP8，分块 scale |
| FP8 Rowwise     | 权重 FP8，逐行 scale |
| NVFP4           | 权重 NVFP4 |
| MXFP4           | 权重 MXFP4 |
| W4A16 GPTQ      | 权重 4bit、激活 16bit，GPTQ 算法 |
| W4A8 GPTQ       | 权重 4bit、激活 8bit，GPTQ 算法 |
| W4A16 AWQ       | 权重 4bit、激活 16bit，AWQ 算法 |
| W4A8 AWQ        | 权重 4bit、激活 8bit，AWQ 算法 |

C. KV Cache 量化（与权重量化正交，可叠加）
| FP8 KV Cache    | 至少覆盖 bf16 权重 + FP8 KV |
| NVFP4 KV Cache  | 至少覆盖 bf16 权重 + NVFP4 KV |

目标：
1. 补齐框架所有已支持模型、量化的来量化 benchmark 测试结果，追加到 benchmark_quantization_models.md，格式与已有表格一致。
2. 覆盖所有「本地有权重且框架支持」的模型：
   - bf16 权重模型：bf16 基线 + B 类全部模式 + C 类 KV 量化。
   - fp8 权重模型（如 Qwen3-30B-A3B-Instruct-2507-FP8）：按其权重格式对应的
     FP8 模式直接加载运行。

- 若框架支持「量化权重 + 量化 KV」叠加（如 FP8 权重 + FP8 KV），需补充组合测试。
- 某模式或组合在当前框架/当前设备 下不支持时，必须在文档中标注「不支持 + 原因」，不得省略。

规则：
- 同一模型所有模式使用相同负载与采样参数，保证横向可比。
- GPTQ/AWQ 若需要校准，记录校准数据集与样本数；在线量化记录量化开关参数。
- 每条结果标注：量化模式、KV cache 精度、是否叠加量化。
- 指标口径与 vLLM/SGLang 对齐；只追加，不修改已有结果。


模型量化特性 benchmark 的交付要求（每个「模型 × 精度」组合都必须提供）：
交付（每个「模型 × 量化模式」组合都必须提供）：
1. 环境说明：rapid_llm 版本/commit、CUDA/驱动、硬件、模型与权重路径、并行配置、启动参数、量化模式。
2. 工作负载：数据集、输入/输出长度、请求数、并发、采样参数。
3. 完整可复现的启动与压测命令。
4. 原始运行日志或关键日志。
5. 全部指标：TTFT、TPOT、TPS、吞吐、延迟分位（P50/P90/P99）、错误率、显存占用/GPU 利用率。
6. 对比总结：同模型 bf16 vs 各量化模式的吞吐/延迟/显存变化，结论与异常说明。

验收标准：
- benchmark_models.md 含「模型 × 量化模式」覆盖矩阵：每格为实测结果
  或「不支持 + 原因」，无空缺。
- 每条结果环境、负载、命令、日志齐全，第三方可复现。
- benchmark_quantization_models.md 的表格格式统一，同名指标口径一致。

模型权重的量化配置通过解析权重目录下的 config.json 得到，如下所示：

```bash
{
    "quantization_config": {
        "quant_method": "fp8",
        "activation_scheme": "dynamic",
        "weight_block_size": [
        32,
        32
        ],
        "scale_fmt": "ue8m0",
        "expert_dtype": "fp4"
    },
}

任务：对 lite_llama 框架进行全面重构与性能优化。严格分阶段执行，每阶段独立验收。

总目标：
- 代码更干净：更好的架构/类/API 设计，更准确、更好理解的函数、类、文件命名；
  删除冗余、无效、过时设计和死代码；注释精简，只解释关键逻辑与约束。
- 性能更高：TTFT、TPOT、TPS 全面优于基线。
- 精度不降：算子与模型输出不劣于 bf16 基线（容差见验收标准）。
- 测试更严：每个优化特性有独立测试与 benchmark，特性间做组合交叉测试。

阶段 0：建立基线（先测后改，禁止跳过）
- 跑通现有全部测试并记录；阻塞性 bug 单独修复、单独提交。
- 用统一负载跑 baseline benchmark，记录 TTFT/TPOT/TPS、吞吐、显存、精度，
  作为后续所有对比的唯一基线。

阶段 1：重构（只改结构，不改行为）
- 架构/类/API 重设计，统一命名，合并重复模块，删除死代码。
- 硬约束：已有测试全部通过，benchmark 指标与基线一致（允许噪声波动）。
- 重构与优化禁止混在同一提交。

阶段 2：逐项优化（一个特性一个提交）
- 候选特性以代码现状梳理后确认（如算子融合、KV cache、服务调度、量化、并行、overlap等）。
- 每个特性必须四件套齐全：
  1. 可独立启停的开关（feature flag）；
  2. 单元测试（含边界与异常输入）；
  3. 精度验证（与 bf16 基线对比，给出数值容差）；
  4. benchmark（相对基线的 TTFT/TPOT/TPS 变化，禁止无数据的"提速"结论）。

阶段 3：组合/交叉测试
- 可叠加特性两两组合直至全开，验证功能正确、无精度回归、性能可叠加；
  负叠加或不兼容的组合必须记录原因。输出特性兼容性矩阵。

阶段 4：全量终测
- 所有支持的模型启用各自可用的全部优化特性，跑最严格的速度+精度测试，
  输出「模型 × 特性组合」完整 benchmark 矩阵。

每次 benchmark/测试必须提供：
1. 环境：lite_llama 版本/commit、CUDA/驱动、硬件、模型、并行配置、启动参数。
2. 负载：数据集、输入/输出长度、请求数、并发、采样参数。
3. 完整可复现命令。  4. 原始或关键日志。
5. 全部指标：TTFT、TPOT、TPS、TGS（有并行时）、吞吐、延迟分位、错误率、显存/GPU 利用率。
6. 对比总结：与基线或不同特性组合的对比，结论与异常说明。

验收标准：
- 基线数据齐全，所有提速结论可追溯到阶段 0 基线。
- 阶段 1 前后行为等价：测试全通过，指标无显著变化。
- 每个优化特性：开关、测试、精度验证、benchmark 四者缺一不可。
- 组合矩阵无未测空缺；不兼容组合标注原因。
- 终测覆盖全部支持模型，速度不降、精度在容差内。

任务：将 rapid_llm 默认精度策略改为 auto（与 vLLM/SGLang 对齐），清除框架中
写死 fp16 的代码，并用严格测试验证性能与精度无回归。

语义定义（先对齐 auto 的准确含义，再动手）：
- 框架不预设、不强制任何计算精度；默认从模型配置文件（config.json 的
  torch_dtype 等字段）读取，跟随模型自带精度。
- 用户显式指定精度时，以用户指定为准。
- 行为对齐 vLLM/SGLang 的 auto：至少支持 fp16 / bf16 模型配置。

改动规则：
1. kernel 内部 dtype 必须派生自输入张量的 dtype，禁止假设 fp16；
   缺少 bf16 模板实例化/dispatch 时一并补上，不能只删硬编码导致运行时报错。
2. 删除框架层写死 fp16 的代码：torch.float16 字面量、.half() 强转、
   函数签名中 fp16 默认值等。
3. 例外保留：出于数值稳定性的显式精度（如 softmax/累加用 fp32）允许保留，
   但必须加注释说明原因；不确定的先列出待确认，不静默处理。
4. 配置层新增 auto 选项并设为默认；auto 时透传模型配置精度，不做隐式转换。
5. 梳理权重、激活、KV cache 各环节 dtype 来源，杜绝「配置 bf16、某环节
   仍是 fp16」的隐性混精。

测试要求：
- kernel 级：每个改动 kernel 对 fp16/bf16 分别做数值正确性测试，与参考
  实现对比并给出容差；覆盖边界形状与异常输入。
- 模型级：fp16 与 bf16 模型各跑精度验证（与 HF 基线对比 logits/下游任务
  精度），偏差在容差内。
- 性能：改动前后跑同一负载 benchmark，TTFT/TPOT/TPS 不允许显著回退。
- 配置组合交叉覆盖：auto / 用户显式指定 × fp16 配置模型 / bf16 配置模型。

每次 benchmark/测试必须提供：
1. 环境：rapid_llm 版本/commit、CUDA/驱动、硬件、模型、并行配置、启动参数。
2. 负载：数据集、输入/输出长度、请求数、并发、采样参数。
3. 完整可复现命令。  4. 原始或关键日志。
5. 指标：TTFT、TPOT、TPS、吞吐、延迟分位、错误率、显存/GPU 利用率。
6. 对比总结：改动前后性能对比 + fp16/bf16 模型精度对比，结论与异常说明。

验收标准：
- 默认精度策略为 auto，行为与 vLLM/SGLang 一致。
- 代码无残留 fp16 硬编码（数值稳定性例外均有注释）。
- fp16 与 bf16 模型的精度、性能均无回归，测试矩阵无空缺。
- 每条结果环境、负载、命令、日志齐全，第三方可复现。

任务：对 <目标模块/文件范围> 做注释治理与代码质量治理。纯重构，不改变任何外部行为。

一、注释治理
删除：
- 复述代码的注释（代码已自解释，注释只重复 what）。
- 与当前实现不符的过时注释。
- 被注释掉的死代码块。
- 无信息量的装饰性注释（分隔线、"构造函数"、"主流程"这类废话）。
保留并改写：
- 解释 why 的注释：非显而易见的约束、取舍、坑、workaround 原因。
- 公共 API 的 docstring：用途、参数、返回值、异常，不复述实现细节。
- TODO/FIXME：必须附触发条件或负责人，否则删除。
- 算法/论文出处引用、许可证头：原样保留。
风格：精简、准确、严谨，每条注释的存在都必须有不可替代的理由；
注释语言统一为 <英文>。

二、代码质量治理
- 删除死代码、冗余抽象、过时设计（先确认无引用再删）。
- 统一命名：函数/类/变量名准确表达意图，消除歧义。
- 合并重复逻辑：重复文件、重复函数/类，抽取公共入口。
- 设计模式仅在确实降低复杂度时使用；拿不准时，简单实现优于抽象。
- 不改变公共 API 行为；如必须改，单独列出并说明理由。

三、流程约束
- 按模块分批提交，每批可独立审查；注释清理与逻辑改动分开提交。
- 每批完成后跑现有测试，全部通过才进入下一批。
- 涉及性能敏感路径时，改动前后跑 benchmark 对比，不允许显著回退。

验收标准：
- 行为等价：现有测试全部通过，公共 API 无隐性变更。
- 注释：总量显著下降；保留的每条都解释 why；无复述型/过时/死代码注释残留。
- 代码：无死代码、无重复逻辑；命名准确；无过度设计的多余抽象层。
- 交付变更清单：每处删除/改写可追溯到明确理由。

任务：重构 rapid_llm 的三个基础模块（配置 / 权重加载 / 模型注册），设计参考
vLLM。完成后用严格测试证明：加载不更慢、推理精度无回归、推理性能无回退，
并同步更新 RELEASE 特性文档与 README.md。

子任务 1：模型配置模块
目标：直接复用 HF transformers 的 config 体系，不另造轮子。
约束：
- 复用的是 PretrainedConfig/AutoConfig 的 schema 与解析；禁止引入
  transformers 的建模代码（modeling_*.py）。
- 分层设计：HF config 透传 + 框架自有配置（并行、KV cache、量化等）单独
  定义，两者不混（参考 vLLM ModelConfig 的分层方式）。
- 保留框架级校验：缺字段/非法组合给出明确报错。
- 删除自研配置解析代码；对外字段名如有变更，列迁移对照表。

子任务 2：模型权重加载模块
目标：直接加载 HF 权重（safetensors/bin，含分片），只做名字/结构重映射，
不再做格式转换。
约束：
- 重构 loader.py；convert_weights.py 确认无引用后删除。
- 重映射规则（HF 权重名 → 框架内部参数名）集中管理、有单测覆盖。
- 正确性硬标准：新路径加载结果与旧转换路径 logits 级等价（容差写明）。
- 性能硬标准：模型加载耗时不高于旧路径（少了转换环节，预期更快）。

子任务 3：模型注册模块（registry.py）
目标：更优雅、精简、好理解。
约束：
- 统一注册入口 + 懒加载：注册不得拖慢 import。
- 重复注册、未知模型名：报错信息明确。
- 现有全部模型保持可注册、可实例化，逐个核对清单。

通用规则：
- 三个子任务分开提交；行为变更点（字段改名、工具删除）列入
  BREAKING CHANGES 清单。
- 注释精简，只解释关键逻辑与约束。

测试要求：
- 单测：配置解析（与 HF AutoConfig 字段级对比）、重映射规则、注册的
  正常/异常路径。
- 精度：每个支持的模型新旧路径 logits 对比在容差内；抽样跑下游任务精度。
- 性能：加载耗时、冷启动耗时新旧对比；端到端 TTFT/TPOT/TPS 无显著回退。

交付（每项测试/benchmark 必须提供）：
1. 环境：rapid_llm 版本/commit、CUDA/驱动、硬件、模型、并行配置、启动参数。
2. 负载：数据集、输入/输出长度、请求数、并发、采样参数。
3. 完整可复现命令。  4. 原始或关键日志。
5. 指标：加载耗时、TTFT、TPOT、TPS、吞吐、错误率、显存/GPU 利用率。
6. 对比总结：新旧路径对比，结论与异常说明。

验收标准：
- 三个模块单测全通过；全部支持模型的 logits 等价性验证通过。
- 加载耗时不高于旧路径，推理指标无显著回退。
- convert_weights.py 与自研配置解析代码已删除，无残留引用。
- README.md 与文档同步更新；BREAKING CHANGES 与迁移指南完整。

任务：rapid_llm 新增并行能力：TP / DP / EP / PCP / DCP，支持混合并行，并保证
与已有特性（CUDA Graph、调度器、投机解码）叠加使用时精度、性能无回归。各并行的目标模型，
EP 需 MoE 模型，PCP/DCP 需长上下文场景。分阶段实施，每阶段独立验收。

术语对齐（先统一定义，避免歧义；"等"字不生效，并行类型以本清单为准）：
- TP（张量并行）：将同一层的权重和计算切分到多个 rank，通常用于单层内矩阵乘的并行。经典 Megatron-style TP 在列/行并行后需要合并部分结果，因此常伴随 all-reduce 或 reduce-scatter/all-gather；但 all-reduce 并非 TP 的必要条件，具体通信原语取决于切分方式、并行组合与硬件拓扑。
- DP（数据并行）：请求级并行。多个模型副本独立处理不同请求，以分摊吞吐。每个副本持有完整模型（或按其他并行切分后的完整逻辑模型），副本间不切分单层计算；推理时通常无需通信，训练时需同步梯度。
- EP（专家并行）：将 MoE 的专家切分到不同 rank。Token 经路由后通过 all-to-all 发送到对应专家计算，再通过 all-to-all 返回结果。通信原语以 all-to-all 为主，常与 DP、TP 组合使用。
- PCP（prefill 上下文并行）：在 prefill 阶段沿序列维切分输入。各 rank 处理部分 token 的 prefill 计算，通常需要通信合并注意力结果或 KV 缓存，以支持长上下文 prefill。
- DCP（decode 上下文并行）：在 decode 阶段沿 KV cache 的序列维切分。各 rank 持有部分 KV cache，注意力计算需要跨 rank 通信（如 all-gather 或 all-to-all）合并输出，以降低单卡 KV cache 压力，支持长上下文 decode。

阶段 1：TP（基础设施，先做）
- 范围：attention/MLP 切分、embedding/sampler、NCCL 通信。
- 正确性锚点：TP=1 与 TP=N 输出一致（容差内）。

阶段 2：DP
- 范围：请求路由、多副本调度、负载均衡；与调度器的职责边界写清。

阶段 3：EP（依赖 MoE 模型）
- 范围：专家放置策略、all-to-all、路由与负载均衡。

阶段 4：PCP / DCP（长上下文）
- 范围：序列维切分、KV cache 分布、跨 rank attention。

阶段 5：混合并行
- 组合矩阵显式列出、逐格验证，不允许"理论上支持"：
  <待确认，示例：TP×DP、TP×EP、TP+PCP、TP+PCP+DCP>。
- 每格必须有结果：功能正确 + 精度在容差内 + 性能达标，否则标注原因。

阶段 6：与已有特性交叉验证
- 组合矩阵：<并行方式> × {CUDA Graph、投机解码、调度器策略}；
  全开组合必须无精度/性能问题；负叠加或不兼容记录原因。

测试要求：
- 正确性：每种并行 N 卡 vs 单卡输出一致（logits 级 + 端到端生成双验证）。
- 性能：扩展效率实测（如 TP=2 吞吐 ≥ 单卡 × <阈值>），通信开销单列。
- 精度：抽样下游任务，容差写明。

交付（每项测试/benchmark 必须提供）：
1. 环境：rapid_llm 版本/commit、CUDA/驱动、硬件（卡数/互联拓扑）、模型、
   并行配置、启动参数。
2. 负载：数据集、输入/输出长度（长上下文场景需注明）、请求数、并发、采样参数。
3. 完整可复现命令。  4. 原始或关键日志。
5. 指标：TTFT、TPOT、TPS、TGS、吞吐、延迟分位、错误率、显存/GPU 利用率。
6. 对比总结：不同并行度/组合的对比，结论与异常说明。

Git 与文档：
- 新建分支，按功能拆 commit（每种并行至少一个，交叉验证单独提交），
  每个 commit 独立通过测试；完成后推送远程仓库。
- 更新文档与 README.md：各并行用法、组合约束、启动命令；README 增加
  真实录制的 gif 运行示例。

验收标准：
- 五种并行各自的正确性/精度/性能达标，测试矩阵无空缺。
- 混合并行组合矩阵逐格有结果或「不支持 + 原因」。
- 与 CUDA Graph/投机解码/调度器的交叉矩阵无未测空缺。
- commit 拆分清晰；文档、README、gif 齐备。

# 任务：rapid_llm 量化特性开发（权重量化 + KV Cache 量化 + 混合精度）

## 背景
rapid_llm 需要补齐量化能力。量化实现需与框架现有功能（模型加载、张量并行、
CUDA Graph、调度器、投机解码）正交集成，不能只做"单开可用"。

## 范围（做什么）
1. 权重量化方案，每项包含完整链路：checkpoint 加载 → 量化 kernel →
   量化 Linear 层 → 量化 MoE 层接入：
   - FP8 Block-wise（支持 32×32 与 128×128 块缩放）
   - NVFP4、MXFP4
   - GPTQ：W4A16、W4A8
   - AWQ：W4A16、W4A8
2. KV Cache 量化（与权重量化正交、可叠加）：
   - FP8 KV Cache
   - NVFP4 KV Cache
   需说明设计：KV 的 scale 粒度（per-token / per-head）、量化发生在写入时
   还是读取时反量化。
3. 混合量化：量化配置支持按模块类型指定精度（如 dense Linear 用 FP8、
   MoE 专家用 MXFP4，参考 expert_dtype 式配置），e2e 推理结果正确。
4. 兼容性：以上量化能力与 TP、CUDA Graph、投机解码、调度器同时开启，
   精度与性能无回归。

## 范围（不做什么）
- 不做训练侧量化（QAT/PTQ 导出工具不在本任务内，只消费现成 checkpoint）；
- 不改动与量化无关的模型代码。

## 代码质量要求
- 量化方案通过统一接口注册接入，新增方案不改框架代码；
- scale 处理、dequant 等公共逻辑只实现一次；
- 每个文件开头英文头注释：作用、核心设计、用法（≤15 行）；
- 删除死代码，注释只解释关键约束。

## 验收标准（全部满足才算完成，数据必须实测）
1. 功能矩阵：7 种权重量化方案各自可加载、推理正确；
   权重量化 × KV Cache 量化的叠加组合可用。
2. 精度（相对 BF16 基线的困惑度劣化，同一测试集）：
   W8A8 / FP8 Block ≤ 1%；W4A16（AWQ/GPTQ）≤ 2%；FP4 系 ≤ 3%。
   阈值可按实测基线调整，但必须给出数字，不接受"看起来对"。
3. 性能：目标硬件上实测 decode tokens/s 与峰值显存，对比 BF16 基线；
   优化停止条件 = 连续两轮尝试提升均 < 5%，记录后停止。
4. 兼容性矩阵（每格实测精度+性能，不允许"应该没问题"）：
   量化 × {TP, CUDA Graph, 投机解码} 各组合。
5. 混合量化：FP8 Linear + MXFP4 专家的模型 e2e 输出正确。

## 交付物
1. 测试报告：环境（硬件、CUDA/驱动、commit）、模型、数据集、
   可复现命令、原始日志、指标汇总表；
2. 文档：README.md 更新（各量化方案用法 + gif 运行示例），
   每个量化方案一页说明（支持的 checkpoint 格式、已知限制）；
3. 代码提交：新建分支，按功能拆 commit——建议粒度：每种权重量化
   方案一个、KV Cache 量化一个、混合量化一个、兼容性修复按问题拆分；
   commit message 写明改动与验证结果，完成后 push 远程仓库。

# 任务：rapid_llm 新增模型支持（DeepSeek 系列）

## 背景
rapid_llm 需新增 DeepSeek-V3、DeepSeek-V4、DeepSeek-V4.1-Flash 的支持。
第一里程碑只做一件事：精度对齐 transformers，不做任何性能优化。

## 范围（做什么）
1. 模型支持：DeepSeek-V4.1-Flash。
   通过统一 registry 注册接入（复用模型模块重构的注册入口），
   新增模型不改框架分发逻辑。
2. 权重获取双通道：国内环境从 ModelScope、国外环境从 HuggingFace，
   通过环境变量或配置切换；提供两个来源的下载与校验脚本。
3. 模型结构实现：MLA attention、MoE 路由等 DeepSeek 特有结构；
   权重 key 映射（checkpoint → 框架内部命名）需有对照表。
4. 依赖说明：若目标 checkpoint 为 FP8 块量化格式，依赖量化 feature
   先就绪；量化未就绪时先用 BF16 转换版验证，并在文档注明。

## 范围（不做什么）
- 不实施算子融合、overlap、并行优化—这些是第二阶段，
   本任务只产出方案文档（见交付物 4）；
- 不修改已有模型的实现。

## 验收标准（全部满足才算完成，数据必须实测）
1. 精度对齐 transformers（每个模型、同一组 prompt）：
   - 贪心解码输出一致率 ≥ 99%（逐 token 对比，给出不一致样本）；
   - 首 token logits 的最大绝对差与 KL 散度，给出数值；
   - 同一评测集分数差异 ≤ 0.5 分。
2. 双源一致性：同一模型从 ModelScope 与 HuggingFace 加载后，
   权重 checksum 一致，或同一 prompt 输出逐 token 一致。
3. 性能基线：记录未优化状态的 TTFT / TPOT / 吞吐，作为后续优化的
   对比基准（本阶段不要求数字好看，要求数字存在）。
4. 测试规模策略：CI 用小参数代理模型（如果有）跑回归，
   全尺寸模型做上线前验证，文档写明两者关系。

## 交付物
1. 精度对齐报告：模型 × 指标矩阵、环境、commit、可复现命令、原始日志；
2. README.md 更新：模型支持矩阵、双源下载命令、运行示例 gif；
3. 权重 key 映射对照表（每模型一份）；
4. 第二阶段优化方案文档（只写方案，不写实现）：
   - 算子融合候选清单：哪些算子对可融合、预期收益、参考实现出处；
   - overlap 方案：参考 SGLang 的具体机制（如 TBO 双 batch 交错、
     层内通信计算重叠），说明哪些适用于本框架；
   - 并行策略建议。
5. git：新建分支，commit 按模型拆分（每模型一个：结构实现 + 权重映射），
   CI 修复单独成 commit；message 写明验证结果，push 远程仓库。

# 任务：rapid_llm 已支持模型的性能优化（模型：____，填入具体模型名）

## 背景
目标模型已完成接入并通过精度对齐（与 transformers 贪心输出一致率 ≥ 99%）。
本任务在此基线上做性能优化。铁律：任何优化不得以精度回归为代价；
每轮只改一处，改完即测。

## 执行流程（四阶段，按序执行，不得跳步）

### 阶段 0：建立基线
用 benchmarks/ 模块跑出未优化的完整数据：TTFT、TPOT、吞吐、峰值显存、
GPU 利用率。固定环境（commit、硬件、负载参数），后续所有对比以此为准。

### 阶段 1：profiling 定位瓶颈（优化点只能从这里产出，禁止凭感觉）
- nsys 出 timeline：找气泡、kernel launch 开销、同步点；
- 逐层耗时拆解：找占比异常的层；
- roofline 判定：prefill 看算力利用率、decode 看显存带宽利用率，
  先分清计算瓶颈还是带宽瓶颈；
- 外部对照：与同模型在 vLLM/SGLang 的实测数字逐项对比，
  差距最大的指标就是第一优先级优化点；
- 特性交叉矩阵：CUDA Graph / TP / 投机解码分别开关，找性能退化的组合。
产出：瓶颈清单（按预期收益排序）。

### 阶段 2：逐项优化
按清单顺序实施，候选类型封闭枚举：算子融合、CUDA Graph 覆盖范围、
通信-计算重叠、KV Cache 布局、kernel 选择/替换、调度开销。
每项优化一个 commit，禁止多项混合提交。

### 阶段 3：验证（每项优化过两道闸）
- 性能闸：before/after 实测，提升 < 5% 的 revert（复杂度不值这个收益）；
- 精度闸：跑模型接入时的精度对齐测试集，贪心一致率不得下降。

## 范围（不做什么）
- 不顺手重构与性能无关的代码；
- 不做量化（独立 feature 任务）；
- 不引入新依赖，确需引入先论证。

## 验收标准
1. 最终报告：相对阶段 0 基线的全指标提升幅度（实测数据）；
2. 精度红线：贪心输出一致率不下降；
3. 每个保留的优化都有独立的 before/after 数据与对应 commit；
4. 停止条件：连续两轮提升均 < 5%，或 profiling 显示已贴近 roofline。

## 交付物
1. profiling 报告：timeline 数据、瓶颈清单、排序依据；
2. 优化记录表：每项的改动、原理、数据、保留/revert 决定及理由；
3. 最终对比：基线 vs 优化后，与 vLLM/SGLang 的差距收敛情况；
4. 文档：README 更新（仅当新增配置项或用法变化）、 model_optimize_benchmarks.md
   更新, 详细记录每个优化措施带来的性能提升；
5. git：新分支，逐项 commit（message 写明该项的实测收益），push 远程。

# 任务：rapid_llm 算子模块架构重构与新模型算子实现

## 背景
rapid_llm 的算子目前散落在各模型文件中，新增模型靠复制粘贴改算子。
本任务建立统一算子层（统一接口 + 注册表 + dispatch），并为新模型
（DeepSeek 系列，见模型支持任务）提供默认 Triton 实现。

## 范围（做什么）
1. 统一算子接口：每类算子一个函数签名，多份实现挂在同一接口下。
2. 算子注册表：所有实现（PyTorch 参考、Triton、CUDA C++、外部库）
   通过同一个注册接口登记。注册方式示例：

   register_op(
       name="attention",
       backend="flashmla",        # 实现名
       fn=flashmla_attention,     # 实现函数
       priority=10,               # 数值越大越优先
       conditions={               # 本实现在什么条件下可用
           "sm": ">=9.0",         # 硬件架构
           "dtype": ["bf16"],     # 支持的数据类型
           "lib": "flashmla",     # 依赖库，未安装则自动跳过
       },
   )

   新增一份实现 = 新增实现文件 + 一次 register_op 调用，不改其他代码。
3. dispatch 机制：每次算子调用，按 priority 从高到低检查各实现的
   conditions，选中第一个全部条件满足的实现。规则集中存在注册表里，
   业务代码不写 if-else。
4. 算子来源四类，地位平等、都走同一注册表：
   - 参考实现（纯 PyTorch）：永远可用，作为正确性对照；
   - 自写 Triton kernel：默认实现；
   - 手写 CUDA C++ kernel：编译为扩展模块后注册，注册方式与其他
     后端完全一致。本任务必须打通这条接入路径（含一个示例 CUDA
     算子跑通"编写→编译→注册→被 dispatch 选中"全流程），但不要求
     新写业务用 CUDA kernel；
   - 外部算子库（可选依赖）：FlashAttention / FlashInfer / FlashMLA
     （attention 系）、DeepGEMM（GEMM）、DeepEP（MoE 通信）。
5. 依赖降级：外部库未安装时自动跳过对应实现，不允许因缺库崩溃。
6. 新模型算子（默认 Triton 实现）：RMSNorm、RoPE、attention（含
   MLA）、MoE 路由/dispatch/combine、GEMM。
7. 编译方式：Triton kernel 首次调用时即时编译（JIT），首次运行有
   编译开销，属预期行为。

## 范围（不做什么）
- 不改模型 forward 逻辑，只替换算子调用入口；
- 不做 kernel 预编译（AOT）：即把 Triton kernel 提前编译好随包发布、
  消除首次运行的 JIT 编译开销。如需此能力，另行立项；
- 外部库的版本锁定与安装脚本另行处理，本任务只做接入与降级。

## 验收标准（全部满足才算完成）
1. 可扩展性演示：新增一份实现，改动只有实现文件 + 一次注册调用。
2. dispatch 正确性（单测覆盖）：
   - 依赖缺失 / 硬件 / dtype / shape 条件不满足时，正确跳到下一
     优先级实现；
   - 所有实现都不满足时，报出明确错误：列出算子名、每份实现被
     跳过的原因。
3. CUDA 路径：示例 CUDA 算子经注册表被 dispatch 选中，结果正确。
4. 数值正确性：每个算子的每份实现与 PyTorch 参考实现 allclose
   （容差按 dtype 定），参数化测试覆盖全部 (算子 × 实现) 组合。
5. 降级验证：逐一卸载每个外部库后，全量测试仍通过。
6. 性能记录：新模型在目标硬件上，每个算子给出各实现的
   microbenchmark，并记录 dispatch 实际选中哪个实现、为什么。

## 交付物
1. 架构说明：接口、注册表、dispatch 流程，含一个具体优先级链实例
   （如 MLA attention：FlashMLA → FlashInfer → Triton → PyTorch）；
2. 算子支持矩阵：算子 × 实现 × 适用条件 × 状态；
3. 测试报告与 microbenchmark 数据（环境、commit、可复现命令）；
4. README 更新：如何新增算子实现——Triton、CUDA C++、外部库
   各给一段完整注册示例；
5. git：新分支，commit 按功能拆分——注册表/dispatch 基础设施一个、
   算子迁移按算子拆、外部库接入按库拆、CUDA 扩展示例一个；
   message 写明验证结果，push 远程。

任务：rapid_llm 开发三个粒度的 overlap 模块，把 CPU 开销、通信开销、内存搬运
开销从关键路径上消除。L1 参考 vLLM model runner v2。完成后用严格测试证明：
性能提升可量化、输出不变、与已有特性交叉使用无问题。

三个粒度（范围以本清单为准，新增需单独提出）：
- L1 CPU-GPU overlap（引擎/调度器层）：异步调度（GPU 执行第 n 步时 CPU
  准备第 n+1 步）、pinned memory 非阻塞 H2D、采样/detokenize 与下一步
  准备并行。
- L2 通信-计算 overlap（分布式层）：
  原理：通信占用互联带宽（NVLink/IB），计算占用 SM，两者是不同硬件资源，
  可以并行。将 batch 沿请求维拆成两个 micro-batch，双 stream 交错流水：
  A 通信时 B 计算、A 计算时 B 通信，每层耗时从「通信 + 计算」降为
  「max(通信, 计算)」，通信被对侧计算掩盖。
  设计要点：decode 沿请求维拆分，prefill 同一序列不可拆断（因果性约束）；
  拆分比例可配，batch 过小时自动退化为不拆；compute/comm 双 stream +
  event 跨流同步，同步点逐层画入设计文档；EP 按 dispatch → 专家 GEMM →
  combine 三段错开流水；两个 micro-batch 激活缓冲独立，显存增量实测量化；
  通信时间 > 计算时间时无法完全掩盖，残余暴露时间必须实测报告。
  自有优化点（≥1 个，禁止照搬已知 two-batch overlap 实现）：写明解决什么
  问题、设计思路、预期收益、实测收益。
- L3 算子内流水（kernel 层）：tile 粒度内存搬运与计算流水（cp.async/TMA、
  double buffer、多级流水）。

架构约束（已识别的耦合点，必须遵守）：
- L1/L2 与引擎、调度器有代码关联：overlap 逻辑与调度逻辑解耦，接口设计
  单独评审；禁止把 overlap 状态散落到调度器各处；交付模块依赖图。
- L3 为独立 kernel，不得依赖引擎/调度器。
- 正确性第一：每级开/关输出逐 token 一致（或容差内）；L1/L2 显式说明
  同步设计（stream 同步点、buffer 生命周期），禁止数据竞争。
- 与 CUDA Graph 的交互单独说明（graph 输入缓冲固定，与异步写入的冲突）。

性能验收（每级分别定义，禁止"极致"这类不可测量的表述）：
- L1：单步 CPU 开销被 GPU 执行完全掩盖；TPOT 较基线改善 ≥ <阈值>%。
- L2：nsys 实测暴露的通信时间下降 ≥ <阈值>%；扩展效率提升。
- L3：kernel 延迟较非流水基线下降 ≥ <阈值>%（memory-bound kernel 给出
  实测带宽利用率）。
- 每级有独立开关，支持分级组合，组合增益分别测量。

nsys 空泡分析（每级必做，是 overlap 验收的核心证据）：
- 每级 overlap 开/关各采集一份 nsys profile，对比 GPU timeline：
  GPU 空泡（idle gap）、暴露通信时间、H2D 空档必须量化并前后对比。
- 报告给出 timeline 关键截图 + 空泡时长数据，证明空泡确实被消除/压缩；
  不允许只用端到端指标宣称 overlap 生效。
- 残余空泡必须定位归因（同步开销/拆分不均/计算过短等）并写入报告。

交叉验证矩阵（逐格验证，不允许"理论上兼容"）：
- {L1, L2, L3} × {CUDA Graph、投机解码、TP、EP、量化}；
- 全开组合无精度/性能问题；负叠加或不兼容记录原因。

测试要求：
- 正确性：每级开/关输出一致性（logits 级 + 端到端生成双验证）。
- 稳定性：高并发长时间稳态运行，无竞态/死锁/显存泄漏。
- 性能：TTFT/TPOT/TPS、吞吐、GPU 利用率，开/关对比。

交付（每项测试/benchmark 必须提供）：
1. 环境：rapid_llm 版本/commit、CUDA/驱动、硬件（含互联拓扑）、模型、
   并行配置、启动参数。
2. 负载：数据集、输入/输出长度、请求数、并发、采样参数。
3. 完整可复现命令。  4. 原始或关键日志；nsys profile 文件与 timeline 分析。
5. 指标：TTFT、TPOT、TPS、TGS（有并行时）、吞吐、延迟分位、错误率、
   显存/GPU 利用率；（L2 额外）暴露通信时间；（每级）GPU 空泡时长前后对比。
6. 对比总结：开/关、各级别组合的对比，结论与异常说明。

Git 与文档：
- 新建分支，按粒度拆 commit（L1/L2/L3 各自独立，交叉验证单独提交），
  每个 commit 独立通过测试；完成后推送远程仓库。
- 更新文档与 README.md：三级 overlap 设计说明（原理、同步设计、模块
  依赖图）、L2 自有优化点说明、用法；README 增加真实录制的 gif 示例。

验收标准：
- 三级 overlap：开关、测试、benchmark 三者齐全。
- 每级均有 nsys 前后对比 timeline，空泡消除可量化，残余空泡有归因。
- L2 有明确写出的自有优化点及其实测收益。
- L1/L2 与引擎/调度器的接口设计有文档、有依赖图。
- 开/关输出一致；稳态运行无竞态/泄漏；交叉矩阵无未测空缺。

# 任务：rapid_llm 调度能力（四阶段：continuous batching → chunked prefill
#        → prefix caching → PD 分离）

## 背景
rapid_llm 当前为静态批处理调度（如现状不符请先更正再开工）。
四个特性按依赖顺序分阶段实施：每阶段独立验收通过后才进入下一阶段，
禁止并行开工——后一个特性建立在前一个的调度循环之上。

## 阶段定义

### 阶段 1：continuous batching
- iteration 级调度：请求在每个 decode step 结束后加入/退出 batch，
  单请求完成即释放资源，不等同 batch 其他请求。
- 配置项：max_num_seqs；调度策略 FCFS。
- 专属验收负载：长短请求混合。验收指标：吞吐 vs 静态批处理的提升
  （实测数据）、单请求延迟无异常恶化。

### 阶段 2：chunked prefill
- 长 prompt 的 prefill 切块执行，块间允许插入 decode。
- 配置项：max_num_batched_tokens（chunk 大小）。
- 专属验收负载：长 prompt + 并发 decode 混合。验收指标：混合负载下
  TPOT 抖动相比阶段 1 下降（给数据）；TTFT 变化如实记录——允许上升，
  但必须给出幅度和解释，禁止只报变好的指标。

### 阶段 3：prefix caching
- block 级前缀复用：按 block hash 命中（参考 vLLM 实现）。
- 配置项：enable_prefix_caching、block 大小（默认 16）。
- 专属验收负载：共享系统前缀的多请求（普通负载测不出命中率）。
  验收指标：命中率、共享前缀场景 TTFT 下降幅度；与 chunked prefill
  同开时行为正确。

### 阶段 4：PD 分离（最小可用版）
- prefill 实例与 decode 实例分离，KV 传输通道打通。
- 本阶段范围只到：1P1D 拓扑端到端跑通、输出正确、TTFT/TPOT 可测。
- 明确不做：多 P 多 D 拓扑、实例编排、负载均衡、容错。

## 范围（不做什么，全程有效）
- 不做优先级调度、抢占策略；
- 不改模型计算代码；
- 除上述四个特性外不新增其他调度功能。

## 通用验收红线（每阶段都过）
1. 正确性：特性开/关两种配置下，同一组 prompt 贪心输出逐 token 一致
   ——调度只能改性能，不能改结果。这是调度类特性的黄金测试。
2. 交叉矩阵：本阶段特性 × {TP, CUDA Graph} 同开无精度、性能回归。
3. 性能数据全部实测，按 benchmarks 规范提供：环境、负载、可复现
   命令、原始日志、TTFT/TPOT/吞吐/显存指标。

## 交付物（每阶段一份）
1. 设计说明（一页）：改了调度循环的哪里、关键数据结构、与已有
   特性的交互；
2. 测试报告：专属负载 + 红线验证数据；
3. README 更新：特性说明、配置项与默认值、适用场景；
4. git：每阶段一组 commit，message 写明验证结果；
   全部完成后 push 远程。

## 背景
# 任务：rapid_llm 新增投机解码模块（可插拔草稿来源，首批接入 dspark、dflash）

## 背景
rapid_llm 新增投机解码能力：草稿 token 由外部库生成，首批接入
dspark、dflash 两个（均为 DeepSeek DeepSpec 体系的草稿模型，机制不同）。
目标模型验证与拒绝采样在框架内完成。无损是硬标准。

模块名说明：下文"调度器 / 模型执行器 / 采样器"是按职责的称呼——
调度器负责请求调度与 token 预算，模型执行器负责前向计算，采样器负责
输出采样。rapid_llm 中对应模块的实际名字以代码为准，先找到对应模块
再动手，找不到就停下来问，不要自行新建同名模块。

## 阶段 0：接口对齐（此阶段不写实现代码）
对 dspark、dflash 分别确认以下信息，各产出一份接口对接文档，
经确认后再动工：
1. 类型：draft model / Medusa / EAGLE / n-gram 中的哪一种；
2. 输入：只要 token ids，还是需要 hidden states / KV；
3. 输出：k 个候选 token？是否含草稿概率；
4. 调用时机：每步同步调用？批量形状；
5. 版本约束、错误语义、超时处理。
两个库的输入可能不同（如一个要 hidden states、一个只要 token ids），
对齐阶段必须暴露这种差异——它决定统一接口的形状。

## 架构设计（核心思想：提议、验证、裁决三者分离）
外部库只负责"提议"（生成候选），框架负责"验证"（目标模型前向）和
"裁决"（拒绝采样）。职责切开后，换草稿库不动框架，改框架不动草稿库。

提议者侧：
- 统一提议者接口：所有草稿来源实现同一个 Proposer 接口
  （propose(...) -> k 个候选 + 草稿概率）；
- 提议者注册表：按名字注册，配置选择启用哪个；新增提议者 =
  新模块 + 一次注册，不改框架代码；
- 各库差异由各自适配器在接口内吸收，框架主流程只见统一接口。

与三个已有模块的结合点（各自的职责边界）：
1. 调度器：草稿预算与回退
   - 投机开启时，每请求每步预留 k+1 个 token 槽位（k 候选 + 1 bonus），
     KV block 分配与 token 记账按此口径；
   - 验证后实际接受 a ≤ k 个，未用槽位回收——token 预算、KV block、
     请求位置游标三方一致回滚；
   - 投机只作用于 decode 阶段，prefill chunk 不参与。
2. 模型执行器：单次批量验证
   - k 个候选拼成一次前向（每请求长度 k+1），一次 forward 拿到
     k+1 个位置的 logits，禁止 k 次串行验证；
   - 候选位置 attention mask 按链式处理（树形候选本期不做）；
   - batch 内各请求实际 k 不同，给出 padding 或变长处理策略。
3. 采样器：拒绝采样与 bonus token
   - 逐位置裁决：接受则用草稿 token；第一个被拒位置从修正分布采样；
   - 全部接受时，从目标模型第 k+1 个分布采 bonus token——bonus 是
     加速收益的一部分，漏掉等于白丢一个 token。

## 范围（做什么）
1. 模块结构：
   - spec_decode/registry.py：提议者注册表；
   - spec_decode/proposers/dspark_proposer.py、dflash_proposer.py；
   - sample/rejection_sampler.py：拒绝采样器，无损的关键；
   - spec_decode/spec_decode_worker.py：主协调器。
2. 配置项：proposer 选择、每步候选数 k、自适应关闭阈值
   （接受率低于阈值自动关闭投机）。
3. 外部库接入层：薄封装；库不可用时明确报错，禁止静默退化。

## 范围（不做什么）
- 不训练、不制作草稿模型；
- 不做树形候选（chain-only）；
- 不改变已有调度特性的语义（chunked prefill、prefix caching 保持原行为）。

## 四个高风险耦合点（逐项设计说明 + 测试）
1. KV cache 回滚：被拒 token 的 KV 槽位正确回收；测试覆盖全部接受 /
   部分接受 / 全部拒绝三条路径。
2. batch 状态分叉：同一步各请求接受数不同、batch 中途变化时，
   调度器与执行器的 token 预算记账一致。
3. CUDA Graph：变长投机步与固定 graph 形状的冲突显式解决
   （多 shape graph / 回退 eager），给结论与实测数据。
4. 采样 RNG：拒绝采样随机数状态管理，保证结果可复现。

## 验收标准
1. 无损性，对每个提议者分别验证：
   - greedy：投机开/关，输出逐 token 一致；
   - 采样：同种子逐 token 一致（首选）；做不到则分布检验：同温度
     各生成 ≥10 万 token，卡方检验 p > 0.05，报告方法与原始数据。
2. 加速（负载固定写明，接受率是负载的函数）：
   - 负载 A（高接受率，如代码续写）：TPOT/吞吐为正收益；
   - 负载 B（低接受率，如高温度开放生成）：劣化 ≤ 5%，自适应开关
     触发正确。
3. 四耦合点测试全覆盖，含接受率 0% / 100% 边界。
4. 交叉矩阵逐格实测（每格 = greedy 一致 + 性能无回归）：
   投机 × {CUDA Graph、TP、量化、通信-计算重叠、chunked prefill、
   prefix caching}；负叠加记录原因。
5. 稳定性：高并发压测 ≥ 30 分钟，无状态错乱，显存曲线平稳。
6. 外部库隔离：dspark、dflash 各有独立 mock，单测不依赖真实库；
   任一库接口变更能被测试立刻暴露。
7. 可扩展性演示：新增一个提议者（可用 mock 演示），改动只有
   实现文件 + 一次注册。

## 交付物
1. 接口对接文档两份（dspark、dflash 各一）；
2. 架构设计说明：三分离思想 + 三个结合点 + 四耦合点；
3. 提议者支持矩阵：库 × 类型 × 接口版本 × 状态；
4. 测试与 benchmark 报告：环境、负载、可复现命令、原始日志、
   指标（TTFT、TPOT、TPS、TGS、吞吐、延迟分位、错误率、显存、
   GPU 利用率、接受率、每步平均接受 token 数）、投机开/关与不同
   接受率负载的对比结论；
5. README 更新：原理、开关与调参；gif 为终端实录的投机开/关速率对比；
6. git：新分支，commit 拆分——投机解码核心 / dspark 接入 / dflash
   接入 / 执行器集成 / 交叉验证与文档，每个 commit 独立过测试，
   完成后推送远程。

# 任务：模型实现模块重构——统一注册入口 + 懒加载

## 背景
rapid_llm/models/ 当前在包导入时全量 import 所有模型文件：模型数量增长导致
import 时间线性膨胀，且新增模型需要改动多处（import 语句、映射表、分发逻辑）。
参考 vLLM 的 ModelRegistry（_LazyRegisteredModel）设计重构。

## 范围（做什么）
1. 统一注册入口：所有模型架构通过单一 registry 注册，对外暴露统一的
   模型查询与实例化入口，删除散落的 if-else / 手动 import 分发代码。
2. 懒加载：registry 只保存 "模型名 → (模块路径, 类名)" 的字符串映射，
   模型真正被使用时才 import 对应模块。
   设计约束：装饰器注册仍然要求先 import 模块才能执行装饰器，达不到
   懒加载目的——必须用字符串映射，不要用装饰器方案。
3. 新增模型的改动收敛为一处：一行注册（或配置文件加一行），
   不再触碰分发逻辑。

## 范围（不做什么）
- 不改任何模型的 forward、算子、权重加载逻辑，纯结构调整；
- 不改对外推理 API 的行为。

## 代码质量要求
- registry 实现独立成单文件，职责单一；
- 文件头英文注释：作用、核心设计、用法（≤15 行）；
- 删除被替代的旧分发代码与死代码。

## 验收标准（全部满足才算完成）
1. 懒加载可验证：python -c "import rapid_llm.models" 后断言
   sys.modules 中不出现任何具体模型实现模块；
   import 时间用 time python -c "import rapid_llm.models" 实测，
   给出重构前后对比，不得变慢。
2. 功能回归：列出现有全部支持的模型清单，逐个加载 + 推理冒烟通过。
3. 新增模型成本演示：新增一个模型的 diff 只有注册一处改动。
4. registry 单测：重复注册的处理、查询未注册模型时的报错信息、
   懒加载断言（上面第 1 条固化成测试）。

## 交付物
1. 重构说明：before/after 结构对比，注册流程图或时序说明；
2. import 时间实测对比（含环境、commit）；
3. 开发者文档更新：新增模型如何注册（README 或 docs/ 一节）；
4. git：新建分支，commit 按功能拆分——registry 基础设施一个、
   存量模型迁移一个、旧分发代码清理一个；message 写明验证结果，
   push 远程仓库。

# 任务：rapid_llm ___ 模块重构（填入模块名/文件路径）

## 背景
当前问题（开工前先填；不清楚就先读代码、总结问题、确认后再动手）：
- 例：职责混杂 / 与其他模块存在重复逻辑 / 死代码 / 性能热点在 ___。

## 目标（按优先级，三件事互不混淆）
1. 结构重构：职责拆分、重复逻辑合并、死代码删除、API 收敛。
   行为必须完全不变。
2. 注释优化：文件头英文注释（作用、核心设计、用法，≤15 行）；
   代码内注释只解释关键约束和设计原因，不复述代码。
3. 性能优化（可选，仅当背景中指出了明确热点）：先 profiling 拿到
   数据再动手，逐项测量。

注意："精度更好"不是本任务的目标——重构的精度要求是"不变"。
过程中发现精度问题，记录下来另行立项，禁止在重构里顺手改数值。

## 范围（不做什么）
- 不改对外接口语义（入参、返回值行为）；确需改的逐个列明并给理由；
- 不改其他模块；发现模块外的问题只记录，不修；
- 不做没有基线的性能"优化"。

## 验收标准
1. 行为不变：重构前后同一组输入，输出逐位一致（推理路径用贪心
   逐 token 对比）；现有测试全部通过。
2. 结构：每一处删除/合并能回答"为什么"；API 给出 before/after
   对照表。
3. 注释：满足目标第 2 条；删掉的注释归类说明（复述代码的 /
   过时的 / 本身错误的）。
4. 性能（仅当做了目标第 3 项）：before/after 实测（环境、负载、
   命令、原始数据）；无提升的改动 revert，不得以"理论上更快"
   保留。

## 交付物
1. before/after 结构与 API 对照；
2. 死代码与重复逻辑清理清单（每条注明依据）；
3. 测试结果；涉及性能时附实测数据；
4. git：结构重构、注释、性能优化分开提交，每个 commit 独立可测。