DeepEP 通信库使用指南（v2.1）

1.1.1 网卡 Affinity 设定

由于真武 810E PPU 和 NIC 并不是 1 比 1 配置，导致部分没有 PIX 网卡的 PPU 在使用网卡时会选择其他 NODE 关系的网卡，导致性能不佳, 对此我们调整为基于 nvml 映射关系的设定，目前是通过环境变量固化配置，后续会自动检测并绑定！如果是直接基于 Python buffer.py 开发和使用，可以不用感知此改动，若是适配 C++ 接口则当下需显式设置环境变量以达到理想性能。

if nvml_device_index // 4 == 0:
	os.environ['NVSHMEM_HCA_LIST'] = 'mlx5_bond_4:1'
if nvml_device_index // 4 == 1:
	os.environ['NVSHMEM_HCA_LIST'] = 'mlx5_bond_2:1'
if nvml_device_index // 4 == 2:
	os.environ['NVSHMEM_HCA_LIST'] = 'mlx5_bond_3:1'
if nvml_device_index // 4 == 3:
	os.environ['NVSHMEM_HCA_LIST'] = 'mlx5_bond_1:1'

1.1.2 Native API 修改

原生 DeepEP 固定只支持机内 NUM_MAX_NVL_PEERS 个 Ranks 的通信规模，为了更加灵活的支持不同配置场景，我们在 Native (CPP) 层做了 API 的修改，新增了 local_ranks 的参数，用于表示机内参与通信的 PPU 数量，它可以是最大 16 PPUs 或者 8 PPUs。

Buffer(int rank, int local_ranks, int num_ranks, int64_t num_nvl_bytes, int64_t num_rdma_bytes, bool low_latency_mode, bool use_nvshmem_transport);

1.1.3 功能增强以及扩展

1.1.4 Python API 扩展

1.1.5 环境变量

1.3.1 Int8 量化支持

从 1.6.0 开始 Low Latency Dispatch 支持 Int8 量化，对应的 API 也有所修改, 无论是 Python 还是 C++ 层面都新增了两个参数：

bool use_int8 ：表示是否开启使用 Int8 量化。

int quant_size：表示 quant 的范围，目前支持 Group 和 Channel 模式：

1. Group 模式就是原生自带的 128 大小，以 128 为 Group 进行量化处理，此时 quant_size 等于 128。

2. Channel 模式就是以 token 为单位进行量化，此时 quant_size 为 hidden_size 大小。

从 2.1 版本开始，APIs 参数进一步扩展，支持 Dispatch mxfp4 量化，以及 Combine int8/fp8 量化。

low_latency_dispatch(const torch::Tensor& x, const torch::Tensor& topk_idx,
                      const std::optional<torch::Tensor>& cumulative_local_expert_recv_stats,
                      const std::optional<torch::Tensor>& dispatch_wait_recv_cost_stats,
                      int num_max_dispatch_tokens_per_rank, int num_experts,
                      bool use_fp8, bool round_scale, bool use_ue8m0, bool use_mxfp4,
                      bool async, bool return_recv_hook, bool use_int8, int quant_size);

low_latency_combine(const torch::Tensor& x, const torch::Tensor& topk_idx, 
                    const torch::Tensor& topk_weights,
                    const torch::Tensor& src_info, const torch::Tensor& layout_range,
                    bool overlap, const std::optional<torch::Tensor>& packed_recv_count,
                    const std::optional<torch::Tensor>& comp_signal, int block_m, int threshold, 
                    int num_sms, const std::optional<torch::Tensor>& combine_wait_recv_cost_stats,
                    int num_max_dispatch_tokens_per_rank, int num_experts,
                    bool zero_copy, bool async, bool return_recv_hook,
                    bool use_fp8, bool round_scale, bool use_int8, int quant_size,
                    const std::optional<torch::Tensor>& out = std::nullopt);

def low_latency_dispatch(self, x: torch.Tensor, topk_idx: torch.Tensor,                                
                         num_max_dispatch_tokens_per_rank: int, num_experts: int,
                         cumulative_local_expert_recv_stats: Optional[torch.Tensor] = None,
                         dispatch_wait_recv_cost_stats: Optional[torch.Tensor] = None,
                         use_fp8: bool = False, round_scale: bool = False, use_ue8m0: bool = False,                               use_mxfp4: bool = False,
                         async_finish: bool = False, return_recv_hook: bool = False,
                         use_int8: bool = False, quant_size: int = 128)

def low_latency_combine(self, x: torch.Tensor, topk_idx: torch.Tensor, topk_weights: torch.Tensor,
                        handle: tuple, overlap: bool = False, packed_recv_count: torch.Tensor = None,
                        comp_signal: torch.Tensor = None, block_m: int = 64, threshold: int = 0,
                        num_sms: int = 3, zero_copy: bool = False, async_finish: bool = False,
                        return_recv_hook: bool = False, out: Optional[torch.Tensor] = None,
                        combine_wait_recv_cost_stats: Optional[torch.Tensor] = None,
                        use_fp8: bool = False, round_scale: bool = False,
                        use_int8: bool = False, quant_size: int = 128)

1.3.2 默认 Enable ICN Link

从 1.6.0 版本开始，deepEP 默认打开 ICN Link，用户可以通过 allow_nvlink_for_low_latency_mode 修改设定。

def __init__(self, group: dist.ProcessGroup,
              num_nvl_bytes: int = 0, num_rdma_bytes: int = 0,
              low_latency_mode: bool = False, num_qps_per_rank: int = 12,
              allow_nvlink_for_low_latency_mode: bool = True,
              explicitly_destroy: bool = False)

1.3.3 MXFP4 量化支持

从2.1.0开始，Low Latency Dispatch 支持 MXFP4 量化，对应的 API 也有所修改，无论是 python 还是 C++ 层面都新增了一个参数：

bool use_mxfp4：表示是否开启使用 MXFP4 量化，只支持quant_size为32。