Service Profiling Guide¶

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

本指南将引导你完成从 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¶

0. 安装与配置¶

无需安装额外包，可通过命令行配置启用。目前，vLLM 默认启用 python stack，这会显著增加采集到的性能数据量。如果你不希望采集 python stack，可以使用 torch_profiler_with_stack=false 将其关闭。

1. 采集准备¶

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

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. 开始采集¶

Note

/start_profile 和 /stop_profile 接口仅在服务器使用 --profiler-config（profiler 字段非空）启动时注册。如果你忘记设置 --profiler-config，这些接口将不存在，curl 会返回 404 Not Found。

性能采集通过发送 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 打开

补充：PD（Prefill-Decode）分离部署场景下的性能采集¶

在 PD（Prefill-Decode）分离部署中，Prefiller 和 Decoder 是独立的 vLLM 实例，各自拥有独立的 API 服务器。必须在每个节点上分别配置和控制性能采集：

P 和 D 都必须使用 --profiler-config 启动（指向不同目录以避免覆盖）。
主要的 PD 负载均衡代理（load_balance_proxy_server_example.py）不会转发 /start_profile 或 /stop_profile。您必须直接对每个节点的 HTTP 端口执行 curl：

# Start profiling on both P and D
curl -X POST http://<prefiller_ip>:<prefiller_port>/start_profile
curl -X POST http://<decoder_ip>:<decoder_port>/start_profile

# Send business requests through the proxy...

# Stop profiling on both P and D
curl -X POST http://<prefiller_ip>:<prefiller_port>/stop_profile
curl -X POST http://<decoder_ip>:<decoder_port>/stop_profile

Note

EPD 代理（epd_load_balance_proxy_layerwise_server_example.py）确实支持向所有 E/P/D 实例广播性能分析命令。

MS Service Profiler¶

0. 从源码构建并升级¶

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

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 是性能分析配置。如果指定路径下不存在该文件，系统会自动生成默认配置。如有需要，您可以根据下文“性能分析配置文件”一节的说明提前自定义该文件。

service_profiling_symbols.yaml 是包含要导入的性能分析点的配置文件。您可以选择不设置 PROFILING_SYMBOLS_PATH 环境变量，此时将使用默认配置文件。同样地，如果该文件在您指定的路径下不存在，系统也会在您指定的路径下生成一个配置文件，供后续配置使用。您可以根据下文“符号配置文件”一节的说明自定义该文件。

2. 启用性能分析¶

要启用性能数据采集开关，请将配置文件 ms_service_profiler_config.json 中的 enable 字段从 0 改为 1。可以通过执行以下 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.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 安装根目录（例如典型 root 安装为 `/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_step_num	Torch Profiler 步数限制。整数 ≥ 0。默认值 `0` 表示收集所有步数。需要将 `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": ""
}

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：默认 timer

- 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"
  # 未指定 handler -> 默认 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

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

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 vl/vllm-ascend

Service Profiling Guide¶

方案对比¶

快速选择指南¶

Ascend PyTorch Profiler¶

0. 安装与配置¶

1. 采集准备¶

2. 开始采集¶

3. 发送请求¶

4. 分析数据¶

5. 查看结果¶

补充：PD（Prefill-Decode）分离部署场景下的性能采集¶

MS Service Profiler¶

0. 从源码构建并升级¶

1. 准备¶

2. 启用性能分析¶

3. 发送请求¶

4. 解析数据¶

5. 查看结果¶

6. 与 MS Service Profiler 相关的附录¶

6.1 性能分析配置文件¶

文件格式¶

示例配置¶

6.2 符号配置文件¶

文件名与加载¶

配置文件更新¶

字段说明¶

配置示例¶

自定义属性收集¶

基本语法¶

示例¶

表达式说明¶

支持的表达式类型¶

高级示例¶

自定义处理器¶