mcpField
H
huawei-cloud-msmodelslim-model-adapt

huawei-cloud-msmodelslim-model-adapt

github.com/huaweicloud开发59158 次安装2 天前更新
代码仓库

关于 huawei-cloud-msmodelslim-model-adapt

该技能指导开发者为新模型创建 msModelSlim 适配器，以运行 W8A8/W4A16 量化流程。适用于仅解码器 LLM 和理解型 VLM 的文本骨干，并包含注册与验证步骤。

主要功能

  1. 01分析模型结构
  2. 02使用 LLM 和 VLM 模板创建适配器
  3. 03实现并注册所需接口
  4. 04执行四步适配器验证

适用场景

  1. 01为 Ascend NPU 上的新 LLM 添加量化支持
  2. 02将 VLM 文本骨干接入量化流程
  3. 03验证适配器的权重与量化工作流

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/huaweicloud/huaweicloud-skills --skill huawei-cloud-msmodelslim-model-adapt

安装后在 Claude Code 中输入/huawei-cloud-msmodelslim-model-adapt确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

assets/
model_adapter_template.py
vlm_model_adapter_template.py
references/
acceptance-criteria.md
core_workflow.md
implementation_guide.md
interface_checklist.md
interface_reference.md
model_analysis.md
moe_unpacked_adapter_example.py
moe_unpacked_module_example.py
registration_guide.md
troubleshooting.md
verification_guide.md
verification-method.md
references/llm/
fallback_config.yaml
w8a8_dynamic_full_model.yaml
w8a8_static_full_model.yaml
references/vlm/
fallback_config.yaml
w8a8_dynamic_full_model.yaml
w8a8_static_full_model.yaml
scripts/
step1_generate_test_model.py
step2_run_quantization.py
step3_verify_weights.py
step4_verify_quant_description.py

详细介绍

Huawei Cloud msModelSlim 模型适配器

概述

本技能介绍如何为新模型创建基础适配器，以在 msModelSlim 中运行 W8A8/W4A16 量化工作流。

架构：模型分析 -> 适配器创建 -> 注册 -> 验证（4 个步骤）

相关技能：

  • huawei-cloud-msmodelslim-model-analysis - 适配器实现前的模型结构分析
  • huawei-cloud-ascend-profiler-db-explorer - 可选：部署后的性能 分析

范围

支持：

  • 仅解码器 LLM
  • 理解型 VLM（仅文本/LLM 主干）

不支持：

  • 多模态生成（Stable Diffusion/Flux/Wan）
  • 仅编码器模型
  • 非 Transformers 架构

架构

┌─────────────────────────────────────────────────────────────┐
│              msModelSlim Model Adapter Skill                │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────────┐    ┌──────────────────────────────┐  │
│  │  Model Analysis │───▶│    Adapter Creation          │  │
│  │  - config.json  │    │    - LLM Adapter Template     │  │
│  │  - modeling_*.py│    │    - VLM Adapter Template     │  │
│  └──────────────────┘    │    - Required Interfaces     │  │
│                          └──────────────────────────────┘  │
│                                    │                       │
│                                    ▼                       │
│                          ┌──────────────────┐             │
│                          │  Registration    │             │
│                          │  & Installation  │             │
│                          └──────────────────┘             │
│                                    │                       │
│                                    ▼                       │
│  ┌──────────────────────────────────────────────────────┐ │
│  │                   Verification (4 Steps)              │ │
│  │  1. Generate Test Model → 2. Full Fallback Quant     │ │
│  │  3. Weight Verification → 4. Quant Description     │ │
│  └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

架构组件

本技能涉及以下云服务和组件：

  • msModelSlim：Huawei Cloud 的模型量化框架，用于 高效压缩模型
  • Transformers Library：用于模型加载和处理的 Hugging Face Transformers
  • ModelScope：模型下载和管理平台
  • Ascend NPU：量化模型部署的目标硬件

使用场景

典型问题场景：

  • 需要在 Ascend NPU 上部署内存占用更低的 LLM 模型
  • 希望在不显著损失准确率的情况下提升推理速度
  • 迁移未内置 msModelSlim 支持的模型
  • 需要为仅解码器 LLM 或 VLM 文本主干进行 W8A8/W4A16 量化

典型用户表述：

  • “如何为 Ascend 量化我的自定义 LLM 模型？”
  • “为 Qwen 模型创建 msModelSlim 适配器”
  • “实现 W4A16 量化工作流”
  • “为量化适配我的 VLM 文本主干”
  • “如何为新模型添加量化支持？”

核心工作流

1. 准备工作
  • 下载模型：建议使用 modelscope download 下载非权重文件。
    • 示例：modelscope download --model <org>/<model> --local_dir ./models/<name> --exclude '*.safetensors'
  • 分析模型：阅读 config.json 和 modeling_*.py，确认 结构和实现。
2. 创建适配器
  • 使用模板：
    • LLM：assets/model_adapter_template.py
    • VLM：assets/vlm_model_adapter_template.py
  • 实现接口：实现 handle_dataset、init_model、 generate_model_visit、generate_model_forward、enable_kv_cache。
  • 关键原则：
    • visit 和 forward 必须严格保持一致。
    • 建议将 MoE 模型拆分为纯线性层。
    • 参见：实现指南
3. 注册与安装
  • 在 config/config.ini 中注册模型和入口，然后执行 bash install.sh。
  • 参见：注册指南
4. 验证适配器（必需）
  • 必须执行四步验证：生成测试模型 -> 完整回退量化 -> 验证完整回退模型与浮点 权重完全一致，且能够完整加载/保存 -> 验证实际量化工作流正常运行（包括描述文件规则 验证）。
  • 参见：验证指南

常用脚本

脚本位于 scripts/ 目录：

  • scripts/step1_generate_test_model.py
  • scripts/step2_run_quantization.py
  • scripts/step3_verify_weights.py
  • scripts/step4_verify_quant_description.py

前置条件

系统要求
  • Python 3.8+
  • transformers >= 4.40.0
  • msmodelslim >= 1.0.0
环境检查

前置条件检查：需要 Python3 + transformers + msmodelslim

python3 --version  # Python3 >= 3.8
python3 -c "import transformers; print('OK')"  # Transformers library
python3 -c "import msmodelslim; print('OK')"  # msModelSlim library

如果尚未安装：pip3 install --user transformers msmodelslim

参考文档

文档说明
模型分析指南模型结构分析指南
实现指南适配器实现说明
注册指南注册和安装指南
验证指南四步验证工作流
接口检查清单必需的接口实现检查清单
核心工作流核心工作流文档
验收标准功能验收标准
故障排除常见问题及解决方案

要求

  • 已安装 transformers >= 4.40.0
  • 已安装 msmodelslim >= 1.0.0
  • 待适配的 Transformers 模型
  • 了解目标量化方案（W8A8/W4A16）

核心命令

# Create model adapter
python3 scripts/create_adapter.py \
  --model Qwen2-7B \
  --quantization W8A8

# Run four-step verification
python3 scripts/verify_adapter.py --adapter ./adapter.py

参数确认

参数说明必填
model模型名称或路径是
quantization量化方案（W8A8/W4A16）是
output适配器输出路径否

评论

支持 Markdown