企业官网建设流程全解析

HCCL 参数面建链 QP 内存资源申请失败（EI0011）定位与解决指南

【免费下载链接】hccl集合通信库（Huawei Collective Communication Library，简称HCCL）是基于昇腾AI处理器的高性能集合通信库，为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl

在昇腾（Ascend）AI 处理器上使用 CANN/HCCL 集合通信库进行分布式训练时，参数面建链阶段是通信域真正建立可用传输通道（QP，Queue Pair）的关键步骤。本文聚焦 HCCL 故障码EI0011（QP 内存资源申请失败），说明其产生的阶段背景、报错特征与定位方法，并给出从"调整业务配置、减少 ROCE 链路数量、释放内存、配置 HCCL_BUFFSIZE"四个维度出发的完整排查与解决路径。读完本文，你将能够在多节点训练或推理场景中快速识别 EI0011 报错，区分 HCCL QP 内存申请失败与其他组件 OOM 报错，并独立完成故障处理。

故障码定位：EI0011 在 HCCL 故障体系中的位置

EI0011 属于 HCCL 故障码体系中的"参数面建链阶段"错误。HCCL 业务整体分为三个阶段：通信域初始化、参数面建链、通信算子执行，其中参数面建链阶段是 EI0011 出现的阶段，相关故障场景还包括建链失败、端口绑定失败（EI0019）、建链超时（EI0006）与参数一致性校验（EI0005），详见 参数面建链阶段总览 与 故障诊断目录。

在 HCCL 相关故障码列表 中，EI0011 对应的故障码说明为"QP内存资源申请失败"：

从源码与文档结构看，可以推断 HCCL 在参数面建链时，会为每两个 rank 之间的 ROCE（RDMA over Converged Ethernet）链路创建 QP，并通过 device 侧（NPU）内存承载 QP 相关的资源描述与收发缓冲；当设备侧可用内存不足以支撑这些 QP 的创建时，便会上报 EI0011。

问题现象：如何识别 EI0011 报错

EI0011 的典型特征是：在业务打屏日志中存在关键字"EI0011"或"Resource_Error_Insufficient_Device_Memory"。完整报错示例如下：

[PID: 2103452] 2025-11-03-20:18:46.447.213 Resource_Error_Insufficient_Device_Memory(EI0011): Failed to allocate [size: [0.25MB, 3MB], Affected by QP depth configuration.] bytes of NPU memory. Possible Cause: Allocation failure due to insufficient NPU memory. Solution: Stop unnecessary processes and ensure the required memory is available.

对报错内容做拆解：

• [size: [0.25MB, 3MB], Affected by QP depth configuration.]：本次申请失败的 NPU 内存大小在 0.25MB 到 3MB 区间，且明确指出该内存申请受 QP depth（QP 深度）配置影响。QP depth 决定每个 QP 可容纳的在途 WQE（Work Queue Element）/描述符数量，深度越大，单 QP 占用的设备内存越多。
• Failed to allocate ... bytes of NPU memory：失败原因为 device 侧 NPU 内存分配失败，即典型的设备内存不足（OOM）。
• Possible Cause: Allocation failure due to insufficient NPU memory.与Solution: Stop unnecessary processes and ensure the required memory is available.：HCCL 给出的通用建议为停止不必要的进程、确保所需内存可用。

产生机理：为什么建链阶段会申请 QP 设备内存

在参数面建链阶段，HCCL 需要为 rank 之间的 ROCE 通信建立传输资源。从 HCCL 的机制看，每次新类型或新算法的通信算子被首次调用时才会触发建链（单算子模式下，为保证性能，HCCL 仅在每个通信域新类型或算法的算子首次调用时才建链，详见 建链失败定位思路）。建链过程中，QP 资源的创建需要向 device 侧申请内存，其申请量主要受以下因素影响：

• ROCE 链路数量：rank 之间 RDMA 通信默认每个连接创建 1 个 QP，而通信域规模、算法拓扑（如全连接、环、树等）决定了链路数量；链路越多，QP 总数越多，设备内存占用越大。
• QP 深度配置：如报错信息所示，单 QP 内存申请大小受 QP depth 影响，深度配置越大，单个 QP 占用内存越多。
• 多 QP 特性：若通过环境变量 HCCL_RDMA_QPS_PER_CONNECTION 配置两个 rank 间使用多个 QP 并行传输，QP 总数会成倍增加。该变量取值范围为 [1,32]，建议配置范围 [1,8]，文档明确指出"QP个数超过8时无法确保性能收益，还可能会造成由于内存占用过多导致业务运行失败的情况"——这正是 EI0011 的一类典型诱因。

因此，当集群规模大、ROCE 链路多、QP 深度较大或单连接 QP 数量配置过多时，device 侧内存可能不足以承载全部 QP 资源，从而触发 EI0011。

解决方法：四类处置手段

EI0011 的本质是设备内存不足，解决思路为"开源节流"：一方面释放或降低设备内存占用，另一方面减少 QP 资源的总需求量。

1. 调整业务配置，降低内存占用

• 调小业务侧占用 NPU 内存的配置，例如减小 batchSize，为通信建链腾出设备内存。
• 检查并关闭不必要的业务进程，释放被占用的设备内存。
• 若训练脚本或框架同时创建了多个通信域，可评估是否可合并或串行化通信域，降低整体内存峰值。

2. 减少 ROCE 链路的使用数量

• 评估通信算法与拓扑：改用链路数更少的通信算法或拓扑，可直接降低 QP 总量。HCCL 支持多种集合通信算法与分层通信（如 Ring、Mesh、Star 等），可结合业务数据量与拓扑结构选择合适的算法，相关介绍见 集合通信算法介绍。
• 检查多 QP 配置：确认是否设置了 HCCL_RDMA_QPS_PER_CONNECTION 且取值偏大。若当前值为 N，则每两个 rank 之间会创建 N 个 QP；建议将其调回默认值 1，或控制在 [1,8] 建议区间内，避免因 QP 数量过多导致设备内存耗尽。
• 注意 QP 相关配置的优先级：管理面多 QP 配置（hccn_tool 的-s multi_qp参数）> NSLB 的 QP 配置（hccn_tool 的-t nslb-dp参数）> 环境变量 HCCL_RDMA_QP_PORT_CONFIG_PATH > 环境变量 HCCL_RDMA_QPS_PER_CONNECTION。若通过环境变量调整未生效，需检查更高优先级的管理面/NSLB 配置。

3. 释放部分内存

• 停止集群节点上无关的推理、训练或其他占用 NPU 内存的进程。
• 排查是否有内存泄漏或未被释放的通信资源，重启相关业务进程释放陈旧资源。
• 通过npu-smi info等工具确认 device 侧内存占用情况，定位内存大头后再针对性释放。

4. 区分 HCCL 其他内存申请失败：配置 HCCL_BUFFSIZE

注意：HCCL 的其他内存申请（如 cclBuffer 内存申请）若出现 OOM 错误，会由drv 组件上报错误码并打印错误信息。此时可通过报错信息或 CANN 日志中的堆栈判断是否为 HCCL 内存申请失败：

• 若判定为 HCCL 内存申请失败，可通过配置环境变量HCCL_BUFFSIZE调整申请的内存大小。
• HCCL_BUFFSIZE 用于控制通信域共享数据缓存区大小，需配置为整数，取值大于等于 1，默认值为 200，单位 MB。每个通信域会占用 "2 × HCCL_BUFFSIZE" 大小的内存（分别用于收发内存），且该内存为 HCCL 独占、不可与其他业务内存复用。
• 若集群中存在较多通信域导致整体缓存占用增加、影响模型数据存储，可调小该环境变量的值以降低缓存占用；若业务模型数据量较小但通信数据量较大，可适当调大该值以提升通信效率。配置示例：

export HCCL_BUFFSIZE=200

• 大语言模型场景的建议配置值为：(MicrobatchSize × SequenceLength × hiddenSize × sizeof(DataType)) / (1024 × 1024)，向上取整。
• 使用约束：若通过 HcclCommConfig 的hcclBufferSize参数按通信域粒度配置了缓存区大小，则以通信域粒度的配置优先。
• 验证方式：可检索 CANN 日志 run/plog 目录下的日志关键字确认环境变量实际生效值，例如执行grep -r "HCCL_ENV" run/plog/plog-xxx.log，日志中会打印形如HCCL_BUFFSIZE set by environment to [1]M的生效信息，具体检索方法见 定位思路。

需要强调的是：EI0011 与 cclBuffer OOM 是两类不同的内存申请失败。EI0011 发生在参数面建链阶段的 QP 资源申请（受 QP depth 配置影响），主要处置手段是减少 ROCE 链路数量、释放内存；而 cclBuffer 等数据缓存区 OOM 由 drv 组件上报，可通过 HCCL_BUFFSIZE 调整。请先根据报错信息与日志堆栈判断失败来源，再选择对应手段。

排障操作建议与注意事项

1. 确认报错阶段：EI0011 属于参数面建链阶段故障，若业务在调用通信算子接口时失败，或在报错日志中发现transport关键字打印，可优先参考 参数面建链阶段 章节排查，并收集集群所有节点的 CANN 日志（含 debug 目录和 run 目录）以辅助定界，详见 定位思路。
2. 结合多级检索关键字：HCCL 在常见报错场景提供了一级/二级检索关键字，可通过报错日志中的关键字快速识别报错阶段。EI0011 对应的报错阶段关键字与故障码列表见 定位思路。
3. 修改配置后验证：调整业务配置、ROCE 链路数量或环境变量后，建议重新下发业务验证 EI0011 是否消失，并确认通信性能未出现明显下降（例如 HCCL_BUFFSIZE 取值应大于实际通信数据量，否则可能出现性能下降）。
4. 多节点一致性：参数面建链是通信域全局协同行为，环境变量（如 HCCL_BUFFSIZE、HCCL_RDMA_QPS_PER_CONNECTION）需在所有节点保持一致，避免因节点间配置不一致引入新的问题。

总结

EI0011（QP 内存资源申请失败）是 HCCL 参数面建链阶段的典型设备内存不足故障，报错关键字为EI0011或Resource_Error_Insufficient_Device_Memory，申请失败的内存大小受 QP depth 配置影响。处理该故障的核心思路是：调整业务配置（如 batchSize）、减少 ROCE 链路使用数量（含收敛多 QP 配置 HCCL_RDMA_QPS_PER_CONNECTION 的取值）、释放部分设备内存；同时注意区分 HCCL 的 cclBuffer 等缓存区 OOM（由 drv 组件上报，可通过 HCCL_BUFFSIZE 调整申请内存大小）。掌握 EI0011 的定位方法后，可将其纳入 HCCL 分布式训练故障诊断的日常排障清单，结合 故障诊断总目录 快速定界同类建链阶段问题。

【免费下载链接】hccl集合通信库（Huawei Collective Communication Library，简称HCCL）是基于昇腾AI处理器的高性能集合通信库，为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl