huawei-cloud-msmodelslim-model-analysis

Huawei Cloud msModelSlim 模型分析

概述

此技能用于在实现 msModelSlim 适配器之前分析候选模型。

架构：实现源码检测 → 模型类型分类 → 结构特征分析 → 风险评估

相关技能：

• huawei-cloud-msmodelslim-model-adapt - 根据分析结果创建适配器

架构组件

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

• msModelSlim：Huawei Cloud 的模型量化框架
• Transformers Library：用于加载模型的 Hugging Face Transformers
• ModelScope：模型下载和管理平台
• config.json：用于分析的模型配置文件

架构图：

┌─────────────────────────────────────────────────────────────┐
│           msModelSlim Model Analysis Skill                  │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐ │
│  │  Model       │───▶│  Source      │───▶│  Structure   │ │
│  │  Input       │    │  Detection   │    │  Analysis    │ │
│  │  (config)    │    │              │    │              │ │
│  └──────────────┘    └──────────────┘    └──────────────┘ │
│         │                   │                   │          │
│         ▼                   ▼                   ▼          │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐ │
│  │  Type        │    │  MoE         │    │  Risk        │ │
│  │  Classification│   │  Assessment │    │  Assessment │ │
│  └──────────────┘    └──────────────┘    └──────────────┘ │
└─────────────────────────────────────────────────────────────┘

使用场景

典型问题场景：

• 在创建 msModelSlim 适配器之前，评估模型适配的可行性
• 分析模型结构和类型分类
• 评估 MoE 量化兼容性
• 确定是否可以使用 msModelSlim 量化模型
• 在开发适配器之前识别潜在风险

典型用户表述：

• “分析我的模型与 msModelSlim 的兼容性”
• “检查这个模型是否可以量化”
• “评估 MoE 融合权重风险”
• “评估模型适配的可行性”
• “分析模型结构以进行量化”
• “AnalysisModelmsModelSlim”
• “ModelQuantization”
• “CheckMoE”

范围

支持：

• 仅解码器 LLM
• VLM 文本主干分析（仅限 LLM/文本路径）

不支持：

• 非 Transformers 实现
• 多模态生成模型（图像/视频/音频生成）

必需输入

• 模型路径或模型仓库标识符

• config.json

• 可选：模型目录中的 modeling_*.py、model.safetensors.index.json

• 如果本地缺少文件：

  • 使用以下命令下载非权重文件： modelscope download --model <org>/<model> --local_dir ./models/<name> --exclude '*.safetensors'
  • 从下载目录读取 config.json 和 modeling_*.py，作为分析输入。

硬性要求：先解析实现源码

必须在进行任何结构分析之前完成。Agent 应手动按以下步骤解析：

1. 读取 config.json：

   • 获取 model_type
   • 获取 auto_map（如果存在）

2. 尝试从 Transformers 中解析：

   • 检查 transformers 库是否支持该 model_type。
   • 检查路径是否存在： transformers/models/<model_type>/modeling_<model_type>.py。
   • 如果存在，记录为 transformers 实现。

3. 如果未解析到，尝试模型本地实现：

   • 检查 auto_map 指向的文件是否存在于模型目录中。
   • 检查模型目录中是否存在 modeling_*.py 文件。
   • 如果存在，记录为 model-local 实现。

4. 如果两种路径都不可用：

   • 停止分析。
   • 请用户提供可读取的模型实现代码。

最低工作流

1. 解析实现源码（上文列出的完整硬性要求）。

2. 确定模型类型、结构差异和连接关系：

   • 类型：纯 LLM / 多模态理解 / 多模态生成
   • 与常见的类 Qwen2 LLM 对比，记录特殊结构设计 （例如 MoE、非标准注意力、SSM/混合块、额外的头部 或并行分支）
   • 检查特殊结构的连接关系（位置、依赖、串行/并行/残差连接， 对骨干网络遍历的影响）

3. 识别结构特征：

   • 解码器层类、注意力/MLP 模块命名、forward 签名

4. 确定影响适配的特性：

   • 层遍历路径和顺序
   • 是否需要逐层加载
   • MoE 融合专家权重风险
   • 量化模型反量化脚本风险
   • MTP 结构的实现可用性和权重处理风险

5. 输出结构化分析结果（参见下方模板）。

6. 提供后续步骤：

   • 继续进行适配器创建工作流
   • 或阻止并说明用户需要提供什么

模型类型、结构差异和连接关系判定

（相对于常见的 Qwen2）

• 纯 LLM：仅输入文本词元，骨干网络是仅解码器语言模型。
• 多模态理解：包含视觉/音频编码器，但生成路径以文本骨干网络为中心；只能分析和适配文本部分。
• 多模态生成：核心目标是生成图像/视频/音频；当前工作流不支持，应直接阻止并说明原因。
• 结构差异只需记录“是否存在 + 影响方向”，无需深入实现细节。
• 连接关系至少应记录：特殊结构位于骨干网络的哪个阶段、连接了哪些模块、连接类型（串行/并行/残差），以及对遍历/前向对齐的影响。

MoE 布局判定

• 非融合 MoE：专家以模块/列表形式展开（通常每个专家都有自己的 gate/up/down 线性层）。
• 融合 MoE：多个专家的权重打包为张量参数，不再是独立的线性层。
• 如果 gate/up/down 中任何一项以 [..., num_experts, ...] 或 [num_experts, ...] 的形式存储，则视为“融合”。
• 三维专家权重（例如 gate/up/down 各自融合为 3D 参数）统一归类为 MoE fused，并在报告中标注“可能需要拆包”。

必需输出：分析报告

Agent 应直接生成分析报告（Markdown 格式），且必须包含以下要素。参见下方模板：

# Analysis Report

## Model Identification
- Model Path/Repository: {model_path}
- `model_type`: {model_type}
- `architectures`: {architectures}

## Implementation Source Analysis
- Result: `transformers` | `model-local` | `unsupported`
- Basis:
  - Resolved file path: {path}
  - Related configuration fields (`model_type`, `auto_map`): {details}

## Model Features and Specifications
- Hidden size: {hidden_size}
- Number of layers: {num_layers}
- Attention heads / KV heads: {num_heads} / {num_kv_heads}
- Analyze only VLM text portion: Yes/No

## Model Type, Structural Differences and Connections
- Model type: Pure LLM | Multimodal understanding | Multimodal generation
- Special structures vs common Qwen2: {special_structures}
- Special structure connections: {special_structure_connections}
- Impact on adaptation workflow: {structure_impact}

## Layer-by-Layer Loading Assessment
- Need layer-by-layer loading: Yes/No
- Reason: {reason}
- Constraints (memory/runtime environment): {constraints}

## MoE Assessment
- Contains MoE: Yes/No
- Layout type: No MoE | Non-fused MoE | Fused MoE
- Suspected fused keys/modules: {keys}
- Expert weight form: Independent linear layers | Packaged tensors
- Needs unpack: Yes/No

## Adaptation Impact Points
- Decoder traversal path: {traversal_path}
- Attention module naming: {attn_module}
- MLP module naming: {mlp_module}
- `visit/forward` strict alignment points: {alignment_points}

## Quantization and MTP Risk Assessment
- Model already quantized: Yes/No
- Quantization determination basis: {quant_evidence}
- Dequantization script provided: Yes/No
- Dequantization script status: {dequant_status}
- MTP structure exists: Yes/No
- MTP implementation code accessibility: Accessible/Not accessible
- MTP risk description: {mtp_risk}

## Risks and Next Steps
- Risk level: Low | Medium | High
- Blockers: {blockers}
- Recommended next steps:
  - Proceed to adapter creation workflow
  - Or request user to provide implementation code

风险识别与用户沟通要求（强制）

• 如果识别为“模型已量化”，必须将“缺少反量化脚本”标记为阻塞项，并明确要求用户主动提供反量化脚本，然后才能继续适配。

• 如果识别到 MTP 结构，但无法访问其实现代码，必须明确告知：

  • Agent 可能无法完整实现 MTP 结构适配；
  • 要继续操作，用户需要自行复制 MTP 相关权重（根据用户侧实现进行映射）。

• 如果命中上述两种风险类型中的至少一种，risk level 不得低于“Medium”。

通过/失败标准

• 通过：实现源码为 transformers 或 model-local，模型类型为纯 LLM 或多模态理解，且报告完整；如果存在量化/MTP 风险，报告中已明确说明用户需要采取的行动。
• 失败：未能解析源码、不支持的实现类型、判定为多模态生成模型，或命中“已量化模型但缺少反量化脚本”的阻塞条件。

增强功能

自动兼容性检查器

此技能包含一个自动模型兼容性检查器，可在迁移前扫描模型架构：

功能：

• 迁移阻碍项检测：识别不受支持的算子、自定义层和框架专属功能
• 早期预警系统：针对已知问题提供早期预警和建议的解决方法
• 兼容性评分：生成兼容性评分并提供详细分析
• 算子覆盖率分析：报告 Ascend NPU 的算子支持覆盖率

兼容性检查类别：

类别	检查项
算子支持	Transformer 层、注意力、归一化
框架功能	自定义算子、动态形状、控制流
权重格式	Safetensors、PyTorch、HF 格式兼容性
特殊结构	MoE、MTP、混合架构

输出格式：

## Compatibility Check Result
- Overall Score: XX/100
- Passed: X/XX checks
- Warning: X items require attention
- Blockers: X items preventing migration

### Detailed Results
| Check Item        | Status     | Details                           |
|-------------------|------------|-----------------------------------|
| Operator coverage | ✓ Pass     | 95% of operators supported         |
| Custom layers     | ⚠️ Warning | 2 custom ops need AscendC impl    |
| Weight format     | ✓ Pass     | Standard Hugging Face format      |

参考文档

• 分析检查清单 - 分析验证检查清单
• 验收标准 - 功能验收标准
• 验证方法 - 验证方法
• 故障排查 - 常见问题及解决方案

前置条件

• 已安装 transformers >= 4.40.0
• 可供分析的模型代码
• 对模型结构有基本了解

分析工作流

分析工作流包括以下步骤：

1. 解析模型配置（config.json）
2. 确定实现来源（transformers 或模型本地代码）
3. 分析模型架构和结构特性
4. 评估 MoE 布局和融合权重风险
5. 生成结构化分析报告
6. 提供适配建议

参数参考

参数	描述	必需
model	模型名称或路径	是
output	分析报告输出路径	否
detailed	输出详细信息	否