状态： Draft
作者： @Tjh-UKN
更新日期： 2026-11-12

目标与实现

KV Trace 记录 vLLM Scheduler、Worker 与 Ascend Model Runner V2 之间的 KV 出入口信息，检查调度声明与执行地址计划是否一致。包装全部位于 msprobe，通过 vLLM general plugin entry point 在对应进程加载，不修改 vLLM/vllm-ascend 源文件，也不依赖在 ModelRunner 初始化的 PrecisionDebugger 去修改 Scheduler 进程。

原完整实现 !1145 保持不动；当前交付按上述三个 PR 拆分。

KV 操作记录只有 kv.bind/write/read；普通 boundary 表示调用边界，不是新增 KV 状态。kv.violation 表示边界约束违规并驱动 log/raise；不再输出 kv.coverage_gap。缺必要原生坐标时跳过依赖该信息的检查，不算错误；原生异常记录为 kv.error 并继续传播。

不重建 allocator、epoch、owners 或 valid_end，不安装逐层 Attention hook。kv.write/read 是边界可见的执行计划，不能单独证明设备实际访存或 KV 数值正确。

当前设计 HTML

下载当前设计说明（HTML，ZIP 附件）

解压打开 msprobe_kv_trace_design_20261112.html。沿用原 design(2).html 的六大章、17 节顺序、CSS、左侧目录与交互脚本；原始验收日志及其他设计章节保持原样。

本次补充 5.4.2 各类日志的完整字段字典：逐项说明 kv.enabled、kv.bind、真实请求和 dummy 的 kv.write、kv.read、各类 boundary、kv.violation、kv.error 的字段含义、类型/单位、出现条件、数组索引对应关系与 null/缺省语义；包含调度增量、推测计数、PCP/DCP 坐标、connector 计划及完成/失败结果的嵌套字段。5.4.3 同步列出当前 38 种 reason 的判定含义和实际附加定位字段，避免把所有异常都理解成具有同一组字段。

字段依据为 msprobe master 4729e4e9b31a6f997e6f24e64dddd3fd9ec248ab，各表附源码位置；附件包含字段字典 JSON、本次源码及哈希清单。配置仍为 additional_config.kv_trace，日志标签及模块/插件名沿用 KV_GUARD / kv_guard。

本节设计附件为日志字段文档更新；下方 master 服务验证仅替换验证报告，不改动该设计附件。

设计 ZIP SHA256：131b662a10486816c2062077fd7a133524e7d29bca556bea7e91402bccfa54ff。

使能

在启动 vLLM 的 Python 环境正常安装 msprobe，使 entry point msprobe_kv_guard = msprobe.vllm_kv_guard:register 可发现。当前验收版本的配置字段为 kv_trace，模块和插件名仍为 kv_guard。

export VLLM_USE_V2_MODEL_RUNNER=1
vllm serve MODEL --additional-config '{"kv_trace":{"enabled":true,"action":"log"}}'

action 支持 log 和 raise；省略配置或设置 enabled:false 关闭。不需要 dump_config 或 PrecisionDebugger。若显式设置 VLLM_PLUGINS 白名单，需包含 msprobe_kv_guard。raise 会阻断结果并可能终止 EngineCore，不保证单请求隔离或恢复。

最终验收报告

下载本次 master 包服务验证报告、原始日志与复跑材料（ZIP）

解压后打开 msprobe_kv_trace_master_service_20261112.html。报告沿用原验证报告的 CSS、交互与证据栏目；同目录证据 ZIP 含本轮完整 server.log、7 份原始请求/响应、实际启动参数、master wheel、安装及构建记录、源码哈希和复跑说明。当前报告以本次完成的 master 服务验证为准。

本次结果：179 真实 NPU 服务验证 4/4 场景、11/11 检查通过；7/7 个 HTTP 请求正常返回，共生成 112 个 token。 action=raise 在 Worker 与 Scheduler 实际启用；完整日志中 kv.bind=74、kv.write=66、kv.read=66、kv.violation=0、kv.error=0。每个响应请求均能对应同一 trace 下的 bind/write/read。

包与版本： 本次固定 msprobe master 4729e4e9b31a6f997e6f24e64dddd3fd9ec248ab，使用该源码的标准 pip wheel 产物，未用 msprobe 源码目录覆盖安装包。wheel SHA256：854bedc2d0181f9921280d9b01f3f199e19ee5d274365ca69f97028fb8e29572。8个已安装产品源文件与该 wheel/master 清单一致，7个选定原生源文件运行前后哈希一致。

环境与范围： 179 / Ascend 910B4，Qwen3-0.6B BF16，MRV2、Eager、TP1/PP1/DP1，prefix caching与chunked prefill启用；配置 additional_config.kv_trace={"enabled":true,"action":"raise"}。沿用 vLLM 24420b7a 和 vllm-ascend 28e9e97 加既有PCP修复的原生环境，实际路径、版本和哈希见附件。依赖下载准备超时后复用既有依赖离线安装，准备日志单列；不将其计入功能场景。验证服务已正常退出0并释放本次资源。

本次没有故障注入，也未重跑 FULL、推测解码、DP/PCP/DCP/connector、关闭基线或性能矩阵。 kv.write/read 仍是边界计划，不能单凭它证明实际KV内容或模型数值正确。此前 e28d647a 组合的25/25用例、71项检查属于历史验收，不计作本次 master 复测。

按附件 README_REPRODUCE.md 选择空闲卡、端口和全新目录复跑；原始模型权重及原生依赖不包含在附件中。日志保留服务器UTC原值。

ZIP SHA256：e905df37ffa832469b382d1beef3e8e17a981daa9a702198e107cf72058938d8。

验收边界与未解决项

• 当前没有独立 kv.alloc/kv.release；finished/preempted 只记录原生通知，不证明请求解绑或物理 block 已归还。生命周期闭环仍是明确缺口。
• 此前组合验收的 slot-only 越界/null 用例检出 write_target_mismatch，没有覆盖 Scheduler binding 同时被改坏、仍自洽时的 write_outside_cache/null_block_write 专用分支。
• 未单独实机验证 MLA、encoder-decoder cross-attention、DBO 或全部 CP/connector 组合；边界信息完全一致的旧引用或纯 KV 内容污染不承诺检出。
• 本轮未测性能或多轮性能波动，也未做浏览器视觉检查；不得沿用旧版本性能作为当前版本验收值。

设计来源

• 整体需求 RFC #658
• 原始 vllm-ascend PR #17833