状态（Status）： Reviewing
作者（Authors）： wangchao285， hekunkun
**创建日期（Created）：**2026-10-28
**更新日期（Updated）：**2026-10-28
相关 Issue/PR： #123（关联 Issue/PR 以便追踪背景）

1. 概述

1.1 简介

本提案面向 vllm-ascend 推理框架，规划一套完整的 KV Cache 可观测性能力，由两个相互独立、可分别使能的子需求组成：

1. 需求一：vllm-ascend PD 分离 kvcache 数值类监控。在预填(Prefill)与解码(Decode)实例分离部署(PD 分离/PD disaggregation)形态下，对 KV Cache 的**容量占用、缓存命中、实例间传输(传输量、速率、时延、队列水位)**等数值指标进行周期采集与上报，支持 Prometheus 等标准观测协议与结构化日志，为容量规划、调度调优、传输链路故障定位提供量化数据支撑。参考实现：msprobe。
2. 需求二：vllm-ascend kvcache 行为类监控(block 级)。在 block 粒度对 KV Cache 的分配、释放、复用、所有权绑定、初始化前缀、逻辑位置等生命周期行为进行跟踪与校验，通过「调度器持有的请求绑定 × 执行元数据 × 算子实参」三方比对，诊断缓存越界、陈旧引用、未初始化写入等非法访问，将运行期黑盒故障转变为可定位、可归因的诊断信息。参考实现：vllm-ascend PR #17833（KV Cache Guard）。

两个子需求共享统一的可观测性框架(指标注册表、采集器、暴露器)，核心价值是显著降低 PD 分离部署与长稳运行的排障成本，让 KV Cache 的数值状态与行为状态从"运行时黑盒"变为"可观测白盒"。监控默认关闭、按需开启，对在线推理引入的开销可控可量化。

1.2 动机

使用场景：PD 分离部署是长上下文与大模型推理提升吞吐、优化 TTFT 的常见形态。P 实例计算密集(产出 KV Cache)，D 实例访存密集(消费 KV Cache)，两者之间通过 KV transfer 连接器(PyNcclConnector / P2pNcclConnector + RDMA/共享显存，kv_transfer_config.kv_role = kv_producer/kv_consumer)批量搬运 KV block。这类集群上生产后，运维与算法人员高频提出三类问题：

• 容量问题：KV Cache 到底占了多少 NPU 显存？P→D 每个请求传了多少数据？缓存命中率是多少？
• 性能/调度问题：传输队列是否堆积？传输时延是否是瓶颈(影响 TTFT/ITL)？prefix cache 是否生效？
• 正确性问题：输出乱码、PPL 飙升等精度劣化，是不是由 KV Cache 非法写入/陈旧复用导致的？具体是哪个 block？

当前痛点：

• vllm-ascend 现有指标聚焦请求级(num_requests_running、kv_cache_usage_perc 等)，缺少 PD 传输面与 block 行为面的观测。问题出现时只能加日志重启、靠经验与 printf 排查，一个跨实例的 KV 传输问题常常要数小时定位。
• KV Cache 损坏类故障(block 释放后被复用写坏、写入未初始化前缀、token 落错 block)具有偶发性与不可复现性，无监控手段时几乎不可归因，严重威胁长稳部署的可靠性，且难以向用户给出明确根因。

必要性：上述两类能力的实现都可在插件层完成、默认关闭、开销可量化，投入可控；而缺失的代价是 PD 部署与 block 级问题持续黑盒，生产可维护性受限。

用户价值：排障时间从"小时级"降至"分钟级"；为容量规划、调度策略调优提供量化依据；为长稳可靠性提供故障诊断与证据链。

不做此提案的影响：PD 分离上生产仍缺少传输面与 block 行为面的基础观测手段，相关故障依赖人工排查，SLO 维护成本居高不下。

1.3 目标

目标

• 需求一(数值类监控)：定义并实现一组 PD 分离场景的 KV Cache 数值指标与采集上报链路(指标统计 + Prometheus /metrics 暴露 + 结构化日志)，覆盖 P 端、D 端与传输面；使能后对在线推理性能的影响控制在设计指标之内(见 3.3)。
• 需求二(行为类监控)：实现 block 级 KV Cache Guard 运行时，覆盖 V1/V2 调度器；正确识别并报告六类非法行为——精确 token 目的地(落块是否正确)、分配代数(use-after-release/陈旧引用)、所有权归属、逻辑 block 顺序、未初始化前缀写入、空 block 写入；支持 log/raise 两种处置动作；默认关闭、配置化使能。
• 共同目标：提供开发者可配置、可集成、可二次扩展的编程与调用接口，并输出配套《编程手册》，保证最终实现可验收。

非目标(边界说明，防止需求蔓延)

• 不做 KV Cache 数值内容级校验：不保存 KV 快照、不做内容哈希，不比对 KV 数据的字节数值。
• 不做传输完整性校验：不校验跨节点/WPAN 传输的 KV 数据是否逐字节一致(网络/RDMA/NPU 传输本身不在本次范围内)。
• 不阻断或撤销已提交的缓存写入，不检查内核(NPU 算子)内部内存指令；Guard 是事后诊断机制，不是实时防护。
• 不做 KV Cache 显存替代、淘汰策略治理或容量规划的业务决策。
• 不承诺跨版本指标命名稳定性：指标命名随上游 vllm 演进可调整，使用者应以随版本发布的《指标字典》为准。

2. 用例分析

针对上述两个子需求的各类场景，用例分析如下。

用例编号	用例名称	主要功能点	关键性能指标	安全隐私	DFX 要求	使用限制/约束
UC-01	PD 传输面数值观测	采集 P→D KV 传输量、传输速率、传输时延分布、传输队列深度；支持 Prometheus 拉取与日志输出	采集周期可配(默认 1 s)；单实例采集附加开销 < 1% CPU	仅暴露数值聚合值(计数/速率/时延分位)，不透出请求内容、token 或业务数据	可维护：指标注册表统一管理并提供指标字典；可测试：可离线注入传输事件验证统计	指标仅反映观测窗口内的传输行为，不包含内容校验；同一型号 NPU 间可横向对比，跨型号对比需谨慎
UC-02	池容量与命中观测	采集 KV pool 占用百分比、block 分配/释放计数、prefix 缓存命中次数与命中率	与指标采集同周期；直方图分桶(如 P50/P95/P99)	同上，仅聚合值	兼容 prefix caching 与 chunked prefill 场景；指标语义需文档化	命中率统计口径(按 token 还是按 block)需在文档中明确，避免误读
UC-03	block 级非法访问诊断(KV Guard)	跟踪 block 分配/释放/调度绑定；用「调度器绑定 × 执行元数据 × 算子实参」三方比对识别六类非法行为；上报告警(结构化日志)	违规检测在算子执行边界完成，不阻塞显式调度流程；guard 使能时额外显存开销有明确上界	元数据仅含 block 号/请求 ID/代数等诊断字段，不含 token 内容与历史	可维护：V1/V2 共享同一 Guard 运行时，仅一处维护；可测试：提供确定性故障注入夹具	不支持的缓存/执行语义(超出守护范围)按文档拒绝并提示；不能撤销已发生写入
UC-04	raise 隔离与恢复	action=raise 时，检测到违规即锁存错误、停止返回 worker 结果，隔离故障请求	违规 → 锁存 → 阻断结果返回的时延可接受(秒级内)	错误上下文同 UC-03，不泄业务数据	可靠：失败锁存语义明确；恢复：worker 重启后可复用	worker 需重启才能复用，运维 SOP 需说明
UC-05	图模式(eager/FULL)兼容	监控在 eager 执行与图模式(图捕获/FULL)下语义一致，不因图捕获边界破坏监控正确性	图模式下监控采集不引入额外图 capture 失败	—	兼容 V1/V2 × eager/FULL × 使能/禁用多维矩阵	图捕获边界的元数据时机差异由运行时内部适配
UC-06	二次开发集成	开发者可配置使能、扩展自定义指标/采集器、将监控接入自有观测系统(对接 Prometheus/日志平台)，可订阅 guard 违规事件	扩展点文档化，接口稳定	扩展点不做额外数据透出，数据脱敏责任在使用方	可维护：提供《编程手册》快速上手；可测试：提供沙箱示例	扩展需遵守指标命名规范(见 3.5)与接口约束

3. 方案设计

3.1 总体方案

整体思路：在 vllm-ascend 插件层构建统一的可观测性框架——KVCache Monitor，包含「指标注册表 + 采集器(Collector)+ 暴露器」三段式结构；数值类监控与行为类监控分别以独立采集器接入框架，行为类监控额外挂接共享的 GuardRuntime(请求/执行校验)。所有能力 opt-in 使能，默认不改变任何调度与执行语义。

系统架构布局：

┌─────────────────────── PD 分离集群 ───────────────────────┐
│                                                            │
│ ┌─ P 实例 ────────────────┐   ┌─ D 实例 ───────────────┐   │
│ │ 调度器(prefix命中/块分配) │   │ 调度器(块获取/复用)     │   │
│ │ 采集器 A(容量/命中)      │   │ 采集器 C(接收/复用)     │   │
│ └───────────┬─────────────┘   └───────────┬─────────────┘   │
│             └── KV block 传输面(数值:量/速率/时延/队列) ──┘   │
│              (PyNcclConnector / P2pNcclConnector + RDMA)     │
│ ┌────────────────── 统一监控框架 KVCache Monitor ──────────┐ │
│ │ 指标注册表 │ 采集器(数值类/行为类) │ 暴露器(/metrics+日志) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ┌────────── 行为类监控:KV Cache Guard Runtime ─────────────┐ │
│ │ 调度器钩子(alloc/release/schedule)× 执行元数据            │ │
│ │ × 算子实参比对 ──▶ 违规(六类)→ action=log / raise       │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

核心逻辑：

• 数值类监控采集链：在 P/D 实例的调度器、worker、KV transfer 连接器等关键点位埋点采集器，采集事件(分配/释放/命中/传输起止)以 O(1) 原子自增/汇总进入进程内统计结构，周期性(默认 1 s)由暴露器对外输出为 Prometheus 指标文本 /metrics，同时可按需输出结构化日志(JSON)。采集走独立轻量线程/异步路径，不阻塞推理线程。
• 行为类监控校验链(Guard)：
  1. 调度器钩子：allocation / release / schedule 三个钩子按引擎实例从配置使能，记录「请求 ↔ 被分配 block」的绑定关系与生命周期。
  2. 执行元数据：V1/V2 各自适配器把调度结果归一化为紧凑元数据(block 号、分配代数、拥有者请求、已初始化前缀、逻辑顺序)。
  3. 算子实参观察：在模型运行器执行边界观察传给算子的实际 block/地址参数。
  4. 三方比对：调度器绑定(预期) vs 执行元数据(绑定) vs 算子实参(实际)，凡不一致即判定为六类非法行为中的某一类；空 block 写入可从元数据直接判定，无需算子钩子。
  5. 生命周期边界：在现有 clear/copy 边界以及 Mooncake receive 完成边界处更新合法性状态。
  6. 处置：log 记录违规上下文；raise 锁存违规并停止返回 worker 结果，worker 需重启才能复用。

平台与依赖：运行于华为昇腾 NPU(如 910B 系列)平台，依赖 CANN、torch_npu 与 vllm-ascend 插件环境，不引入新硬件依赖；数值监控可选依赖 Prometheus 客户端库(或自实现文本暴露端点)。

限制与约束说明：

• Guard 仅对受支持的缓存/执行语义生效，不支持的语义在配置阶段被拒绝并给出提示(与参考实现一致)。
• 监控在「使能 + 内存充足」前置条件下达成性能指标(见 3.3)，极端显存紧张时会优先保证推理不受影响。
• 数值指标跨型号 NPU 对比需注意带宽模型差异(doc 内注明)。

3.2 技术选型

数值类监控实现方式：

候选方案	优点	缺点	结论
内置运行期指标采集(Prometheus /metrics + 日志)	实时、低开销、可对接主流观测体系、可加载 Grafana	需维护指标注册表与命名规范	✅ 选择：实时可观测，满足 UC-01/02/05
离线日志(post-run 解析推理日志)	实现简单、零运行期侵入	滞后、难以对齐跨实例时序、样本不完整	✗ 放弃

行为类监控元数据方案：

候选方案	优点	缺点	结论
紧凑元数据三方比对(本方案)	显存/算力开销小、可捕获六类非法行为、离线可分析	只校验行为不校验内容	✅ 选择：满足非目标约束，命中故障注入场景
KV 快照 + 内容哈希全量校验	可发现内容级损坏	需要保存 KV 数值，显存/带宽开销大，属非目标范围	✗ 放弃
token 历史持久化	证据完整	持久化负担与隐私风险，非目标	✗ 放弃

Guard 运行时实现结构：

候选方案	优点	缺点	结论
V1/V2 共享同一 GuardRuntime(本方案)	单一实现、行为一致、一处维护；V2 仅增加内部适配器(batch id 排序、元数据时机、图捕获边界)	适配层需仔细维护	✅ 选择：与参考实现 PR #17833 演进一致(早期独立 kv_guard_v2.py 模块已因冗余被删除)
V1/V2 各自独立守卫实现	互不干扰	双份实现、行为漂移风险	✗ 放弃

集成落点：监控全部落在 vllm-ascend 插件层与 additional_config 配置面，不 fork、不修改上游 vllm 核心，随上游演进可平滑升级。

3.3 功能与性能设计

3.3.1 需求一：PD 分离 KV Cache 数值类监控

指标设计(以下为设计建议表，最终指标命名与口径以参考实现 msprobe 评审确认后固化进入《指标字典》):

指标名(建议前缀 vllm_ascend_)	含义	数据来源/点位	粒度	单位
kv_cache_usage_percent	KV 池当前占用百分比	P/D 调度器 KV 池	实例级/块粒度聚合	%
kv_block_alloc_total	累计新分配 block 数	P 调度器分配点	实例级 Counter	个
kv_block_free_total	累计释放 block 数	P/D 调度器释放点	实例级 Counter	个
prefix_cache_hits_total	prefix 缓存命中累计次数	P 调度器 prefix 命中点	实例级 Counter(附 token/block 口径标签)	次
prefix_cache_hit_ratio	prefix 缓存命中率(窗口)	命中数 / 总请求前缀块数	窗口聚合	—
pd_transfer_tokens_total	P→D 累计传输 token 数	KV transfer 连接器(发送侧)	实例级 Counter	tokens
pd_transfer_latency_seconds	单次 P→D KV 传输时延直方图	连接器发送起止	直方图(P50/P95/P99)	s
pd_transfer_queue_depth	传输队列当前深度(等待传输的 KV 批次)	连接器队列	实例级 Gauge	批
pd_transfer_in_flight	在途(未完成)传输数	连接器发送中	实例级 Gauge	批

运行核心流程(文字描述)：

1. P 实例调度器为请求分配 prefix 命中段 + 新算段，产生 block 分配事件与命中事件；采集器 A 原子累加。
2. P 实例对需传输的 KV block 发起传输(经 KV transfer 连接器)；连接器在发送起止点记录时延、在发送前记录 token 数，累加传输计数器；队列深度在入队/出队时更新。
3. D 实例接收完成后，采集器 C 更新接收量；若 D 实例侧触发复用/释放，同步更新块计数。
4. 暴露器按周期(默认 1 s)将聚合值格式化为 Prometheus 文本协议输出到 /metrics，同时按日志级别关联打印(可选)。

性能设计与影响范围：

• 全部采集点为 O(1) 原子自增/读写，不申请锁；直方图分桶固定(如 8~10 个桶)；
• 暴露器基于独立异步路径与自研轻量文本序列化，不依赖 gunicorn 等重型 web 栈(如引入 Prometheus 客户端库需评估线程模型)；
• 设计指标：使能数值监控后，在线推理吞吐/时延衰减 ≤ 3%(以同负载同模型使能前后对比为准)；采集周期内 CPU 附加开销 < 1%；额外显存占用可忽略(仅统计结构)。
• 影响范围：仅新增观测侧代码与配置项，不改变调度、执行与传输的原始语义；指标可在运行期开关(热禁用仍保留累计值)。

3.3.2 需求二：KV Cache 行为类监控(block 级)

检查项设计(与参考实现 PR #17833 校验维度一致):

编号	检查维度	非法行为描述	检测原理	是否需要算子实参观察
C1	精确 token 目的地	调度的 token 写入了错误的 block	调度绑定 vs 实参地址比对	是
C2	分配代数(use-after-release)	block 被释放后又被复用，陈旧引用写坏新内容	每 block 维护 allocation generation，引用代数不匹配即违规	是
C3	所有权	block 不归当前请求所有	owner 字段比对	是
C4	逻辑 block 顺序	逻辑 block 顺序与预期不符(乱序/越序)	逻辑顺序号比对	是
C5	已初始化前缀	写入未初始化的前缀块	前缀初始化位 check	是
C6	空 block 写入	对空(null)block 执行写入	从元数据直接判定，无需算子钩子	否

数据模型(核心元数据结构)：

字段	类型	描述
block_id	int	物理 block 号
generation	int	分配代数，每次分配/复用递增
owner_request	str/int	当前拥有的请求标识
init_prefix_len	int	已初始化前缀长度
logical_order	int	逻辑 block 顺序号
status	enum	FREE / ACTIVE / RESERVED(生命周期边界)

执行流程(文字描述)：

1. 配置使能后，调度器钩子(alloc/release/schedule)按引擎实例挂载，在调度决策时建立/更新/清理 BlockState 元数据；
2. 排队/批处理后，V1/V2 适配器将调度结果归一化到执行元数据(batch id 已排序、元数据时间点对齐)；
3. 模型运行器执行边界观察算子实参(实际 block/地址)，与执行元数据、调度器绑定三方比对；
4. 空 block 写入由元数据直接判定；命中任一检查维度即产生一次违规事件；
5. action=log：记录违规上下文到结构化日志；action=raise：锁存错误并停止返回 worker 结果，worker 需重启才可复用；生命周期状态在 clear/copy 边界及 Mooncake receive 完成边界更新，确保比对语义与运行时一致。

限制与约束：Guard 不保存 KV 快照/内容哈希/token 历史；不支持的缓存/执行语义在使能时被拒绝并提示；不阻断已提交写入(仅事后诊断)。

3.4 安全隐私与DFX设计

安全隐私：

• 监控仅采集数字聚合值与块级诊断字段(block 号、代数、请求 ID)，不透出任何 token 内容、请求正文或业务数据；Guard 元数据不保存 KV 数值与 token 历史，天然规避隐私面；
• /metrics 端点默认仅监听本地/受控网段，建议由运维统一做访问控制与加密网关代理；日志输出遵循现有日志脱敏规范；
• 配置接口的非法值(非法字段名、非布尔 enabled、未知 action)一律拒绝，避免配置面被注入。

兼容性：

• 调度语义兼容：V1 与 V2 共享同一 GuardRuntime，V2 仅内部适配器差异(排序、元数据时机、图捕获边界)；与前置存在的 prefix caching、chunked prefill 语义相容(检查项 C5 与之协同)；
• 图模式兼容：eager 与 FULL(图捕获)下监控语义一致，图捕获边界不影响元数据新鲜度；
• 配置兼容：采用 additional_config.kv_guard_config，不引入新环境变量，移除的旧变量不回退(与参考实现一致)；数值监控的指标端点为标准 Prometheus 文本协议，可平滑接入既有观测系统。

可维护性：

• Guard 单一运行时、单一配置面、一处维护；指标经注册表统一管理，附《指标字典》；
• 随版本发布 release note 片段(如 release_notes/fragments/<PR>.yaml)说明行为变更；
• 卸载计划：上游 vllm 若提供"具有相同独立证据的分配生命周期与调度器输出扩展点"，则移除调度器包装，降低维护成本。

可测试性：

• 提供确定性故障注入夹具(向已加载前缀的 dummy block 写入、非法读取、空 block 写入等)，CI 中一键复现；指标采集器支持事件注入式单测。

可靠性：

• 比对不一致仅产生告警/锁存，不引发二次崩溃；统计结构使用原子操作，崩溃后进程内计数归零、不持久化不一致状态；
• raise 的失败锁存语义明确，worker 重启恢复路径文档化；监控自身额外显存有明确上界(仅紧凑元数据，无 KV 快照/哈希/历史)。

3.5 编程与调用设计

3.5.1 编程模型基本设计

开发环境：

• 软/硬件：Linux x86_64 + 昇腾 910B 系列(Ascend 硬件)；python ≥ 3.10；CANN 对应版本 + torch_npu；vllm + vllm-ascend 对应版本(建议同版本配套);
• 工具链：与 vllm-ascend 一致的 lint 工具(ruff)、静态检查、pytest 单测、e2e 启动脚本；调试建议使用 NPU_LOG_LEVEL 与结构化日志采样;
• 可复用框架：监控框架(KVCache Monitor)为 out-of-tree 插件模块随 vllm-ascend 发布，无需用户自建。

开发约束：

• 指标名统一保留 vllm_ascend_ 前缀，注册前查重；
• Guard/监控组件不得改变调度、执行、传输的语义；不得引入推理关键路径上的阻塞/锁竞争；
• 扩展自定义采集器必须遵守注册表与命名空间约束，不依赖 NPU 私有算子(保证可移植到 eager/FULL 两种模式)；
• 不支持的缓存/执行语义应显式拒绝而非静默降级。

可验收设计：

• 验收环境：昇腾 910B4×1 及以上，模型如 Qwen3-0.6B、TP=1、BF16、block_size=128，开启 prefix caching 与 chunked prefill；
• 验收标准：见第 4 章测试设计(单测/集成/e2e 全部通过；使能前后性能衰减满足 3.3 设计指标；故障注入检出率 100%)。

3.5.2 接口定义与设计

3.5.2.1 KV Guard 行为监控配置接口(additional_config.kv_guard_config)

• 接口描述：通过 --additional-config 以 JSON 结构使能 block 级行为监控(KV Cache Guard)并指定违规处置动作。不可用环境变量回退，仅当配置存在且合法时生效。
• 接口原型(配置示例)：

{
  "kv_guard_config": {
    "enabled": true,
    "action": "raise"
  }
}

• 输入/输出参数：

参数名称	输入/输出	类型	描述	取值范围
kv_guard_config	输入	object	行为监控配置整体结构	缺省表示不使能
enabled	输入	boolean	是否使能 Guard	true / false，非布尔值拒绝
action	输入	enum(string)	违规处置动作	"log"(默认)/ "raise"

• 返回参数：

参数名称	类型	描述	取值范围
N/A	—	配置校验失败时启动报错，并给出具体拒绝原因	—

• 异常处理：配置中存在非法字段名、enabled 非布尔、action 值未知时，拒绝启动并打印拒绝原因；不静默忽略。
• 约束说明：Guard 不支持超出其守护范围的缓存/执行语义，相关配置组合被拒绝；raise 模式下触发违规后 worker 结果停止返回，需重启 worker 恢复。
• 变更说明：本接口替代旧的 KV Guard 环境变量(移除、不支持回退)，为 v1 新引入接口。
• 调用参考代码(命令行)：

# log 模式(默认): 违规仅记录日志
vllm serve MODEL \
  --additional-config '{"kv_guard_config":{"enabled":true}}'

# raise 模式: 违规即锁存并停止返回结果
vllm serve MODEL \
  --additional-config '{"kv_guard_config":{"enabled":true,"action":"raise"}}'

3.5.2.2 数值监控指标暴露接口(Prometheus /metrics)

• 接口描述：数值类监控将注册的指标(见 3.3.1 指标表)以 Prometheus 文本协议暴露于本地 HTTP 端点 /metrics，供 Prometheus/Grafana 等系统拉取；同时兼容结构化日志输出。
• 接口原型：GET /metrics(HTTP)，Accept: text/plain; version=0.0.4; charset=utf-8；日志输出为既有 log_struct 通道。
• 输入/输出参数：

参数名称	输入/输出	类型	描述	取值范围
metrics_path	输入(配置)	string	端点路径	"/metrics"(默认，可配置)
scrape_interval	输入(配置)	int	采集/输出周期	默认 1 s，单位 s
指标样本	输出	text	Prometheus 文本协议样本	见 3.3.1 指标表

• 返回参数：

参数名称	类型	描述	取值范围
响应体	text	Prometheus 文本协议指标样本	200 时全部注册指标样本；未使能时为空 200 或禁用状态

• 异常处理：端点内部采集异常时返回重试语义(HTTP 500)且不影响推理进程；统计结构处于竞态窗口时输出最后一次完整快照。
• 约束说明：端点默认仅监听本机回环/受控网段，建议经反向代理与访问控制接入公网；指标命名遵循 vllm_ascend_ 前缀与《指标字典》。
• 变更说明：新增端点与指标，不修改既有 /metrics 与既有 vllm 指标。
• 调用参考代码(Prometheus 配置节选)：

scrape_configs:
  - job_name: "vllm_ascend_kv"
    static_configs:
      - targets: ["<P 实例 IP>:8000", "<D 实例 IP>:8000"]
    metrics_path: /metrics

3.5.2.3 自定义采集器扩展点(二次开发)

• 接口描述：允许开发者向 KVCache Monitor 注册自定义采集器或订阅 Guard 违规事件，便于接入自有观测/告警系统。参考实现为纯函数式注册回调。
• 接口原型：

from vllm_ascend.monitor import register_collector, subscribe_guard_events

@register_collector(name="my_kv_custom_metric", metric_type="gauge")
def my_collector(ctx) -> float:
    """返回当前快照值, 由框架按周期拉取并纳入 /metrics 输出。"""
    ...

def on_guard_violation(event: GuardViolationEvent) -> None:
    """收到违规事件时回调; 实现方自行处理幂等与限流。"""
    ...

subscribe_guard_events(on_guard_violation)

• 输入/输出参数：

参数名称	输入/输出	类型	描述	取值范围
name	输入	string	自定义指标名，需带 vllm_ascend_ 前缀	唯一，注册查重失败即报错
metric_type	输入	enum(string)	指标类型	gauge / counter / histogram
采集器返回值	输出	float/int	采样快照值	数值范围取决于实现
GuardViolationEvent	输出	object	违规事件对象(block_id、generation、维度、时间戳等)	见 3.3.2 检查项

• 返回参数：注册成功返回句柄；失败(重名/非法类型)抛异常。
• 异常处理：自定义采集器异常被框架捕获并打印告警，不影响既有指标与推理。
• 约束说明：采集器必须为无阻塞纯函数；违规事件回调必须幂等并自行限流；不得在回调中修改 Guard 内部状态。
• 变更说明：新增扩展点，向后兼容。
• 调用参考代码：见上方原型内注释；完整示例随《编程手册》发布。

3.5.3 编程手册设计

在既有 vllm-ascend 文档体系内更新——新增/扩展 《user_guide / feature_guide》 中的 KV Cache 监控章节(数值监控 + Block 级行为监控)，采用随版本更新、单独成章方式输出，建议包含：

1. 功能概述与适用场景(PD 分离、长稳排障)；
2. 使能方式：--additional-config 配置示例(数值监控开关、KV Guard enabled/action)；
3. 指标字典：全部 vllm_ascend_* 指标定义、口径(含命中率按 token/block 口径说明)、单位；
4. 违规检查项说明(C1~C6)与日志样例解读；
5. 故障排查 SOP：典型告警(传输堆积、命中率低、action=raise 锁存)的处理步骤；
6. 二次开发指南：自定义采集器与违规事件订阅示例、命名规范与约束；
7. 限制与 FAQ：不支持语义、跨型号对比注意、指标命名演进策略。

4. 测试设计

单元测试(Unit)：

• KV Guard 元数据状态机(alloc/release/schedule/clear/copy 边界的 BlockState 流转)；
• 三个接口的配置解析与非法配置拒绝(非法字段、非布尔 enabled、未知 action)；
• 数值指标聚合正确性(直方图分桶、Counter 累加、Gauge 快照)与注册表查重；
• V1/V2 共享安装、V2 batch id 排序、图元数据新鲜度、失败锁存语义(参考实现为 108 个聚焦单测，本设计维持同等覆盖)。

集成测试(Integration)：

• 兼容矩阵：V1/V2 × eager/FULL × disabled/enabled 的「服务可用性 + 零误报」验证(参考实现为 910B4 原生 8 个服务器、112 个 HTTP-200 补全，enabled 组记录 raise 且零违规)；同矩阵加做使能前后性能对比(吞吐、TTFT/TPOT、峰值显存)，验证 3.3.1 设计指标(衰减 ≤ 3%)；
• 扩展协议矩阵：prefix caching、chunked prefill、Mooncake 场景的回归(参考实现扩展套件 603 通过率，基线 3 项既有失败不在本次范围)。

端到端测试(E2E)：

• 故障注入：向已加载前缀的 dummy block 写入、构造陈旧引用后的非法读取、空 block 写入三类故障，在 MP/MLA 等真实 NPU 算子上验证 C1~C6 全部被检出(log 与 raise 两种模式)；
• PD 数值链路端到端核对：在 1P1D 部署下，核对 /metrics 中 pd_transfer_* 指标与真实传输请求量、时延统计、池水位一致，且与 D 实例接收侧计数对齐；
• KV Guard 事件 → 日志/告警 → 恢复(重启 worker)全链路演练。

性能/资源测试：

• 使能/禁用对照：同负载、同模型、同批次下吞吐与 TTFT/TPOT 差异；
• Guard 额外显存上界测量(仅紧凑元数据)，文档化结果。

5. 缺点和风险

说明潜在风险（Breaking Change、性能回退、复杂度提升、引入的安全问题）、负面影响（对现有功能/用户的冲击）、实现成本（代码量/维护成本/人力投入）、是否有API或版本兼容性、旧版本迁移方案问题等，给出应对措施。

6. 现有技术

参考其他项目/社区的类似设计，说明借鉴与差异。

7. 未解决问题

待社区讨论/决策的开放问题，如硬件适配范围、参数默认值等（需在RFC通过前解决）。

附录

• 参考资料链接
• 术语表
• 文档更新计划