llmcompression-add-model

新增 LLM/VLM 模型到 llm_compression

整体流程

1. 确定参考源 → leap_llm 或 transformers
2. 差异分析 → 详细对比新增模型与参考模型的 diff
3. 创建目录结构 → llm_compression/models/<model_name>/
4. 编写 blocks/、model.py、process_utils.py、<model_name>_model.py
5. 创建配置文件 → llm_compression/configs/<model_name>.yml
6. 注册模型 → llm_compression/models/__init__.py
7. 自测验证 → 至少完成 smoke test；如真实权重不可用，做半真实配置验证
8. 生成报告 → 输出接入报告并记录关键问题、解决方式和验证结果

---

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。

核心步骤：

1. 阅读 configuration_<model>.py：获取 config 字段及默认值
2. 阅读 modeling_<model>.py：提取 Attention/MLP/DecoderLayer/Model/ForCausalLM 结构
3. 与框架内参考模型逐项对比差异

---

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.