vLLM 使用统计采集机制详解：收集范围、源码实现与退出方法

vLLM 默认会采集匿名的使用统计数据，帮助工程团队了解哪些硬件与模型配置被广泛使用，从而把优化精力集中在最常见的负载上。本文以 Usage Stats Collection 文档为核心，结合 vllm/usage/usage_lib.py 与 vllm/v1/utils.py 的源码实现，讲清 vLLM 到底采集了哪些数据、数据从哪里来、如何本地预览，以及如何通过环境变量或配置文件彻底关闭采集。

机制总览：默认开启、匿名、透明

vLLM 的使用统计采集遵循三个原则：

• 默认开启：无需任何配置，引擎初始化后会自动上报环境信息；
• 匿名且透明：数据不含任何敏感信息，且每次上报都会先写入本地文件，用户可随时查看原文；
• 部分公开：数据经过清洗和聚合后会面向社区公开发布（例如 2024 年度使用报告），用于展示社区真实的硬件/模型分布。

从源码结构看，整个机制集中在 vllm/usage/usage_lib.py：全局单例 usage_message = UsageMessage() 负责收集平台信息并发送到统计服务器，而真正决定"是否采集"的入口是 is_usage_stats_enabled()（该文件 L50-L68）：

• 默认应为启用状态；
• 以下任一条件为真时关闭：环境变量 VLLM_DO_NOT_TRACK=1、DO_NOT_TRACK=1、VLLM_NO_USAGE_STATS=1，或存在文件 ~/.config/vllm/do_not_track；
• 判定结果会缓存在全局变量 _USAGE_STATS_ENABLED 中，进程生命周期内只计算一次。

注意官方文档中只提到了 VLLM_NO_USAGE_STATS 和 DO_NOT_TRACK，但从源码看 VLLM_DO_NOT_TRACK 同样是有效的关闭开关，且在 vllm/envs.py 中可以看到 VLLM_DO_NOT_TRACK 的实现会同时读取 VLLM_DO_NOT_TRACK 与 DO_NOT_TRACK 两个变量。

采集了哪些数据

上报的载荷分为三组字段，全部为扁平 KV 结构（源码注释明确说明服务端只支持 flat KV pair，见 UsageMessage.__init__ 中 L124 附近的 NOTE）。

1. 环境与硬件信息

字段	含义	采集来源
uuid	每次上报会话的唯一标识	uuid4() 生成
provider	云厂商（AWS/AZURE/GCP/OCI/RUNPOD/UNKNOWN）	_detect_cloud_provider()
num_cpu / cpu_type / cpu_family_model_stepping	CPU 核数、型号、家族/型号/步进	cpuinfo 库
total_memory	物理内存总量（字节）	psutil.virtual_memory().total
architecture	机器架构，如 x86_64	platform.machine()
platform	操作系统平台字符串	platform.platform()
gpu_count / gpu_type / gpu_memory_per_device	GPU 数量、型号、单卡显存	按平台分支：CUDA/类 CUDA 用 current_platform.device_count() 与 cuda_get_device_properties(0, ("name", "total_memory"))；XPU 用 torch.xpu 接口；TPU 通过 tpu_inference 库获取 chip 数量与 HBM 上限
cuda_runtime / xpu_runtime	运行时版本	torch.version.cuda / torch.version.xpu
env_var_json	一组特定环境变量值的 JSON 序列化	见下文环境变量列表

其中 env_var_json 固定采集这五个环境变量（_USAGE_ENV_VARS_TO_COLLECT，该文件 L36-L42）：VLLM_USE_MODELSCOPE、VLLM_USE_FLASHINFER_SAMPLER、VLLM_PP_LAYER_PARTITION、VLLM_USE_TRITON_AWQ、VLLM_ENABLE_V1_MULTIPROCESSING——它们直接反映用户实际启用了哪些特性路径。

2. vLLM 与模型信息

• model_architecture：模型架构类名，如 OPTForCausalLM；当模型走 Transformers 后端包装时，从源码结构看会显示为 TransformersForCausalLM(原始架构) 的形式，以区分原生实现与包装实现（见 vllm/v1/utils.py 中的 report_usage_stats）；
• vllm_version：当前版本号；
• context：上报发生的入口上下文，取值来自 UsageContext 枚举（该文件 L111-L117）：UNKNOWN_CONTEXT、LLM_CLASS、API_SERVER、OPENAI_API_SERVER、OPENAI_BATCH_RUNNER、ENGINE_CONTEXT；
• log_time：纳秒级 UTC 时间戳；
• source：取自环境变量 VLLM_USAGE_SOURCE，默认值为 production。

3. 引擎配置参数（extra_kvs）

引擎初始化时，report_usage_stats()（vllm/v1/utils.py）还会把当前 vLLM 的关键配置一并上报，包括：

• 常见配置：dtype、block_size、gpu_memory_utilization、kv_cache_memory_bytes；
• 量化相关：quantization、kv_cache_dtype；
• 特性开关：enable_lora、enable_prefix_caching、enforce_eager、disable_custom_all_reduce；
• 并行设置：tensor_parallel_size、data_parallel_size、pipeline_parallel_size、enable_expert_parallel、all2all_backend、kv_connector；
• 批处理上限：max_model_len、max_num_seqs、max_num_batched_tokens；
• 注意力与编译：attention_backend（None 表示运行时按平台自动选择）、compilation_mode（如 NONE、STOCK_TORCH_COMPILE、VLLM_COMPILE）；
• 投机解码：spec_decode_method、num_speculative_tokens；
• 专家负载均衡：enable_eplb、num_redundant_experts、num_experts。

下面是文档给出的 v0.4.0 时期的上报示例（当前版本字段更多，示例中不含后续新增字段）：

{
  "uuid": "fbe880e9-084d-4cab-a395-8984c50f1109",
  "provider": "GCP",
  "num_cpu": 24,
  "cpu_type": "Intel(R) Xeon(R) CPU @ 2.20GHz",
  "cpu_family_model_stepping": "6,85,7",
  "total_memory": 101261135872,
  "architecture": "x86_64",
  "platform": "Linux-5.10.0-28-cloud-amd64-x86_64-with-glibc2.31",
  "gpu_count": 2,
  "gpu_type": "NVIDIA L4",
  "gpu_memory_per_device": 23580639232,
  "model_architecture": "OPTForCausalLM",
  "vllm_version": "0.3.2+cu123",
  "context": "LLM_CLASS",
  "log_time": 1711663373492490000,
  "source": "production",
  "dtype": "torch.float16",
  "tensor_parallel_size": 1,
  "block_size": 16,
  "gpu_memory_utilization": 0.9,
  "quantization": null,
  "kv_cache_dtype": "auto",
  "enable_lora": false,
  "enable_prefix_caching": false,
  "enforce_eager": false,
  "disable_custom_all_reduce": true
}

上报流程：从引擎初始化到周期心跳

上报触发点与 UsageContext

各入口在引擎初始化时调用上报，且带上了自己的 UsageContext，用于区分用户通过哪种方式使用 vLLM：

• LLM_CLASS：vllm/entrypoints/llm.py 中离线 LLM 类；
• OPENAI_API_SERVER：vllm serve API 服务（vllm/entrypoints/cli/serve.py、vllm/entrypoints/launchers/api_server/entry.py、vllm/entrypoints/grpc_server.py）；
• OPENAI_BATCH_RUNNER：vllm/entrypoints/launchers/run_batch.py 批量任务；
• ENGINE_CONTEXT：V1 引擎默认上下文（vllm/v1/engine/async_llm.py、vllm/v1/engine/llm_engine.py）。

两次上报：一次性快照 + 周期心跳

UsageMessage.report_usage()（该文件 L153-L173）并不阻塞主流程——它会启动一个守护线程执行两步：

1. 一次性上报 _report_usage_once：采集平台/硬件信息、模型架构、引擎配置，先 _write_to_file 落盘，再 _send_to_server 发送到统计服务器；
2. 持续上报 _report_continuous_usage（L248-L263）：每 600 秒（10 分钟）发送一次轻量心跳，载荷只含 uuid、log_time 以及通过 set_runtime_usage_data() 写入的全局运行时数据（_GLOBAL_RUNTIME_DATA）。源码注释说明其目的是收集 vLLM 实例的在线时长（uptime）数据点，并预留了后续上报性能指标的扩展空间。

云厂商检测与失败静默

• _detect_cloud_provider()（L75-L108）先依次读取 /sys/class/dmi/id/ 下的 product_version、bios_vendor、product_name、chassis_asset_tag、sys_vendor 五个 DMI 文件，将内容中的 amazon/microsoft corporation/google/oraclecloud 映射为 AWS/AZURE/GCP/OCI；再回退到环境变量（如 RUNPOD_DC_ID 对应 RUNPOD）；都不匹配则返回 UNKNOWN。
• _send_to_server（L265-L271）通过 requests.Session 向统计服务器（默认 https://stats.vllm.ai，可用 VLLM_USAGE_STATS_SERVER 环境变量覆盖）POST JSON；网络异常被静默吞掉，仅在 debug 日志级别下记录，因此统计上报失败不会影响推理服务本身。
• _write_to_file（L273-L278）以 JSON Lines 方式追加写入 ~/.config/vllm/usage_stats.json（目录由 VLLM_CONFIG_ROOT 决定，默认 ~/.config/vllm，见 vllm/envs.py）。

本地预览采集到的数据

由于每次上报都会先落盘，你可以直接查看将要/已经发送的原始数据：

tail ~/.config/vllm/usage_stats.json

文件为追加式 JSON Lines 格式：初始化时是完整快照，之后每 10 分钟追加一行轻量心跳（uuid + log_time + 运行时数据）。如果通过 VLLM_CONFIG_ROOT 修改过配置根目录，则文件路径相应变为 $VLLM_CONFIG_ROOT/usage_stats.json。

如何退出统计采集（Opt-out）

官方文档提供三种等效的退出方式，任选其一即可：

# Any of the following methods can disable usage stats collection
export VLLM_NO_USAGE_STATS=1
export DO_NOT_TRACK=1
mkdir -p ~/.config/vllm && touch ~/.config/vllm/do_not_track

结合源码可补充以下细节：

• 环境变量在 vllm/envs.py 中统一定义：VLLM_NO_USAGE_STATS 仅在显式取值为 "1" 时生效；VLLM_DO_NOT_TRACK 的取值逻辑是 VLLM_DO_NOT_TRACK 或 DO_NOT_TRACK 任一为 "1" 即视为开启（因此文档中的 DO_NOT_TRACK 是社区通用约定，vLLM 原生支持）。此外源码中的 is_usage_stats_enabled() 还识别独立的 VLLM_DO_NOT_TRACK，属于文档未列出的第四个开关；
• 文件方式的判断路径是 $VLLM_CONFIG_ROOT/do_not_track，默认即 ~/.config/vllm/do_not_track；只要文件存在即关闭，无需写入任何内容；
• 判定只在进程内首次调用时执行一次并缓存，因此修改环境变量或创建文件后需要重启 vLLM 进程才能生效；
• 测试代码也印证了这一开关的实际用途，例如 tests/entrypoints/llm/offline_mode/test_offline_mode.py 中通过 mock.patch.dict(os.environ, {"VLLM_NO_USAGE_STATS": "1"}) 关闭采集，避免测试触达网络。

相关环境变量速查

环境变量	默认值	作用
VLLM_NO_USAGE_STATS	0	置为 1 关闭采集
VLLM_DO_NOT_TRACK / DO_NOT_TRACK	未设置	任一为 1 关闭采集（后者为社区通用约定）
VLLM_USAGE_STATS_SERVER	https://stats.vllm.ai	统计上报服务器地址
VLLM_USAGE_SOURCE	production	上报数据中的 source 字段，便于区分数据来源场景
VLLM_CONFIG_ROOT	~/.config/vllm	本地统计文件与 do_not_track 标记文件的根目录

小结

vLLM 的使用统计是一个"默认开启、可完全自证"的轻量遥测机制：它只收集硬件环境、模型架构和引擎配置这类匿名信息，采集逻辑集中在 vllm/usage/usage_lib.py，配置字段由 vllm/v1/utils.py 的 report_usage_stats() 补充。对生产环境而言，如果出于合规要求不希望任何遥测出站，推荐组合使用 export VLLM_NO_USAGE_STATS=1 与环境变量 DO_NOT_TRACK=1（后者对第三方工具同样通用）；如果想先核实采集内容再决定，直接 tail ~/.config/vllm/usage_stats.json 查看本地落盘原文是最直接的方式。