自动调优使用说明

功能说明

自动调优功能面向需要精确控制量化后模型精度的用户，通过自动化的量化配置搜索和评估流程，帮助用户找到满足精度要求的量化方案。本功能支持根据用户指定的精度需求，自动尝试不同的量化配置，并通过评估服务验证量化后的模型精度，最终输出满足需求的量化模型。

工具使用说明

前置依赖

使用自动调优功能前，需要完成以下工具的安装：

vLLM-Ascend：用于量化后模型拉起服务化。自动调优功能在评估量化后模型精度时，需要使用 vLLM-Ascend 将量化后的模型以服务化方式启动。建议直接使用官方提供的镜像进行安装，详细安装说明请参考 vLLM-Ascend 安装文档。
AISbench：用于量化后模型测试。自动调优功能使用 AISbench 对量化后的模型进行精度评估和测试。AISbench 主页：https://gitee.com/aisbench/benchmark。完成安装后，还需要参考 AISbench 指南准备对应的数据集。

请确保上述工具已正确安装并配置，否则自动调优功能将无法正常进行模型评估。

模型支持

重要提示：在使用自动调优功能之前，请确保使用的模型是支持的。需要同时满足以下两个条件：

量化工具支持：模型需要在量化工具的支持列表中，可以通过查看 msmodelslim/config/config.ini 中的 ModelAdapter 确定模型是否支持，其中包含了当前支持的模型适配器及其支持的模型名。如果模型不在支持列表中，需要先进行模型适配，实现相应的模型接口后才能使用自动调优功能。
vLLM-Ascend 支持：模型需要被 vLLM-Ascend 支持，能够将量化后的模型以服务化方式启动。请先确定 vLLM-Ascend 是否支持量化后模型服务化拉起。

启动命令

自动调优功能通过命令行方式启动，正确安装 msModelSlim 工具及上述前置依赖后，可以通过如下命令运行：

msmodelslim tune [ARGS]

例如，使用自动调优功能对 Qwen3-32B 模型进行调优，则调优命令如下，其中${MODEL_PATH}为Qwen3-32B原始浮点权重路径，${SAVE_PATH}为用户自定义的调优结果保存路径，${CONFIG}为调优配置文件路径。

msmodelslim tune --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --config ${CONFIG} --device npu --model_type Qwen3-32B --trust_remote_code True

建议：为了在精度达标时将最终量化配置Yaml保存到实践库，建议设置环境变量 MSMODELSLIM_CUSTOM_PRACTICE_REPO。例如：

export MSMODELSLIM_CUSTOM_PRACTICE_REPO=/path/to/your/practice/repo
msmodelslim tune --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --config ${CONFIG} --device npu --model_type Qwen3-32B --trust_remote_code True

用户输入命令后，系统将根据配置文件中指定的精度需求，自动尝试不同的量化配置，并对量化后的模型进行评估，直到找到满足精度要求的量化方案或达到最大迭代次数/超时时间。

接口说明

#全局调用命令行
msmodelslim tune --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --config ${CONFIG} --device ${DEVICE} --model_type ${MODEL_TYPE} --timeout ${TIMEOUT} --trust_remote_code ${TRUST_REMOTE_CODE}

参数名称	解释	是否可选	范围
model_path	模型路径	必选	类型：Str
save_path	调优结果保存路径	必选	类型：Str
config	调优配置文件路径	必选	1. 类型：Str 2. 配置文件路径，必须为完整的文件路径 3. 配置文件格式为yaml，用户需要自定义配置文件，可以参考 `msmodelslim/docs/功能指南/自动调优/example` 目录下的配置文件格式进行自定义
device	量化设备	可选	1. 类型：Str 2. 参考值：'npu','npu:0,1,2,3','cpu' 3. 默认值为"npu"（单设备） 4. 指定多个设备时（如：'npu:0,1,2,3'），系统启动DP逐层量化，请确定配置的算法是否支持分布式执行
model_type	模型名称	可选	1. 类型：Str 2. 默认值为"default" 3. 大小写敏感，请参考大模型支持矩阵
timeout	调优超时时间	可选	1. 类型：Str 2. 格式：`<天数>D`、`<小时数>H` 或 `<天数>D<小时数>H` 3. 示例：'1D'、'2H'、'3D4H' 4. 默认值：None（无超时限制）
trust_remote_code	是否信任自定义代码	可选	1. 类型：Bool，默认值：False 2. 请确保加载的自定义代码文件的安全性，设置为True有安全风险。
h, help	命令行参数帮助信息	可选	-

注意：

模型支持：使用自动调优功能前，请确保模型在支持列表中。可以通过查看 msmodelslim/config/config.ini 中的 ModelAdapter 确定模型是否支持。如果模型不支持，需要先进行模型适配。
自定义配置文件：用户需要自定义调优配置文件，配置文件格式为yaml。用户可以参考 msmodelslim/docs/功能指南/自动调优/example 目录下的配置文件格式进行自定义。配置文件的详细说明请参考自动调优配置协议说明。精度目标设置与不同模型的服务化参数配置都需要在配置文件中进行修改。
调优过程会自动尝试不同的量化配置，每次尝试都会对量化后的模型进行评估，直到找到满足所有精度需求的量化方案。
调优历史会保存在 save_path/history 目录中，用户可以通过查看历史记录了解调优过程。

如果需要打印调优运行日志，可通过以下环境变量进行设置。

环境变量	解释	是否可选	范围
MSMODELSLIM_LOG_LEVEL	打印同级及以上日志	可选	INFO(默认),DEBUG
MSMODELSLIM_CUSTOM_PRACTICE_REPO	自定义最佳实践库配置文件保存路径	可选	类型：Str。设置此环境变量后，当精度达标时会将最终量化配置Yaml保存到指定路径；如果不设置，只能在 `save_path/history` 中找到量化配置

调优流程说明

自动调优功能的工作流程如下：

创建模型适配器：根据指定的模型类型创建模型适配器，确保指定的模型可支持。
初始化调优服务：根据指定的配置文件路径加载调优计划，创建量化配置生成器。
开始迭代调优：记录调优开始时间和超时时间，进入迭代循环：

每次迭代包含以下步骤：
- 检查超时：在每次迭代开始时检查是否超过最大迭代耗时，如果超时则停止迭代。
- 生成量化配置Yaml：通过量化配置生成器生成量化配置（Yaml格式的practice）。首次迭代时传入None，基于初始策略和精度需求生成配置；后续迭代时传入上一次的精度评估结果，根据评估结果生成新的配置。
- 量化模型：根据生成的量化配置Yaml，对模型进行量化，量化权重临时存入用户指定路径。
- 评估模型精度：使用 vLLM-Ascend 将量化后的模型以服务化方式启动，然后使用 AISbench 对量化后的模型进行精度评估和测试，产生精度指标。
- 保存调优历史：将本次迭代的量化配置Yaml和精度指标保存到调优历史。
- 判断是否继续：将评估得到的精度指标作为下一次迭代的输入。如果策略判断精度已达标，会抛出StopIteration异常，停止迭代；否则继续下一次迭代。
停止条件：迭代会在以下任一条件满足时停止：
- 精度指标达到用户指定的目标精度要求
- 达到最大迭代次数
- 达到最大迭代耗时（由 --timeout 参数指定）
保存结果：
- 最终Yaml：当精度达标时，如果设置了环境变量 MSMODELSLIM_CUSTOM_PRACTICE_REPO，会将满足精度要求的最终量化配置Yaml保存到该环境变量指定的路径；如果不设置该环境变量，只能在 save_path/history 目录中找到量化配置。如果因达到最大迭代次数或超时而停止，则不会保存到最佳实践库。
- 最终权重：最后一次迭代生成的量化权重保存在用户指定的路径。