mcgatom/codex-cannbot/model-infer-migrator

模型适配与部署基线技能

把 HF 模型或本地代码适配到 infer 仓的两种部署模式之一，产出符合规范的模型目录和标准化性能基线。

本技能聚焦单卡基础适配 + 部署基线采集（eager 模式、PyTorch 标准算子），不涉及并行化、KV 模式优化、融合算子、图模式等性能改造。这些由后续 skill（parallel-impl / kvcache / fusion / graph-mode）接手。

部署模式判定

框架部署模式（推荐）：模型声明契约接入 cann-recipes-infer/executor/core/，调度 / KV 管理 / 批组装 / 采样 / PD 分离 / MTP / profiler 等公共流程由框架负责。模型通过 support_models.py 注册。

独立部署模式：模型不接 cann-recipes-infer/executor/core/，自管 Runner / KV cache / 推理脚本。适用仓外项目复用 skill 或框架契约不适用的特殊算法。

判定优先级

编排层（如 model-infer-optimize）派发本 skill 时不能与用户交互，应在 dispatch prompt 中显式带 部署模式: ...；缺失时按工作目录自检，仍无法确定则默认框架部署。用户直接调用本 skill 且信号不明确时，可向用户确认。

判定后跳转：

• 框架部署模式 → 「## 框架部署模式」大节
• 独立部署模式 → 「## 独立部署模式」大节

覆盖场景（共通）

共通工作流

Step 1: 环境检测 + 部署模式判定

确认 NPU 可用（npu-smi info）、torch 和 torch_npu 版本匹配。按上面「部署模式判定」表选择模式。

Step 2: 场景判断

• 无 infer.sh → 场景 A → Step 3
• 有 infer.sh → 执行一次：成功则场景 C → Step 4，失败则场景 B → Step 3
• NPU 环境不可用 → 报告环境问题，结束

Step 3: 代码准备（场景 A/B）

跳到对应大节执行：

• 框架部署模式 → 「## 框架部署模式」适配要点
• 独立部署模式 → 「## 独立部署模式」适配要点

Step 4: 试运行 + 基线采集

执行 bash infer.sh，按结果分流：

• 跑通：用 dataset: "default"（读 cann-recipes-infer/dataset/default_prompt.json）采集基线

``bash python3 scripts/collect_baseline.py \ --log-file {log_path} \ --output {output_dir}/{model_name}/agentic/baseline/baseline_metadata.json \ --yaml-file {yaml_path} \ --rank 1 `` 输出吐字正常（可读、不重复、长度合理），baseline_metadata.json 中的 output_text 需记录完整输出。多卡推理读 rank 1 的 log（rank 0 经 tee 可能截断）。

• 补采子场景：reviewer log 已有 + 代码未提交新 commit + YAML 未变 → 跳过 bash infer.sh 重跑，直接用既有 log 调脚本提取即可

• OOM（显存不足）：本阶段输出代码骨架并标记"需多卡"，由 optimize 编排进入并行化阶段；并行 + kvcache 等优化跑通后由编排层补采基线。产物：多卡占位 YAML（待 parallel-impl 接入）+ 空 agentic/baseline/ 目录 + README 标注 OOM 预期与下游 skill 任务；单卡 YAML 跑不通时不必保留。

• 其他错误：参考 references/common_issues.md；NPU 运行时错误 → model-infer-runtime-debug；精度异常 → model-infer-precision-debug。

日志路径：

• 框架部署模式：${RES_PATH}/log_0.log（由 launch 创建）
• 独立部署模式：infer.py 输出到 stdout / 自定义日志路径

产物文件结构

两模式产物文件命名 100% 一致，YAML schema 同 4 段式：

{output_dir}/{model_name}/
├── config/{model_name}.yaml
├── cann-recipes-infer/models/
│   ├── configuration_{model_name}.py
│   └── modeling_{model_name}.py
├── infer.py                      ★ 独立部署模式自带；框架部署模式不带（统一走 cann-recipes-infer/executor/offline/infer.py，不推荐自带）
├── infer.sh
├── runner_{model_name}.py        ★ 独立模式独有
├── requirements.txt
├── README.md
└── agentic/baseline/baseline_metadata.json

注意：cann-recipes-infer/models/{model_name}/models/ 下不要放 `__init__.py`。

框架部署模式

接入 cann-recipes-infer/executor/core/ 框架，模型走 InferenceConfig + CommManager + cache_unit 契约，启动通过 cann-recipes-infer/executor/offline/infer.py + launch。本阶段为最简部署基线，KV 先用 Legacy 模式跑通；PA 等进一步改造由 kvcache 优化阶段处理。

模型类作为框架扩展点与 ModelWorker / ExecutionEngine / Scheduler / InferenceConfig / CommManager / ForwardMetaData 协作；调度、KV 管理、批组装、采样由框架统一负责。

适配要点

1. 复制 HF 实现到 `cann-recipes-infer/models/{model_name}/models/`：vendoring HF modeling 和 configuration（禁止 `from transformers import 模型类`）。删除训练专用代码，保留 PyTorch 标准算子。modeling 类基类改为 nn.Module。

• 命名规则：目录 / 文件 / 模块名用下划线
• HF 依赖剪裁（通用替换）：
• Cache / DynamicCache → 删，用 Legacy self.k_cache / v_cache
• create_causal_mask → 删，用 forward_metadata.attention_mask
• PreTrainedModel / GradientCheckpointingLayer / ALL_ATTENTION_FUNCTIONS → 删，改为 nn.Module
• 纯函数（RMSNorm / rotate_half / RoPE 工具）→ 保留

1. 改造 ForCausalLM 构造签名为 (config, infer_config, comm_manager, prefix)。读取参数从 runner_settings.get(...) 改为 infer_config.parallel_config.attn_tp_size 等点访问；通信组从 comm_manager.get_group(...) 取。

1. 改造 forward 签名为 (input_ids, position_ids, forward_metadata, slot_mapping=None, block_table=None, **kwargs)。input_ids 是 packed [TotalTokens]，运行时元数据从 forward_metadata 读，返回 packed logits。

1. KV 路径选择（按场景二选一，互斥；框架按是否存在 get_cache_info() 分发）：

• 路径 A — Legacy + HF SDPA（默认推荐 — 单卡 + 等长 batch baseline，最简）
• Attention 声明 self.cache_unit = (num_kv_heads_per_rank * head_dim,)，框架按 (batch, seq, *cache_unit) 预分配 k_cache / v_cache；模型 forward 内用标准 indexing 或 torch_npu.scatter_update_ 写 cache
• 顶层 forward 入口对 packed 1D input_ids 做 BSND reshape 回 [B, S]（gemma-4 BSND shim 套路；仅等长 batch 适用）
• 不实现 get_cache_info() / 不声明 cache_entries
• 路径 B — 最简 Paged + HF SDPA（多卡 / 变长 batch / 用户明确指定 Paged 起步时使用）
• 实现 get_cache_info() + cache_entries（FullAttention，按实际 KV head 维度，不引入 MLA latent 压缩）
• 写 cache 用 npu_scatter_nd_update_ 接 forward_metadata.slot_mapping[attn_type]；attention 读 cache 后用 HF 原版 SDPA / 标准 PyTorch（不上 FA 算子）
• 顶层 forward 直接走 packed 1D，无需 BSND shim
• 共通约定：
• 两路径互斥，选定后整套代码（cache 写入、attention 读法、forward 输入形态）保持一致
• reference 已注册模型的 get_cache_info() 是 kvcache skill 升级后的产物（含 MLA absorb / FA / nope+rope 双 entry），不要整段照搬到 migrator 阶段
• 模型自有 cache（非 KVCache，如 N-gram / hash buffer / speculative buffer）由 model class 自管，不上报 cache_entries
• FA 算子接入 / MLA absorb / 复杂 attn_type（SlidingWindow / 混合）/ latent 压缩 由 kvcache skill 接手

1. 实现权重契约：load_weights(weights) 接 HF checkpoint stream；process_weights_after_loading() 触发 quant_method.process_weights_after_loading（MoE / 量化模型必须实现）。

1. 注册到 `cann-recipes-infer/executor/core/support_models.py`：

``python model_dict = {"{model-key}": ({ModelName}ForCausalLM, {ModelName}Config)} ` 含 MTP 的注册为 3 元组：("key", MainCausalLM, MTPClass, Config)`。

1. 写 YAML、infer.sh、requirements、README：模板见 references/framework_templates.md。requirements.txt 优先对齐仓内已注册同架构模型（参考路由表），缺失的再按 HF 原仓补；避免引入与既有模型冲突的版本约束。

migrator 输出框架契约骨架 + Legacy KV + HF 原版 attention 的 world_size=1 单卡代码。FA 算子改造、Paged 改造、复杂架构 KV、多卡部署 / 权重切分由 kvcache / parallel-impl skill 接手；本阶段不做。

模型类契约速查

完整签名、ForwardMetaData 字段表、CommManager 通信组命名见 references/framework_templates.md。

参考模型路由表

已在 cann-recipes-infer/executor/core/support_models.py 注册的参考实现：

独立部署模式

不依赖 cann-recipes-infer 框架，模型自管 Runner / 推理脚本。仍可复用 cann-recipes-infer/module/linear.py 的 ParallelLinear（独立加载）和 cann-recipes-infer/executor/model_loader/weight_utils.py 的权重加载工具。

适配要点

1. 复制 HF 实现到 `cann-recipes-infer/models/{model_name}/models/`：vendoring HF modeling 和 configuration，删除训练专用代码。

1. 改造 modeling forward 接口为自定义参数（不用 ForwardMetaData）：

``python def forward(self, input_ids, position_ids=None, past_key_values=None, kv_len=None, attention_mask=None, is_prefill=True) ` Attention 层接收 past_key_value + kv_len，用 torch_npu.scatter_update_ 更新 KV。decode 分支 attention_mask=None`。

1. 写自定义 Runner 骨架（runner_{model_name}.py，不继承 ModelRunner）：

• __init__(yaml_file_path): 解析 yaml；加载 tokenizer / config / model；预创建 mask；预计算 RoPE
• init_static_kvcache: 最简占位（每层一对 (k, v) tensor，BSH layout，简单 zeros 分配）
• model_generate(prompts, warm_up=False): tokenize batch → prefill → decode loop → detokenize；日志格式 {model_name} inference time cost of {stage} is X ms 与仓库对齐

1. 写 infer.py：实例化 Runner（传 yaml 路径），先 model_generate(prompts, warm_up=True) 预热，再 warm_up=False 正式跑。

1. 写 infer.sh、requirements、README：模板见 references/standalone_templates.md。

migrator 输出 Runner 骨架 + 最简 KV 占位 + HF 原版 attention 的单卡代码。FA 算子接入、PA 启用、SlidingWindow / MLA absorb 等优化由 kvcache skill 接手；多卡 dist.* + ParallelLinear 替换由 parallel-impl skill 接手。

Runner 契约速查

权重管理（共通）

通过 YAML 的 model_config.model_path 指定权重路径。

权重已在本地？
  ├─ 是 → 填入 YAML model_config.model_path
  └─ 否 → 权重大小？
           ├─ < 5GB → 下载到本地（huggingface-cli / snapshot_download / modelscope）
           └─ >= 5GB → 提示用户自行下载并提供路径

migrator 阶段单卡跑通即可；并行权重切分、在线/离线切分由 parallel-impl skill 处理。

baseline_metadata.json 格式（共通）

{
  "timestamp": "<ISO8601>",
  "yaml_path": "config/{model_name}.yaml",
  "environment": {
    "npu_model": "<npu_model>",
    "num_cards": <int>,
    "cann_version": "<x.y.z>",
    "pytorch_version": "<x.y.z>",
    "torch_npu_version": "<x.y.z>",
    "exe_mode": "<eager|ge_graph|npugraph_ex>"
  },
  "model_config": {
    "model_name": "<model_name>",
    "model_source": "<hf_url_or_local_path>"
  },
  "performance": {
    "prefill_ms": <float>,
    "decode_avg_ms": <float>,
    "output_text": "<sample_output>"
  },
  "verification": {
    "all_ranks_success": <bool>
  }
}

yaml_path 指向运行时使用的 YAML，parallel_config / scheduler_config 等并行/调度配置不重复嵌入 JSON。decode_avg_ms 须剔除首步冷启（编译落地开销，约 30-50ms 偏高）。分析推算（非 runtime 实测）的性能字段加 _estimated 后缀以示区分。

结束条件

共通条目（必须）：

1. 标准文件结构完整（modeling + configuration + YAML + infer.sh + requirements + README）
2. modeling 框架契约骨架到位（构造签名 / forward 签名 / 权重契约；KV 按部署模式接入：框架部署用 Legacy cache_unit，独立部署用最简 list of (k, v)）

跑通态条目（按场景二选一）：

• 单卡可跑通：bash infer.sh 跑通 + 输出吐字正常 + agentic/baseline/baseline_metadata.json 已生成
• 单卡 OOM：标记"需多卡"，不必跑通；baseline 由 optimize 编排在并行化后补采

部署模式专属：

• 框架部署模式：模型已注册到 cann-recipes-infer/executor/core/support_models.py
• 独立部署模式：含 runner_{model_name}.py + 自带 infer.py

参考文档索引