服务性能分析指南¶

在推理服务过程中，有时需要监控推理服务框架的内部执行流程，以识别性能问题。通过收集关键流程的开始和结束时间戳、识别关键函数或迭代、记录关键事件以及收集各类信息，可以快速定位性能瓶颈。

本指南将引导您完成从 vLLM-Ascend 服务框架和算子中收集性能数据的过程。它涵盖了从准备、收集、分析到可视化的完整工作流程，帮助您快速上手性能收集工具。

下面提供两种性能收集方案：Ascend PyTorch Profiler 和 MS Service Profiler。您可以根据实际需求选择合适的工具进行性能分析和问题排查。

方案对比¶

功能	Ascend PyTorch Profiler	MS Service Profiler
安装方式	内置，无需额外安装	需要从源码构建 msserviceprofiler
采集粒度	PyTorch 算子级别	服务框架函数级别
控制方式	API 请求控制	配置文件控制
适用场景	模型算子性能分析	服务框架工作流分析
数据格式	ascend_pt 格式	Chrome Tracing + CSV
主要优势	算子级性能分析	服务框架工作流可视化
支持的采集能力	PyTorch 算子级别	PyTorch 算子级别和服务框架函数级别

Ascend PyTorch 性能分析器¶

0. 安装与配置¶

无需安装额外软件包，可通过命令行配置启用。当前 vLLM 默认启用 python stack，这可能会显著增加采集的性能数据量。如果不需要采集 python stack，可以使用 torch_profiler_with_stack=false 禁用它。

1. 采集前准备¶

启动在线服务，并设置 --profiler-config 参数以控制性能文件的保存路径。设置该参数后，采集功能即被启用。

export VLLM_PROMPT_SEQ_BUCKET_MAX=128
export VLLM_PROMPT_SEQ_BUCKET_MIN=128
python3 -m vllm.entrypoints.openai.api_server \
--port 8080 \
--model "facebook/opt-125m" \
--tensor-parallel-size 1 \
--max-num-seqs 128 \
--profiler-config '{"profiler": "torch", "torch_profiler_dir": "./vllm_profile", "torch_profiler_with_stack": false}' \
--dtype bfloat16 \
--max-model-len 256

注意：2026年1月19日：vLLM 主线已弃用 VLLM_TORCH_PROFILER_DIR 环境变量。相关 PR 使用 vLLM Ascend 主线代码采集 profiler 数据时，请记得使用 --profiler-config（在线）参数或 profiler_config（离线）参数。

2. 开始采集¶

性能采集通过发送 API 请求来控制。可以在实际业务数据稳定后开始采集，采集几秒后停止；也可以先开始采集，再发送业务请求，最后停止。

发送以下请求以启动性能分析服务：

curl -X POST http://localhost:8080/start_profile

发送以下请求以停止性能分析服务：

curl -X POST http://localhost:8080/stop_profile

3. 发送请求¶

根据实际业务数据发送请求。发送请求后，停止性能分析服务，数据将自动保存到之前配置的路径：

curl http://localhost:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "facebook/opt-125m",
    "prompt": "San Francisco is a",
    "max_tokens": 7,
    "temperature": 0
}'

curl -X POST http://localhost:8080/stop_profile

4. 分析数据¶

进入 ./vllm_profile 目录，找到生成的 *ascend_pt 文件夹。需要先对该文件夹进行分析，才能查看性能分析数据。

from torch_npu.profiler.profiler import analyse
analyse("./vllm_profile/localhost.localdomain_*_ascend_pt/")

5. 查看结果¶

分析完成后，*ascend_pt 目录下会包含许多文件，主要分析关注点为 ASCEND_PROFILER_OUTPUT 文件夹。该目录将包含以下文件：

analysis.db：数据库格式的性能数据
api_statistic.csv：API 调用统计
ascend_pytorch_profiler_0.db：数据库格式的性能数据
kernel_details.csv：内核级相关数据
operator_details.csv：算子级相关数据
op_statistic.csv：算子利用率数据
step_trace_time.csv：调度数据
trace_view.json：Chrome tracing 格式数据，可使用 MindStudio Insight 打开

↑ Back to Top

MS Service Profiler¶

0. 从源码构建并升级¶

msserviceprofiler 工具随 CANN Toolkit 包预装。使用以下命令从源码安装或升级。

git clone https://gitcode.com/Ascend/msserviceprofiler.git
cd msserviceprofiler
bash scripts/build_and_upgrade.sh

1. 准备工作¶

在启动服务前，设置环境变量 SERVICE_PROF_CONFIG_PATH 指向性能分析配置文件，并设置环境变量 PROFILING_SYMBOLS_PATH 指定需要导入的符号的 YAML 配置文件。之后，根据您的部署方式启动 vLLM 服务。

cd ${path_to_store_profiling_files}
# Set environment variable
export SERVICE_PROF_CONFIG_PATH=ms_service_profiler_config.json
export PROFILING_SYMBOLS_PATH=service_profiling_symbols.yaml

# Start vLLM service
vllm serve Qwen/Qwen2.5-0.5B-Instruct &

文件 ms_service_profiler_config.json 是性能分析配置文件。如果指定路径下不存在该文件，将自动生成默认配置。如有需要，您可以根据下方Profiling Configuration File部分的说明提前自定义配置。

service_profiling_symbols.yaml 是包含待导入性能分析点的配置文件。您可以选择**不**设置 PROFILING_SYMBOLS_PATH 环境变量，此时将使用默认配置文件。如果文件在您指定的路径下不存在，系统同样会在您指定的路径生成一个配置文件供后续配置。您可以根据下方Symbols Configuration File部分的说明进行自定义。

2. 启用性能分析¶

要启用性能数据采集开关，请将配置文件 enable 中的 0 字段从 1 改为 ms_service_profiler_config.json。这可以通过执行以下 sed 命令来完成：

sed -i 's/"enable":\s*0/"enable": 1/' ./ms_service_profiler_config.json

3. 发送请求¶

选择适合您实际性能分析需求的请求发送方式：

curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json"  \
    -d '{
         "model": "Qwen/Qwen2.5-0.5B-Instruct",
        "prompt": "Beijing is a",
        "max_tokens": 5,
        "temperature": 0
}' | python3 -m json.tool

4. 解析数据¶

# xxxx-xxxx is the directory automatically created based on vLLM startup time
cd /root/.ms_server_profiler/xxxx-xxxx

# parse data
msserviceprofiler parse --input-path=./ --output-path output

5. 查看结果¶

解析后，output 目录将包含：

chrome_tracing.json：Chrome tracing 格式数据，可在 MindStudio Insight 中打开。
profiler.db：数据库格式的性能数据。
request.csv：请求相关数据。
kvcache.csv：KV Cache 相关数据。
batch.csv：批量调度相关数据。

6. MS Service Profiler 相关附录¶

(profiling-configuration-file)=

6.1 性能分析配置文件¶

性能分析配置文件控制性能分析参数和行为。

文件格式¶

配置采用 JSON 格式。主要参数：

参数	描述	是否必填
enable	性能分析开关： 0：关闭 1：开启默认值：0	是
prof_dir	存储采集的性能数据的目录。默认值：`${HOME}/.ms_server_profiler`	否
profiler_level	数据采集级别。默认值为 "INFO"（正常级别）。	否
acl_task_time	采集算子调度延迟和执行延迟的开关。取值： 0：关闭。默认值；0 或任何无效值表示关闭。 1：开启。开启时，使用 `aclprofCreateConfig` 调用 `ACL_PROF_TASK_TIME_L0`。 2：开启。基于 MSPTI 的转储。开启时，在启动服务前设置：`export LD_PRELOAD={INSTALL_DIR}/lib64/libmspti.so`，其中 `{INSTALL_DIR}` 是 CANN 安装根目录（例如典型根安装的 `/usr/local/Ascend/cann`）。 3：开启。基于 Torch Profiler 的转储。	否
acl_prof_task_time_level	性能分析级别和持续时间。取值： L0：仅采集算子调度和执行延迟；开销较低（无算子基本信息）。 L1：采集 AscendCL 接口性能（主机-设备和设备间同步/异步内存拷贝延迟），以及算子调度、执行和基本信息，用于全面分析。 `{time}`：可选的持续时间段；整数 1–999，单位秒。如果未设置，默认为 L0 直到程序退出；无效值回退到默认值。级别和持续时间可以组合，例如 `"acl_prof_task_time_level": "L1;10"`。注意：使用 Torch Profiler 时（`acl_task_time` 设置为 `3`），不支持 `{time}` 持续时间。	否
timelimit	服务的性能分析持续时间。进程在此时间后自动停止。范围：整数 0–7200，单位：秒。默认值 0 表示无限制。建议至少 120 秒；运行时间过短可能导致解析输出数据不足并触发警告。	否
domain	将性能分析限制在指定域以减少数据量。字符串，以分号分隔，区分大小写，例如 "Request; KVCache"。空字符串表示所有可用域。可用域：Request, KVCache, ModelExecute, BatchSchedule, Communication。注意：如果所选域不完整，分析输出可能因缺少数据而显示警告。请参见参考表 1。	否
torch_prof_stack	采集算子调用栈（框架和 CPU 算子）。取值：`false`（默认，关闭），`true`（开启）。需要将 `acl_task_time` 设置为 `3`。注意：开启此配置会引入额外的性能开销。	否
torch_prof_step_num	Torch Profiler 步数限制。整数 ≥ 0。默认值 `0` 表示采集所有步骤。需要将 `acl_task_time` 设置为 `3`。	否
profiler_step_num	算子和服务框架性能分析的步数限制。整数 ≥ 0。 `0` 或无效值会停止整个服务性能分析过程。实际记录的步数取决于 `modelRunnerExec` 事件。	否

配置示例¶

{
    "enable": 1,
    "prof_dir": "./vllm_prof",
    "acl_task_time": 0,
    "acl_prof_task_time_level": ""
}

(symbols-configuration-file)=

6.2 符号配置文件¶

符号配置文件定义了要分析哪些函数/方法，并支持通过自定义属性收集进行灵活配置。

文件名与加载¶

默认加载路径：~/.config/vllm_ascend/service_profiling_symbols.MAJOR.MINOR.PATCH.yaml（根据已安装的vllm版本）

如果需要自定义分析点，强烈建议将符号配置文件复制到工作目录，并通过PROFILING_SYMBOLS_PATH环境变量指向该文件。

配置文件更新¶

更改分析符号后，请重启vLLM服务以加载更新后的配置文件。

字段说明¶

字段	描述	示例
symbol	Python 导入路径 + 属性链	`"vllm.v1.core.kv_cache_manager:KVCacheManager.free"`
handler	处理器类型	`"timer"`（默认）或 `"pkg.mod:func"`（自定义）
domain	域标签	`"KVCache"`, `"ModelExecute"`
name	事件名称	`"EngineCoreExecute"`
min_version	支持的最低 vLLM 版本	`"0.9.1"`
max_version	支持的最高 vLLM 版本	`"0.11.0"`
attributes	自定义属性采集	仅支持 `"timer"` 处理器。请参见以下章节

配置示例¶

示例1：自定义处理器

- symbol: vllm.v1.core.kv_cache_manager:KVCacheManager.free
  handler: ms_service_profiler.patcher.config.custom_handler_example.kvcache_manager_free_example_handler
  domain: Example
  name: example_custom

示例2：默认计时器

- symbol: vllm.v1.engine.core:EngineCore.execute_model
  domain: ModelExecute
  name: EngineCoreExecute

示例3：版本约束

- symbol: vllm.v1.executor.abstract:Executor.execute_model
  min_version: "0.9.1"
  # No handler specified -> default timer

自定义属性收集¶

attributes字段支持灵活的自定义属性收集，并允许对函数参数和返回值进行操作和转换。

基本语法¶

参数访问：直接使用参数名，例如 input_ids
返回值访问：使用 return 关键字
管道操作：使用 | 链接多个操作
属性访问：使用 attr 访问对象属性

示例¶

- symbol: vllm_ascend.worker.model_runner_v1:NPUModelRunner.execute_model
  name: ModelRunnerExecuteModel
  domain: ModelExecute
  attributes:
  - name: device
    expr: args[0] | attr device | str
  - name: dp
    expr: args[0] | attr dp_rank | str
  - name: batch_size
    expr: args[0] | attr input_batch | attr _req_ids | len

表达式说明¶

len(input_ids)：获取参数 input_ids 的长度。
len(return) | str：获取返回值的长度并转换为字符串（相当于 str(len(return))）。
return[0] | attr input_ids | len：获取返回值中第一个元素的 input_ids 属性的长度。

支持的表达式类型¶

基本操作：len()、str()、int()、float()
索引访问：return[0]、return['key']
属性访问：return | attr attr_name
管道组合：使用 | 链式操作

高级示例¶

attributes:
  # Get tensor shape
  - name: tensor_shape
    expr: input_tensor | attr shape | str

  # Get specific value from a dict
  - name: batch_size
    expr: kwargs['batch_size']

  # Conditional expression (requires custom handler support)
  - name: is_training_mode
    expr: training | bool

  # Complex data processing
  - name: processed_data_len
    expr: data | attr items | len | str

自定义处理器¶

当 handler 指定自定义函数时，必须符合以下签名：

def custom_handler(original_func, this, *args, **kwargs):
    """
    Custom handler

    Args:
        original_func: the original function object
        this: the bound object (for methods)
        *args: positional arguments
        **kwargs: keyword arguments

    Returns:
        processing result
    """
    # Custom logic
    pass

如果自定义处理器导入失败，系统将自动回退到默认的计时器模式。

↑ Back to Top