msModelSlim 自动调优加速特性设计说明书¶

所属SIG组:	msit
落入版本:	26.0.0
设计人员:	joejoezhou
日期:	20260122

您对"本文档"的复制，使用，修改及分发受知识共享(Creative Commons)署名—相同方式共享4.0国际公共许可协议（以下简称"CC BY-SA 4.0"）的约束。为了方便用户理解，您可以通过访问https://creativecommons.org/licenses/by-sa/4.0/了解CC BY-SA 4.0的概要 (但不是替代)。 CC BY-SA 4.0的完整协议内容您可以访问如下网址获取：https://creativecommons.org/licenses/by-sa/4.0/legalcode。

改版记录

日期	修订版本	修订描述	作者	审核
20260122	1.0.0	文档创建	joejoezhou	panyj1993

1.特性概述

1.1范围

1.2特性需求列表

2.需求场景分析

2.1特性需求来源与价值概述

2.2特性场景分析

2.3特性影响分析

2.3.1硬件限制

2.3.2技术限制

2.3.3对License的影响分析

2.3.4对系统性能规格的影响分析

2.3.5对系统可靠性规格的影响分析

2.3.6对系统兼容性的影响分析

2.3.7与其他重大特性的交互性，冲突性的影响分析

2.4同类社区/商用软件实现方案分析

3.特性/功能实现原理（可分解出来多个Use Case）

3.1目标

3.2总体方案

4.Use Case一实现

4.1 Use Case描述

4.2特性设计思路

4.3约束条件

4.4详细实现（从用户入口的模块级别或进程级别消息序列图）

4.5子系统间接口（主要覆盖模块接口定义）

4.6子系统详细设计

4.6.1 乱码检测检查项设计

4.6.2 预检查流程设计

4.7DFX属性设计

4.7.1性能设计

4.7.2升级与扩容设计

4.7.3异常处理设计

4.7.4资源管理相关设计

4.7.5小型化设计

4.7.6可测性设计

4.7.7安全设计

4.8系统外部接口

4.9自测用例设计

5.Use Case二实现

5.1 Use Case描述

5.2特性设计思路

5.3约束条件

5.4详细实现（从用户入口的模块级别或进程级别消息序列图）

5.5子系统间接口（主要覆盖模块接口定义）

5.6子系统详细设计

5.6.1 精度缓存设计

5.6.2 历史索引设计

5.6.3 缓存复用机制设计

5.6.4 断点续调流程设计

5.7DFX属性设计

5.7.1性能设计

5.7.2升级与扩容设计

5.7.3异常处理设计

5.7.4资源管理相关设计

5.7.5小型化设计

5.7.6可测性设计

5.7.7安全设计

5.8系统外部接口

5.9自测用例设计

6.Use Case三实现

6.1 Use Case描述

6.2特性设计思路

6.3约束条件

6.4详细实现（从用户入口的模块级别或进程级别消息序列图）

6.5子系统间接口（主要覆盖模块接口定义）

6.6子系统详细设计

6.6.1 新策略模块设计

6.6.2 模型结构类型识别设计

6.6.3 专家经验表设计

6.6.4 自动查表机制设计

6.6.5 策略实现方式

6.7DFX属性设计

6.7.1性能设计

6.7.2升级与扩容设计

6.7.3异常处理设计

6.7.4资源管理相关设计

6.7.5小型化设计

6.7.6可测性设计

6.7.7安全设计

6.8系统外部接口

6.9自测用例设计

7.可靠性&可用性设计

7.1冗余设计

7.2故障管理

7.3过载控制设计

7.4升级不中断业务

7.5人因差错设计

7.6故障预测预防设计

8.特性非功能性质量属性相关设计

8.1可测试性

8.2可服务性

8.3可演进性

8.4开放性

8.5兼容性

8.6可伸缩性/可扩展性

8.7可维护性

8.8资料

9.数据结构设计（可选）

10.参考资料清单

表目录

表1：特性需求列表

表2：安全设计确认表

表3：资料修改清单

图目录

图1：方案总体实现原理图

List of abbreviations 缩略语清单 ：

Abbreviations 缩略语	Full spelling 英文全名	Chinese explanation 中文解释
MHA	Multi-Head Attention	多头注意力机制
MLA	Multi-Head Latent Attention	多头潜在注意力机制
DSA	Distributed Sparse Attention	分布式稀疏注意力机制
SWA	Sliding Window Attention	滑动窗口注意力机制
NPU	Neural Processing Unit	神经网络处理单元
YAML	YAML Ain't Markup Language	YAML标记语言
MD5	Message Digest Algorithm 5	消息摘要算法5

1.特性概述¶

精度反馈自动调优是msModelSlim工具已有的核心特性，通过自动化流程减少模型量化精度调优的人工工作量。该功能基于成熟的量化模式已积累的精度调优经验，通过自动迭代生成量化配置、评估模型精度、并根据精度反馈调整策略，直到找到满足精度要求的量化方案。

自动调优加速特性是在已有精度反馈自动调优功能基础上的加速优化，旨在进一步提升自动调优的效率和可靠性。本特性通过三个关键优化点来加速自动调优过程：1）对话乱码时跳过数据集测评，避免无效评估浪费计算资源；2）支持断点续调，避免因意外中断导致重复评估；3）基于专家经验的调优策略，简化用户配置并提高调优效率。

本特性对客户的价值主要体现在：1）节省计算资源，通过智能跳过无效评估减少不必要的计算开销；2）提高调优可靠性，支持断点续调避免工作损失；3）简化用户操作，基于专家经验自动选择最优策略，降低配置复杂度。

本文档主要描述自动调优加速特性的设计实现，包括三个主要Use Case：对话乱码时跳过数据集测评、自动调优支持断点续调、基于专家经验的调优策略。本文档适用于msModelSlim工具的自动调优功能开发、测试和维护人员。

1.1范围¶

本特性是在已有精度反馈自动调优功能基础上的加速优化，主要包含以下功能点：

对话乱码检测与跳过机制：在正式评估前进行预检查，检测模型输出是否为乱码，如果检测到乱码则跳过数据集测评，节省计算资源。这是对已有自动调优功能的优化，避免无效评估浪费计算资源。
断点续调功能：支持从历史精度缓存中恢复已评估的量化配置结果，避免重复评估，实现调优过程的断点续调。这是对已有自动调优功能的优化，提高调优过程的可靠性。
基于专家经验的调优策略：创建独立的expert_experience策略模块，支持基于模型结构类型（如MHA/MLA/DSA/SWA/GatedDeltaNet等）自动查表获取算法的搜索空间，无需用户手动输入。这是对已有自动调优功能的优化，简化用户配置并提高调优效率。

注意：精度反馈自动调优流程本身是已有功能，不在本特性范围内。本特性仅包含上述三个加速优化点。

1.2特性需求列表¶

表1：特性需求列表

需求编号	需求名称	特性描述	备注
1	对话乱码时跳过数据集测评	在模型精度评估前，通过预检查机制检测模型输出是否为乱码。如果检测到乱码，则跳过数据集测评，直接返回精度为0的评估结果，节省计算资源	-
2	自动调优支持断点续调	支持从历史精度缓存中恢复已评估的量化配置结果。当调优过程因意外中断后，重新启动时会自动检测并复用历史精度缓存，避免重复评估相同的量化配置	-
3	基于专家经验的调优策略	创建独立的expert_experience策略模块，支持根据模型结构类型（如MHA/MLA/DSA/SWA/GatedDeltaNet等）自动查表获取算法的搜索空间，无需用户手动输入搜索空间配置	-

2.需求场景分析¶

2.1特性需求来源与价值概述¶

msModelSlim工具已经实现了精度反馈自动调优功能，通过自动化流程减少模型量化精度调优的人工工作量。然而，在实际使用过程中，发现自动调优功能存在以下问题：

无效评估浪费资源：当量化后的模型输出为乱码时，仍然会进行完整的数据集测评，浪费大量计算资源。
中断后无法恢复：如果调优过程因意外中断（如系统故障、手动停止等），重新启动时需要从头开始，无法复用已评估的配置结果。
配置复杂度高：standing_high策略需要用户手动输入算法的搜索空间，对于不熟悉量化调优的用户来说，配置复杂度较高。

自动调优加速特性旨在解决上述问题，通过三个关键优化点来加速自动调优过程。该特性对用户带来的具体价值包括：

节省计算资源：通过智能跳过无效评估（如乱码检测），节省计算资源，降低调优成本。预计可以节省10-30%的评估时间。
提高调优可靠性：支持断点续调，避免因意外中断导致的工作损失，提高调优过程的可靠性。即使调优过程中断，也可以从历史精度缓存中恢复，避免重复评估。
简化用户操作：基于专家经验自动选择最优策略，无需用户手动输入搜索空间配置，降低配置复杂度，提高调优效率。

如果没有该特性，自动调优功能虽然可以正常工作，但会存在上述问题，影响调优效率和用户体验。

2.2特性场景分析¶

场景触发条件及对象¶

触发条件：
用户需要对大语言模型或多模态模型进行量化
用户希望通过自动调优找到满足精度要求的量化方案
用户配置了自动调优计划（YAML配置文件）
使用对象：
模型量化工程师：具备一定的模型量化知识，熟悉msModelSlim工具的使用
AI应用开发者：需要将模型部署到NPU设备上，对量化精度有要求
使用接口：
命令行接口：msmodelslim tune 命令
配置文件：YAML格式的调优计划配置文件

主要应用场景¶

新模型量化场景：
用户首次对某个模型进行量化，需要找到满足精度要求的量化方案
子场景：模型结构已知，但量化参数未知
关键操作：配置调优计划、启动自动调优、等待调优完成、获取最终量化配置
模型精度优化场景：
用户已有量化方案，但精度不达标，需要通过自动调优优化精度
子场景：在现有量化方案基础上进行微调
关键操作：基于现有方案启动调优、迭代优化、验证精度提升
批量模型量化场景：
用户需要对多个模型进行量化，希望自动化处理
子场景：模型系列相同，但参数不同
关键操作：批量配置调优计划、并行或串行执行调优、汇总结果

2.3特性影响分析¶

自动调优加速特性集成到已有精度反馈自动调优功能的核心调优流程中，与以下模块存在交互：

量化服务模块：调用量化服务对模型进行量化
评估服务模块：调用评估服务对量化后的模型进行精度评估
调优策略模块：使用不同的调优策略生成量化配置
历史管理模块：管理调优历史记录和精度缓存
模型适配器模块：适配不同模型系列的接口

与其他需求及特性的交互分析¶

与量化特性的交互：自动调优依赖量化功能，需要量化服务支持多种量化配置
与评估特性的交互：自动调优依赖评估功能，需要评估服务支持精度评估和预检查
与最佳实践库的交互：调优成功后，可以将最终量化配置保存到最佳实践库
与模型适配器的交互：
三种调优策略在需自动敏感层分析时，模型适配器均须实现 ModelSlimPipelineInterfaceV1（即 PipelineInterface，与 CLI msmodelslim analyze 相同）
standing_high：始终自动敏感层分析
standing_high_with_experience：另须 StandingHighWithExperienceInterface（load_model，离群值抑制探测）
敏感层分析由 PipelineAnalysisService / Runner 调用 init_model、pipeline 方法，策略侧不预先 load_model

平台差异性分析¶

硬件平台：主要支持NPU设备（如昇腾系列），需要NPU设备支持模型量化和推理
操作系统：支持Linux操作系统，需要Python 3.8+

兼容性分析¶

前向兼容性：新版本的自动调优功能兼容旧版本的量化配置格式
配置兼容性：支持旧版本的调优计划配置文件格式，但建议使用新格式

约束及限制¶

模型支持限制：仅支持已实现模型适配器的模型系列
精度评估限制：需要vLLM-Ascend支持量化后模型的服务化启动
资源限制：调优过程需要足够的存储空间保存量化模型和评估结果

2.3.1硬件限制¶

NPU设备要求：需要支持模型量化和推理的NPU设备，至少需要一张NPU卡
内存要求：调优过程需要足够的内存加载模型和进行量化计算，建议至少32GB内存
存储要求：需要足够的存储空间保存量化模型、评估结果和历史记录，建议至少100GB可用空间
网络要求：如果使用远程评估服务，需要稳定的网络连接

规避方案：

对于内存不足的情况，可以通过减少batch size或使用模型并行来降低内存占用
对于存储不足的情况，可以定期清理历史记录或使用外部存储

2.3.2技术限制¶

操作系统：Linux（推荐Ubuntu 20.04+或CentOS 7+）

编程语言：Python 3.8+

依赖框架：

PyTorch：用于模型加载和量化
vLLM-Ascend：用于模型服务化启动和推理
AISbench：用于精度评估

规避方案：

对于不支持的Python版本，建议使用conda或virtualenv创建虚拟环境
对于依赖框架版本不兼容的情况，建议参考安装指南使用指定版本

2.3.3对License的影响分析¶

本特性主要使用以下开源软件和技术：

PyTorch：BSD许可证，允许商业使用
vLLM-Ascend：Apache 2.0许可证，允许商业使用
AISbench：Apache 2.0许可证，允许商业使用
Pydantic：MIT许可证，允许商业使用

所有引入的第三方开源软件均符合msModelSlim项目的License要求，不会对项目的License合规性造成影响。

2.3.4对系统性能规格的影响分析¶

基于特性运行资源的设定条件：

内存要求：至少需要32GB内存，推荐64GB以上。主要用于：
模型加载：根据模型大小，可能需要10-50GB内存
量化计算：需要额外的10-20GB内存用于量化过程
评估服务：需要5-10GB内存用于评估服务运行
存储要求：至少需要100GB可用存储空间，推荐200GB以上。主要用于：
量化模型保存：每个量化配置的模型可能需要10-50GB
评估结果保存：历史记录和精度缓存可能需要10-50GB
临时文件：调优过程中的临时文件可能需要20-50GB
NPU要求：至少需要1张NPU卡，推荐2张以上。主要用于：
模型量化：量化过程需要NPU支持
模型推理：评估过程需要NPU进行推理

2.3.5对系统可靠性规格的影响分析¶

特性对于可靠性指标的假设和约束：

调优成功率：在正常条件下，对于已支持的模型系列，调优成功率应达到80%以上
断点续调可靠性：历史精度缓存的恢复成功率应达到99%以上
异常处理：对于常见的异常情况（如网络中断、存储不足等），应能够优雅降级或提供明确的错误提示

2.3.6对系统兼容性的影响分析¶

本特性不会影响系统的前向兼容性：

配置兼容性：新版本的自动调优功能兼容旧版本的量化配置格式和调优计划格式
接口兼容性：自动调优的接口设计考虑了向后兼容，旧版本的调用方式仍然有效
数据兼容性：历史精度缓存的格式设计考虑了版本兼容，支持跨版本使用

2.3.7与其他重大特性的交互性，冲突性的影响分析¶

与量化特性的交互：
自动调优依赖量化功能，需要量化服务支持多种量化配置
自动调优不会影响手动量化功能，两者可以并存
与评估特性的交互：
自动调优依赖评估功能，需要评估服务支持精度评估和预检查
自动调优不会影响手动评估功能，两者可以并存
与最佳实践库的交互：
调优成功后，可以将最终量化配置保存到最佳实践库
最佳实践库中的配置可以被自动调优策略参考使用
与模型适配器的交互：
调优策略在需自动敏感层分析时，均须 ModelSlimPipelineInterfaceV1（即 PipelineInterface）
standing_high：始终自动敏感层分析
standing_high_with_experience：另须 StandingHighWithExperienceInterface（load_model）
对于不支持自动调优的模型，仍可以使用手动量化功能

2.4同类社区/商用软件实现方案分析¶

目前，在模型量化自动调优领域，主要的实现方案包括：

Neural Network Intelligence (NNI)：微软开源的自动机器学习工具，支持模型压缩和量化自动调优。其优势在于支持多种调优算法和分布式调优，但主要面向PyTorch和TensorFlow框架，对NPU设备的支持有限。
msModelSlim自动调优：本特性的实现方案，主要优势包括：
集成度高：与msModelSlim工具深度集成，支持完整的量化-评估-调优流程
NPU优化：针对昇腾NPU设备进行深度优化，支持高效的量化推理
智能跳过：通过乱码检测等机制，智能跳过无效评估，节省计算资源
断点续调：支持历史精度缓存恢复，提高调优过程的可靠性
专家经验：基于历史经验自动选择最优策略，提高调优成功率

相比同类方案，本特性的主要优势在于对NPU设备的深度优化和智能化的调优策略，能够更高效地找到满足精度要求的量化方案。

3.特性/功能实现原理（可分解出来多个Use Case）¶

3.1目标¶

自动调优加速特性的目标是在已有精度反馈自动调优功能的基础上，通过三个关键优化点来加速自动调优过程。具体目标包括：

资源优化：通过智能跳过无效评估（如乱码检测），节省计算资源，降低调优成本。目标是在检测到乱码时，能够节省90%以上的评估时间。
可靠性保障：支持断点续调，避免因意外中断导致的工作损失，提高调优过程的可靠性。目标是历史精度缓存的恢复成功率达到99%以上。
效率提升：基于专家经验自动选择最优策略，简化用户配置，提高调优效率。目标是减少用户配置时间，提高调优成功率。
兼容性保证：所有优化点都保持与已有自动调优功能的兼容性，不影响现有功能的使用

3.2总体方案¶

自动调优加速特性是在已有精度反馈自动调优功能基础上的优化，采用以下设计思路：

预检查优化：在已有评估流程中增加预检查机制，在正式评估前检测模型输出是否为乱码，如果检测到乱码则跳过数据集测评。
历史缓存优化：在已有调优流程中增加历史精度缓存机制，支持从历史缓存中恢复已评估的配置结果，实现断点续调。
策略优化：创建新的expert_experience策略模块，基于专家经验自动获取算法的搜索空间，简化用户配置。

所有优化点都集成到已有的自动调优流程中，不影响现有功能的正常使用。

硬件选择¶

NPU设备：使用昇腾NPU设备进行模型量化和推理，充分利用NPU的量化加速能力
存储设备：使用本地存储或网络存储保存量化模型和评估结果

算法选择¶

调优策略：采用standing_high策略作为基础调优策略，同时提供独立的expert_experience策略模块，支持基于模型结构类型的专家经验自动查表
精度评估：使用AISbench进行精度评估，支持多种评估数据集
预检查机制：使用乱码检测和期望答案检查等预检查机制，智能跳过无效评估

架构布局¶

已有精度反馈自动调优功能采用分层架构设计：

应用层：AutoTuningApplication，负责协调整个调优流程
策略层：ITuningStrategy，负责生成量化配置和调整策略
服务层：量化服务、评估服务，负责具体的量化和评估操作
数据层：历史管理模块，负责管理调优历史记录和精度缓存

自动调优加速特性通过以下方式集成到已有架构中：

预检查优化：在评估服务层增加预检查机制，在正式评估前进行乱码检测
历史缓存优化：在数据层增加精度缓存机制，支持断点续调
策略优化：在策略层增加expert_experience策略模块，基于专家经验自动获取搜索空间

Use Case分解¶

根据场景分析和系统分解，识别出三个关键Use Case，每个Use Case对自动调优功能产生特定影响，需要实现相应的特性：

Use Case 1：用户在自动调优过程中，如果模型输出乱码，希望跳过无效评估
用户场景：用户在自动调优过程中，发现量化后的模型输出为乱码，希望系统能够智能识别并跳过无效的数据集测评，节省计算资源
对自动调优功能的影响：需要在评估前进行预检查，检测模型输出是否为乱码，如果检测到乱码则跳过数据集测评
实现的特性：对话乱码时跳过数据集测评
Use Case 2：用户在自动调优过程中，如果调优异常中断，希望重新拉起后能继续调优
用户场景：用户在自动调优过程中，如果调优因意外中断（如系统故障、手动停止等），希望重新拉起自动调优后能够复用历史记录，继续精度调优过程，避免重复评估
对自动调优功能的影响：需要支持断点续调，能够从历史精度缓存中恢复已评估的量化配置结果
实现的特性：自动调优支持断点续调
Use Case 3：用户在配置自动调优时，希望根据模型结构类型自动获取搜索空间
用户场景：用户在配置自动调优时，不熟悉量化调优的搜索空间配置，希望系统能够根据模型结构类型（如MHA/MLA/DSA/SWA/GatedDeltaNet等）自动查表获取算法的搜索空间，简化配置操作
对自动调优功能的影响：需要提供基于专家经验的调优策略，支持根据模型结构类型自动获取搜索空间
实现的特性：基于专家经验的调优策略

对接原则¶

接口标准化：所有模块接口采用标准化的接口定义，便于扩展和维护
数据格式统一：使用统一的YAML格式保存配置和结果，便于解析和存储
错误处理规范：统一的错误处理和日志记录机制，便于问题定位和调试

方案整体架构图¶

┌─────────────────────────────────────────────────────────────┐
│                    用户命令行接口                            │
│                  msmodelslim tune                            │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              AutoTuningApplication (应用层)                   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  1. 加载调优计划                                       │   │
│  │  2. 初始化调优策略                                     │   │
│  │  3. 检测历史精度缓存                                   │   │
│  │  4. 迭代调优循环                                       │   │
│  │     - 生成量化配置                                     │   │
│  │     - 尝试恢复历史                                     │   │
│  │     - 量化模型                                        │   │
│  │     - 评估模型精度（含预检查）                         │   │
│  │     - 保存调优历史                                     │   │
│  │     - 判断是否继续                                     │   │
│  └──────────────────────────────────────────────────────┘   │
└──────────────────────┬──────────────────────────────────────┘
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 调优策略层    │ │ 量化服务层    │ │ 评估服务层    │
│ITuningStrategy│ │IQuantService │ │EvaluateService│
│              │ │              │ │              │
│- standing_high│ │- 模型量化     │ │- 精度评估     │
│- 专家经验策略  │ │- 配置生成     │ │- 预检查       │
└──────────────┘ └──────────────┘ └──────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              历史管理模块 (数据层)                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  - 精度缓存管理 (accuracy.yaml)                       │   │
│  │  - 历史记录管理 (history.yaml)                        │   │
│  │  - 配置文件管理 (practice configs)                     │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

图1：方案总体实现原理图

4.Use Case一实现¶

4.1 Use Case描述¶

Use Case名称：对话乱码跳过数据集测评

Use Case场景：

用户在自动调优过程中，量化后的模型输出为乱码
用户希望系统能够智能识别乱码并跳过无效的数据集测评，节省计算资源
系统在正式评估前进行预检查，检测模型输出是否为乱码
如果检测到乱码，则跳过数据集测评，直接返回精度为0的评估结果

对自动调优功能的影响：

需要在评估流程中增加预检查机制
需要实现乱码检测功能
需要支持跳过无效评估的逻辑

实现的特性：对话乱码时跳过数据集测评

4.2特性设计思路¶

在模型精度评估过程中，如果量化后的模型输出为乱码，继续进行完整的数据集测评会浪费大量计算资源。因此，本特性通过在正式评估前进行预检查，检测模型输出是否为乱码，如果检测到乱码则跳过数据集测评，直接返回精度为0的评估结果。

设计思路包括：

预检查机制：在正式评估前，通过发送测试消息检测模型输出是否符合预期
乱码检测：使用多种检查项（空文本、重复字符、正常字符比例、控制字符、重复模式等）检测模型输出是否为乱码
智能跳过：如果检测到乱码，则跳过数据集测评，直接返回精度为0的评估结果，节省计算资源

4.3约束条件¶

模型服务化要求：需要模型能够通过vLLM-Ascend以服务化方式启动，支持API调用
预检查配置要求：需要在调优计划配置文件中配置precheck字段，指定乱码检测的测试用例
网络要求：如果评估服务在远程运行，需要稳定的网络连接

4.4详细实现（从用户入口的模块级别或进程级别消息序列图）¶

处理流程¶

用户启动自动调优
   │
   ▼
AutoTuningApplication.tune()
   │
   ▼
评估服务启动模型服务化
   │
   ▼
EvaluateService.evaluate()
   │
   ├─→ 检查是否配置了precheck
   │   │
   │   ├─→ 是：执行预检查
   │   │   │
   │   │   ├─→ GarbledTextRule.check()
   │   │   │   │
   │   │   │   ├─→ 遍历测试用例
   │   │   │   │   │
   │   │   │   │   ├─→ test_chat_via_api() 发送测试消息
   │   │   │   │   │
   │   │   │   │   ├─→ is_garbled_text() 检测乱码
   │   │   │   │   │   │
   │   │   │   │   │   ├─→ 空文本检查 (EmptyTextCheckItem)
   │   │   │   │   │   ├─→ 重复字符检查 (RepeatedCharCheckItem)
   │   │   │   │   │   ├─→ 正常字符比例检查 (NormalCharRatioCheckItem)
   │   │   │   │   │   ├─→ 控制字符检查 (ControlCharCheckItem)
   │   │   │   │   │   └─→ 重复模式检查 (RepeatedPatternCheckItem)
   │   │   │   │   │
   │   │   │   │   └─→ 如果检测到乱码：返回精度为0的评估结果
   │   │   │   │
   │   │   │   └─→ 如果所有测试用例通过：继续执行正式评估
   │   │   │
   │   │   └─→ 否：直接执行正式评估
   │   │
   │   └─→ 执行正式数据集测评
   │
   └─→ 返回评估结果

模块交互说明¶

AutoTuningApplication：协调整个调优流程，调用评估服务进行精度评估
EvaluateService：负责模型精度评估，在执行正式评估前检查是否配置了precheck
GarbledTextRule：实现乱码检测预检查规则，通过多种检查项检测模型输出是否为乱码
GarbledTextCheckItem：各种乱码检测检查项的接口实现，包括空文本、重复字符、正常字符比例、控制字符、重复模式等检查项

4.5子系统间接口（主要覆盖模块接口定义）¶

新增接口¶

GarbledTextPrecheckConfig (msmodelslim/infra/evaluation/precheck/garbled_text_rule.py)
类型：Pydantic BaseModel
功能：乱码检测预检查配置，包含测试用例列表
字段：
- type: Literal["garbled_text"]，固定值
- test_cases: Optional[List[TestCaseConfig]]，测试用例列表
GarbledTextRule (msmodelslim/infra/evaluation/precheck/garbled_text_rule.py)
类型：BasePrecheckRule子类
功能：实现乱码检测预检查规则
方法：
- is_garbled_text(text: str, check_items: List[str]) -> bool：检测文本是否为乱码
- check(host: str, port: int, served_model_name: str, datasets: List[str]) -> Optional[List[EvaluateAccuracy]]：执行乱码检测预检查
GarbledTextCheckItem (msmodelslim/infra/evaluation/precheck/garbled_text_rule.py)
类型：ABC抽象基类
功能：乱码检测检查项接口
子类：
- EmptyTextCheckItem：空文本检查
- RepeatedCharCheckItem：重复字符检查
- NormalCharRatioCheckItem：正常字符比例检查
- ControlCharCheckItem：控制字符检查
- RepeatedPatternCheckItem：重复模式检查

修改接口¶

BasePrecheckRule.check() (msmodelslim/infra/evaluation/precheck/base.py)
功能扩展：支持返回精度评估结果，如果预检查失败则返回精度为0的评估结果

4.6子系统详细设计¶

4.6.1 乱码检测检查项设计¶

乱码检测采用责任链模式，支持多种检查项的组合使用：

EmptyTextCheckItem：检查文本是否为空
实现：检查文本去除空白字符后是否为空
阈值：无
RepeatedCharCheckItem：检查是否存在大量连续重复字符
实现：统计文本中连续重复字符的最大长度，如果超过文本长度的30%则判定为乱码
阈值：0.3（可配置）
NormalCharRatioCheckItem：检查正常字符比例是否过低
实现：统计中英文、数字、常见标点符号的比例，如果低于50%则判定为乱码
阈值：0.5（可配置）
ControlCharCheckItem：检查是否包含大量控制字符
实现：统计控制字符（排除换行、回车、制表符）的比例，如果超过10%则判定为乱码
阈值：0.1（可配置）
RepeatedPatternCheckItem：检查是否存在明显的重复模式
实现：检查文本开头的模式是否在文本中重复出现，如果重复次数达到阈值且重复部分占总长度的比例达到阈值则判定为乱码
阈值：min_pattern_count=3, min_pattern_ratio=0.5（可配置）

4.6.2 预检查流程设计¶

配置解析：从调优计划配置文件中解析precheck配置，创建GarbledTextPrecheckConfig对象
测试用例执行：遍历配置的测试用例，对每个测试用例：
通过API发送测试消息到模型服务
获取模型响应
使用配置的检查项检测响应是否为乱码
如果检测到乱码，记录警告日志并返回精度为0的评估结果
继续评估：如果所有测试用例通过，继续执行正式的数据集测评

4.7DFX属性设计¶

4.7.1性能设计¶

预检查开销：预检查仅发送少量测试消息（通常1-3条），开销很小，相比完整的数据集测评可以节省90%以上的时间
检查项性能：各种检查项的实现都是O(n)时间复杂度，n为文本长度，性能开销可忽略不计
对现有特性的影响：预检查是可选的，如果不配置precheck，不会影响现有的评估流程

4.7.2升级与扩容设计¶

配置兼容性：新版本的预检查功能兼容旧版本的配置文件格式，如果未配置precheck字段，则跳过预检查
检查项扩展性：通过注册机制支持新增检查项，不影响现有检查项的使用

4.7.3异常处理设计¶

API调用异常：如果测试消息发送失败，记录警告日志并继续执行下一个测试用例，不中断评估流程
检查项异常：如果某个检查项执行失败，记录警告日志并继续执行下一个检查项
配置异常：如果precheck配置格式错误，记录错误日志并跳过预检查，继续执行正式评估

4.7.4资源管理相关设计¶

内存占用：预检查仅需要少量内存存储测试消息和响应，内存占用可忽略不计
网络I/O：预检查需要发送少量HTTP请求，网络I/O开销很小
计算资源：预检查的计算开销很小，不会对系统性能造成明显影响

4.7.5小型化设计¶

本特性不会影响小型化版本的规格，预检查功能是轻量级的，内存和CPU占用都很小。

4.7.6可测性设计¶

测试应该涵盖以下方面：

功能测试：
正常文本通过所有检查项
空文本被检测为乱码
重复字符文本被检测为乱码
控制字符文本被检测为乱码
重复模式文本被检测为乱码
混合乱码文本被检测为乱码
边界值测试：
文本长度为0
文本长度为1
文本长度非常大（>10000字符）
检查项阈值边界值
异常场景测试：
API调用失败
检查项执行异常
配置格式错误
网络中断
性能测试：
预检查耗时测试
大量测试用例的性能测试

4.7.7 安全设计¶

4.7.7.1 安全设计确认¶

安全属性	检查项	检查项详细说明	是否涉及	是否满足
访问通道控制	是否新增侦听端口	新增侦听端口需刷新通信矩阵	否	不涉及
访问通道控制	是否新增进程或组件间通信	新增进程或组件间通信刷新通信矩阵	是	满足
访问通道控制	是否新增认证方式	新增认证方式需刷新通信矩阵及产品文档	否	不涉及
权限控制	是否涉及创建文件或目录	创建文件或目录须显式指定文件或目录的访问权限	否	不涉及
权限控制	账号权限是否满足“权限最小化原则”	系统中各账号应赋予最小权限	是	满足
权限控制	是否存在用户权限提升	禁止出现用户非法权限提升	否	不涉及
未公开接口	是否新增GUC参数	新增GUC参数需刷新产品文档	否	不涉及
未公开接口	是否新增或修改函数、视图、系统表	新增或修改函数、视图、系统表需刷新产品文档，考虑权限控制	否	不涉及
未公开接口	是否新增SQL语法	新增SQL语法需刷新产品文档，支持记录审计日志	否	不涉及
未公开接口	是否新增内部工具	新增内部工具需刷新产品文档	否	不涉及
未公开接口	脚本中是否存在注释代码	Shell/Python等解释性语言禁止注释代码，注释代码需要删除	否	不涉及
未公开接口	是否存在隐藏命令、参数、端口等接入方式	对于现网维护期间不会使用的命令/参数、端口等接入方式（包括但不限于产品的生产、调测、维护用途），必须删除（如通过编译宏）	否	不涉及
未公开接口	系统是否存在隐藏后门	禁止系统预留任何的未公开账号，所有账号必须可被系统管理，并在资料中予以说明	否	不涉及
未公开接口	禁止在产品对外部用户发布的软件（包含软件包/补丁包）中提供破解类、网络嗅探类工具。	1、禁止在产品对外部用户发布的软件（包含软件包/补丁包）中提供可修改任意用户口令、具有“口令破解能力”（指口令暴力破解、利用系统/算法漏洞恶意破解口令）、对包含敏感数据的文件（如包含密钥的配置文件、数据库）进行解密的功能或工具。2、禁止在系统中保留第三方的网络嗅探工具tcpdump、gdb、strace、readelf网络、进程调试工具，cpp、gcc、dexdump、mirror、JDK开发/编译工具和仅在调测阶段使用的自研调试工具/脚本（例如：仅在调试阶段使用的加解密脚本、调测功能、可以提权的命令），由于业务需要必须保留的，需要进行严格的访问控制。同时在资料中说明保留的原因、使用的场景、风险。	否	不涉及
敏感数据保护	认证凭据不允许明文存储在系统中，应该加密保护。	认证凭据（如口令/私钥等）不允许明文存储在系统中，应该加密保护。	否	不涉及
敏感数据保护	用于敏感数据传输加密的密钥，不能硬编码在代码中。	禁止口令和密钥硬编码。	否	不涉及
敏感数据保护	是否明文打印口令或密钥等敏感信息	禁止在系统中存储的日志、调试信息、错误提示及ps命令等信息打印明文敏感信息（口令/私钥/预共享密钥）。	否	不涉及
敏感数据保护	是否明文回显口令	禁止明文回显口令。	否	不涉及
敏感数据保护	是否使用第三方和开源软件的缺省口令	禁止使用第三方和开源软件的缺省口令，参考安全设计指南第1.5章节。	否	不涉及
敏感数据保护	是否将密码明文存储在配置文件中	明文密码不允许写入配置文件（命令行工具安装部署及使用时必需配置密码的场景除外）。	否	不涉及
敏感数据保护	是否使用不安全的加密算法	禁止使用私有的或业界已知不安全的加密算法。推荐加密算法安全设计指南6.2章节。	否	不涉及
敏感数据保护	口令等敏感信息是否使用安全的传输通道	在非信任网络之间进行敏感信息传输须采用安全传输通道或者加密后传输。参考安全设计指南第10章。	是	满足
敏感数据保护	内存中口令或密钥等敏感信息使用后是否销毁	内存中的口令或密钥等信息使用完毕后立即清0。	否	不涉及
敏感数据保护	密码算法中使用到的随机数必须是密码学意义上的安全随机数。	密码算法中使用到的随机数必须是密码学意义上的安全随机数，参考安全设计指南6.3章节。	否	不涉及
敏感数据保护	资料中是否存在不安全的示例	资料中的示例需要是安全的，对用户进行正确的引导，若示例中存在潜在的风险，要在资料中进行说明。	是	满足
认证	是否提供认证机制	新系统需要提供认证机制并缺省开启。	否	不涉及
认证	认证是否在服务端进行	认证处理过程需要在服务端进行。	否	不涉及
认证	认证失败后服务端是否返回有效信息	认证失败后，服务端返回信息不能提供详细的、可用于判断具体错误原因的提示。	否	不涉及
外部参数校验	是否对外部输入进行合法性校验	1、使用外部输入数据作为循环终止条件、数组下标、内存分配大小参数等，可能导致系统出现死循环、缓冲区溢出、内存越界、拒绝服务等一系列行为。2、文件路径等外部输入应进行合法性校验，防止注入风险	是	满足
三方件引入	是否新引入三方组件	1.新增三方组件需要通过安全编译选项、病毒、漏洞、开源片段引用、license合规、开源组件扫描，参考版本发布网络安全质量要求。2.新增三方组件需保证来源可信。	否	不涉及

4.7.7.2 敏感数据分析¶

本Use Case不涉及敏感数据的处理，主要是对模型输出文本进行乱码检测，不涉及用户认证、密钥管理等敏感操作。

4.7.7.3 设计实现¶

本Use Case的安全设计主要体现在：

外部输入校验：对测试消息和模型响应进行合法性校验，防止注入攻击
网络通信安全：如果评估服务在远程运行，使用HTTPS等安全传输通道
错误信息处理：错误信息不泄露敏感信息，仅记录必要的调试信息

4.8系统外部接口¶

本Use Case不会影响系统外部接口，主要是内部实现优化。用户可以通过调优计划配置文件中的precheck字段来启用或禁用乱码检测功能。

4.9自测用例设计¶

自测用例设计如下：

正常文本测试：
输入：正常的中文文本“你好，世界”
预期：通过所有检查项，继续执行正式评估
空文本测试：
输入：空字符串或仅包含空白字符的字符串
预期：被EmptyTextCheckItem检测为乱码，返回精度为0的评估结果
重复字符测试：
输入：包含大量连续重复字符的文本，如"aaaaaaaaaa..."
预期：被RepeatedCharCheckItem检测为乱码，返回精度为0的评估结果
控制字符测试：
输入：包含大量控制字符的文本
预期：被ControlCharCheckItem检测为乱码，返回精度为0的评估结果
重复模式测试：
输入：包含明显重复模式的文本，如"abcabcabc..."
预期：被RepeatedPatternCheckItem检测为乱码，返回精度为0的评估结果
混合乱码测试：
输入：包含多种乱码特征的文本
预期：被至少一个检查项检测为乱码，返回精度为0的评估结果
API调用失败测试：
输入：模拟API调用失败
预期：记录警告日志，继续执行下一个测试用例，不中断评估流程
配置错误测试：
输入：precheck配置格式错误
预期：记录错误日志，跳过预检查，继续执行正式评估

5.Use Case二实现¶

5.1 Use Case描述¶

Use Case名称：精度调优异常中断后需断点续调

Use Case场景：

用户在自动调优过程中，调优因意外中断（如系统故障、手动停止等）
用户希望重新拉起自动调优后能够复用历史记录，继续精度调优过程
系统在重新启动时自动检测历史精度缓存
如果存在历史精度缓存，系统会复用已评估的量化配置结果，避免重复评估

对自动调优功能的影响：

需要支持断点续调功能
需要实现历史精度缓存机制
需要支持从历史缓存中恢复已评估的配置结果

实现的特性：自动调优支持断点续调

5.2特性设计思路¶

在自动调优过程中，如果因为意外中断（如系统故障、手动停止等）导致调优过程中断，重新启动时需要能够从历史精度缓存中恢复已评估的量化配置结果，避免重复评估相同的配置，实现调优过程的断点续调。

设计思路包括：

精度缓存机制：将每次迭代的量化配置和精度评估结果保存到精度缓存中，使用MD5哈希值作为配置的唯一标识
历史检测机制：在调优开始时检测是否存在历史精度缓存，如果存在则加载到内存中
缓存复用机制：在每次迭代时，首先尝试从精度缓存中查找匹配的量化配置，如果找到则直接使用历史评估结果，跳过量化、服务化启动、预检查和评估步骤

5.3约束条件¶

存储要求：需要足够的存储空间保存精度缓存，精度缓存文件为YAML格式
路径一致性：断点续调要求使用相同的save_path，系统会在save_path/history目录中查找精度缓存
配置一致性：断点续调要求量化配置完全一致（通过MD5哈希值匹配），如果配置有变化则无法复用

5.4详细实现（从用户入口的模块级别或进程级别消息序列图）¶

处理流程¶

用户启动自动调优（可能为断点续调）
   │
   ▼
AutoTuningApplication.tune()
   │
   ▼
TuningHistoryManager.load_history()
   │
   ├─→ 检测save_path/history目录
   │   │
   │   ├─→ 如果存在accuracy.yaml：加载精度缓存到内存
   │   │
   │   └─→ 如果不存在：创建空的精度缓存
   │
   ▼
YamlTuningHistory._load_accuracy_database()
   │
   ├─→ 读取accuracy.yaml文件
   │
   ├─→ 解析为字典格式（key为MD5，value为评估结果）
   │
   └─→ 加载到内存中的_accuracy_cache
   │
   ▼
开始迭代调优循环
   │
   ├─→ 生成量化配置 (PracticeConfig)
   │
   ├─→ 计算配置的MD5哈希值
   │
   ├─→ 在精度缓存中查找匹配的配置
   │   │
   │   ├─→ 如果找到：直接使用历史评估结果，跳过量化、评估步骤
   │   │
   │   └─→ 如果未找到：执行量化、评估步骤
   │       │
   │       ├─→ 量化模型
   │       │
   │       ├─→ 评估模型精度
   │       │
   │       └─→ 保存到精度缓存
   │
   └─→ 继续下一次迭代

模块交互说明¶

AutoTuningApplication：协调整个调优流程，在调优开始时加载历史精度缓存，在每次迭代时尝试从缓存中恢复评估结果
TuningHistoryManager：管理调优历史，负责加载和保存精度缓存
YamlTuningHistory：实现基于YAML的精度缓存管理，包括加载、保存、查询等功能
calculate_practice_md5：计算量化配置的MD5哈希值，用于唯一标识配置

5.5子系统间接口（主要覆盖模块接口定义）¶

新增接口¶

TuningHistoryInfra (msmodelslim/app/auto_tuning/practice_history_infra.py)
类型：ABC抽象基类
功能：调优历史操作接口
方法：
- get_accuracy(practice: PracticeConfig) -> Optional[EvaluateResult]：从历史中获取精度评估结果
- append_history(practice: PracticeConfig, evaluation: EvaluateResult) -> None：追加历史记录
- clear_records() -> None：清除历史记录（但保留精度缓存）
- get_accuracy_count() -> int：返回精度记录数量
TuningHistoryManagerInfra (msmodelslim/app/auto_tuning/practice_history_infra.py)
类型：ABC抽象基类
功能：调优历史管理器接口
方法：
- load_history(database: str) -> TuningHistoryInfra：加载调优历史
YamlTuningHistory (msmodelslim/infra/yaml_practice_history_manager.py)
类型：TuningHistoryInfra实现类
功能：基于YAML的调优历史实现
数据文件：
- accuracy.yaml：精度缓存，key为MD5，value为评估结果
- history.yaml：历史索引，记录每次迭代的配置ID和评估结果
calculate_practice_md5 (msmodelslim/infra/yaml_practice_history_manager.py)
类型：函数
功能：计算量化配置的MD5哈希值
实现：将配置序列化为JSON字符串，计算MD5哈希值

修改接口¶

AutoTuningApplication._tune() (msmodelslim/app/auto_tuning/application.py)
功能扩展：在调优开始时加载历史精度缓存，在每次迭代时尝试从缓存中恢复评估结果

5.6子系统详细设计¶

5.6.1 精度缓存设计¶

精度缓存采用YAML格式存储，结构如下：

accuracy:
  <md5_hash_1>:
    accuracies:
      - dataset: dataset1
        accuracy: 0.85
      - dataset: dataset2
        accuracy: 0.90
    is_satisfied: true
  <md5_hash_2>:
    accuracies:
      - dataset: dataset1
        accuracy: 0.75
    is_satisfied: false

精度缓存的key为量化配置的MD5哈希值，value为评估结果（EvaluateResult对象序列化后的字典）。

5.6.2 历史索引设计¶

历史索引采用YAML格式存储，结构如下：

records:
  - practice_id: standing_high_0
    evaluation:
      accuracies:
        - dataset: dataset1
          accuracy: 0.85
      is_satisfied: true
    md5: <md5_hash_1>
    time: "2026-01-22 10:00:00"
  - practice_id: standing_high_1
    evaluation:
      accuracies:
        - dataset: dataset1
          accuracy: 0.75
      is_satisfied: false
    md5: <md5_hash_2>
    time: "2026-01-22 10:05:00"

历史索引记录每次迭代的配置ID、评估结果、MD5哈希值和时间戳。

5.6.3 缓存复用机制设计¶

配置匹配：使用MD5哈希值匹配量化配置，确保配置完全一致
缓存查找：在每次迭代时，首先计算当前配置的MD5哈希值，然后在精度缓存中查找匹配的配置
结果复用：如果找到匹配的配置，直接使用历史评估结果，跳过量化、服务化启动、预检查和评估步骤
缓存更新：如果未找到匹配的配置，执行量化、评估步骤后，将结果保存到精度缓存中

5.6.4 断点续调流程设计¶

历史检测：在调优开始时，检测save_path/history目录中是否存在accuracy.yaml文件
缓存加载：如果存在，加载精度缓存到内存中；如果不存在，创建空的精度缓存
迭代恢复：在每次迭代时，首先尝试从精度缓存中恢复评估结果，如果找到则复用，如果未找到则执行完整的量化、评估流程
缓存保存：每次迭代后，将评估结果保存到精度缓存中，确保下次启动时可以复用

5.7DFX属性设计¶

5.7.1性能设计¶

缓存加载性能：精度缓存加载到内存中，查找性能为O(1)，不会影响调优性能
MD5计算性能：MD5哈希值计算开销很小，不会影响调优性能
对现有特性的影响：断点续调功能是可选的，如果不使用相同的save_path，不会影响现有的调优流程

5.7.2升级与扩容设计¶

数据格式兼容性：精度缓存的数据格式设计考虑了版本兼容，支持跨版本使用
存储扩展性：精度缓存采用YAML格式，易于扩展和维护

5.7.3异常处理设计¶

文件读取异常：如果精度缓存文件读取失败，记录警告日志并创建空的精度缓存，不中断调优流程
数据解析异常：如果精度缓存数据格式错误，记录错误日志并创建空的精度缓存，不中断调优流程
存储异常：如果精度缓存保存失败，记录错误日志但不中断调优流程，下次启动时可能无法复用

5.7.4资源管理相关设计¶

内存占用：精度缓存加载到内存中，内存占用取决于缓存大小，通常为几MB到几十MB
磁盘I/O：精度缓存的读写操作频率较低，磁盘I/O开销很小
存储空间：精度缓存文件大小取决于评估结果数量，通常为几KB到几MB

5.7.5小型化设计¶

本特性不会影响小型化版本的规格，精度缓存功能是轻量级的，内存和存储占用都很小。

5.7.6可测性设计¶

测试应该涵盖以下方面：

功能测试：
首次调优：创建空的精度缓存
断点续调：从历史精度缓存中恢复评估结果
配置匹配：相同配置能够正确匹配
配置不匹配：不同配置不能匹配
边界值测试：
精度缓存为空
精度缓存包含大量记录（>1000条）
MD5哈希值冲突（理论上不可能，但需要测试）
异常场景测试：
精度缓存文件不存在
精度缓存文件格式错误
精度缓存文件读取失败
精度缓存文件保存失败
存储空间不足
性能测试：
精度缓存加载耗时测试
精度缓存查找耗时测试
大量记录的缓存性能测试

5.7.7 安全设计¶

5.7.7.1 安全设计确认¶

本Use Case的安全设计与Use Case一类似，主要关注文件操作的安全性，不涉及敏感数据的处理。

5.7.7.2 敏感数据分析¶

本Use Case不涉及敏感数据的处理，主要是对量化配置和评估结果进行存储和查询，不涉及用户认证、密钥管理等敏感操作。

5.7.7.3 设计实现¶

本Use Case的安全设计主要体现在：

文件权限控制：精度缓存文件使用安全的文件权限，防止未授权访问
数据完整性：使用MD5哈希值确保配置的唯一性和完整性
错误处理：错误信息不泄露敏感信息，仅记录必要的调试信息

5.8系统外部接口¶

本Use Case不会影响系统外部接口，主要是内部实现优化。用户可以通过使用相同的save_path来实现断点续调功能。

5.9自测用例设计¶

自测用例设计如下：

首次调优测试：
输入：新的save_path，不存在历史精度缓存
预期：创建空的精度缓存，正常执行调优流程
断点续调测试：
输入：相同的save_path，存在历史精度缓存
预期：加载历史精度缓存，在迭代时复用已评估的配置结果
配置匹配测试：
输入：相同的量化配置
预期：能够正确匹配，复用历史评估结果
配置不匹配测试：
输入：不同的量化配置
预期：不能匹配，执行完整的量化、评估流程
缓存文件异常测试：
输入：精度缓存文件不存在或格式错误
预期：记录警告日志，创建空的精度缓存，不中断调优流程
大量记录测试：
输入：精度缓存包含大量记录（>1000条）
预期：能够正常加载和查找，性能满足要求

6.Use Case三实现¶

6.1 Use Case描述¶

Use Case名称：调优策略内置专家经验

Use Case场景：

用户在配置自动调优时，不熟悉量化调优的搜索空间配置
用户希望系统能够根据模型结构类型（如MHA/MLA/DSA/SWA/GatedDeltaNet等）自动查表获取算法的搜索空间
系统根据模型结构类型自动获取推荐算法搜索空间，简化用户配置操作

对自动调优功能的影响：

需要提供基于专家经验的调优策略
需要实现模型结构类型识别功能
需要实现专家经验表机制
需要支持自动查表获取搜索空间

实现的特性：基于专家经验的调优策略

6.2特性设计思路¶

当前standing_high策略需要用户手动输入算法的搜索空间（anti_outlier_strategies），对于不熟悉量化调优的用户来说，配置复杂度较高。本特性创建一个新的独立调优策略模块expert_experience，支持根据模型结构类型（如MHA/MLA/DSA/SWA/GatedDeltaNet等）自动查表获取算法的搜索空间，无需用户手动输入搜索空间配置。

新策略模块可以复用standing_high策略的核心逻辑（如摸高算法），但是作为独立的策略实现，具有以下特点：

独立模块：创建新的策略目录msmodelslim/core/tune_strategy/expert_experience/，包含独立的策略配置和实现
模型结构类型识别：支持识别模型的注意力机制类型，如MHA（Multi-Head Attention）、MLA（Multi-Head Latent Attention）、DSA（Distributed Sparse Attention）、SWA（Sliding Window Attention）、GatedDeltaNet等
专家经验表：维护一个专家经验表，记录不同模型结构类型对应的推荐算法搜索空间
自动查表：根据模型结构类型自动查表获取算法的搜索空间，如果未找到匹配的类型，则使用默认的搜索空间
策略复用：可以复用standing_high策略的摸高算法逻辑，但通过专家经验表自动获取搜索空间，简化用户配置

6.3约束条件¶

模型结构支持：需要模型适配器能够识别并提供模型结构类型信息
专家经验表维护：需要维护专家经验表，记录不同模型结构类型对应的推荐算法搜索空间
策略注册：新策略需要在setup.py中注册，包括策略配置和策略实现的entry point
向后兼容：新策略不影响现有的standing_high策略，两者可以并存使用

6.4详细实现（从用户入口的模块级别或进程级别消息序列图）¶

处理流程¶

用户启动自动调优（使用expert_experience策略）
   │
   ▼
ExpertExperienceStrategy.__init__()
   │
   ├─→ 获取模型结构类型
   │   │
   │   └─→ ModelAdapter.get_attention_type()
   │
   ├─→ 在专家经验表中查找匹配的类型
   │   │
   │   └─→ ExpertExperienceTable.get_search_space(attention_type)
   │
   ├─→ 如果找到：使用查表结果作为anti_outlier_strategies
   │
   └─→ 如果未找到：使用默认搜索空间
   │
   ▼
创建StandingHighStrategy实例（复用摸高算法逻辑）
   │
   ├─→ 使用自动获取的anti_outlier_strategies
   │
   └─→ 执行standing_high策略的摸高算法
      │
      └─→ 使用自动获取的搜索空间进行调优

模块交互说明¶

ExpertExperienceStrategy：新的调优策略实现，负责根据模型结构类型自动获取算法的搜索空间
ExpertExperienceTable：专家经验表，维护不同模型结构类型对应的推荐算法搜索空间
ModelAdapter：模型适配器，提供模型结构类型信息
StandingHighStrategy：standing_high策略实现，可以被ExpertExperienceStrategy复用其核心逻辑

6.5子系统间接口（主要覆盖模块接口定义）¶

新增接口¶

ExpertExperienceStrategyConfig (msmodelslim/core/tune_strategy/expert_experience/strategy.py)
类型：StrategyConfig子类
功能：专家经验策略配置，继承StandingHighStrategyConfig的配置项，但anti_outlier_strategies字段为可选
字段：
- type: Literal["expert_experience"]，固定值
- anti_outlier_strategies: Optional[List[AutoProcessorConfigList]]，可选，如果未指定则自动获取
- template: ModelslimV1ServiceConfig，量化模板配置
- metadata: Metadata，元数据配置
ExpertExperienceStrategy (msmodelslim/core/tune_strategy/expert_experience/strategy.py)
类型：BaseTuningStrategy子类，ITuningStrategy实现
功能：专家经验策略实现，根据模型结构类型自动获取算法的搜索空间，然后复用standing_high策略的摸高算法逻辑
方法：
- __init__(config: StrategyConfig, dataset_loader: DatasetLoaderInfra)：初始化策略，自动获取搜索空间
- generate_practice(model: IModel, device: DeviceType) -> Generator[PracticeConfig, Optional[EvaluateResult], None]：生成量化配置，复用standing_high策略的逻辑
ExpertExperienceTable (msmodelslim/core/tune_strategy/expert_experience/expert_experience_table.py)
类型：类
功能：专家经验表，维护不同模型结构类型对应的推荐算法搜索空间
方法：
- get_search_space(attention_type: str) -> Optional[List[AutoProcessorConfigList]]：根据模型结构类型获取推荐算法搜索空间
- get_default_search_space() -> List[AutoProcessorConfigList]：获取默认算法搜索空间
ModelAdapter.get_attention_type() (msmodelslim/model/base.py)
类型：方法（需要模型适配器实现）
功能：获取模型的注意力机制类型
返回：str，如"MHA"、"MLA"、"DSA"、"SWA"、"GatedDeltaNet"等

新增目录结构¶

msmodelslim/core/tune_strategy/expert_experience/
├── __init__.py
├── strategy.py              # ExpertExperienceStrategyConfig和ExpertExperienceStrategy
└── expert_experience_table.py  # ExpertExperienceTable

策略注册¶

在setup.py中注册新策略：

"msmodelslim.strategy_config.plugins": [
    "standing_high=msmodelslim.core.tune_strategy.standing_high.strategy:StandingHighStrategyConfig",
    "expert_experience=msmodelslim.core.tune_strategy.expert_experience.strategy:ExpertExperienceStrategyConfig",
],
"msmodelslim.strategy.plugins": [
    "standing_high=msmodelslim.core.tune_strategy.standing_high.strategy:StandingHighStrategy",
    "expert_experience=msmodelslim.core.tune_strategy.expert_experience.strategy:ExpertExperienceStrategy",
],

6.6子系统详细设计¶

6.6.1 新策略模块设计¶

ExpertExperienceStrategy作为独立的新策略模块，设计要点：

策略配置：ExpertExperienceStrategyConfig继承StandingHighStrategyConfig，但anti_outlier_strategies字段改为可选
策略实现：ExpertExperienceStrategy在初始化时自动获取搜索空间，然后创建StandingHighStrategy实例复用其核心逻辑
策略复用：通过组合方式复用standing_high策略的摸高算法，而不是直接修改standing_high策略

6.6.2 模型结构类型识别设计¶

模型结构类型识别通过模型适配器实现，模型适配器需要实现get_attention_type()方法，返回模型的注意力机制类型。常见的模型结构类型包括：

MHA：Multi-Head Attention，标准的多头注意力机制
MLA：Multi-Head Latent Attention，多头潜在注意力机制（如DeepSeek-V3.2）
DSA：Distributed Sparse Attention，分布式稀疏注意力机制
SWA：Sliding Window Attention，滑动窗口注意力机制
GatedDeltaNet：门控Delta网络注意力机制

6.6.3 专家经验表设计¶

专家经验表采用字典结构，key为模型结构类型，value为推荐算法搜索空间。示例结构如下：

EXPERT_EXPERIENCE_TABLE = {
    "MHA": [
        [LinearProcessorConfig(...), ...],  # 策略1
        [LinearProcessorConfig(...), ...],  # 策略2
        ...
    ],
    "MLA": [
        [LinearProcessorConfig(...), ...],  # 策略1
        [LinearProcessorConfig(...), ...],  # 策略2
        ...
    ],
    "DSA": [
        [LinearProcessorConfig(...), ...],  # 策略1
        ...
    ],
    ...
}

专家经验表基于历史调优经验维护，记录不同模型结构类型对应的推荐算法搜索空间。

6.6.4 自动查表机制设计¶

类型识别：首先通过模型适配器获取模型结构类型
查表匹配：在专家经验表中查找匹配的类型
结果使用：如果找到匹配的类型，使用查表结果；如果未找到，使用默认搜索空间
策略复用：将自动获取的搜索空间传递给StandingHighStrategy，复用其摸高算法逻辑

6.6.5 策略实现方式¶

ExpertExperienceStrategy的实现方式：

初始化阶段：
检查用户是否指定了anti_outlier_strategies
如果未指定，通过模型适配器获取模型结构类型
在专家经验表中查找匹配的类型，获取推荐算法搜索空间
如果未找到，使用默认搜索空间
策略执行阶段：
创建StandingHighStrategyConfig，使用自动获取的anti_outlier_strategies
创建StandingHighStrategy实例，复用其摸高算法逻辑
调用StandingHighStrategy.generate_practice()执行调优

6.7DFX属性设计¶

6.7.1性能设计¶

查表性能：专家经验表查找性能为O(1)，不会影响调优性能
类型识别性能：模型结构类型识别开销很小，不会影响调优性能
对现有特性的影响：自动查表功能是可选的，如果用户手动指定了搜索空间，不会影响现有的调优流程

6.7.2升级与扩容设计¶

专家经验表扩展性：专家经验表采用字典结构，易于扩展和维护，可以随时添加新的模型结构类型
向后兼容性：如果用户手动指定了搜索空间，则优先使用用户指定的配置，保持向后兼容

6.7.3异常处理设计¶

类型识别异常：如果模型适配器无法识别模型结构类型，记录警告日志并使用默认搜索空间
查表异常：如果在专家经验表中未找到匹配的类型，记录警告日志并使用默认搜索空间
配置异常：如果查表结果格式错误，记录错误日志并使用默认搜索空间

6.7.4资源管理相关设计¶

内存占用：专家经验表加载到内存中，内存占用很小，通常为几KB
计算资源：查表操作的计算开销很小，不会对系统性能造成明显影响

6.7.5小型化设计¶

本特性不会影响小型化版本的规格，专家经验表功能是轻量级的，内存占用很小。

6.7.6可测性设计¶

测试应该涵盖以下方面：

功能测试：
用户指定搜索空间：使用用户指定的配置
自动查表成功：根据模型结构类型自动获取搜索空间
自动查表失败：使用默认搜索空间
类型识别失败：使用默认搜索空间
边界值测试：
专家经验表为空
专家经验表包含大量类型（>100种）
模型结构类型未知
异常场景测试：
模型适配器不支持类型识别
专家经验表格式错误
查表结果格式错误
性能测试：
查表耗时测试
类型识别耗时测试

6.7.7 安全设计¶

6.7.7.1 安全设计确认¶

本Use Case的安全设计与Use Case一类似，主要关注配置的安全性，不涉及敏感数据的处理。

6.7.7.2 敏感数据分析¶

本Use Case不涉及敏感数据的处理，主要是对模型结构类型和算法搜索空间进行查询和配置，不涉及用户认证、密钥管理等敏感操作。

6.7.7.3 设计实现¶

本Use Case的安全设计主要体现在：

配置验证：对查表结果进行配置验证，确保配置格式正确
错误处理：错误信息不泄露敏感信息，仅记录必要的调试信息

6.8系统外部接口¶

本Use Case会影响系统外部接口：

新策略配置接口：ExpertExperienceStrategyConfig中的anti_outlier_strategies字段为可选，用户可以不指定该字段，系统会自动根据模型结构类型获取
模型适配器接口：需要模型适配器实现get_attention_type()方法，提供模型结构类型信息
策略选择接口：用户可以在调优计划配置文件中选择使用"expert_experience"策略，而不是"standing_high"策略
策略注册接口：新策略需要在setup.py中注册entry point，包括策略配置和策略实现

6.9自测用例设计¶

自测用例设计如下：

策略选择测试：
输入：用户在调优计划配置文件中选择"expert_experience"策略
预期：系统创建ExpertExperienceStrategy实例，而不是StandingHighStrategy实例
用户指定搜索空间测试：
输入：用户在配置文件中指定了anti_outlier_strategies
预期：使用用户指定的配置，不进行自动查表
自动查表成功测试：
输入：模型结构类型为"MHA"，专家经验表中存在该类型
预期：自动获取对应的搜索空间，创建StandingHighStrategy实例并复用其逻辑
自动查表失败测试：
输入：模型结构类型为"Unknown"，专家经验表中不存在该类型
预期：使用默认搜索空间，记录警告日志，创建StandingHighStrategy实例并复用其逻辑
类型识别失败测试：
输入：模型适配器不支持类型识别
预期：使用默认搜索空间，记录警告日志，创建StandingHighStrategy实例并复用其逻辑
专家经验表异常测试：
输入：专家经验表格式错误
预期：使用默认搜索空间，记录错误日志，创建StandingHighStrategy实例并复用其逻辑
策略复用测试：
输入：使用expert_experience策略进行调优
预期：能够正确复用standing_high策略的摸高算法逻辑，调优结果与standing_high策略一致

7.可靠性&可用性设计¶

7.1冗余设计¶

自动调优加速特性采用以下冗余设计：

精度缓存冗余：精度缓存采用YAML格式持久化存储，即使调优过程中断，历史精度缓存仍然保留，支持断点续调
配置备份：每次迭代的量化配置都会保存到历史记录中，支持配置的备份和恢复
日志记录：详细的日志记录，支持问题定位和恢复

7.2故障管理¶

故障检测¶

精度评估失败检测：如果精度评估失败，记录错误日志并继续下一次迭代
量化失败检测：如果量化失败，记录错误日志并继续下一次迭代
服务化启动失败检测：如果模型服务化启动失败，记录错误日志并继续下一次迭代

故障隔离¶

迭代隔离：每次迭代独立执行，单次迭代失败不影响其他迭代
模块隔离：量化、评估、预检查等模块独立执行，单个模块失败不影响其他模块

故障恢复¶

自动恢复：通过断点续调机制，支持从历史精度缓存中恢复已评估的配置结果
手动恢复：用户可以通过使用相同的save_path重新启动调优，自动恢复历史精度缓存

7.3过载控制设计¶

迭代次数限制：支持设置最大迭代次数，防止无限迭代
超时控制：支持设置最大迭代耗时，防止调优过程无限运行
资源监控：监控内存、存储等资源使用情况，如果资源不足则停止调优

7.4升级不中断业务¶

配置兼容性：新版本的自动调优功能兼容旧版本的配置文件格式
数据兼容性：历史精度缓存的格式设计考虑了版本兼容，支持跨版本使用
接口兼容性：自动调优的接口设计考虑了向后兼容，旧版本的调用方式仍然有效

7.5人因差错设计¶

配置验证：对调优计划配置文件进行验证，如果配置错误则给出明确的错误提示
参数校验：对命令行参数进行校验，如果参数错误则给出明确的错误提示
日志提示：详细的日志记录，帮助用户理解调优过程和结果

7.6故障预测预防设计¶

资源监控：监控内存、存储等资源使用情况，提前预警资源不足
性能监控：监控调优过程的性能指标，提前预警性能问题
异常检测：检测异常情况（如精度评估失败、量化失败等），提前预警潜在问题

8.特性非功能性质量属性相关设计¶

8.1可测试性¶

重点从特性在测试的方向和规格上展开描述，说明在测试人员测试时应该测哪些方面，需要注意哪些边界值、异常值、异常场景。

8.2可服务性¶

对特性提供丰富的可维护可服务的措施，提供对特性的使用、维护、问题处理等的完整资料说明。

8.3可演进性¶

重点从特性架构、功能的可演进性上展开描述。

8.4开放性¶

重点描述特性的对外接口开放性，包括接口的规范性，比如符合 __SQL 2011__ 标准。

8.5兼容性¶

重点描述特性是否会影响系统的前向兼容性，即旧功能在升级新版本之后是否可使用，使用行为是否和旧版本保持一致。

8.6可伸缩性/可扩展性¶

有效满足系统容量变化的要求，包括数据库节点的扩缩容、数据库服务器本身的扩缩容。

8.7可维护性¶

重点从特性的可维护性展开描述，比如诊断视图、 __log__ 打印等。

8.8资料¶

参考下表，评估特性会涉及到的各类资料的修改点，并说明具体修改点。

类别	手册名称	是否涉及（Y/N）	具体修改或新增内容简述
白皮书	技术白皮书	N	XX章节新增XX技术
产品文档	产品描述	Y	技术指标刷新为XX
	特性描述	Y	新增XX特性
	编译指导书	Y	XXX
	安装指南	Y	安装集群章节需刷新XX场景
	管理员指南	N	XXX
	开发者指南（包括开发教程、SQL参考、系统表和系统视图、GUC参数说明、错误码说明、API参考等）	Y	在XX章节增加XXX功能
	工具参考	Y	新增XX工具
	术语表	Y	新增术语XX
入门	简易教程	N	XXX

9.数据结构设计（可选）¶

自动调优加速特性主要使用YAML格式存储数据，包括：

精度缓存 (accuracy.yaml)：
结构：字典格式，key为MD5哈希值，value为评估结果
用途：存储已评估的量化配置和精度结果，支持断点续调
历史索引 (history.yaml)：
结构：列表格式，每个元素包含配置ID、评估结果、MD5哈希值和时间戳
用途：记录每次迭代的配置和评估结果，支持历史查询
量化配置 (practice configs)：
结构：YAML格式的PracticeConfig对象
用途：存储每次迭代的量化配置，支持配置的备份和恢复

10.参考资料清单¶

msModelSlim工具文档：
自动调优功能使用指南
调优计划配置文件格式说明
API参考文档
相关代码实现：
msmodelslim/app/auto_tuning/application.py：自动调优应用层实现
msmodelslim/core/tune_strategy/standing_high/strategy.py：standing_high策略实现
msmodelslim/infra/evaluation/precheck/garbled_text_rule.py：乱码检测预检查实现
msmodelslim/infra/yaml_practice_history_manager.py：历史管理模块实现
设计原则：
接口标准化原则
数据格式统一原则
错误处理规范原则