MindStudio ModelSlim 使用指南
1. 功能概述
MindStudio ModelSlim（msModelSlim） 是昇腾生态下的高性能模型压缩工具，支持稠密 LLM、MoE 及多模态模型的量化与压缩，开发者可通过命令行与配置快速调优并导出适配 MindIE、vLLM-Ascend 等框架的模型，在昇腾 AI 处理器上高效部署。
本目录文档分为业务流程指南与工具使用指南两类，可根据实际需求选择查阅。
业务流程指南
| 功能模块 | 说明 | 适用场景 |
|---|---|---|
| 新模型量化调优流程 | 量化方案设计 → 权重量化 → 算子与组图 → 测评 → 发布；不达标则修订方案再闭环 | 新模型或目标量化模式未验证，需从方案做到发布 |
| 精度调优方法 | 系统化调优手段：离群值抑制、量化策略、校准集与回退 | 精度不达标时的人工调优路径 |
| 主流模型量化部署 | 端到端指引：获取量化权重、部署推理服务、精度测评与在线监控 | 已获得量化权重、需要部署上线的场景 |
| 量化推理精度异常定位 | 按「理解输入输出格式 → logprobs 确认 → 控制实验 → 激活值逐层对比」定位输出异常来源 | 量化后 badcase 增多、输出异常、无法对齐浮点输出 |
工具使用指南
| 功能模块 | 说明 | 适用场景 |
|---|---|---|
| 一键量化 | 集成主流大模型量化最佳实践，支持多种量化算法与导出格式，开箱即用 | 推荐首选，适用于支持一键量化的模型 |
| 权重量化 | 从下载浮点模型、模型适配、编写配置、执行量化到交付件校验 | 未收录于支持矩阵，或目标量化模式尚未验证的 LLM / 多模态理解 / 多模态生成模型 |
| 敏感层分析 | 按 linear / layer / attn scope 分析敏感层并改写量化配置 |
线性层回退、整块回退、FA 量化方案设计与精度调优 |
| 自动调优 | 根据精度目标自动迭代搜索量化配置，全流程自动化 | 精度不达标时无需人工反复调参 |
| 调试模式 | 保存量化过程上下文，便于排查问题与算法分析 | 问题定位、算法研究 |
| 一键量化使用指南 | 从模型支持确认到交付件校验的完整使用流程，逐步讲解 msmodelslim quant 命令各参数 |
首次使用一键量化的用户 |
2. 业务流程指南
2.1 新模型量化调优流程
新模型或目标量化模式未验证时，按「量化方案设计 → 权重量化 → 算子开发与组图 → 精度/性能测评 → 权重发布」主路径推进。测评不达标则进入量化方案修订，再回到权重量化继续闭环，直至发布。
详细过程请参见《新模型量化调优流程》。
2.2 精度调优方法
当量化精度未达预期时，可按「确认精度问题可信 → 调整离群值抑制 → 调整量化策略 → 调整校准集 → 量化回退」的递进路径进行系统调优。
详细方法请参见《量化精度调优指南》。
2.3 主流模型量化部署
从量化权重出发，按「获取量化权重 → 部署推理服务 → 精度测评 → 在线监控」的步骤完成量化模型的上线交付，建立测评基线并持续观测资源使用情况。
详细方法请参见《主流模型量化部署流程指南》。
2.4 量化推理精度异常定位
当量化模型出现 badcase、输出异常或无法对齐浮点输出时，按「理解输入输出格式 → logprobs 快速确认 → Completion API 控制实验 → 激活值逐层对比」从宏观到微观逐层收敛，定位输出异常来源并给出处置建议。
详细方法请参见《量化推理精度异常定位流程指南》。
3. 工具使用指南
3.1 一键量化
一键量化基于 msModelSlim 最佳实践库，自动匹配最优配置，并通过 YAML 自由组合量化流水线。除命令行参数外，还支持：
- 多种量化算法：离群值抑制、线性量化、KV Cache、FA3 等，算法总览与配置字段详见《量化算法说明》。
- 多种导出格式：AscendV1、compressed-tensors、MindIE-SD 等，格式选型与兼容性详见《量化格式》。
详细使用方法请参见《一键量化使用指南》。
3.2 权重量化
当目标模型（大语言模型、多模态理解或多模态生成）未收录于支持矩阵，或虽已收录但目标量化模式尚未验证时，按「下载浮点模型 → 完成模型适配 → 编写量化配置 → 执行量化 → 校验交付件」完成接入；各类别适配细节见对应接入指南。本流程以 msmodelslim quant 为统一入口产出可部署量化权重；部署与精度/性能测评属后续操作。
详细方法请参见《权重量化使用指南》。
3.3 敏感层分析
敏感层分析用于评估各层对量化的敏感程度。按分析范围（scope）分别推进「确认推荐指标 → 获取浮点权重 → 按需完成模型适配 → 执行分析命令 → 解读结果并改写 YAML」；少数指标若要求额外分析接口，按对应算法说明补齐。
按 scope 的操作过程请参见：
- 线性层敏感层分析使用指南（
scope=linear） - 层级敏感层分析使用指南（
scope=layer） - Attention 敏感层分析使用指南（
scope=attn）
3.4 自动调优
自动调优功能可根据精度目标自动迭代搜索最优量化配置，量化与评估全流程自动化，无需人工反复调参。
详细使用方法请参见《自动调优使用指南》。
3.5 调试模式
调试模式是一键量化的高级特性，启用后会在量化完成时保存过程上下文（中间结果、统计与张量信息等），便于问题排查与算法分析。
详细使用方法请参见《调试模式使用指南》。
3.6 一键量化使用指南
按「确认模型支持 → 下载浮点模型 → 确定量化方案与场景标签 → 执行一键量化 → 校验交付件」的步骤完成权重量化交付，msmodelslim quant 命令的每个参数一个步骤逐步讲解。
详细使用方法请参见《一键量化使用指南》。