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 の融合重みのリスクを評価してください」
• 「モデルを適応できるか評価してください」
• 「量子化に向けてモデル構造を分析してください」
• 「モデルを msModelSlim で分析」
• 「モデルを量子化」
• 「MoE を確認」

対象範囲

サポート対象：

• デコーダーのみの 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 を読み込み、分析の入力として使用します。

必須要件：まず実装ソースを解析する

構造分析を始める前に、必ず完了してください。エージェントは以下の手順を手動で解析してください。

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：テキストトークンのみを入力し、バックボーンはデコーダーのみの言語モデルです。
• マルチモーダル理解：ビジョン／オーディオエンコーダーを含みますが、生成経路の中心はテキストバックボーンです。分析と適応の対象にできるのはテキスト部分のみです。
• マルチモーダル生成：画像／動画／音声の生成が主な目的です。現在のワークフローではサポートされていないため、処理を停止し、理由を直接説明してください。
• 構造上の違いは、「存在の有無＋影響の方向」を記録するだけでよく、実装の詳細を掘り下げる必要はありません。
• 接続関係では、少なくとも特殊構造がバックボーンのどの段階にあるか、どのモジュールに接続するか、接続の種類（直列／並列／残差）、走査／forward の整合性への影響を記録してください。

MoE レイアウトの判断

• 非融合 MoE：エキスパートがモジュール／リストとして展開されます（一般に、各エキスパートは独自の gate/up/down 線形レイヤーを持ちます）。
• 融合 MoE：複数のエキスパートの重みがテンソルパラメーターとしてまとめられており、個別の線形レイヤーではなくなっています。
• gate/up/down のいずれかが [..., num_experts, ...] または [num_experts, ...] の形式で格納されている場合は、「融合」として扱ってください。
• 3 次元のエキスパート重み（例：gate/up/down がそれぞれ 3 次元パラメーターに融合されている場合）は、すべて MoE fused に分類し、レポートに「展開が必要な場合あり」と明記してください。

必須の出力：分析レポート

エージェントは分析レポートを直接生成してください（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 構造が特定されたものの実装コードにアクセスできない場合、次の内容を明確に伝える必要があります。

  • エージェントは MTP 構造の適応を完全には実装できない可能性があります。
  • 続行するには、ユーザー自身が MTP 関連の重みをコピーする必要があります（ユーザー側の実装に合わせてマッピングしてください）。

• 上記 2 種類のリスクのうち少なくとも 1 つに該当する場合、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	詳細情報を出力するかどうか	いいえ