服务化实测寻优使用指南¶

简介¶

服务化实测寻优（msmodeling optix）是一项基于 PSO 粒子寻优算法的服务化参数实测寻优功能，支持在 VLLM 和 MindIE 等真实服务框架上自动搜索，获取符合时延要求的最佳吞吐参数组合。

适用对象与阅读路径¶

本文适用于需要对 vLLM、MindIE 服务化部署参数进行自动寻优的性能工程师和部署工程师。建议按以下顺序阅读：

先阅读推荐实践：环境与部署栈与工具安装，在 uv 虚拟环境中安装 msmodeling，并确认系统已部署 vLLM/MindIE。
再阅读使用前准备与快速入门，确认服务框架与测评工具可独立运行。
阅读命令参数说明与配置文件说明（含 [deploy]），完成一次默认寻优。
遇问题时查阅环境变量与排障；根据业务 SLO 调整搜索空间请参见输出结果文件说明。

工具主要包括两大核心功能模块：

参数寻优模块：利用PSO粒子寻优算法自动生成服务化参数组合，不断逼近最优解；同时，Early Rejection算法通过理论建模、调优经验及部分实测数据对服务化参数完成早期评估；
参数验证模块：自动化启动服务化进程与测评工具进程，进行参数测试，获取性能结果。当前已支持的测评工具包括 AISBench、vllm_benchmark。

[!NOTE]

旧版 benchmark 工具将逐步由 AISBench 替代，推荐优先使用 AISBench。若当前环境仍保留 vllm_benchmark 适配能力，可按本文对应章节配置。

服务化实测寻优能够基于以上功能模块，自动推荐吞吐较优的服务化参数组合。

目前工具已基于llama3-8b和qwen3-8b通过验证，理论上不限制支持模型范围，后续计划扩大支持范围的验证。

基本概念

VLLM、MindIE：服务化框架，支持对模型进行服务化部署。
vllm_benchmark、AISBench：推理性能评测工具，支持对服务化进行推理性能评测。

产品支持情况 ¶

[!NOTE]

昇腾产品的具体型号，请参见《昇腾产品形态说明》。

产品类型	是否支持
Atlas 350 加速卡	x
Atlas A3 训练系列产品/Atlas A3 推理系列产品	√
Atlas A2 训练系列产品/Atlas A2 推理系列产品	√
Atlas 200I/500 A2 推理产品	√
Atlas 推理系列产品	√
Atlas 训练系列产品	x

[!NOTE]

针对Atlas A2 训练系列产品/Atlas A2 推理系列产品，当前仅支持该系列产品中的Atlas 800I A2 推理服务器。针对Atlas 推理系列产品，当前仅支持该系列产品中的Atlas 300I Duo 推理卡+Atlas 800 推理服务器（型号：3000）。

使用前准备¶

环境与部署栈

层面	推荐做法	说明
msmodeling / OptiX	必须使用 uv 虚拟环境安装	安装会带上 `torch`、`transformers` 等，供 TensorCast 仿真使用，不是 OptiX 寻优用的；写进系统 Python 会冲掉部署栈里的同名包
vLLM / MindIE / 测评工具	默认使用系统环境	假定机器上已按官方文档完成服务化与测评工具部署，一般不必再建部署 venv

OptiX 拉起服务或测评子进程时，会从 PATH、PYTHONPATH 里去掉 msmodeling 虚拟环境的痕迹，再用系统 PATH 找 vllm、mindieservice_daemon、ais_bench 等命令。不必手改子进程环境变量，也不必为部署栈单独再建一个 venv。

若命令不在默认 PATH、或机器上装了多份运行时，可通过 OPTIX_DEPLOY_PATH 或 config.toml 里的 [deploy] path_prefix 指定部署根目录。

完整步骤见推荐实践：环境与部署栈；仿真侧通用安装见《环境搭建指南》。

部署栈准备

在系统环境，或 [deploy] 所指向的路径下，确认服务化与测评工具能正常运行。可参考 VLLM Server、MindIE Service，以及 AISBench 测评工具部署。

工具安装¶

[!IMPORTANT] OptiX 必须装在虚拟环境里。在仓库根目录执行 uv sync 即可自动创建 .venv 并完成安装。

安装 msmodeling 会同时装上 torch、transformers 等包。这些依赖给 TensorCast 仿真用，真机寻优并不靠它们。如果在系统 Python 里安装 msmodeling，往往会改掉系统里原有的 torch、transformers 版本，结果是：

vLLM、MindIE 起不来或推理报错

和 Ascend 推理栈上已验证的版本对不上

同机其他部署工具也跟着坏掉

只在 uv 虚拟环境里装 msmodeling；vLLM、MindIE、测评工具继续用系统里现成的那套。

寻优工具集成在 msmodeling 仓库根目录。按以下步骤安装：

git clone https://gitcode.com/Ascend/msmodeling.git   # 如已拉取，则不用重复拉取
cd msmodeling
uv sync

[!NOTE] uv sync 会自动创建 .venv、以可编辑模式安装 msmodeling（含 msmodeling optix CLI），无需 uv venv 或 pip install -e .。若当前分支未包含 OptiX 源码目录，请切换到包含 OptiX 代码的发布分支或使用对应发布包；仅复制文档文件无法提供 msmodeling optix 命令。 [!WARNING] 不要在 msmodeling 虚拟环境里 pip install vllm、mindie_llm 等部署包。也不要在未建 venv 的系统 Python 里安装 msmodeling。详见推荐实践：环境与部署栈。

推荐实践：环境与部署栈 ¶

典型场景：系统里已经部署好 vLLM 或 MindIE，msmodeling 单独装在 uv 虚拟环境里。

① 安装 msmodeling（uv）

cd /path/to/msmodeling
uv sync

验证：uv run msmodeling optix --help

② 确认系统部署栈可用

可先 deactivate 退出 msmodeling venv，再检查系统里的命令，例如：

which vllm
vllm --help

which vllm 应落在系统路径，例如 /usr/local/bin/vllm，而不是 msmodeling 的 .venv/bin/vllm。

MindIE 场景请确认 mindieservice_daemon 可用，或 MIES_INSTALL_PATH 指向的安装正确。

③ 可选：指定部署根目录

仅当系统 PATH 找不到正确命令时再配：

export OPTIX_DEPLOY_PATH=/path/to/custom-deploy-root

也可写入 optix/config.toml，字段说明见配置文件说明中的 [deploy]：

[deploy]
path_prefix = "/path/to/custom-deploy-root"

④ 在 msmodeling venv 中运行 OptiX

source /path/to/msmodeling/.venv/bin/activate
msmodeling optix -e vllm -b ais_bench

上一步若设置了 OPTIX_DEPLOY_PATH，保持 export 即可。

⑤ 确认日志

启动日志里出现 [optix/env] ... 部署命令 vllm → /usr/local/bin/vllm 一类信息，说明子进程走的是系统部署栈，而不是 msmodeling venv。

[!NOTE] 默认不必再建部署专用 venv。只有 PATH 布局特殊时才需要 OPTIX_DEPLOY_PATH 或 [deploy] path_prefix。

工具卸载¶

在 msmodeling 虚拟环境中卸载：

pip uninstall msmodeling

快速入门¶

确认 which vllm 不在 msmodeling venv 里，vLLM 场景示例：
```
source /path/to/msmodeling/.venv/bin/activate
which vllm
```
正确示例：/usr/local/bin/vllm。错误示例：/path/to/msmodeling/.venv/bin/vllm，见环境变量与排障。
完成使用前准备与推荐实践：环境与部署栈章节要求。
修改配置文件：启动寻优前需用户按照实际情况配置 config.toml，包括寻优参数、测评工具参数、服务化参数。参考配置文件说明章节完成配置。也可通过 -c 参数将配置文件放在任意路径，具体见命令参数说明。
启动寻优：完成上述步骤后，执行以下命令，一键启动自动寻优：
```
msmodeling optix
```
默认执行的是基于AISBench的vLLM服务化参数寻优。
查看结果：寻优时间由模型大小和数据集大小决定，一般在4~8小时完成，结束后会生成data_storage_*.csv的文件并保存在当前目录的result/store子目录中，其中记录了各组参数的性能，详细介绍请参见输出结果文件说明。

命令参数说明¶

功能说明

工具结合参数验证、参数寻优模块，通过真机实测给出可靠的服务化参数推荐值。

注意事项

启动寻优前，确认 vllm 或 mindie 以及 ais_bench 或 vllm_benchmark 已在系统部署环境里能跑，且没有装进 msmodeling 虚拟环境。
config.toml 中的模型路径、端口、数据集路径和服务启动参数需与实际部署环境保持一致。
自动寻优会反复拉起服务并执行测评，耗时通常较长，建议在独占或资源稳定的环境中运行。
环境隔离异常时，日志前缀 [optix/env] 会给出原因与修复建议，详见环境变量与排障。

命令格式

msmodeling optix [options]

参数说明

参数	可选/必选	说明
-lb或--load_breakpoint	可选	控制是否从断点恢复寻优过程，配置本参数表示开启，默认未配置表示关闭。
--backup	可选	决定是否在寻优过程中备份数据，配置本参数表示开启备份，可取值： •True：开启备份 •False：不开启备份。默认值为`False`。
-b或--benchmark_policy	可选	指定测评工具，可取值： •vllm_benchmark：使用vllm_benchmark作为测试工具 •ais_bench：使用AISBench作为测试工具默认值为`ais_bench`。用户需自行选择适配的推理框架以及测试框架。
-e或--engine	可选	指定推理框架，可取值： •vllm：使用VLLM作为推理框架 •mindie：使用MindIE作为推理框架默认值为`vllm`。
-c或--config	可选	指定自定义配置文件路径（TOML格式）。支持以下三种形式： •绝对路径：直接使用指定路径； •相对路径（含目录分隔符）：相对于当前工作目录解析； •仅文件名：在当前工作目录下查找。默认不指定，工具按预设路径顺序自动搜索配置文件。指定文件必须为有效 TOML 格式，且具有最高配置优先级。

使用示例（vllm服务化参数寻优）

修改配置文件：启动寻优前需用户按照实际情况配置 config.toml，包括寻优参数、测评工具参数、服务化参数。参考配置文件说明章节完成配置。
如果需要设置环境变量作用于vllm/mindie服务，只需在运行工具前设置环境变量即可，例如：
```
export ASCEND_RT_VISIBLE_DEVICES=0
```
工具会在寻优过程中自动设置。
前置条件准备就绪后，执行以下命令，一键启动自动寻优：
```
msmodeling optix -e vllm
```
若在VLLM场景下使用vllm_benchmark测评工具可参考
```
msmodeling optix -e vllm -b vllm_benchmark
```

使用示例（mindie服务化参数寻优）

修改配置文件：启动寻优前需用户按照实际情况配置 config.toml，包括寻优参数、测评工具参数、服务化参数。参考配置文件说明章节完成配置。
如果需要设置环境变量作用于vllm/mindie服务，只需在运行工具前设置环境变量即可，例如：
```
export ASCEND_RT_VISIBLE_DEVICES=0
```
工具会在寻优过程中自动设置。
前置条件准备就绪后，执行以下命令，一键启动自动寻优：
```
msmodeling optix -e mindie
```

使用示例（指定自定义配置文件）

如果配置文件不在默认搜索路径中，可通过 -c 参数显式指定：

# 绝对路径
msmodeling optix -c /data/configs/my_config.toml

# 当前目录下的文件名
msmodeling optix -c my_config.toml

# 相对路径
msmodeling optix -e vllm -b vllm_benchmark -c ../configs/vllm_config.toml

指定的配置文件具有最高优先级，会覆盖默认路径下的同名配置项。

输出说明

自动寻优完成后，输出csv格式的结果文件，在当前目录下生成result/store文件夹存放。详情介绍请参见输出结果文件说明。

输出结果文件说明¶

输出csv中的每一行对应一组参数，前四列为性能指标。用户可以根据需求筛选满足要求的性能行，将VLLM/MindIE参数以及vllm_benchmark/AISBench的参数改为csv中的数据即可。

字段	说明
generate_speed	吞吐。
time_to_first_token	TTFT 时延，单位为秒。
time_per_output_token	TPOT 时延，单位为秒。
success_rate	测试返回请求成功率。
throughput	测试吞吐，单位为请求数/秒。
CONCURRENCY	并发数。
REQUESTRATE	发送速率。
error	记录这次参数没有正常执行的原因，在发送错误时记录。
backup	数据记录地址，当开启--backup时记录。
real_evaluation	标记数据是否由真实测试结果得到。false代表该组数据由gp模型预测得到。
fitness	寻优算法优化值，该值越小代表该组参数效果越好
num_prompts	记录这次寻优测评工具发送的请求数。

其余列为对应的VLLM或MindIE的config.toml参数。

附录¶

配置文件说明¶

部署环境 [deploy]

子进程拉起 vLLM、MindIE 或测评工具时，OptiX 会先去掉 msmodeling 虚拟环境相关变量，再按下面配置找部署根目录，bin/ 下应有 vllm、ais_bench 等：

参数	必选	说明
`path_prefix`	可选	部署根目录，用来覆盖默认系统 PATH。不设则剥离 msmodeling venv 后直接走系统 PATH，效果同目录级的 `OPTIX_DEPLOY_PATH`

与 optix/config.toml 注释一致的写法：

# 仅当系统 PATH 找不到 vllm、ais_bench 等时再打开
[deploy]
# path_prefix = "/path/to/custom-deploy-root"

寻优参数： n_particles （寻优种子数）、iters （迭代轮次数）、 tpot_slo （time_per_output_token的限制时延）等。用户可根据预估时间来自行配置种子和迭代次数。我们单个种子使用时间为拉起服务+测试数据。比如用户拉起服务+完成测试需9-10min，且愿意用8小时来进行寻优，则一共可跑约50个种子，建议用户配置5 * 10。设置种子数为10，迭代次数为5，建议用户配置种子数为迭代次数的2倍左右。

注意：以下寻优参数均为必填项，不可删除或省略，否则运行时会报错。

参数	可选/必选	说明
n_particles	必选	寻优种子数，即一组生成的参数组合数，取值范围为：1-1000的整数。建议设为 15 ~ 30。
iters	必选	迭代轮次数，取值范围为：1-1000的整数。建议设为 5 ~ 10。
ttft_penalty	必选	`time_to_first_token` 即首token时延超时惩罚系数，若对 `time_to_first_token` 没有时延要求设置为0即可。取值范围：【0, 100】。建议设为1。
tpot_penalty	必选	`time_per_output_token` 即非首token时延超时惩罚系数，若对`time_per_output_token`没有时延要求设置为0即可。取值范围：【0, 100】。建议设为1。
success_rate_penalty	必选	请求成功率惩罚系数，取值范围为：1-1000的整数。建议设为5。
ttft_slo	必选	`time_to_first_token`的限制时延。如对`time_to_first_token`限制为2s内，则设为2，取值范围：(0, 100]，单位s。
tpot_slo	必选	`time_per_output_token`的限制时延。如对`time_per_output_token`限制为50ms内，则设为0.05，取值范围：(0, 100]，单位s。
service	必选	标注多机启动时为主机或从机，多机场景下从机设为 `slave`，可取值： •master：主机 •slave：从机，默认值为`master`。

测评工具参数：若使用AISBench测评，需修改以下参数，可以参照AISBench 快速入门进行修改。

参数	说明
models	指定模型任务，可根据模型配置说明进行配置。
datasets	指定数据集任务，可根据数据集准备指南进行配置。
mode	运行模式。可根据运行模式说明进行配置。
num_prompts	控制运行数据集的条数，`mode`为`perf`时有效。

若使用vllm_benchmark测评，需修改以下参数：

参数	可选/必选	说明
host	必选	主机ip，需与`[vllm.command]`中的`host`保持一致，可设为`127.0.0.1`。
port	必选	端口号，需与`[vllm.command]`中的`port`保持一致。
model	必选	模型路径，需与`[vllm.command]`中的`model`保持一致。
served_model_name	必选	模型名称，需与`[vllm.command]`中的`served_model_name`保持一致。
dataset_name	必选	数据集名称。
dataset_path	必选	数据集路径。
num_prompts	必选	控制运行数据集的条数。取值范围：1-10000的整数。
others	可选	拼接其他参数，注意参数间使用空格分隔，参数内部不能留有空格。如`--ignore-eos --custom-output-len 1500`。默认为空。

VLLM服务化参数：使用VLLM框架时，需修改config.toml中的[vllm.command]参数，如：

[vllm.command]
host = "127.0.0.1"
port = "8000"
model = "/workspace/vllm/models/llama-2-7b-chat-hf"
served_model_name = "llama-2-7b-chat-hf"
others = ""

参数	可选/必选	说明
host	必选	主机ip，需与`[vllm_benchmark.command]`中的`host`保持一致，可设为`127.0.0.1`。
port	必选	端口号，需与`[vllm_benchmark.command]`中的`port`保持一致。
model	必选	模型路径，需与`[vllm_benchmark.command]`中的`model`保持一致。
served_model_name	必选	模型名称，需与`[vllm_benchmark.command]`中的`served_model_name`保持一致。
others	可选	拼接其他参数，注意参数间使用空格分隔，参数内部不能留有空格。如：`--tensor-parallel-size 2 --no-enable-prefix-caching`。默认为空。

VLLM自定义参数寻优¶

寻优工具支持通过 [[vllm.target_field]] 添加 VLLM 参数参与寻优。根据参数生效方式不同，配置方式分为两类：

VLLM 环境变量：只需在 [[vllm.target_field]] 中声明，且 config_position = "env"。工具会在每轮寻优启动服务前自动写入同名大写环境变量，不需要写入 [vllm.command] 的 others。
VLLM 命令行参数：先在 [[vllm.target_field]] 中声明，再在 [vllm.command] 的 others 中通过变量引用拼接到启动命令。

变量引用规则：在 others 中使用 $字段名大写 的格式引用寻优字段，工具运行时会自动将其替换为当前迭代的实际值。

示例一：VLLM 环境变量寻优¶

如果待寻优参数本身是 VLLM 环境变量，只需添加到 [[vllm.target_field]]。例如：

[[vllm.target_field]]
name = "VLLM_WORKER_MULTIPROC_METHOD"
config_position = "env"
dtype = "enum"
dtype_param = ["fork", "spawn"]
value = "fork"

此类参数无需在 [vllm.command] 的 others 中引用，保持 others = "" 或仅填写其他命令行参数即可。

示例二：命令行枚举数值参数（以 `gpu_memory_utilization` 为例）¶

第一步：声明寻优字段。

[[vllm.target_field]]
name = "GPU_MEMORY_UTILIZATION"
config_position = "env"
dtype = "enum"
dtype_param = [0.9, 0.91, 0.92]
value = 0.9

第二步：在 [vllm.command] 的 others 中引用变量。

[vllm.command]
# ... 其他必填参数 ...
others = "--gpu-memory-utilization $GPU_MEMORY_UTILIZATION"

示例三：命令行开关型/复合字符串参数（以编译配置 `--compilation-config` 为例）¶

当参数本身是一段完整的 CLI 字符串时，可将"不启用"（空字符串 ""）和"启用"两种形态作为枚举候选值。工具遇到空字符串时会自动跳过，不向启动命令追加任何内容。

第一步：声明寻优字段。

注意：TOML 字符串使用双引号 " 作为边界符，若字符串内容中包含双引号，需使用 \" 转义，否则会解析报错。

[[vllm.target_field]]
name = "COMPILATION_CONFIG"
config_position = "env"
dtype = "enum"
dtype_param = ["", "--compilation-config '{\"cudagraph_mode\": \"FULL_DECODE_ONLY\"}'"]
value = "--compilation-config '{\"cudagraph_mode\": \"FULL_DECODE_ONLY\"}'"

第二步：在 [vllm.command] 的 others 中引用变量。

[vllm.command]
# ... 其他必填参数 ...
others = "$COMPILATION_CONFIG"

MindIE服务化参数：可以参考MindIE server 配置参数说明进行修改。服务化参数可直接指定参数的范围，如配置服务化参数 max_batch_size 的寻优搜索空间为 10 ~ 400，则可设置：

[[mindie.target_field]]
name = "max_batch_size" # 服务化参数名称
config_position = "BackendConfig.ScheduleConfig.maxBatchSize" # 服务化参数在MindIE Server中的位置
min = 10 # 最小值
max = 400 # 最大值
dtype = "int" # 数据类型

此外，也可设置参数与另一参数相关，如 max_prefill_batch_size 与 max_batch_size 相关，max_prefill_batch_size = ratio * max_batch_size (0 < ratio < 1)则可设置：

[[mindie.target_field]]
name = "max_prefill_batch_size"
config_position = "BackendConfig.ScheduleConfig.maxPrefillBatchSize"
min = 0
max = 1
dtype = "ratio"
dtype_param = "max_batch_size" # 表明该参数与max_batch_size相关

此外，target_field 支持的所有 dtype 类型如下：

分类	dtype	含义	dtype_param 格式
基础类型	`int`	在 [min, max] 内取整数	—
基础类型	`float`	在 [min, max] 内取浮点数	—
基础类型	`bool`	布尔开关（参数值 > 0.5 时为 true）	—
基础类型	`enum`	从候选列表中选值（支持数值或字符串）	候选值列表，如 `[1, 2, 4, 8]`
基础类型	`range`	按步长在 [min, max] 内枚举	步长整数，如 `10`
二元派生	`ratio`	`int(比例 × target)`	依赖字段名（字符串），如 `"max_batch_size"`
二元派生	`share`	`target.min + target.max - target.value`（互补）	依赖字段名（字符串）
二元派生	`factories`	`product ÷ target`	`{"target_name": "字段名", "product": 值, "dtype": "int"}`
二元派生	`times`	`product × target`	`{"target_name": "字段名", "product": 值, "dtype": "int"}`
三元派生	`ternary_factories`	`product ÷ (field_a × field_b)`	`{"target_names": ["A", "B"], "product": 值, "dtype": "int"}`
三元派生	`ternary_times`	`product × field_a × field_b`	`{"target_names": ["A", "B"], "product": 值, "dtype": "int"}`

[!note] 说明

派生类型字段（factories / times / ternary_factories / ternary_times）的值由依赖关系自动推导，不参与粒子群搜索，需将 min 和 max 均设为 0。若任一依赖字段值为 0（除法场景）或 None/NaN（乘法场景），本轮推导跳过，字段保持原值并输出警告日志。

三元派生类型使用示例

场景一：tp、pp 为可调参数，dp 由总卡数（16）自动推导（dp = 16 ÷ (tp × pp)）：

[!note] 约束说明

ternary_factories 要求各依赖字段的乘积能合法推出派生字段。对于 dtype = "int"，product 必须能被依赖字段乘积整除，否则会触发优先级修复。

int 类型内置保护：结果不足 1 或不能整除时优先尝试修复源字段；修复失败后按 min/max 降级处理，并输出 WARNING。

显式设置范围：在 dtype_param 中配置 min_value / max_value 可覆盖上下界。

最佳实践：限制 tp、pp 的枚举候选使乘积可整除 product，避免依赖降级处理。

# 方式一（最佳实践）：限制 tp 和 pp 的枚举候选值，保证 tp × pp ≤ 16
[[mindie.target_field]]
name = "tp"
config_position = "BackendConfig.ModelDeployConfig.ModelConfig.0.tp"
min = 0
max = 1
dtype = "enum"
dtype_param = [1, 2, 4, 8]   # tp 最大为 8

[[mindie.target_field]]
name = "pp"
config_position = "BackendConfig.ModelDeployConfig.ModelConfig.0.pp"
min = 0
max = 1
dtype = "enum"
dtype_param = [1, 2]          # pp 限制为 1 或 2，保证 tp × pp 最大 8 × 2 = 16 不超出

[[mindie.target_field]]
name = "dp"
config_position = "BackendConfig.ModelDeployConfig.ModelConfig.0.dp"
min = 0
max = 0
dtype = "ternary_factories"
dtype_param = {target_names = ["tp", "pp"], product = 16, dtype = "int"}
# 示例：tp=4, pp=2 → dp = 16 ÷ (4 × 2) = 2
#        tp=8, pp=2 → dp = 16 ÷ (8 × 2) = 1

# 方式二：配置 min_value 作为修复失败后的下界保护，并输出警告
[[mindie.target_field]]
name = "dp"
config_position = "BackendConfig.ModelDeployConfig.ModelConfig.0.dp"
min = 0
max = 0
dtype = "ternary_factories"
dtype_param = {target_names = ["tp", "pp"], product = 16, dtype = "int", min_value = 1}
# 如果没有可修复的合法组合，且结果低于 min_value，会降级至 min_value=1，并输出 WARNING

优先级修复策略（priority_policy）

当 PSO 生成的 tp、pp 组合不能合法推出 dp（如不能整除、超界）时，系统会尝试修复。修复策略由 priority_policy 控制：

策略名	语义	适用场景
`balanced`（默认）	将粒子均分两组：前半用 `target_names` 顺序修复，后半用反序修复，降低单一解码顺序带来的结构性偏置	用户没有明确字段优先偏好，默认使用
`fixed`	用户显式指定修复顺序：高优先级字段尽量保持不动，优先调整低优先级字段	用户明确知道哪个字段更应该稳定

# balanced（默认）策略示例
# 适用：用户没有指定哪个字段更重要，系统自动均衡分配修复方向
[[mindie.target_field]]
name = "dp"
config_position = "BackendConfig.ModelDeployConfig.ModelConfig.0.dp"
min = 0
max = 0
dtype = "ternary_factories"
dtype_param = {
  target_names = ["tp", "pp"],
  product = 32,
  dtype = "int",
  priority_policy = "balanced"   # 默认即为 balanced，可不写
}

# fixed 策略示例
# 适用：用户明确知道 tp 应保持稳定，优先调整 pp
[[mindie.target_field]]
name = "dp"
config_position = "BackendConfig.ModelDeployConfig.ModelConfig.0.dp"
min = 0
max = 0
dtype = "ternary_factories"
dtype_param = {
  target_names = ["tp", "pp"],
  product = 32,
  dtype = "int",
  priority_policy = "fixed",
  priority = ["tp", "pp"]        # tp 高优先：尽量保留 tp，首先调整 pp
}
# 示例： tp=8、pp=3（非法）：
#   stage1：固定 tp=8，在 pp 候选中找最近合法値 → pp=4， dp=1
#   stage1 失败时再 stage2：两个字段均可调整，按距离升序搜索

[!note] priority_policy 说明

balanced 是默认策略，不配置时自动生效。

balanced 通过将粒子按解码顺序分层，降低单一字段顺序导致的结构性偏置，但不能保证全局最优。

fixed 适合用户明确知道哪个字段更应该稳定的场景，例如 tp 由硬件资源决定时。

修复分两阶段：stage1 固定高优先字段、调整低优先字段；stage1 失败后 stage2 两个字段均可调整。

全部候选都不合法时，修复失败，降级至 min/max 截断，并输出 warning。

场景二：seq_len、prefill_batch_size 为可调参数，max_prefill_tokens 自动设为二者之积的 2 倍（max_prefill_tokens = 2 × seq_len × prefill_batch_size）：

[[mindie.target_field]]
name = "seq_len"
config_position = "BackendConfig.ModelConfig.seqLen"
min = 0
max = 1
dtype = "enum"
dtype_param = [512, 1024, 2048, 4096]

[[mindie.target_field]]
name = "prefill_batch_size"
config_position = "BackendConfig.ScheduleConfig.maxPrefillBatchSize"
min = 1
max = 16
dtype = "int"

[[mindie.target_field]]
name = "max_prefill_tokens"
config_position = "BackendConfig.ScheduleConfig.maxPrefillTokens"
min = 0         # 设为 0 使其成为常量，不参与搜索
max = 0
dtype = "ternary_times"
dtype_param = {target_names = ["seq_len", "prefill_batch_size"], product = 2, dtype = "int"}
# 当 seq_len=1024, prefill_batch_size=4 时，max_prefill_tokens = 2 × 1024 × 4 = 8192

日志检测：检查日志中出现的异常信息，区分致命错误和可重试错误，实现智能错误处理和重试机制。可检测的错误类型包括内存溢出（OOM）、设备故障（NPU）、网络错误和IO错误等。致命错误（如OOM、NPU故障）会立即停止调度器，可重试错误（如网络抖动、IO失败）会触发自动重试（最多3次）。

参数	可选/必选	说明
log_snippet_length	可选	日志片段长度，用于显示错误详情。取值范围：50-1000，默认为200。
service_errors.fatal_patterns	可选	服务化框架致命错误模式列表，默认为空。常见致命错误包括内存溢出、设备故障等。
service_errors.retryable_patterns	可选	服务化框架可重试错误模式列表，默认为空。常见可重试错误包括网络错误、IO错误等。
benchmark_errors.fatal_patterns	可选	测评工具致命错误模式列表，默认为空。
benchmark_errors.retryable_patterns	可选	测评工具可重试错误模式列表，默认为空。

配置示例：

[health_check]
log_snippet_length = 200

[health_check.service_errors.fatal_patterns]
out_of_memory = ["out of memory", "OOM killed", "MemoryError"]
device_error = ["NPU error", "device fault", "Ascend error"]

[health_check.service_errors.retryable_patterns]
network_error = ["connection reset", "connection refused", "timeout"]
io_error = ["file not found", "permission denied", "IO error"]

插件模式¶

现在寻优工具支持用户自定义搜索参数配置以及测试工具，用户可以根据自己的需求配置。只需适配我们的插件模式，注册对应的插件即可，详情请参见插件开发操作步骤。

环境变量与排障 ¶

环境变量

变量	说明
`OPTIX_DEPLOY_PATH`	可选。部署环境根目录，其 `bin/` 下应有 `vllm`、`ais_bench` 等。优先级高于 `config.toml` 的 `[deploy] path_prefix`；不设则用系统 PATH
`MIES_INSTALL_PATH`	MindIE 安装根目录，子进程会保留，不用为隔离而改

优先级从高到低：OPTIX_DEPLOY_PATH、config.toml 的 [deploy] path_prefix、仅剥离 msmodeling venv 后走系统 PATH。

日常启动

系统里已经装好 vLLM 时，通常不用设 OPTIX_DEPLOY_PATH：

source /path/to/msmodeling/.venv/bin/activate
msmodeling optix -e vllm -b ais_bench

PATH 布局特殊时再设：

export OPTIX_DEPLOY_PATH=/path/to/custom-deploy-root
source /path/to/msmodeling/.venv/bin/activate
msmodeling optix -e vllm -b ais_bench

[optix/env] 日志对照

日志	含义	处理
`当前未检测到虚拟环境`	没用 venv 装 msmodeling	在仓库根目录执行 `uv sync`（会自动创建 `.venv`）；别装到系统 Python，否则 `torch`、`transformers` 会冲掉部署栈
`找不到部署命令：vllm` 或 `mindieservice_daemon`	剥离 venv 后系统 PATH 里没有命令	先确认系统已装 vLLM 或 MindIE；必要时设 `OPTIX_DEPLOY_PATH` 或 `[deploy] path_prefix`
`命令 vllm 解析到 msmodeling 虚拟环境`	msmodeling venv 里误装了 vllm	在该 venv 里 `pip uninstall vllm`，改用系统里的 vLLM
`部署命令 vllm → ...` 且路径在系统侧	正常	不用改

日志说明¶

寻优工具使用 loguru 输出结构化日志。控制台每行包含 run_id、stage 等上下文字段。请在启动工具之前设置日志级别：

# 推荐
export OPTIX_LOG_LEVEL=INFO

# 兼容旧变量（仅当未设置 OPTIX_LOG_LEVEL 时生效）
export MODELEVALSTATE_LEVEL=DEBUG

级别	可见内容
`INFO`（默认）	里程碑：baseline 通过、服务就绪、迭代摘要、最优结果；子进程启动为多行 `command:` / `log:`
`DEBUG`	参数与配置细节、子进程 I/O（`Popen`、读日志、benchmark CSV glob）；每行含 `file:line`；未捕获异常含完整堆栈
`TRACE`	PSO 粒子级细节（fitness、粒子位置、单次评测参数）；与 DEBUG 相同含 `file:line` 列

示例 — 仅看迭代摘要：

export OPTIX_LOG_LEVEL=INFO
msmodeling optix -e vllm

示例 — 排查失败候选的参数：

export OPTIX_LOG_LEVEL=DEBUG
msmodeling optix -e mindie --backup

VLLM/MindIE 及测评子进程日志写入结果目录或 /tmp。启动日志为多行可读格式：

Starting service subprocess
  command: vllm serve model_path --host 127.0.0.1 --port 8080
  log: /tmp/ms_serviceparam_optimizer__abc123

baseline 失败时 CLI 边界仅输出一次含 exit=、command:、log: 及日志末尾数行的消息（不再嵌套包装）。框架在构造插件前按各类声明的 required_executable 检查 PATH：-b 缺失时抛出 BenchmarkUnavailableError，-e 缺失时抛出 SimulatorUnavailableError（如 vllm），均发生在寻优开始前，不会拉起子进程或清理输出目录。

故障排查¶

现象	可能原因	处理建议
退出码 `1`，提示 `No feasible solution found`	baseline 或 PSO 全部候选 fitness 为 `inf`	查看 CSV `error` 列；使用 `OPTIX_LOG_LEVEL=DEBUG`；检查服务与测评命令
`Optimizer aborted` 并带堆栈	`main()` 未捕获的致命错误	根据边界单次 traceback 修复配置、路径或健康检查规则
`BenchmarkResultError`（`OptimizerError` 子类）/ AISBench CSV 不唯一	测评输出目录下 0 个或多个 `performances//.csv`	清理输出目录；确保每次评测只产生一份 CSV；立即终止整次寻优（非单粒子失败）
控制台仅有 `run_id`、`stage`，细节较少	默认 `INFO` 不打印粒子级日志	设置 `OPTIX_LOG_LEVEL=TRACE` 查看 PSO 内部
`BenchmarkUnavailableError` 启动即失败	所选 `-b` 插件声明的 CLI 不在 `PATH`	安装 benchmark CLI 或更换 `-b`；发生在寻优开始前
`SimulatorUnavailableError` 启动即失败	所选 `-e` 插件声明的 CLI 不在 `PATH`（如 `vllm`）	安装推理框架 CLI 或更换 `-e`；发生在寻优开始前
`BaselineRunError` 含 `exit=` / `log:` / `log tail:`	baseline 子进程失败	先看控制台末尾日志；需要时再打开完整 log 文件
边界错误行 `run_id` 或 `stage` 为 `-`	较新版本已修复：边界日志在 `contextualize` 内输出	升级；边界错误应显示真实 `run_id` 与 `stage`
`--config` 指向不存在文件	路径错误或文件未部署	检查路径；抛出 `ConfigFileNotFoundError`（退出码 `1`）

CLI 退出码

退出码	含义
`0`	找到可行最优解并完成输出
`1`	`OptimizerError` 子类（`ConfigFileNotFoundError`、`BenchmarkResultError`、`NoFeasibleSolutionError`、`BaselineRunError` 等）或未捕获致命错误

当前所有失败路径均以退出码 1 退出；请通过日志消息或 OptimizerError 子类区分失败类型，而非依赖不同非零退出码。

领域错误集中在 optix.optimizer.errors.OptimizerError 及其子类，便于区分 config 缺失、TOML 非法、baseline 失败与无可行解，无需解析日志文本。非法 TOML 抛出 InvalidConfigError。

退出码非零时，请结合控制台日志与 CSV error 列排查。

服务化实测寻优 使用指南¶

简介¶