已合并
[Doc]优化资料文档：FAQ分类索引重构与README易用性提升 #851
LeeQT创建于 18 天前
[Doc]优化资料文档：FAQ分类索引重构与README易用性提升 #851
已合并
共 11 个文件变更+337-184
| @@ -92,7 +92,7 @@ repos: | |||
| 92 | hooks: | 92 | hooks: |
| 93 | - id: gitleaks-offline-scan | 93 | - id: gitleaks-offline-scan |
| 94 | name: Gitleaks Secret Scan(Local Binary) | 94 | name: Gitleaks Secret Scan(Local Binary) |
| 95 | - entry: bash -c 'if [ -f ./gitleaks.exe ]; then ./gitleaks.exe "$@"; else ./gitleaks "$@"; fi' -- | 95 | + entry: bash -c 'if [ -f ./gitleaks.exe ]; then ./gitleaks.exe "$@"; elif [ -f ./gitleaks ]; then ./gitleaks "$@"; elif command -v gitleaks >/dev/null 2>&1; then gitleaks "$@"; else echo "[gitleaks] binary not found, please put gitleaks(.exe) in repo root or PATH" >&2; exit 1; fi' -- |
| 96 | language: system | 96 | language: system |
| 97 | pass_filenames: true | 97 | pass_filenames: true |
| 98 | args: | 98 | args: |
| @@ -11,7 +11,6 @@ | |||
| 11 | [](./docs/zh/quick_start/quantization_quick_start.md) | 11 | [](./docs/zh/quick_start/quantization_quick_start.md) |
| 12 | [](https://deepwiki.com/Keithwwa/msmodelslim) | 12 | [](https://deepwiki.com/Keithwwa/msmodelslim) |
| 13 | [](https://zread.ai/mindstudio-docs/master) | 13 | [](https://zread.ai/mindstudio-docs/master) |
| 14 | - [](https://msmodelslim.readthedocs.io/zh-cn/latest/) | ||
| 15 | [](https://www.hiascend.com/cn/developer/software/mindstudio) | 14 | [](https://www.hiascend.com/cn/developer/software/mindstudio) |
| 16 | [](https://gitcode.com/Ascend/msmodelslim/issues/new) | 15 | [](https://gitcode.com/Ascend/msmodelslim/issues/new) |
| 17 | 16 | ||
| @@ -30,6 +29,11 @@ | |||
| 30 | 29 | ||
| 31 | - 新增对 Gemma4 Dense `gemma-4-31B-it`（W8A8）、Gemma4 MoE `gemma-4-26B-A4B-it`（W8A8）模型的量化支持 | 30 | - 新增对 Gemma4 Dense `gemma-4-31B-it`（W8A8）、Gemma4 MoE `gemma-4-26B-A4B-it`（W8A8）模型的量化支持 |
| 32 | 31 | ||
| 32 | +</span> | ||
| 33 | + | ||
| 34 | +<details> | ||
| 35 | +<summary>🗂️ 更多历史更新（点击展开）</summary> | ||
| 36 | + | ||
| 33 | 🔹 **[2026.07.07]** | 37 | 🔹 **[2026.07.07]** |
| 34 | 38 | ||
| 35 | - 新增对腾讯混元 `Hy3`（W8A8）模型的量化支持 | 39 | - 新增对腾讯混元 `Hy3`（W8A8）模型的量化支持 |
| @@ -44,108 +48,93 @@ | |||
| 44 | - 新增对 `DeepSeek-V4-Flash`（W8A8）模型的量化支持 | 48 | - 新增对 `DeepSeek-V4-Flash`（W8A8）模型的量化支持 |
| 45 | - 新增对 `Kimi-K2.5`（W4A8）模型的量化支持 | 49 | - 新增对 `Kimi-K2.5`（W4A8）模型的量化支持 |
| 46 | 50 | ||
| 47 | -🔹 **[2026.03.01]** | 51 | +📄 更多历史更新记录，请参见《[最新消息](./docs/index.md)》。 |
| 48 | - | ||
| 49 | -- 新增对 `GLM-4.6V`（W8A8）模型的量化支持 | ||
| 50 | - | ||
| 51 | -</span> | ||
| 52 | - | ||
| 53 | -<details> | ||
| 54 | -<summary>🗂️ 历史更新（点击展开）</summary> | ||
| 55 | - | ||
| 56 | -**2026年2月** | ||
| 57 | - | ||
| 58 | -- msModelSlim 支持 Qwen3-Omni-30B-A3B-Thinking、Qwen3-Omni-30B-A3B-Instruct W8A8 量化 | ||
| 59 | -- msModelSlim 支持 Qwen2.5-Omni-7B W8A8 量化 | ||
| 60 | -- msModelSlim 支持 Qwen3.5-397B-A17B W8A8 量化 | ||
| 61 | -- msModelSlim 支持 GLM-5 W4A8 量化 | ||
| 62 | -- msModelSlim 优化一键量化场景推荐 | ||
| 63 | - | ||
| 64 | -**2026年1月** | ||
| 65 | - | ||
| 66 | -- msModelSlim 支持 Qwen3-VL-32B-Instruct W8A8 量化 | ||
| 67 | - | ||
| 68 | -**2025年12月** | ||
| 69 | - | ||
| 70 | -- msModelSlim 支持量化精度反馈自动调优，可根据精度需求自动搜索最优量化配置 | ||
| 71 | -- msModelSlim 支持自主量化多模态理解模型，支持多模态理解模型的量化接入 | ||
| 72 | -- msModelSlim 一键量化支持多卡量化，支持分布式逐层量化，提升大模型量化效率 | ||
| 73 | -- msModelSlim 支持 DeepSeek-V3.2 W8A8 量化，单卡 64GB 显存、100GB 内存即可执行 | ||
| 74 | -- msModelSlim 支持 DeepSeek-V3.2-Exp W4A8 量化，单卡 64GB 显存、100GB 内存即可执行 | ||
| 75 | -- msModelSlim 支持 Qwen3-VL-235B-A22B W8A8 量化 | ||
| 76 | - | ||
| 77 | -**2025年11月** | ||
| 78 | - | ||
| 79 | -- msModelSlim 模型适配支持插件化和配置注册，支持依赖预检 | ||
| 80 | - | ||
| 81 | -**2025年10月** | ||
| 82 | - | ||
| 83 | -- msModelSlim 支持 Qwen3-235B-A22B W4A8、Qwen3-30B-A3B W4A8 量化，vLLM-Ascend 已支持量化模型推理部署 | ||
| 84 | - | ||
| 85 | -**2025年9月** | ||
| 86 | - | ||
| 87 | -- msModelSlim 支持 DeepSeek-V3.2-Exp W8A8 量化，单卡 64GB 显存、100GB 内存即可执行 | ||
| 88 | -- msModelSlim 现已解决Qwen3-235B-A22B在 W8A8 量化下频繁出现"游戏副本"等异常token的问题 | ||
| 89 | -- msModelSlim 支持 DeepSeek R1 W4A8 per-channel 量化【Prototype】 | ||
| 90 | -- msModelSlim 支持大模型量化敏感层分析 | ||
| 91 | - | ||
| 92 | -**2025年8月** | ||
| 93 | - | ||
| 94 | -- msModelSlim 支持 Wan2.1 模型一键量化 | ||
| 95 | -- msModelSlim 支持大模型逐层量化，显著降低大模型量化内存占用 | ||
| 96 | -- msModelSlim 支持大模型 SSZ 权重量化算法，通过迭代搜索最优缩放因子和偏移量提升量化精度 | ||
| 97 | 52 | ||
| 98 | </details> | 53 | </details> |
| 99 | 54 | ||
| 55 | +--- | ||
| 56 | + | ||
| 100 | ## ℹ️ 简介 | 57 | ## ℹ️ 简介 |
| 101 | 58 | ||
| 102 | -**MindStudio ModelSlim（msModelSlim）** 是昇腾生态下的高性能模型压缩工具，支持稠密LLM、MoE及多模态模型的量化与压缩，开发者可通过 msModelSlim 工具快速调优并导出适配 MindIE、vLLM-Ascend 等框架的模型，在昇腾AI处理器上实现高效部署。 | 59 | +**MindStudio ModelSlim（msModelSlim）** 是昇腾生态下的高性能模型压缩工具，支持稠密LLM、MoE及多模态模型的量化与压缩。开发者可通过命令行与配置快速调优并导出适配 MindIE、vLLM-Ascend 等框架的模型，在昇腾AI处理器上高效部署。 |
| 103 | 60 | ||
| 104 | -## ⚙️ 功能介绍 | 61 | +**它能为你带来什么：** |
| 105 | 62 | ||
| 106 | -| 功能名称 | 功能描述 | | 63 | +- 🚀 **推理加速**：量化后显著降低显存占用，提升推理吞吐与部署成本效率（例如 Qwen3.6-27B 模型原始权重50+GB，量化后30+GB，显存节约40%）。 |
| 107 | -|---------|--------| | 64 | +- 🎯 **开箱即用**：集成主流大模型量化最佳实践，`msmodelslim quant` 一条命令完成量化。 |
| 108 | -| **一键量化** | 集成主流大模型量化最佳实践，支持 W4A8、W8A8、W8A16 等多种量化类型，自动匹配最优配置，开箱即用。 | | 65 | +- 🔧 **精度可控**：提供敏感层分析、自动调优与精度反馈闭环，量化精度可量化、可调优。 |
| 109 | -| **自主量化** | 提供标准接入框架，支持开发者将自有 LLM 及多模态模型快速集成至一键量化流程。 | | 66 | +- 🧩 **生态友好**：导出的量化权重无缝接入 vLLM-Ascend 等主流推理框架。 |
| 110 | -| **敏感层分析** | 多维度评估各层量化敏感度，精准定位应回退或提位宽的层，为量化配置调优提供数据支撑。 | | ||
| 111 | -| **自动调优** | 根据精度目标自动迭代搜索量化配置，量化与评估全流程自动化，无需人工反复调参。 | | ||
| 112 | -| **权重转换** | 无需校准集，离线对已有量化权重做格式与精度变换（如 FP8→BF16、BF16→MXFP8）。 | | ||
| 113 | 67 | ||
| 114 | -> **模型支持情况概览**：各功能所适配的模型及其量化类型详见《[模型支持矩阵](./docs/zh/knowledge_base/model/README.md)》。 | 68 | +--- |
| 115 | 69 | ||
| 116 | -## 🚀 快速入门 | 70 | +## 🚀 快速开始 |
| 117 | 71 | ||
| 118 | -帮助用户快速完成大模型量化功能，请参见《[msModelSlim 快速入门](./docs/zh/quick_start/quantization_quick_start.md)》。 | 72 | +**手把手教你完成端到端模型量化**，请参见《[快速入门](./docs/zh/quick_start/quantization_quick_start.md)》： |
| 73 | + | ||
| 74 | +--- | ||
| 119 | 75 | ||
| 120 | ## 📦 安装指南 | 76 | ## 📦 安装指南 |
| 121 | 77 | ||
| 122 | -介绍工具的环境依赖与安装方法，请参见《[msModelSlim 安装指南](./docs/zh/install_guide/install_guide.md)》。 | 78 | +msModelSlim已发布到PyPI，可通过pip直接安装。 |
| 79 | + | ||
| 80 | +```bash | ||
| 81 | +# 安装 msModelSlim（最新版本已更新到PyPI源） | ||
| 82 | +pip install msmodelslim | ||
| 83 | + | ||
| 84 | +# 验证安装：打印命令行帮助信息即表示安装成功 | ||
| 85 | +msmodelslim --help | ||
| 86 | +``` | ||
| 87 | + | ||
| 88 | +> 更多安装方式，请参见《[安装指南](./docs/zh/install_guide/install_guide.md)》。 | ||
| 89 | + | ||
| 90 | +--- | ||
| 123 | 91 | ||
| 124 | ## 📘 使用指南 | 92 | ## 📘 使用指南 |
R | |||
| 125 | 93 | ||
| 126 | -工具的详细使用方法，请参见《[msModelSlim 使用指南](./docs/zh/user_guide/README.md)》。 | 94 | +**想了解msModelSlim如何使用？** 可按需选择入口： |
| 95 | + | ||
| 96 | +| 业务流程 | 对应工具/功能 | | ||
| 97 | +|---------|--------------| | ||
| 98 | +| 《[新模型量化调优流程](./docs/zh/user_guide/process_new_model_quantization_tuning.md)》 | [权重量化](./docs/zh/user_guide/usage_weight_quantization.md)、[敏感层分析](./docs/zh/user_guide/usage_sensitive_linear_analysis.md) | | ||
| 99 | +| 《[精度调优方法](./docs/zh/user_guide/process_quantization_precision_tuning.md)》 | [敏感层分析](./docs/zh/user_guide/usage_sensitive_linear_analysis.md)、[自动调优](./docs/zh/user_guide/usage_auto_precision_tuning.md)、[调试模式](./docs/zh/user_guide/usage_debug_mode.md) | | ||
| 100 | +| 《[主流模型量化部署](./docs/zh/user_guide/process_mainstream_model_deployment.md)》 | [一键量化](./docs/zh/user_guide/usage_quick_quantization.md) | | ||
| 101 | +| 《[量化推理精度异常定位](./docs/zh/user_guide/process_quantization_accuracy_anomaly_locating.md)》 | [调试模式](./docs/zh/user_guide/usage_debug_mode.md) | | ||
| 102 | + | ||
| 103 | +> 更多使用指南，请参见《[使用指南](./docs/zh/user_guide/README.md)》。 | ||
| 104 | + | ||
| 105 | +--- | ||
| 127 | 106 | ||
| 128 | ## 📚 知识库 | 107 | ## 📚 知识库 |
| 129 | 108 | ||
| 130 | -工具相关的术语和概念，请参见《[推理加速知识库](./docs/zh/knowledge_base/README.md)》。 | 109 | +**不懂 `W4A8`/`W8A8` 等量化术语？** 请参见《[推理加速知识库](./docs/zh/knowledge_base/README.md)》。 |
| 110 | + | ||
| 111 | +--- | ||
| 131 | 112 | ||
| 132 | ## 💡 典型案例 | 113 | ## 💡 典型案例 |
| 133 | 114 | ||
| 134 | -通过典型问题场景帮助用户理解并掌握工具使用，请参见《[msModelSlim 典型案例](./docs/zh/best_practices/README.md)》。 | 115 | +**需要模型量化调优的典型场景？** 请参见《[msModelSlim 典型案例](./docs/zh/best_practices/README.md)》。 |
| 116 | + | ||
| 117 | +--- | ||
| 135 | 118 | ||
| 136 | ## ❓ FAQ | 119 | ## ❓ FAQ |
| 137 | 120 | ||
| 138 | -常见问题及解决方案，请参见《[FAQ](./docs/zh/support/faq.md)》。 | 121 | +**遇到了问题？** 请参见《[FAQ](./docs/zh/support/faq.md)》。 |
| 122 | + | ||
| 123 | +--- | ||
| 139 | 124 | ||
| 140 | ## 🌌 智能检索 | 125 | ## 🌌 智能检索 |
| 141 | 126 | ||
| 142 | 为提升文档查阅效率，我们提供多种高效检索方式：<br> | 127 | 为提升文档查阅效率，我们提供多种高效检索方式：<br> |
| 128 | +🔹 [AI 智能体（msagent）](https://gitcode.com/Ascend/msagent/blob/master/docs/zh/agent_guide/Quantizer.md)：msModelSlim 量化能力已集成至 msagent 智能体，通过自然语言交互即可自动完成模型量化任务。<br> | ||
| 143 | 🔹 [AI 问答（DeepWiki）](https://deepwiki.com/Keithwwa/msmodelslim)：自然语言问答，快速把握项目架构与模块关系。<br> | 129 | 🔹 [AI 问答（DeepWiki）](https://deepwiki.com/Keithwwa/msmodelslim)：自然语言问答，快速把握项目架构与模块关系。<br> |
| 144 | -🔹 [精确搜索（ReadTheDocs）](https://msmodelslim.readthedocs.io/zh-cn/latest/)：关键词全文检索，直达接口、参数与报错等信息。<br> | 130 | + |
| 131 | +--- | ||
| 145 | 132 | ||
| 146 | ## 🛠️ 贡献指南 | 133 | ## 🛠️ 贡献指南 |
| 147 | 134 | ||
| 148 | -具体请参见《[贡献指南](./docs/zh/contributing/contributing_guide.md)》。 | 135 | +**想要贡献力量？** 具体请参见《[贡献指南](./docs/zh/contributing/contributing_guide.md)》。 |
| 136 | + | ||
| 137 | +--- | ||
| 149 | 138 | ||
| 150 | ## ⚖️ 相关说明 | 139 | ## ⚖️ 相关说明 |
| 151 | 140 | ||
| @@ -154,14 +143,18 @@ | |||
| 154 | 🔹 《[安全声明](docs/zh/legal/SECURITY.md)》<br> | 143 | 🔹 《[安全声明](docs/zh/legal/SECURITY.md)》<br> |
| 155 | 🔹 《[免责声明](docs/zh/legal/disclaimer.md)》<br> | 144 | 🔹 《[免责声明](docs/zh/legal/disclaimer.md)》<br> |
| 156 | 145 | ||
| 146 | +--- | ||
| 147 | + | ||
| 157 | ## 🤝 建议与交流 | 148 | ## 🤝 建议与交流 |
| 158 | 149 | ||
| 159 | 欢迎大家为社区做贡献。如果有任何疑问或建议，请提交 [Issues](https://gitcode.com/Ascend/msmodelslim/issues)，我们会尽快回复。感谢您的支持。 | 150 | 欢迎大家为社区做贡献。如果有任何疑问或建议，请提交 [Issues](https://gitcode.com/Ascend/msmodelslim/issues)，我们会尽快回复。感谢您的支持。 |
| 160 | 151 | ||
| 161 | | 即时互动（微信群） | 官方资讯（公众号） | 深度支持（助手/论坛） | | 152 | | 即时互动（微信群） | 官方资讯（公众号） | 深度支持（助手/论坛） | |
| 162 | -|:----------------------------------------------------------------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 153 | +|:----------------------------------------------------------------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 163 | | <img src="https://raw.gitcode.com/Ascend/docs/files/master/common/Writing_Template/figures/qr_code_wechat_work.png" width="120"><br><sub>*扫码加入技术交流群*</sub> | <img src="https://raw.gitcode.com/Ascend/docs/files/master/common/Writing_Template/figures/qr_code_wechat_official_account.png" width="120"><br><sub>*扫码关注官方公众号*</sub> | 扫码入群并关注公众号，直达 MindStudio 用户与开发者最快捷的交流平台：<br> **快速提问：** 与社区小伙伴即时探讨技术问题<br>**掌握动态：** 第一时间获取版本发布与功能更新通知<br> **经验共享：** 与广大开发者交流最佳实践与实战心得 <br> <br> **更多支持渠道**：👉 昇腾助手：[](https://gitcode.com/Ascend/msit/blob/master/docs/zh/figures/readme/xiaozhushou.png) 👉 昇腾论坛：[](https://www.hiascend.com/forum/) | | 154 | | <img src="https://raw.gitcode.com/Ascend/docs/files/master/common/Writing_Template/figures/qr_code_wechat_work.png" width="120"><br><sub>*扫码加入技术交流群*</sub> | <img src="https://raw.gitcode.com/Ascend/docs/files/master/common/Writing_Template/figures/qr_code_wechat_official_account.png" width="120"><br><sub>*扫码关注官方公众号*</sub> | 扫码入群并关注公众号，直达 MindStudio 用户与开发者最快捷的交流平台：<br> **快速提问：** 与社区小伙伴即时探讨技术问题<br>**掌握动态：** 第一时间获取版本发布与功能更新通知<br> **经验共享：** 与广大开发者交流最佳实践与实战心得 <br> <br> **更多支持渠道**：👉 昇腾助手：[](https://gitcode.com/Ascend/msit/blob/master/docs/zh/figures/readme/xiaozhushou.png) 👉 昇腾论坛：[](https://www.hiascend.com/forum/) | |
| 164 | 155 | ||
| 156 | +--- | ||
| 157 | + | ||
| 165 | ## 🙏 致谢 | 158 | ## 🙏 致谢 |
| 166 | 159 | ||
| 167 | 本工具由华为公司的下列部门联合贡献：<br> | 160 | 本工具由华为公司的下列部门联合贡献：<br> |
| @@ -1,4 +1,4 @@ | |||
| 1 | -# 欢迎来到 msModelSlim | 1 | +# 欢迎来到 msModelSlim |
| 2 | 2 | ||
| 3 | <p align="center"> | 3 | <p align="center"> |
| 4 | <img src="assets/modelslim_slogan.png" alt="ModelSlim Slogan" width="340" /> | 4 | <img src="assets/modelslim_slogan.png" alt="ModelSlim Slogan" width="340" /> |
| @@ -10,9 +10,10 @@ MindStudio ModelSlim（昇腾模型压缩工具，msModelSlim），一个以加 | |||
| 10 | 10 | ||
| 11 | ## :star: 核心优势 | 11 | ## :star: 核心优势 |
| 12 | 12 | ||
| 13 | -* **高效压缩** :package: —— 支持多种量化算法，显著降低显存占用。 | 13 | +- 🚀 **推理加速**：量化后显著降低显存占用，提升推理吞吐与部署成本效率（例如 DeepSeek-V3.2 单卡 64GB 显存、100GB 内存即可完成 W8A8 量化）。 |
R 【review】“例如 DeepSeek-V3.2 单卡 64GB 显存、100GB 内存即可完成 W8A8 量化”并不是推理加速的体现，而是工具本身的低消耗能力，可以在资源受限的场景下完成量化。   | |||
| 14 | -* **昇腾亲和** :gear: —— 深度适配昇腾硬件，确保最佳推理性能。 | 14 | +- 🎯 **开箱即用**：集成主流大模型量化最佳实践，`msmodelslim quant` 一条命令完成量化。 |
| 15 | -* **简单易用** :magic_wand: —— 丰富的模型最佳实践库，快速实现模型优化。 | 15 | +- 🔧 **精度可控**：提供敏感层分析、自动调优与精度反馈闭环，量化精度可量化、可调优。 |
| 16 | +- 🧩 **生态友好**：导出的量化权重无缝接入 vLLM-Ascend 等主流推理框架。 | ||
| 16 | 17 | ||
| 17 | ## :loudspeaker: 最新消息 | 18 | ## :loudspeaker: 最新消息 |
| 18 | 19 | ||
| @@ -25,8 +25,7 @@ msmodelslim quant --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --device n | |||
| 25 | 25 | ||
| 26 | ## 大语言模型支持列表 | 26 | ## 大语言模型支持列表 |
| 27 | 27 | ||
| 28 | -!!! info "提示" | 28 | +> **提示**：下表内容较多，若显示不全，您可以**按住鼠标滚轮**或使用**底部滚动条**左右拖动查看。 |
| 29 | - 下表内容较多，若显示不全，您可以**按住鼠标滚轮**或使用**底部滚动条**左右拖动查看。 | ||
| 30 | 29 | ||
| 31 | <div class="custom-table"> | 30 | <div class="custom-table"> |
| 32 | 31 | ||
| @@ -1,114 +1,34 @@ | |||
| 1 | +--- | ||
| 2 | +title: FAQ 总览（索引） | ||
| 3 | +description: msModelSlim 常见问题统一索引，按安装/运行/硬件/精度/部署/告警六类导航至对应 FAQ 子文档；本页不含具体问答。 | ||
| 4 | +keywords: [FAQ, 常见问题, 故障排查, 索引, Killed, pydantic, DT_BFLOAT16] | ||
| 5 | +--- | ||
| 6 | + | ||
| 1 | # FAQ | 7 | # FAQ |
| 2 | 8 | ||
| 3 | -## 1. 为什么我的程序会显示“Killed”并异常退出？ | 9 | +> 本文档为 msModelSlim 常见问题（FAQ）的统一索引。FAQ 按主题拆分为多篇子文档，便于 AI 检索与快速定位；具体问答内容请在对应分类文档中查阅。 |
| 4 | 10 | ||
| 5 | -在使用msModelSlim工具运行推理量化时，出现类似以下报错信息： | 11 | +## 分类索引 |
| 6 | 12 | ||
| 7 | -```text | 13 | +| 分类 | 覆盖问题 | 文档 | |
| 8 | -Killed | 14 | +|------|---------|------| |
| 9 | -... | 15 | +| 1. 安装与依赖 | pydantic 版本冲突、accelerate 依赖安装失败 | [faq_installation.md](./faq_installation.md) | |
| 10 | -[Error] TBE Subprocess[task_distribute] raise error[], main process disappeared! | 16 | +| 2. 运行与资源 | 进程 Killed、显存/内存不足（OOM） | [faq_runtime.md](./faq_runtime.md) | |
| 11 | -... | 17 | +| 3. 硬件兼容 | DT_BFLOAT16 不支持、InplaceIndexAdd 编译失败 | [faq_hardware.md](./faq_hardware.md) | |
| 12 | -``` | 18 | +| 4. 精度与调优 | 预留分类（精度调优、异常定位指引） | [faq_precision.md](./faq_precision.md) | |
| 19 | +| 5. 部署与推理 | 预留分类（MindIE / vLLM-Ascend 部署指引） | [faq_deployment.md](./faq_deployment.md) | | ||
| 20 | +| 6. 告警与提示 | DeprecationWarning 等告警处理 | [faq_warning.md](./faq_warning.md) | | ||
| 13 | 21 | ||
| 14 | -### 解决方法 | 22 | +## 检索指引 |
| 15 | 23 | ||
| 16 | -请先确认你的进程没有被其他用户kill或抢占同一个NPU资源。一般而言，如果不存在其他用户抢占系统资源的情况，那么可能就是NPU显存不足或系统内存不足导致。可通过以下命令查看系统日志、看管系统内存情况、清理系统内存。 | 24 | +- **按主题定位**：从上方分类索引进入对应子文档。 |
| 25 | +- **按关键词搜索**：直接使用关键词（如 `Killed`、`pydantic`、`DT_BFLOAT16`）在各子文档或全文检索中定位。 | ||
| 26 | +- **AI 检索**：各子文档头部均含 AI 可读元数据（`title` / `description` / `keywords`），AI 可通过元数据快速判断文档相关性，减少全文读取带来的 token 开销。 | ||
| 17 | 27 | ||
| 18 | -```shell | 28 | +## 修订记录 |
| 19 | -# dmesg查看被内核终止的进程或显存不足终止的进程 | ||
| 20 | -dmesg | grep -A 3 -B 1 -i "killed process\|oom-kill" | ||
| 21 | 29 | ||
| 22 | -# 看管系统内存 | 30 | +| 日期 | 版本 | 变更说明 | |
| 23 | -watch free -h | 31 | +| --- | --- | --- | |
| 24 | - | 32 | +| 2026-08-17 | v2.1 | 精简各文档头部元数据：由 type/category/scope/related 收拢为 title/description/keywords 三字段，scope（排除域）并入 description，降低文档头冗余，保持 AI 检索与 token 优化能力。 | |
| 25 | -# 清理缓存和内存，部分场景可能需要sudo权限 | 33 | +| 2026-08-17 | v2.0 | 重构：FAQ 拆分为多篇分类子文档（安装/运行/硬件/精度/部署/告警），本文档改为统一索引；各子文档新增 AI 可读元数据头。 | |
| 26 | -sync && echo 3 > /proc/sys/vm/drop_caches | 34 | +| 2026-08-17 | v1.0 | 按《msModelSlim资料规范》重构：新增分类编号结构、统一条目三段式、补齐缩写全称与关联文档链接。 | |
| 27 | - | ||
| 28 | -# 停止所有python进程，部分场景可能需要sudo权限 | ||
| 29 | -pkill python | ||
| 30 | -``` | ||
| 31 | - | ||
| 32 | -## 2. 为什么安装时提示pydantic版本冲突？ | ||
| 33 | - | ||
| 34 | -msModelSlim依赖pydantic>=2.10.1，请确保环境中的pydantic版本满足此要求。 | ||
| 35 | - | ||
| 36 | -### pip安装时的错误信息 | ||
| 37 | - | ||
| 38 | -```text | ||
| 39 | -ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts. | ||
| 40 | -check-wheel-contents 0.6.0 requires pydantic~=2.0, but you have pydantic 1.0 which is incompatible. | ||
| 41 | -``` | ||
| 42 | - | ||
| 43 | -### 解决方法 | ||
| 44 | - | ||
| 45 | -请尝试升级pydantic或卸载环境中依赖低版本pydantic的其他软件包，直至环境无版本冲突。 | ||
| 46 | - | ||
| 47 | -## 3. 为什么安装msModelSlim报错？ | ||
| 48 | - | ||
| 49 | -### 3.1 自动安装accelerate依赖库时报错 | ||
| 50 | - | ||
| 51 | -msModelSlim依赖accelerate库来支持多卡运行，因此将其写入requirements.txt，在安装时通过pip自动下载accelerate。 | ||
| 52 | - | ||
| 53 | -第一种已知原因是部分 Python 3.8 环境与accelerate冲突，报错信息如下： | ||
| 54 | - | ||
| 55 | -```text | ||
| 56 | -ERROR: Could not find a version that satisfies the requirement puccinialin (from versions: none) | ||
| 57 | -``` | ||
| 58 | - | ||
| 59 | -此时，可尝试升级Python环境至 Python 3.9 及以上版本 | ||
| 60 | - | ||
| 61 | -如果您的环境已升级至 Python 3.9 或以上版本，但仍然出现报错，可能是由于os版本过低，导致安装 `huggingface_hub` 的子依赖失败，报错信息如下： | ||
| 62 | - | ||
| 63 | -```text | ||
| 64 | -error: subprocess-exited-with-error | ||
| 65 | -``` | ||
| 66 | - | ||
| 67 | -此时可尝试升级os版本，或通过以下命令进行规避： | ||
| 68 | - | ||
| 69 | -```bash | ||
| 70 | -pip install "huggingface_hub==0.20.3" | ||
| 71 | -pip install accelerate | ||
| 72 | -``` | ||
| 73 | - | ||
| 74 | -请注意，`huggingface_hub==0.20.3`非`accelerate`官方推荐版本，可能会引发其他兼容性问题。因此，该方案仅供参考，`msModelSlim`对由此带来的问题不承担相应责任。 | ||
| 75 | - | ||
| 76 | -## 4. 为什么量化权重时出现报错**PTA call acl api failed. *** The param dtype not implemented for DT_BFLOAT16, should be in dtype support list [\*\*\*]** | ||
| 77 | - | ||
| 78 | -部分Ascend硬件（例如Atlas 300I/300T系列）只支持float16精度推理，如果模型权重采用`bfloat16`精度量化，可能会导致量化失败。 | ||
| 79 | - | ||
| 80 | -### 解决方法 | ||
| 81 | - | ||
| 82 | -修改模型权重路径下`config.json`中的`torch_dtype`为`float16`进行量化。 | ||
| 83 | - | ||
| 84 | -## 5. 为什么在300I/300T系列硬件上量化权重时会报错**RuntimeError: The Inner error is reported as above. The process exits for this inner error, and the current working operator name is InplaceIndexAdd.** | ||
| 85 | - | ||
| 86 | -### 问题原因 | ||
| 87 | - | ||
| 88 | -在300I/300T系列硬件上进行传统量化（V0）时，由于JIT编译模式与该系列硬件存在兼容性问题，导致`InplaceIndexAdd`算子编译失败，从而引发运行时错误。 | ||
| 89 | - | ||
| 90 | -### 解决方法 | ||
| 91 | - | ||
| 92 | -在传统量化（V0）模型量化脚本（`msmodelslim/example`路径下）中，添加`torch_npu.npu.set_compile_mode(jit_compile=False)`来禁用JIT编译模式。 | ||
| 93 | - | ||
| 94 | -**示例代码：** | ||
| 95 | - | ||
| 96 | -```python | ||
| 97 | -import torch_npu | ||
| 98 | - | ||
| 99 | -# 在量化脚本开头添加以下代码 | ||
| 100 | -torch_npu.npu.set_compile_mode(jit_compile=False) | ||
| 101 | - | ||
| 102 | -# 然后执行量化操作 | ||
| 103 | -# ... 后续的量化代码 | ||
| 104 | -``` | ||
| 105 | - | ||
| 106 | -## 6. 量化结束告警：**sys:1: DeprecationWarning: builtin type swigvarlink has no module attribute** | ||
| 107 | - | ||
| 108 | -### 问题原因 | ||
| 109 | - | ||
| 110 | -旧版 SWIG 生成的第三方库与 Python 3.10+ 不兼容。 | ||
| 111 | - | ||
| 112 | -### 解决方法 | ||
| 113 | - | ||
| 114 | -此告警不影响量化结果，升级触发该警告的第三方库即可消除（如 sentencepiece）。 | ||
| @@ -0,0 +1,15 @@ | |||
| 1 | +--- | ||
| 2 | +title: FAQ - 部署与推理（预留） | ||
| 3 | +description: 部署与推理 FAQ（暂无条目）；MindIE / vLLM-Ascend 部署问题请查阅《主流模型量化部署》。 | ||
| 4 | +keywords: [部署, 推理, MindIE, vLLM-Ascend, 上线] | ||
| 5 | +--- | ||
| 6 | + | ||
| 7 | +# 部署与推理 FAQ | ||
| 8 | + | ||
| 9 | +> 本节为预留分类，暂无 FAQ 条目。用于沉淀量化模型在 MindIE、vLLM-Ascend 等推理引擎部署与推理阶段的常见问题。 | ||
| 10 | + | ||
| 11 | +已获得量化权重、需要部署上线的场景，请参见： | ||
| 12 | + | ||
| 13 | +- 《[主流模型量化部署](../user_guide/process_mainstream_model_deployment.md)》 | ||
| 14 | + | ||
| 15 | +新增条目请按 1.x 顺序追加，并保持“问题现象 / 问题原因 / 解决方法 / 关联文档”的结构。 | ||
| @@ -0,0 +1,65 @@ | |||
| 1 | +--- | ||
| 2 | +title: FAQ - 硬件兼容 | ||
| 3 | +description: 硬件兼容类问题的原因与解决；不覆盖安装、运行、精度、部署问题。 | ||
| 4 | +keywords: [硬件, 兼容, Ascend, 300I, 300T, DT_BFLOAT16, float16, InplaceIndexAdd, JIT] | ||
| 5 | +--- | ||
| 6 | + | ||
| 7 | +# 硬件兼容 FAQ | ||
| 8 | + | ||
| 9 | +> 本节覆盖 msModelSlim 与 Ascend 硬件兼容性相关的常见问题。新增条目按 1.x 顺序追加，并保持“问题现象 / 问题原因 / 解决方法 / 关联文档”的结构。 | ||
| 10 | + | ||
| 11 | +## 1.1 为什么量化权重时出现报错“PTA call acl api failed... The param dtype not implemented for DT_BFLOAT16”？ | ||
| 12 | + | ||
| 13 | +### 问题现象 | ||
| 14 | + | ||
| 15 | +量化权重时报错： | ||
| 16 | + | ||
| 17 | +```text | ||
| 18 | +PTA call acl api failed. *** The param dtype not implemented for DT_BFLOAT16, should be in dtype support list [***] | ||
| 19 | +``` | ||
| 20 | + | ||
| 21 | +### 问题原因 | ||
| 22 | + | ||
| 23 | +部分Ascend硬件（例如Atlas 300I/300T系列）只支持float16精度推理，如果模型权重采用bfloat16（DT_BFLOAT16）精度量化，可能导致量化失败。 | ||
| 24 | + | ||
| 25 | +### 解决方法 | ||
| 26 | + | ||
| 27 | +修改模型权重路径下`config.json`中的`torch_dtype`为`float16`后进行量化。 | ||
| 28 | + | ||
| 29 | +### 关联文档 | ||
| 30 | + | ||
| 31 | +模型部署与量化产物使用请参见《[主流模型部署流程](../user_guide/process_mainstream_model_deployment.md)》。 | ||
| 32 | + | ||
| 33 | +## 1.2 为什么在300I/300T系列硬件上量化权重时会报错“RuntimeError: The Inner error is reported as above... InplaceIndexAdd”？ | ||
| 34 | + | ||
| 35 | +### 问题现象 | ||
| 36 | + | ||
| 37 | +在300I/300T系列硬件上量化权重时报错： | ||
| 38 | + | ||
| 39 | +```text | ||
| 40 | +RuntimeError: The Inner error is reported as above. The process exits for this inner error, and the current working operator name is InplaceIndexAdd. | ||
| 41 | +``` | ||
| 42 | + | ||
| 43 | +### 问题原因 | ||
| 44 | + | ||
| 45 | +在300I/300T系列硬件上进行传统量化（V0）时，JIT（Just-In-Time，即时编译）编译模式与该系列硬件存在兼容性问题，导致`InplaceIndexAdd`算子编译失败，从而引发运行时错误。 | ||
| 46 | + | ||
| 47 | +### 解决方法 | ||
| 48 | + | ||
| 49 | +在传统量化（V0）模型量化脚本（`msmodelslim/example`路径下）中添加`torch_npu.npu.set_compile_mode(jit_compile=False)`来禁用JIT编译模式。 | ||
| 50 | + | ||
| 51 | +**示例代码：** | ||
| 52 | + | ||
| 53 | +```python | ||
| 54 | +import torch_npu | ||
| 55 | + | ||
| 56 | +# 在量化脚本开头添加以下代码 | ||
| 57 | +torch_npu.npu.set_compile_mode(jit_compile=False) | ||
| 58 | + | ||
| 59 | +# 然后执行量化操作 | ||
| 60 | +# ... 后续的量化代码 | ||
| 61 | +``` | ||
| 62 | + | ||
| 63 | +### 关联文档 | ||
| 64 | + | ||
| 65 | +传统量化（V0）的使用说明请参见《[传统量化 V0 使用指南](../user_guide/traditional_quantization_v0/README.md)》。 | ||
| @@ -0,0 +1,69 @@ | |||
| 1 | +--- | ||
| 2 | +title: FAQ - 安装与依赖 | ||
| 3 | +description: 安装与依赖类问题的原因与解决；不覆盖运行、硬件、精度、部署问题。 | ||
| 4 | +keywords: [安装, pip, 依赖, pydantic, accelerate, 版本冲突, huggingface_hub] | ||
| 5 | +--- | ||
| 6 | + | ||
| 7 | +# 安装与依赖 FAQ | ||
| 8 | + | ||
| 9 | +> 本节覆盖 msModelSlim 安装与依赖相关的常见问题。新增条目按 1.x 顺序追加，并保持“问题现象 / 问题原因 / 解决方法 / 关联文档”的结构。 | ||
| 10 | + | ||
| 11 | +## 1.1 为什么安装时提示pydantic版本冲突？ | ||
| 12 | + | ||
| 13 | +### 问题现象 | ||
| 14 | + | ||
| 15 | +安装或使用时出现类似以下报错信息： | ||
| 16 | + | ||
| 17 | +```text | ||
| 18 | +ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts. | ||
| 19 | +check-wheel-contents 0.6.0 requires pydantic~=2.0, but you have pydantic 1.0 which is incompatible. | ||
| 20 | +``` | ||
| 21 | + | ||
| 22 | +### 问题原因 | ||
| 23 | + | ||
| 24 | +msModelSlim依赖pydantic>=2.10.1，当环境中已安装低版本pydantic时，会与其他依赖低版本pydantic的软件包产生版本冲突。 | ||
| 25 | + | ||
| 26 | +### 解决方法 | ||
| 27 | + | ||
| 28 | +升级pydantic至2.10.1及以上版本，或卸载环境中依赖低版本pydantic的其他软件包，直至环境无版本冲突。 | ||
| 29 | + | ||
| 30 | +### 关联文档 | ||
| 31 | + | ||
| 32 | +安装的具体步骤与依赖要求请参见《[安装指南](../install_guide/install_guide.md)》。 | ||
| 33 | + | ||
| 34 | +## 1.2 为什么安装msModelSlim报错？ | ||
| 35 | + | ||
| 36 | +### 问题现象 | ||
| 37 | + | ||
| 38 | +安装时自动安装accelerate依赖库报错，出现以下两类错误信息之一： | ||
| 39 | + | ||
| 40 | +```text | ||
| 41 | +ERROR: Could not find a version that satisfies the requirement puccinialin (from versions: none) | ||
| 42 | +``` | ||
| 43 | + | ||
| 44 | +或： | ||
| 45 | + | ||
| 46 | +```text | ||
| 47 | +error: subprocess-exited-with-error | ||
| 48 | +``` | ||
| 49 | + | ||
| 50 | +### 问题原因 | ||
| 51 | + | ||
| 52 | +- **第一种**：部分Python 3.8环境与accelerate冲突，导致依赖解析失败。 | ||
| 53 | +- **第二种**：环境已升级至Python 3.9及以上后仍报错，一般是操作系统版本过低，导致安装`huggingface_hub`的子依赖失败。 | ||
| 54 | + | ||
| 55 | +### 解决方法 | ||
| 56 | + | ||
| 57 | +- 针对第一种情况：升级Python环境至Python 3.9及以上版本。 | ||
| 58 | +- 针对第二种情况：升级操作系统版本，或通过以下命令规避： | ||
| 59 | + | ||
| 60 | +```bash | ||
| 61 | +pip install "huggingface_hub==0.20.3" | ||
| 62 | +pip install accelerate | ||
| 63 | +``` | ||
| 64 | + | ||
| 65 | +> 注意：`huggingface_hub==0.20.3`非`accelerate`官方推荐版本，可能引发其他兼容性问题，该方案仅供参考，msModelSlim对由此带来的问题不承担相应责任。 | ||
| 66 | + | ||
| 67 | +### 关联文档 | ||
| 68 | + | ||
| 69 | +安装的具体步骤与依赖要求请参见《[安装指南](../install_guide/install_guide.md)》。 | ||
| @@ -0,0 +1,16 @@ | |||
| 1 | +--- | ||
| 2 | +title: FAQ - 精度与调优（预留） | ||
| 3 | +description: 精度与调优 FAQ（暂无条目）。 | ||
| 4 | +keywords: [精度, 调优, 敏感层, 自动调优, 回退, badcase, 精度异常] | ||
| 5 | +--- | ||
| 6 | + | ||
| 7 | +# 精度与调优 FAQ | ||
| 8 | + | ||
| 9 | +> 本节为预留分类，暂无 FAQ 条目。用于沉淀量化精度异常定位、自动调优、敏感层分析等主题的常见问题。 | ||
| 10 | + | ||
| 11 | +量化精度不达标、badcase 增多、无法对齐浮点输出等问题，请参见： | ||
| 12 | + | ||
| 13 | +- 《[精度调优方法](../user_guide/process_quantization_precision_tuning.md)》 | ||
| 14 | +- 《[量化推理精度异常定位](../user_guide/process_quantization_accuracy_anomaly_locating.md)》 | ||
| 15 | + | ||
| 16 | +新增条目请按 1.x 顺序追加，并保持“问题现象 / 问题原因 / 解决方法 / 关联文档”的结构。 | ||
| @@ -0,0 +1,48 @@ | |||
| 1 | +--- | ||
| 2 | +title: FAQ - 运行与资源 | ||
| 3 | +description: 运行与资源类问题的排查与解决；不覆盖安装、硬件、精度、部署问题。 | ||
| 4 | +keywords: [Killed, OOM, NPU, 显存, 内存, 资源, 进程, dmesg] | ||
| 5 | +--- | ||
| 6 | + | ||
| 7 | +# 运行与资源 FAQ | ||
| 8 | + | ||
| 9 | +> 本节覆盖 msModelSlim 运行与资源相关的常见问题。新增条目按 1.x 顺序追加，并保持“问题现象 / 问题原因 / 解决方法 / 关联文档”的结构。 | ||
| 10 | + | ||
| 11 | +## 1.1 为什么我的程序会显示“Killed”并异常退出？ | ||
| 12 | + | ||
| 13 | +### 问题现象 | ||
| 14 | + | ||
| 15 | +在使用msModelSlim工具运行推理量化时，出现类似以下报错信息： | ||
| 16 | + | ||
| 17 | +```text | ||
| 18 | +Killed | ||
| 19 | +... | ||
| 20 | +[Error] TBE Subprocess[task_distribute] raise error[], main process disappeared! | ||
| 21 | +... | ||
| 22 | +``` | ||
| 23 | + | ||
| 24 | +### 问题原因 | ||
| 25 | + | ||
| 26 | +一般是进程被其他用户kill或抢占同一个NPU资源，或NPU显存不足、系统内存不足导致。 | ||
| 27 | + | ||
| 28 | +### 解决方法 | ||
| 29 | + | ||
| 30 | +先确认进程没有被其他用户kill或抢占NPU资源。若不存在资源抢占情况，可通过以下命令查看系统日志、监控系统内存并清理内存： | ||
| 31 | + | ||
| 32 | +```shell | ||
| 33 | +# dmesg查看被内核终止的进程或显存不足终止的进程 | ||
| 34 | +dmesg | grep -A 3 -B 1 -i "killed process\|oom-kill" | ||
| 35 | + | ||
| 36 | +# 监控系统内存 | ||
| 37 | +watch free -h | ||
| 38 | + | ||
| 39 | +# 清理缓存和内存，部分场景可能需要sudo权限 | ||
| 40 | +sync && echo 3 > /proc/sys/vm/drop_caches | ||
| 41 | + | ||
| 42 | +# 停止所有python进程，部分场景可能需要sudo权限 | ||
| 43 | +pkill python | ||
| 44 | +``` | ||
| 45 | + | ||
| 46 | +### 关联文档 | ||
| 47 | + | ||
| 48 | +量化所需的硬件与资源要求请参见《[快速入门](../quick_start/quantization_quick_start.md)》。 | ||
| @@ -0,0 +1,27 @@ | |||
| 1 | +--- | ||
| 2 | +title: FAQ - 告警与提示 | ||
| 3 | +description: 告警与提示类问题的处理说明；不覆盖安装、运行、硬件、精度、部署问题。 | ||
| 4 | +keywords: [告警, 提示, DeprecationWarning, swigvarlink, SWIG, sentencepiece] | ||
| 5 | +--- | ||
| 6 | + | ||
| 7 | +# 告警与提示 FAQ | ||
| 8 | + | ||
| 9 | +> 本节覆盖 msModelSlim 运行过程中告警与提示类常见问题。新增条目按 1.x 顺序追加，并保持“问题现象 / 问题原因 / 解决方法”的结构。 | ||
| 10 | + | ||
| 11 | +## 1.1 量化结束告警“sys:1: DeprecationWarning: builtin type swigvarlink has no module attribute”？ | ||
| 12 | + | ||
| 13 | +### 问题现象 | ||
| 14 | + | ||
| 15 | +量化结束时出现告警： | ||
| 16 | + | ||
| 17 | +```text | ||
| 18 | +sys:1: DeprecationWarning: builtin type swigvarlink has no module attribute | ||
| 19 | +``` | ||
| 20 | + | ||
| 21 | +### 问题原因 | ||
| 22 | + | ||
| 23 | +旧版SWIG（Simplified Wrapper and Interface Generator，简化包装器与接口生成器）生成的第三方库与Python 3.10+不兼容。 | ||
| 24 | + | ||
| 25 | +### 解决方法 | ||
| 26 | + | ||
| 27 | +此告警不影响量化结果，升级触发该告警的第三方库即可消除（如sentencepiece）。 | ||
【review】使用指南应该要链接到具体的使用指南文档中。