HCCL 01 ：为什么 HCCL 需要 Python 绑定

HCCL（Huawei Collective Communication Library）只有 C 接口。自研训练框架、HPC 脚本、模型调优工具这些 Python 应用想直接调 HCCL 通信算子，面临的现实是：

• libhccl.so 只导出 C 符号，没有 Python binding；
• 用户自己写 ctypes.CDLL("libhccl.so")，然后逐函数声明 argtypes/restype；
• HcclRootInfo 是 4108 字节的不透明结构体，HcclCommConfig 有 20 个字段——手工复刻头文件，偏移错一位，底层直接段错误；
• 每个项目各写各的，重复且易错，头文件一升级全部得跟着改。

如果

用 Python 标准库 ctypes 直接加载 libhccl.so，对 19 个 C API 提供 Python 绑定：

Python 接口与 C 接口一一对应、参数语义一致，无中间封装层。

为什么是 ctypes

形态

experimental/eco_system/python/
├── hccl4py/
│   ├── __init__.py     # 包入口
│   ├── _binding.py     # 私有声明层：CDLL + argtypes/restype + 结构体
│   ├── types.py        # 公开常量层：HcclDataType / HcclReduceOp / HcclResult
│   ├── comm.py         # 通信域管理 5 接口
│   └── ops/            # 14 个通信算子（每算子一模块）
├── examples/           # 14 个算子样例 + 通信域初始化样例
└── README.md

无构建、无 wheel、无第三方依赖。source set_env.sh + export PYTHONPATH 即可用。

性能口径

绑定层是单次参数转发，无内存拷贝。开销来源只有 ctypes 参数编组（Python 对象 → C 参数）。验收口径：

同一算子同一规模，Python 2-rank median/? − C median/? ≤ 10μs，基于 3/? 轮复测的 median/? 分布。

后面 几 篇按实现顺序展开：架构分层 → ctypes 结构体 → inline 函数处理 → 错误处理 → 14 个算子 → 踩坑实录 → 性能基准 → 测试工程 → 等。