服务性能分析指南

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

本指南将引导您完成从 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 Profiler
• 服务框架工作流 → 使用 MS Service Profiler

---

Ascend PyTorch Profiler

0. 安装与配置

无需安装额外包；可通过命令行配置启用。目前，vLLM 默认启用了 python 调用栈，这会显著增加采集的性能数据量。如果您不希望采集 python 调用栈，可以使用 torch_profiler_with_stack=false 来禁用它。

1.采集准备

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

VLLM_PROMPT_SEQ_BUCKET_MAX=128
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-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 追踪格式数据，可在 MindStudio Insight 中打开

↑ 返回顶部

---

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 追踪格式数据，可在 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 的数据落盘；使用 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

表达式说明

1. len(input_ids)：获取参数 input_ids 的长度。
2. len(return) | str：获取返回值的长度并转换为字符串（等价于 str(len(return))）。
3. 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

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

↑ 返回顶部