CANN模型推理迁移器

【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skillsname: model-infer-migrator description: 基于 PyTorch 框架的昇腾 NPU 模型推理适配与部署基线技能。从 HF 链接或本地模型代码出发按 cann-recipes-infer 仓库规范适配到 ModelRunner 推理框架输出可运行的标准模型目录和性能基线数据。触发场景新模型适配到昇腾 NPU 推理框架、已有模型的部署基线采集、模型迁移和初始跑通验证。模型框架适配与部署基线技能从 HF 模型链接或本地代码出发按 cann-recipes-infer 仓库规范完成框架适配和部署基线建立。产出符合仓库标准的模型目录结构Runner infer.py infer.sh YAML 配置并采集标准化的性能基线数据。本技能聚焦基础适配eager 模式、PyTorch 标准算子不涉及融合算子替换、KVCache 优化、图模式适配等性能优化。覆盖场景场景输入状态处理A只有 HF 链接无代码下载 适配框架 生成标准文件 基线采集B有本地代码但跑不通诊断修复最多 5 轮 基线采集C代码可运行但无标准化基线直接基线采集执行流程Step 1: 环境检测 场景判断若 dispatch prompt 未提供环境信息先确认 NPU 可用npu-smi info、torch 和 torch_npu 版本匹配。根据工作目录状态判断场景无 infer.sh → 场景 A → Step 2有 infer.sh → 执行一次成功则场景 C → Step 4失败则场景 B → Step 2NPU 环境不可用 → 报告环境问题结束无论 baseline/baseline_metadata.json 是否已存在都按标准流程重新采集并覆盖。已有基线可能不符合标准采集方式缺少 warmup、未使用 collect_baseline.py、字段不完整等。Step 2: 代码准备场景 A/B场景 A按框架标准生成完整文件结构详见「代码准备规范」。场景 B诊断 infer.sh 执行失败的原因修复后重试最多 5 轮。NPU 运行时错误参考 model-infer-runtime-debug skill。Step 3: 试运行执行bash infer.sh根据结果分流跑通→ Step 4OOM→ 估算显存需求报告需多卡结束其他错误→ 回到 Step 2Step 4: 基线采集使用dataset: default读dataset/default_prompt.json。infer.py 内model_generate(warm_upTrue)做预热model_generate()正式推理框架 ModelRunner 自动输出 Prefill/Decode 耗时日志。其中 Prefill 耗时为首次 forward 的耗时Decode 耗时为后续每步 forward 的平均值warmup 和编译开销不计入。注意基线采集前必须确认 infer.py 包含 warmup 调用model_generate(warm_upTrue)。无 warmup 时首次推理包含编译开销导致基线数据偏高。推理完成后执行collect_baseline.py从日志解析耗时 采集环境信息输出baseline/baseline_metadata.json。框架launch函数将日志输出到${RES_PATH}/log_0.logRES_PATH 由框架自动创建格式为res/{date}/{model_name}/。python3 .claude/skills/model-infer-migrator/scripts/collect_baseline.py \ --log-file {RES_PATH}/log_0.log \ --output {output_dir}/{model_name}/baseline/baseline_metadata.json \ --yaml-file {yaml_path}多卡场景多卡推理生成多个 rank 日志log_0.log~log_N.log使用 rank 0 的日志。验证要求输出吐字正常可读、不重复、长度合理异常则回到 Step 2 诊断。baseline_metadata.json 中的 output_text 需记录完整输出。代码准备规范场景 A产出文件结构输出目录默认cann-recipes-infer/models/{model_name}/可通过 dispatch prompt 配置其他路径。{output_dir}/{model_name}/ ├── config/ │ └── {model_name}_{config}.yaml ├── cann-recipes-infer/models/ │ ├── configuration_{model_name}.py │ ├── model_setting.py │ └── modeling_{model_name}.py ├── infer.py ├── infer.sh ├── runner_{model_name}.py ├── requirements.txt ├── README.md └── baseline/ └── baseline_metadata.json通用适配流程所有模型都走以下固定步骤复制 HF 实现到 cann-recipes-infer/models/ 目录从 HF transformers 复制 modeling/configuration 相关文件最小改动适配框架。禁止from transformers导入模型类modeling 和 configuration 代码必须 vendoring 到仓库内不依赖 transformers 提供模型实现modeling 构造函数对齐__init__(self, config, runner_settingsNone, **kwargs)框架通过from_pretrained将runner_settings作为 kwarg 传入modeling class 需要能接收确保import torch_npu在模型或 runner 代码中执行否则 NPU 设备不可用推理会回退到 CPU删除训练专用代码gradient_checkpointing、labels/loss 等保留 PyTorch 标准算子不替换 NPU 融合算子创建 Runner继承 ModelRunner通过路由表选择架构相近的参考模型学习其框架接口用法方法签名、input_dict 构造方式、调用链。modeling 代码采用最小改动 vendoring 策略——直接复制 HF 的 modeling 实现到仓库仅做框架接口适配forward 签名、input_dict 对接不重写推理逻辑、不从仓库参考模型复制 modeling 代码创建 infer.py、infer.sh、YAML 配置、model_setting.py参考references/templates.md创建 requirements.txt、README.mdRunner 接口要点继承executor.model_runner.ModelRunner需要实现的方法方法职责__init__(self, runner_settings)调用super().__init__(runner_settings)初始化模型特有参数init_model()加载模型和 config调用super().init_model(ModelClass, ConfigClass)model_input_prepare(self, input_dict)从 input_dict 提取字段构造模型 forward 所需的入参字典model_output_process(self, model_inputs, outputs, input_dict)从 outputs 提取 logits更新 input_dict 状态next token、kv_len、is_prefill 等model_generate(self, prompts, warm_upFalse)顶层推理方法见下方调用链说明调用链Runner 子类的model_generate是顶层入口接收原始 prompts 字符串。内部需要tokenize prompts → 构造 input_dict包含 input_ids、generate_ids、attention_mask、is_prefill 等调用基类super().model_generate(input_dict, input_lens, warm_up)基类内部循环调用model_input_prepare→model_inference→model_output_processmodel_setting.py包含check_vars校验并行参数和update_vars计算派生配置参考仓库模型的同名文件。重要实现 Runner 前必须完整阅读参考模型的 runner 代码特别是 model_generate 和 model_input_prepare 的完整实现理解 input_dict 的构造方式和字段含义。不同模型的 input_dict 字段差异较大不能仅依据方法签名编写。参考模型路由表模型架构参考模型参考路径标准 LLMMHA/GQAgpt-osscann-recipes-infer/models/gpt_oss/MoE 架构qwen3-moecann-recipes-infer/models/qwen3_moe/MLA 架构DeepSeek 系列deepseek-r1cann-recipes-infer/models/deepseek_r1/长序列longcat-flashcann-recipes-infer/models/longcat-flash/多模态/视频生成hunyuan-videocann-recipes-infer/models/hunyuan-video/权重管理通过 YAML 的model_path指定权重路径支持任意本地路径。权重已在本地 ├─ 是 → 填入 YAML model_path └─ 否 → 权重大小 ├─ 5GB → 下载到本地如 huggingface-cli、snapshot_download、modelscope 等路径填入 YAML └─ 5GB → 提示用户自行下载并提供路径并行部署场景基线采集前确认权重已正确配置在线切分enable_online_split_weight: True或离线预切分目录结构完整。权重处理由 parallel-impl skill 负责migrator 仅做运行前检查。基线采集scripts/collect_baseline.py从框架 ModelRunner 的推理日志中解析性能数据采集环境信息输出baseline/baseline_metadata.json。baseline_metadata.json 格式{ timestamp: 2026-04-06T15:30:00, environment: { npu_model: Ascend 910B4, num_cards: 1, cann_version: 8.5.0, pytorch_version: 2.6.0, torch_npu_version: 2.6.0.post1, exe_mode: eager }, model_config: { model_name: Qwen3-0.6B, model_source: https://huggingface.co/Qwen/Qwen3-0.6B }, performance: { prefill_ms: 70.15, decode_avg_ms: 71.5, output_text: ... } }格式从框架日志可解析的字段出发不包含框架不输出的数据。结束条件全部条件满足后结束不做额外优化或探索。场景 A/B单卡适配完成标准文件结构完整modeling config runner infer.py infer.sh YAML model_settingbash infer.sh在 NPU 上跑通输出吐字正常可读、不重复、长度合理baseline_metadata.json 已生成场景 A/B单卡显存不足完整的单卡框架适配已完成modelingHF 实现本地化 框架接口适配、Runner继承 ModelRunner、infer.py、infer.sh、YAMLworld_size1、model_setting.py、configuration、requirements.txt代码可作为并行化改造的基础parallel-impl 在此基础上替换并行层、加通信组、生成多卡 YAML报告显存需求和预估卡数场景 C多卡基线采集bash infer.sh在多卡 NPU 上跑通baseline_metadata.json 已生成输出吐字正常可读、不重复、长度合理参考文档索引文档路径框架适配模板infer.py / infer.sh / YAMLreferences/templates.md基线采集脚本scripts/collect_baseline.pyModelRunner 基类cann-recipes-infer/executor/model_runner.py【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考