vLLM Ascend · 根模块 API 参考

vllm_ascend 包入口（108 行）。_ensure_global_patch 在 engine-core 初始化前应用进程级 vLLM patch；register() 向 vLLM 注册 NPU 平台（Platform），并依次注册 KV connector（register_connector）、模型加载器（register_model_loader）、服务级 profiling（register_service_profiling）与 Ascend 定制模型（register_model），是整个插件被 vLLM 识别的起点。

Ascend 配置中心（1473 行）。AscendConfig 承载 additional_config 的全部 Ascend 专属选项：输入范围校验（_validate_user_input_ranges）、派生校验（derive_and_validate）、MC2 通信算法校验、sparse C8 KV offload 兼容性检查、megamoe 支持判定、dump 配置落盘、compile ranges 解析与分段点更新等；子配置类：AscendCompilationConfig/AscendFusionConfig（图优化与融合算子开关）、EplbConfig、RejectionSamplerConfig（Block/Entropy Verify）、RlConfig（强化学习负载默认值）、DynamicSpecConfig（动态投机）、FinegrainedTPConfig、XliteGraphConfig、ProfilingChunkConfig、BatchJobSchedConfig、ShortRequestFirstConfig、DyntraLBConfig、SchedulerConfig、SparseKVOffloadConfig；init_ascend_config/get_ascend_config/clear_ascend_config 管理全局单例生命周期。

NPU forward 上下文（456 行）。set_ascend_forward_context 是核心上下文管理器：把注意力元数据、token 数、DP 分布、profile-run 标志等注入 forward 状态供各层读取；select_moe_comm_method 按 A2/A3/A5 硬件代际与并行配置选择 MoE 通信方法（_select_a2/a3/a5_moe_comm_method，结合 MC2 tokens 容量判定）；set_mc2_tokens_capacity/set_mc2_mask 管理 MC2 通信容量与掩码的全局状态；override_mrv2_in_profile_run 为单次 forward 临时设置 MRV2 profile-run 标记；_ExtraForwardContextProxy 为 v1/v2 两个运行器提供统一的 forward-context 属性访问代理。

批不变（batch-invariant）模式（163 行）。enable_batch_invariant_mode/init_batch_invariance 把关键算子替换为批不变实现：add_rms_norm 绕过 AclnnAddRmsNorm（其无法保证批不变，改用等价组合实现）、reduce_sum 用 npu_reduce_sum_batch_invariant 替换 torch.sum；override_envs_for_invariance 设置相关环境变量。目的是保证同一输入在不同 batch size 下产生逐位一致的结果（RL 训练/数值对齐场景必需）。

轻量配置工具（50 行）。config 装饰器把普通 dataclass 变成与 vLLM config 兼容的配置类（不导入 vllm.config，避免依赖），用于定义无需完整 vLLM 配置体系的小型配置对象。

CPU 亲和性绑核（804 行）。DeviceInfo 解析 npu-smi 输出：分离 header、识别 CPU 列表、枚举逻辑 NPU、解析 NPU-CPU 拓扑亲和（parse_topo_affinity）与可用 CPU；CpuAlloc 生成并应用绑核方案：cpu_to_mask 转亲和性掩码、average_distribute 平均分配、extend_numa 跨 NUMA 扩展、build_ascend_950_cpu_pools 为 Ascend 950 构建专用 CPU 池、bind_uvb_poll_window_threads 绑定 UVB 轮询线程；bind_cpus(rank_id) 是对外入口：按 rank 的 NPU 拓扑把 worker 线程绑到最优 CPU 集合，减少跨 NUMA 访问；is_arm_cpu 判断 ARM 平台。

环境变量定义模块（87 行）。通过模块级 __getattr__ 惰性解析环境变量（访问时才读取并校验），__dir__ 支持自动补全，集中管理 vllm_ascend 的全部环境变量开关。

日志配置（208 行）。在 vLLM 日志体系上叠加 Ascend 标识：AscendFormatter/AscendColoredFormatter 给每条日志加 [vllm-ascend] 前缀并从调用方文件路径推断模块名（_infer_module_name）；RotatingAscendFileHandler 按 _setup_file_logging 配置的大小上限轮转日志文件；configure_ascend_logging/configure_ascend_file_logging 完成 vllm_ascend logger 的格式化器与文件 handler 装配；_use_color 判断终端是否启用彩色输出。

自定义算子 meta 注册（77 行）。register_meta_if_necessary 为算子注册 fake/meta 推导函数（torch.compile 需要无设备执行的形状推导）；bgmv_expand_meta/sgmv_expand_meta 分别定义 LoRA BGMV/SGMV expand 算子的输出形状推导规则。

NPU 平台类（1567 行）。NPUPlatform 是 vLLM Platform 在昇腾上的实现：设备能力声明（sleep 模式、cumem 分配器、pin memory、hybrid KV cache、静态图模式、自定义集合通信、opaque attention op）、设备管理（set_device/manual_seed_all）、KV cache 规格注册（register_custom_kv_cache_specs）、pass 管理器选择（get_pass_manager_cls）等；模块级校验与装配函数：_fix_incompatible_config 修正与 NPU 不兼容的配置、_validate_eplb_config/_validate_parallel_config/_validate_fa3_backend/_validate_sfa_dcp_kv_sp 等专项校验、_update_compilation_modes/_setup_compile_backend 更新编译与 cudagraph 模式并重算捕获尺寸、_setup_worker_and_scheduler 选择 worker/调度器实现（含重计算调度器与 DyntraLB 调度器类解析）、_set_pytorch_npu_alloc_env 配置分配器环境。

服务级 profiling 配置生成器（591 行）。generate_service_profiling_config 生成 service_profiling_symbols.yaml 配置文件（指定需要采集的性能符号），get_config_dir 定位 vllm_ascend 配置目录，_cleanup_temp_file 清理临时文件；配合 CANN 的 Profiler 实现按需采集。

全局工具集（1570 行）。硬件与设备：is_rc_device 检测 310P 是否 RC 模式、aligned_16 为 310P 做 16 对齐；DSV4 辅助：extract_dsv4_layer_index/get_dsv4_spec_layer_idx_from_weight_name/get_dsv4_compress_ratio 处理层号与压缩比；格式转换：nd_to_nz_2d/nd_to_nz_spec 把 ND 张量/掩码转为 NZ 分块布局、_custom_pad/_custom_reshape/_custom_transpose 封装设备端变换；多流管理：current_stream/global_stream/shared_experts_calculation_stream/attention_calculation_stream/cp_chunkedprefill_comm_stream 提供各计算/通信流；自定义算子：enable_custom_op 惰性初始化 vllm_ascend_C（避免 CANN RTS 提前初始化）、bootstrap_custom_op_env/register_ascend_customop 注册环境与算子、find_hccl_library 定位 HCCL 库；细粒度 TP 开关：lmhead_tp_enable/embedding_tp_enable/oproj_tp_enable/olora_tp_enable；其他：dispose_tensor 释放张量、update_cudagraph_capture_sizes、vllm_version_is 版本判断、adapt_patch 全局/局部 patch 适配、setup_ascend_local_comm_res 加载 A5 本地通信端点配置。

compilation 子包标记。该包实现 Ascend 的图编译与 ACL graph 捕获重放：编译器接口、图融合 pass 管理器及各融合 pass。

ACL graph 捕获与重放核心（396 行）。ACLGraphWrapper 把可执行对象包装出 ACL graph 捕获/重放能力（__call__ 按形状桶捕获后重放）；GraphParams 按捕获 token 数键控图参数，提供主模型/draft/draft-prefill 三套 set/get/update 接口；update_full_graph_params 在重放前重绑注意力后端的 host 侧参数（block table/seq lens 等）；weak_ref_workspaces 用弱引用持有 workspace 防止捕获期间被回收；_is_stream_resource_capture_error/_is_old_hdk_capture_error 识别捕获失败的已知错误类型以便降级处理。

可中断 ACL graph 封装（91 行）。BreakableACLGraphWrapper 支持 in/out 图边界打断的捕获（_capture）与重放（_replay），用于单张图无法覆盖整个前向（如含条件分支或通信边界）时把前向切成多段图执行。

Ascend 编译器接口（368 行）。AscendCompiler 是注册给 torch.compile 的自定义编译器：compute_hash 计算编译缓存键、initialize_cache 初始化缓存目录、compile/load 编译与加载；_configure_backend 配置后端选项；fusion_pass_compile 走图融合 pass 的编译路径（配合 GraphFusionPassManager）；npugraph_ex_compile 走 NPU graph 扩展编译路径；_compute_decode_cudagraph_batch_sizes 计算 decode 图的批量捕获尺寸；compile_fx 为 FX 图的标准编译入口（含分解规则）。

图融合 pass 管理器（69 行）。GraphFusionPassManager 维护融合 pass 列表：add 注册 pass、configure 按 compile range 配置适用范围、__call__ 依次执行各 pass 对 FX 图做模式匹配重写。

compilation.passes 子包标记。该包收录基于模式匹配的图融合 pass。

AllGather+chunk 恒等折叠 pass（40 行）。AllGatherChunkNoOpCleanupPass 匹配 all_gather 后接 sequence_parallel_chunk 的组合（gather 后又按原样切回），把整段重写为 identity 消除无效通信。

融合模式基类（63 行）。BasePattern 定义模式匹配 pass 的骨架：get_inputs 声明模式占位输入、get_pattern 给出匹配子图、get_replacement 给出替换子图、get_extra_stream_scope_check 附加同流检查、register 把模式注册进 torch 图替换体系。

乘加融合 pass（110 行）。MulsAddPattern 匹配逐元素 x*scale+y 序列，替换为单个 muls_add 算子减少访存；MulsAddFusionPass 在指定 compile range 内应用该模式（is_applicable_for_range 判断适用性）。

无效节点清理 pass（62 行）。NoOpEliminationPass 在其他 pattern 重写后扫描图：识别 view/reshape 类节点（_is_view_like），若其维度变换前后等价（_dims_equivalent/_all_dims_equivalent）则从图中移除，减图优化噪声。

Norm+量化融合 pass 族（403 行）。匹配 AddRMSNorm 后接量化的组合并融合为单一算子：静态量化（AddRMSNormQuantPattern 及带 bias 变体）、动态量化（AddRMSNormDynamicQuantPattern 及带 bias 变体）、动态 MX 量化（AddRMSNormDynamicMXQuantPattern）、RMSNorm+MX 量化（RMSNormDynamicMXQuantPattern）；AddRMSNormQuantFusionPass 为 pass 入口，_model_uses_w4a4_quant 检查模型是否含 W4A4 层以决定是否启用。

QK-Norm+RoPE 融合 pass（244 行）。QKNormRopeFusionPattern（及带 bias 变体）匹配 QKV 分裂后对 Q/K 各做 RMSNorm 再接 RoPE 的子图，融合为单个 qk_rmsnorm_rope 算子；QKNormRopeFusionPass 为 pass 入口并判断适用 compile range。

compilation.passes.utils 子包标记。

NPU graph 扩展工具检查（75 行）。extra_stream_scope_check 校验匹配子图的所有节点在同一条流上（跨流子图不能安全融合）；check_and_register_fusion_pass 检查通过后把 pattern 类注册进融合体系。