horizonrobotics 新增 LLM/VLM 模型到 llm_compression
整体流程
- 确定参考源 → leap_llm 或 transformers
- 差异分析 → 详细对比新增模型与参考模型的 diff
- 创建目录结构 →
llm_compression/models/<model_name>/ - 编写 blocks/、
model.py、process_utils.py、<model_name>_model.py - 创建配置文件 →
llm_compression/configs/<model_name>.yml - 注册模型 →
llm_compression/models/__init__.py - 自测验证 → 至少完成 smoke test；如真实权重不可用，做半真实配置验证
- 生成报告 → 输出接入报告并记录关键问题、解决方式和验证结果
Step 0：确定参考源
首先检查 leap_llm/models/ 下有没有同名目录：
- 有：以
leap_llm该模型的forward()方法为主要参考（不是build()） - 没有：去 transformers 源码查找：
<site-packages>/transformers/models/<model_name>/modeling_<model_name>.py
同时参考已集成模型的框架写法：
- VLM：
llm_compression/models/qwen2_5_vl/（无 QK-Norm）或qwen3_vl/（有 QK-Norm + DeepStack） - LLM：
llm_compression/models/qwen3/
当 leap_llm 没有参考模型时（从 transformers 对齐）
必须直接阅读 transformers 源码，提取模型结构信息。详细的阅读方法、config 字段速查和对齐检查清单见 transformers_alignment_guide.md。
核心步骤：
- 阅读
configuration_<model>.py：获取 config 字段及默认值 - 阅读
modeling_<model>.py：提取 Attention/MLP/DecoderLayer/Model/ForCausalLM 结构 - 与框架内参考模型逐项对比差异
Step 0.5：差异分析（必须在写代码前完成）
整理差异清单，包含三类：
- 模型层 diff：attention 形式（q_norm/k_norm、attention_bias、sliding_window）、mlp（bias、激活函数）、norm 类型、rope 实现、权重命名
- 数据层 diff：position_ids 方式（1D 还是 3D mRoPE）、mask 形状、padding 方向、多模态输入
- generate 逻辑层 diff：prefill/decode 流程、chunk_prefill、cache 管理、停止条件
要求：
- 明确指出哪里相同、哪里不同，不要笼统说"类似 qwen3"
- 无法确认的点标记"待确认"
Step 1：blocks/attention.py
1.0 License 头声明（blocks/ 下所有文件 + model.py 必须添加）
models/*/blocks/ 下的所有 .py 文件以及 models/*/model.py 派生自 HuggingFace Transformers（Apache 2.0），必须保留 transformers 原始的完整 License 声明，并追加 Horizon 修改声明。
获取正确的 Copyright 行：查看 transformers/models/<model>/modeling_<model>.py 文件头的 Copyright 行，原样复制。不同模型的 Copyright 行不同（如 Qwen 系列含 Alibaba Group，Gemma 系列只有 HuggingFace Team）。
# Copyright <year> <original authors from transformers>. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# Modifications Copyright (c) Horizon Robotics. All rights reserved.
此声明适用于 blocks/ 下所有文件（__init__.py、attention.py、mlp.py、transformer_block.py、moe.py、vision_*.py、linear_attention.py、text_*.py 等）以及 model.py。
1.1 逐项确认（无论参考源是 leap_llm 还是 transformers）
| 检查项 | llm_compression 映射 |
|---|---|
| proj bias | 与参考源一致，若从 config 读则 getattr(config, "attention_bias", False) |
| q_norm/k_norm | 有则 horizon_plugin_pytorch.nn.RMSNorm(head_dim, eps=config.rms_norm_eps) |
| head_dim | getattr(config, "head_dim", config.hidden_size // config.num_attention_heads) |
| scaling | 成员变量 self.scaling = self.head_dim ** -0.5 |
1.2 量化组件
self.cache_k_fq = QuantStub()
self.cache_v_fq = QuantStub()
self.dequant = DeQuantStub()
- 有 leap_llm：对照
build()中 leap 算子位置插入 - 无 leap_llm：参考 qwen3 的标准模式——cache KV 操作前后 quant/dequant 是固定的
1.3 关键规则
- RoPE 后必须立即 reshape 回 4D 再做 cache 操作
- cache KV: cat 前 dequant，cat 后重新量化
attention_mask已是 4D，直接torch.add，不要 unsqueeze- GQA matmul: reshape 为
[bsz, num_kv_heads, -1, head_dim]再 matmul - new_key/new_value 返回前 quant → dequant
shape 流和代码模板见 reference.md
Step 2：model.py（TextModel）
2.1 cos/sin 预计算
- 无 leap_llm 时：阅读 transformers 的
<Model>RotaryEmbedding，提取inv_freq公式 - 大多数模型用标准 RoPE，可复用 qwen3 的
_set_cos_sin_cache，只需确认rope_theta - 预计算后截取到
max_kvcache_len，存为普通属性（不用register_buffer）
2.2 QuantStub 与 cos/sin 索引
- QuantStub 标准四件套：
quant_input_embeds、quant_cos、quant_sin、quant_attention_mask、dequant - 有 leap_llm：对照
build()中 leap 算子输入 - 无 leap_llm：直接复用标准四件套
- cos/sin 用
torch.gather按position_ids索引；VLM mRoPE 需按 mrope_section 分别索引再拼接
代码模板见 reference.md
2.4 forward() 输出
# 取最后 token → norm → lm_head → dequant
return token_logits, new_keys, new_values
Step 3：process_utils.py
3.1 复用 generate_utils.py
from llm_compression.models.generate_utils import (
chunk_prefill_forward, chunk_visual_forward, get_causal_mask,
get_causal_mask_chunks, get_decoder_mask, get_paded_input_ids_attn_mask,
init_kv_cache, init_prefill_kv_cache, is_finished, padding_data,
process_kv_cache,
)
3.2 generate_func 流程
prefill：判断 chunk_prefill → 左 padding → 初始化 KV cache → position_ids 转 int64 → get_causal_mask → forward
decode：init_kv_cache → 循环（argmax/sampling → embed → position_ids.long() → decoder_mask → forward → process_kv_cache）
3.3 config 访问（关键差异）
- LLM：
config.max_kvcache_len/config.max_lm_input_len（update_config_from_custom_config直接写入 model_config） - VLM：
config.text_config.max_kvcache_len/config.text_config.max_lm_input_len（嵌套 config）
3.4 VLM 额外逻辑
| 函数 | 用途 |
|---|---|
get_rope_index |
mRoPE 3D position_ids (3, bsz, seq_len) |
gen_inputs_embeds |
masked_scatter 将 image embeddings 填入 text |
scatter_deepstack_embeds |
DeepStack 中间层 visual features |
Step 4：_model.py（BaseQModel 子类）
4.1 build_model config 更新
- LLM：
update_config_from_custom_config(model_config, self.custom_config.model.text_config) - VLM：分别 update
model_config.vision_config和model_config.text_config
4.2 权重加载与 get_qconfig_setting
- 权重映射：HF key 去掉
model.前缀，加lm.前缀；lm_head.weight→lm.lm_head.weight。注意：不是映射到prefill.，而是映射到lm.，因为model.prefill = model.lm是引用赋值 - 验证：
miss_key仅含 QuantStub 相关 key，unexpected_key合理 - 有 leap_llm：
ConstFakeQuant(N)→{"output": qintN}，FakeQuantMatmul(a, b, None)→{"input": [qintA, qintB]} - 无 leap_llm：参考 qwen3 标准配置（cache_k_fq: qint16, cache_v_fq: qint8, matmul: [qint8, qint16]/[qint16, qint8]）
- 使用
SetDynamicQuantTemplate(op_kwargs={nn.Linear: {"block_size": "full", "dim": -1}})配置动态量化 - KV cache 配置推荐用
self.get_kvcache_names(model_name)遍历构建
代码模板见 reference.md
4.4 必须实现的接口
build_model、get_model_trace_dummy_input、get_generated_model、get_generated_model_cfg、get_model_dtype、get_kvcache_names、get_model_input_output_name、input_preprocess、output_postprocess、get_qconfig_setting
所有 import 必须放文件顶部。
Step 5：配置文件
必须先问用户模型权重路径。
- LLM：
model_list: [prefill, decode]，无vision_config - VLM：
model_list: [visual, prefill, decode]，vision_config默认image_height/width: 448 max_lm_input_len默认 512，max_kvcache_len默认 1024，rmsnorm_version: cuda_hpmodel_dtype: float32是默认精度
shared LM 模式：当显存不足以 deepcopy LM 时，可用 model_list: [visual, lm]（VLM）或 [lm]（LLM），prefill 和 decode 共享同一份权重，显存减半。BaseQModel.is_shared_lm_mode() 自动检测。
Step 6：注册与验证
注册：llm_compression/models/__init__.py 中 from .<model_name>.<model_name>_model import XxxModel
测试：yml 中 eval_step: 5 → sh llm_compression/scripts/torch_eval.sh（使用项目 conda 环境）→ 成功标准：exit_code: 0 + Evaluation Results 表格
Step 7：自测验证（新增模型后必须执行）
7.1 最低要求
至少完成以下 3 类检查中的 1 类；如果真实权重不可用或模型过大，优先做第 2 类：
- 权重级验证：能加载真实权重时，跑
build_model+torch_eval.sh - 半真实配置 smoke test：保留真实模型关键结构参数，裁剪层数或 expert/vocab 大小，直接跑
process_utils.generate_func - 小配置 smoke test：手工构造小 config，验证 prefill/decode/cache 主链路可执行
7.2 推荐 smoke test 覆盖矩阵
chunk_prefill=Falsechunk_prefill=True- 仅
linear_attention路径（如果模型存在） - 至少 1 个
full_attention路径（如果模型存在） - 至少
1层和2层两组 case；若前几层没有覆盖到关键结构，可补 1 个特定层型 case
7.3 半真实配置裁剪原则
当真实模型太大、权重不完整或容易爆显存时：
- 保留：
hidden_size、head_dim、num_attention_heads、num_key_value_heads、rope_parameters、layer_types、线性注意力关键维度 - 可以裁剪：
num_hidden_layers、vocab_size、num_experts、num_experts_per_tok - 目标：优先验证结构、shape、cache 流是否正确，而不是追求语义输出
7.4 自测记录要求
需要至少记录以下信息：
- 使用的环境与 GPU，如
CUDA_VISIBLE_DEVICES=0,1,2 - 测试类型：小配置 / 半真实配置 / 真实权重
- 测试 case 列表
- 每个 case 是否通过
- 关键输出：返回 shape、是否报错、是否覆盖
chunk_prefill
Step 8：生成报告与留痕
8.1 报告文件
完成新增模型后，生成报告文件：
- 推荐路径：
llm_compression/reports/<model_name>_integration_report.md
8.2 报告至少包含
- 任务背景：用户要求、模型目录、环境、GPU 约束
- 参考源：
leap_llm还是transformers - 差异分析摘要：模型层、数据层、generate 逻辑层
- 代码改动：新增/修改了哪些文件
- 遇到的问题：如权重不完整、模型太大、cache 不兼容、shape 报错
- 解决方式：具体采取了什么裁剪、替代验证或代码修复
- 自测结果：测试矩阵、是否通过、代表性输出
- 未完成项/风险：例如真实权重尚未验证、量化尚未验证
常见报错
| 报错 | 排查 |
|---|---|
config has no attribute 'text_config' |
LLM 直接 config.xxx |
size mismatch at dim 3 |
causal_mask 多余 squeeze？kv_len ≠ max_kvcache_len？ |
gather() Expected int64 |
position_ids 在 process_utils 转 .long() |
| 3D vs 4D shape 不匹配 | RoPE 后未 reshape 回 4D？cur_len 取错维度？ |
miss_key 含非 QuantStub key |
权重映射遗漏 |
mat1 and mat2 cannot be multiplied |
hidden_size/head_dim 不匹配 |
核心方法论
- 不能无脑 copy：bias、norm、scaling、rope、cache 格式逐项对照
- 参考源用法：有 leap_llm 时
forward()参考结构 +build()参考量化位置；无 leap_llm 时 transformersforward()是唯一参考，量化位置参考已集成模型 - shape 全程追踪：遇到 mismatch 从数据生成处开始追踪
- 职责分离：process_utils 管数据预处理、model.py 管前向计算、qmodel.py 管配置加载和权重映射
- 框架模式复用：cache KV 处理、QuantStub 四件套、generate_func 流程、权重映射逻辑都是模板化的
详细案例见 qwen3_case_study.md，transformers 对齐详细指南见 transformers_alignment_guide.md。