vLLM Ascend · 分布式通信模块 API 参考

NPU 设备间通信器（58 行）。NPUCommunicator 适配 vLLM 的 DeviceCommunicator；_NpuAll2AllManager 是 NPU 上的 no-op all2all 管理器，实现容错接口（support_fault_tolerance/query_fault/query_active_mask）以兼容 vLLM 主线的容错逻辑但不实际执行 all2all。

PyHcclCommunicator（171 行）：用 Python 直接驱动 HCCL 库的轻量通信器，提供 all_reduce 与 broadcast，绕过 torch.distributed 的 ProcessGroup 以降低开销，用于自定义通信组（如 MC2/OTP 组）。

HCCL C 库的 ctypes 封装（264 行）。HCCLLibrary 加载 HCCL so 并声明 C 接口：hcclGetUniqueId/hcclCommInitRank 建组、hcclAllReduce/hcclBroadcast 通信、hcclCommDestroy 销毁，HCCL_CHECK 错误检查与 hcclGetErrorString 错误信息；hcclDataTypeEnum/hcclRedOpTypeEnum 负责 torch dtype/归约操作到 HCCL 枚举的映射。

EPLB 异步模式的 Gloo CPU 中转通信器（56 行）。AscendGlooEplbCommunicator 在 Ascend 上用 Gloo（CPU 侧）传输专家负载信息：_to_global_peer_rank 换算对端全局 rank、add_send/add_recv 登记收发、needs_profile_buffer_reservation 声明 profile 缓冲预留。

EPLB 状态扩展（179 行）。AscendEplbLayerState 在上游 EPLB 层状态上维护图稳定的专家副本路由表（refresh_expert_replica_routing_table），保证 ACL graph 重放期路由表地址不变；AscendEplbState 包裹上游状态：rearrange 执行专家重排、from_mapping 按映射构建（兼容不同 vLLM 版本的 mapping 契约 _upstream_from_mapping_accepts_valid_expert_count）、_has_global_fresh_recorded_load 判断全局负载新鲜度；refresh_model_routing_tables 刷新全模型或单层的路由表（异步提交后刷单层）。

KV 传输子包注册入口（101 行）。register_connector 把 Ascend 实现的各 KV connector（MultiConnector、Mooncake 系列、AscendStore、CPU offload 系列等）按配置注册进 vLLM 的 connector 工厂。

多 connector 组合器（199 行）。AscendMultiConnector 把多个底层 KV connector 组合使用（如 Mooncake + 本地 offload）：按层配置复用完成等待（_configure_layerwise_reuse_completion）、外部 slot 释放等待（_wait_for_external_slot_release）、Mamba 状态拷贝（prepare/finish_mamba_state_copy），并把 save/load/matched-tokens 等标准接口分发到子 connector。

Mooncake KV P2P 传输 connector（4078 行，分布式最大文件）。实现 PD 分离下 prefill→decode 的 KV 传输：MooncakeConnectorScheduler 侧计算匹配 token 数、构建传输块 ID（含 SWA 特判 _get_swa_transfer_block_ids）、按握手元数据管理端口偏移；MooncakeConnectorWorker 侧管理 KV 组规格序列化（_serialize_kv_group_spec）、层到组映射（_build_kv_group2layeridx）、对齐张量基址恢复、全部组的传输（_transfer_kv_cache_all_groups）；MooncakeConnector 协调双方：get_num_new_matched_tokens 查询远端命中、start_load_kv/wait_for_layer_load 加载、save_kv_layer/wait_for_save 保存；后台线程：KVCacheSendingThread/KVCacheRecvingThread 负责异步收发与失败标记；KVCacheTaskTracker 跟踪任务完成与超时回收；工具函数：连续块分组（group_concurrent_contiguous）、ZMQ 重试收发（ensure_zmq_send/recv）、SHA-256 哈希、PP 分层索引切分。

Mooncake 混合架构（注意力+Mamba/SWA 混合 KV）传输 connector（2132 行）。在基础版之上处理混合缓存的传输：SWA 裁剪块表（get_sw_clipped_blocks）、传输块 ID 计算（_compute_transfer_block_ids）、KV 缓存重排（reformat_kv_cache_with_fused_op/reformat_kv_cache/_cat_kv_cache）、PP 感知握手元数据（set_xfer_handshake_metadata_pp_aware）、TP 拉取数计算（_get_tp_num_need_pulls）与远端 rank 映射（_prefill_get_remote_rank/_get_remote_ranks_for_req）。

Mooncake 层级（layerwise）传输 connector（2259 行）。KV 按层流水传输以重叠计算与通信：MooncakeLayerwiseConnector 提供 wait_for_layer_load/wait_for_layer_reuse/on_kv_cache_written 等层级接口；Worker 侧层级复用状态管理（_init_layerwise_reuse_state/_mark_layer_reuse_pending/_complete_layer_reuse）、KV buffer 创建、块分裂元数据（_get_kv_split_metadata 及 Mamba 变体）、远端块对齐；Scheduler 侧混合缓存 prefill 计数与裁剪（_hybrid_prefill_token_count/_truncate_request_for_hybrid_prefill/_trim_hybrid_remote_block_ids）、metaserver 访问（_access_metaserver）；收发线程按层组织任务（KVCacheSendingLayerThread/KVCacheRecvingLayerThread，SendTask/TransferMeta/LoadSpec 数据结构）。

PD 分离 SFA Remote D2H connector 主入口（243 行）。SfaRemoteD2HConnector 按角色（producer/consumer）与 KV 角色分发到对应实现，实现标准 connector 接口：命中查询、分配后状态更新、加载/保存、完成查询与加载错误块上报（get_block_ids_with_load_errors）、CPU 块数查询。

SFA PD RD2H 线缆协议（178 行）。infer_sfa_component_group_ids 从层名推断（主缓存组, indexer 组）ID；SfaPDProducerReqMeta/ProducerMetadata 与 SfaPDConsumerReqMeta/ConsumerMetadata 定义两端请求级元数据（D 侧目的地由 vLLM 常规块管理器持有）；SendTask 传输任务单元；get_external_request_id 生成外部请求 ID。

D 侧 memfabric pull 读线程（754 行）。MembPullReadThread 从远端内存fabric批量拉取 KV：_build_req_descriptors 构建请求读描述、_do_read_batch 批量读（_coalesce_desc 合并相邻段减少读次数、_tp_block_range 计算 TP 块范围）、_record_chunk_done 记录分块完成、discard_requests 丢弃失败请求、get_and_clear_done/failed 收割结果。

SFA PD RD2H 调度器侧（509 行）。SFAPDRD2HScheduler 处理 D 侧调度：命中查询、metaserver 提交与回调（_submit_metaserver_request/_on_metaserver_done）；SFAPDRD2HProducerScheduler 处理 P 侧：块 ID 规范化（_normalize_block_ids）、匹配 token 数与元数据构建。_SendReqInfo 维护已传 token 计数。

P 侧 memfabric pull 发送线程（366 行）。MembPullSendingThread 把 P 侧 KV 推给 D 侧：_ensure_dealer 维护 ZMQ DEALER 连接、_process_send_task 处理层发送任务、_send_mf_meta 发送 memfabric 元数据、_drain_read_replies 处理读回复、层完成信号（_signal_layer_done）与失败标记（_fail_layer/_record_layer_error），record_p_save_event/mark_layer_pending 跟踪保存进度。

SFA PD RD2H worker 侧（855 行）。SFAPDRD2HConsumerWorker（D 侧）：注册 KV 缓存、发起加载（start_load_kv）、构建消费读状态（_build_consumer_read_state）、注册 memfabric pull（_register_memfabric_pull）、TP 读状态汇聚（_gather_tp_read_status）；SFAPDRD2HProducerWorker（P 侧）：保存 KV（save_kv_layer/on_kv_cache_written）、层发送入队（_enqueue_layer_send）、prefill rank→decode rank 映射、层存储槽位推断（_infer_layer_storage_slots）、PD 读完成等待（_wait_for_pd_read_completion）；_resolve_kv_transfer_backend 选择传输后端、npu_generate_uuid 生成物理芯片唯一标识。

AscendStore KV 连接器入口（369 行）。AscendStoreConnector 对接外部 KV 存储池：命中查询（get_num_new_matched_tokens）、PP 感知握手元数据（set_xfer_handshake_metadata_pp_aware）、层级加载等待、Mamba 状态拷贝、外部 slot 释放等待（set_external_slot_release_waiter）；AscendStoreKVEvents 聚合多 worker 的 KV 事件；LookupKeyServer 提供 scheduler 侧键查询 RPC 服务。

注意力计算栅栏（91 行）。AttentionComputeStartGate 在计算流到达注意力处开门：record_attention_compute_start 在注意力前打点，MemCache 类异步工作 wait 该栅栏保证不早于注意力开始；reset/get_attention_compute_start_gate 管理每层栅栏实例。

存储后端工厂（57 行）。get_layerwise_backend(backend_name) 按名字返回对应后端模块（memcache/mooncake/yuanrong），各模块实现统一的层级传输协议。

存储后端抽象基类（56 行）。Backend 定义统一接口：创建 scheduler 客户端、设备绑定、缓冲注册（register_buffer）、键存在性查询（exists/batch_is_exist/batch_get_key_info）、批量分配（batch_alloc）、租约管理（batch_add/remove_lease）、写完成标记（batch_write_finish）与 put/get。

MemCache 存储后端（311 行）。MemcacheBackend 实现基类接口：按需初始化存储（_setup_store/ensure_initialized）、设备缓冲注册、批量键信息/分配/租约/写完成；键构造规则：make_full_key（整块键：模型/组/块哈希/rank）、make_partial_key（部分块键含 token 数）、make_hit_check_keys（全 rank 命中检查键）；extract_layout_config 提取层级布局配置；_is_device_sdma 判断设备 SDMA 能力。

Mooncake 存储后端（411 行）。MooncakeBackend 对接 Mooncake Store：setup（_mooncake_setup_supports_ssd_offload 判断 v0.3.11+ 的 SSD 卸载参数）、缓冲注册、exists/put/get；MooncakeStoreConfig 支持文件与环境变量加载（from_file/load_from_env）；工具：_normalize_tenant_id 租户 ID 规范化、_parse_global_segment_size/_convert_to_bytes 带单位（GB/MB/KB/B）的容量解析。

元戎（Yuanrong）存储后端（162 行）。YuanrongBackend 对接元戎存储：设备绑定、缓冲注册、exists/get/put；YuanrongConfig 支持文件与环境变量两种配置加载方式。

外部缓存协调器（390 行）。AscendStoreCoordinator 为外部 KV 池做混合缓存命中判定：ExternalCachedBlockPool 以键存在性为依据的 BlockPool 适配（get_cached_block）、find_longest_cache_hit 找最长命中（按 KV 组校验与拆分 _verify_and_split_kv_cache_groups）、load/store/lookup_mask 各方向掩码计算（_reachable_masks 可达掩码）、投机解码块哈希（block_hashes_for_spec）；模块级 _find_longest_cache_hit/_reachable_block_mask 按管理器类缓存避免重复构建。

AscendStore 传输线程族（1621 行）。KVTransferThread 是基座：请求队列管理（add_request/discard_finished_requests）、失败上抛（raise_if_failed）、存储计数（add/dec_stored_request）、传输包切分（_split_transfer_packets）、限速批拷贝（_batch_copy_with_limits）；派生线程按模式分工：KVCacheStoreSending/RecvingThread（整请求存取）、KVCacheStoreKeyLayerSending/RecvingThread（关键层优先存取）、KVCacheStoreLayerSending/RecvingThread（层级存取，含 H2D 提交错峰 _stagger_h2d_submit 避免带宽尖峰）；LayerBatchBuilder 构建批量传输数组（去重传输块、共享/地址数组）；record_failed_blocks 记录失败块。

层级缓存布局（369 行）。LayerwiseCacheLayout/LayerwiseLayerCacheSpecs/NamedKVCacheSpec 描述逻辑层到物理层的映射与各层缓存规格；LayerwiseReuseLayout 按主缓存规格分组构建可复用物理层槽位（build_layerwise_reuse_layout）；get_layerwise_kv_cache_specs 把组级规格展开为每逻辑层规格；apply_layerwise_kv_cache_plan 把逻辑层张量重写到共享物理 KV 缓冲（省显存）；build_layerwise_cache_layout 解析 extra_config 构建布局。

AscendStore 元数据中心（1236 行）。键体系：KeyMetadata 汇总模型名/并行/块大小等键要素、PoolKey/LayerPoolKey 池键（可按层拆分）、infer_tp_mismatch_info 推断 TP 不匹配信息（TPMismatchInfo）；缓存族：infer_cache_family_from_ratio 按压缩比推断缓存族、infer_group_cache_families 按组推断（区分 dense/SWA/compressed）；块大小：infer_group_block_sizes/infer_cache_transfer_granularity 推断组块大小与传输粒度（LCM 对齐）；ChunkedTokenDatabase 维护 token 块哈希数据库（store/load 掩码、_make_key_by_hash、部分块处理）；传输任务结构：LoadSpec、RequestTracker/ReqMeta、AscendConnectorMetadata、LayerBatchReqMeta/LayerBlockRange/SharedBlockData/LayerTransferTask/LayerLoadTask/LayerMultiBlockReqMeta/AscendStoreKVConnectorWorkerMetadata；工具：normalize_block_ids_by_group、block_hash 与字符串/字节互转、_LazyGroupedBlockHashList 惰性分组哈希表。

AscendStore 调度器侧（1073 行）。KVPoolScheduler 决定哪些前缀可从外部池加载：请求跟踪（_get_or_create_request_tracker）、存储查询键生成（_generate_store_query_keys）、命中 token 计算（_get_store_lookup_hit_tokens/_get_layerwise_hit_tokens，层级模式走 _make_layerwise_hit_check_keys）、传输粒度向下取整（_floor_to_cache_transfer_granularity）、Mamba 组与 SWA 块推断（_infer_mamba_groups/_infer_swa_blocks）、SWA 裁剪块表（get_sw_clipped_blocks）；LookupKeyClient 通过 ZMQ RPC 远程查询键。

AscendStore worker 侧（2475 行）。KVPoolWorker 是最大的单类，组装 worker 全部传输基础设施：并行信息/传输配置/键头配置初始化、元数据与后端初始化（_init_metadata/_init_backend）、KV 事件初始化、层级配置与组-层构建器（_init_layerwise_config/_build_group_layer_builders）、传输线程启动（_start_kv_transfer_threads）、缓存协调器构建（_build_cache_coordinator）、Mamba 缓存与对齐状态判定（_uses_mamba_kv_cache/_infer_group_uses_align_state）、外部 slot 释放等待。

vLLM 原生 CPU KV 卸载的 Ascend worker（328 行）。SingleDirectionNPUOffloadingHandler 用有序 NPU DMA 流单向搬运块（transfer_async/get_finished/wait/shutdown）；NPUOffloadingWorker 组装为原生 offloading 的 worker；_new_descriptor_buffers 分配 DMA 描述符缓冲。

原生 CPU offloading 规格适配（97 行）。NPUOffloadingSpec 使用 vLLM 的 CPU manager 但替换为 Ascend 传输 worker（create_worker/get_worker）；_normalize_legacy_num_blocks 把旧版块容量配置按对齐换算（不改动 vLLM 配置对象）。

原生 offloading connector 的 Ascend 布局适配（338 行）。Ascend 的 K/V（及可选 scale）分离存储与 vLLM 假设不同：_canonicalize_split_attention_cache 规范化分离张量、_make_int8_block_view 建零拷贝 [num_blocks, page_bytes] 视图；AscendOffloadingConnectorWorker/AscendOffloadingConnector 在边界层完成布局适配。

NPU↔CPU 块拷贝 DMA 后端（124 行）。NPUDmaCopyBackend 基于 aclrtMemcpyBatchAsync 在工作线程执行拷贝：init 初始化、launch_copy 提交拷贝、_copy_loop 消费拷贝队列、shutdown 退出。

底层 NPU 内存操作（99 行）。BatchMemcpyParams 预计算每张量的指针/跨度描述符；build_params 为全部子张量构建缓存描述（src/dst + 方向）；copy_blocks 在当前 NPU 流上发起批量异步 DMA（一次调用拷贝多组块）。

简单 CPU offload connector 适配（54 行）。AscendSimpleCPUOffloadConnector 复用 vLLM 的 connector 逻辑，仅把其 CUDA worker 替换为 NPU 版本。

简单 CPU offload 的 NPU worker（286 行）。SimpleCPUOffloadNPUWorker：register_kv_caches 注册 KV 缓存、_build_block_views 按块构建 CPU/NPU 两侧视图（_flatten_kv_value 展开每层缓存的全部组成张量）、get_finished 收割完成传输。

重计算 CPU 卸载调度器侧管理器（647 行）。RecomputeCPUOffloadScheduler 把被抢占请求的 KV 块保住到 CPU 内存，恢复时免重算：抢占状态管理（_create_preempt_state/PreemptedRequestState）、CPU 配置推导（_derive_cpu_config）、SWA/Mamba 组识别（_get_group_is_sliding_window/_get_group_is_mamba）、块 ID 对齐（_align_group_block_ids）、抢占前保存与分配后加载（_prepare_preempt_store_specs/_prepare_preempt_load_after_alloc）、GPU 块池绑定（bind_gpu_block_pool）、命中查询与元数据构建。

重计算 CPU 卸载元数据（52 行）。RecomputeCPUOffloadMetadata 承载调度器→worker 的传输指令；RecomputeCPUOffloadWorkerMetadata 聚合 worker→scheduler 的完成存储事件（aggregate）。

重计算 CPU 卸载连接器（246 行）。RecomputeCPUOffloadConnectorV1 实现最小 CPU KV 卸载闭环：抢占处理（handle_preemptions）、加载/保存（start_load_kv/wait_for_layer_load/save_kv_layer/wait_for_save）、元数据绑定与清理、GPU 块池绑定、命中查询与分配前后状态更新。

重计算 CPU 卸载 worker 侧（319 行）。RecomputeCPUOffloadWorker 执行实际 CPU/NPU 传输：传输提交（_submit_transfer）、事件轮询与全量刷同步（_poll_load_events/_flush_and_sync_all）、抢占处理、完成事件上报（get_finished/build_connector_worker_meta）。

UCM（统一缓存管理）连接器（324 行）。UCMConnectorV1 把 KV 卸载委托给 UCM 框架：按层取委托（_get_ucm_delegate_for）、预留钩子调用（_call_ucm_reserved_hook）、host 传输缓冲操作注入（set_host_xfer_buffer_ops）、抢占处理、加载/保存与加载错误块上报。

稀疏 KV offload 管理器（1206 行）。SparseKVOffloadManager 管理稀疏注意力的 KV 分层驻留：全量 KV 在 CPU、topk 选中的块驻留 NPU——offload_new_kv 把新 KV 写入 CPU 池、onload_topk_kv 把 topk 块加载到 NPU（CPU 路径 _onload_topk_kv_cpu）、层注册与层 ID 管理；内存规划：plan_sparse_kv_offload_memory 按 NPU/DRAM/活跃需求三者上限决定卸载块数（SparseKVOffloadMemoryBudget）、get_sparse_kv_offload_cpu_pool_size_bytes 计算对齐 host 分配上界；张量准备：allocate_kv_cache_tensors_for_sparse_kv_offload（从对齐 int8 raw 分配 K/V）、reshape_kv_cache_tensors_for_sparse_kv_offload 重塑为 offload 布局；元数据：update_sparse_kv_offload_metadata 填充 LRU 请求身份张量、prepare_sparse_kv_offload_mtp_dummy_metadata MTP 哑元数据；缓冲：allocate_kv_offload_topk_buffer_pair/profile_buffers；init/get_sparse_kv_offload_manager 管理全局单例。

MemFabric 传输引擎进程级初始化（165 行）。MemfabricBackend 规整 SFA PD connector 使用的 MemFabric API（get_rpc_port/register_memory/batch_transfer_sync_read）；GlobalMemfabricTE 按角色惰性创建每进程一个引擎（configure/get_transfer_engine/register_buffer）。

Mooncake 传输引擎全局单例（43 行）。GlobalTE 惰性创建 TransferEngine 并提供缓冲注册（register_buffer），供各 Mooncake connector 共享同一引擎实例。

KV 传输共享工具（445 行）。PD TP 变换：kv_alltoall_and_rearrange/alltoall_and_rearrange/rearrange_output 处理 P↔D 侧 TP 比例不同的 alltoall 与重排、get_tp_rank_head_mapping/get_head_group_mapping 计算 KV head 到 rank 的映射、context_parallel_parameters_check 校验 CP 参数一致性；传输映射：get_local_remote_block_port_mappings/get_transfer_mappings 计算块到远端 rank/端口的映射；内存注册：RegisterRange/RegisterRegions 管理注册区间、collect_storage_merged_register_regions 按共享存储合并注册区（减少 HCCL/Mooncake 注册条目）、validate_register_region_count 校验；其他：align_memory 内存对齐、get_transfer_timeout_value 读取超时配置、get_cp_group 构建 CP 通信组、iter_kv_cache_tensors 展平 KV 张量、tensor_storage_key 共享存储分组键。

Ascend 并行组管理（243 行）。init_ascend_model_parallel 初始化模型并行并创建 Ascend 专属通信组：MC2 组（get_mc2_group，MoE 通信）、MLP TP 组、OTP 组（细粒度 o_proj TP）、LM head TP 组、embedding TP 组、P 组、动态 EPLB 组；get_global_rank 计算跨所有并行维度的全局唯一 rank；destroy_ascend_model_parallel 销毁全部组。

分布式小工具（55 行）。get_decode_context_model_parallel_world_size/rank 补回 vLLM main 已移除的 DCP 辅助函数；all_gather_async 异步 all-gather；split_tensor_along_first_dim 沿第一维切分张量（可选连续切片）。

权重传输注册入口（40 行）。register_engine 把 Ascend 的权重传输引擎（HCCL/NPU IPC）注册为 vLLM 插件，供 RL 训练框架按后端名选择。

HCCL 权重传输引擎（340 行）。HCCLWeightTransferEngine 用 HCCL 在训练器与推理 worker 间传权重：trainer_init/trainer_send_weights 训练侧初始化与发送（_stateless_init_process_group 无状态建组）、receive_weights worker 侧接收、start/finish_weight_update 包裹一次权重更新会话、shutdown 退出；配套数据类 InitInfo/UpdateInfo/TrainerSendWeightsArgs。

NPU IPC 权重传输引擎（426 行）。NPUIPCWeightTransferEngine 用 Ascend IPC 共享内存传权重（免拷贝、低开销）：worker 侧 init_transfer_engine/receive_weights、start/finish_weight_update、shutdown；NPUIPCTrainerWeightTransferEngine 为训练侧：trainer_init、send_weights（_send_packed 打包发送/_send_unpacked 逐张量发送/_do_send 底层发送、_all_gather_and_merge_handles 聚合 IPC 句柄、_post_send_sync 后置同步）；npu_generate_uuid 生成物理 NPU 芯片唯一标识；get_ip 取本机 IP；数据类 NPUIPCWeightTransferInitInfo/UpdateInfo/NPUIPCTrainerInitInfo。

打包张量工具（325 行）。为权重传输提供打包-解包：packed_broadcast_producer/consumer 把张量流打包进定长缓冲做 HCCL 广播（多缓冲流水）、packed_npu_ipc_producer/consumer 把张量打包进可复用 IPC 缓冲按块产出与按名解包（含形状/dtype/物理芯片 ID 元数据）。