1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | cupynumeric-hdf5-nvidia-skills（SKILL.md 内部名称 cupynumeric-hdf5） |
GitHub |
| 作者/维护者 | NVIDIA Corporation（legate@nvidia.com）；技能目录仓库 nvidia/skills 每日自动同步自 nv-legate/cupynumeric 产品仓库的 skills/ 子目录 |
GitHub API + SKILL.md metadata |
| 来源链接 | https://github.com/nvidia/skills/tree/main/skills/cupynumeric-hdf5 | — |
| 许可证 | CC-BY-4.0 OR Apache-2.0（双许可，SKILL.md frontmatter 明确声明） | GitHub |
| GitHub Stars/Forks | 技能所属目录仓库 nvidia/skills 整体 2,817★/331 forks（覆盖 300+ 个不同 NVIDIA 产品的技能，不代表本技能自身热度）；封装的产品 nv-legate/cupynumeric 单独仓库 981★/88 forks，最近一次提交为 2026-08-07 |
GitHub API |
| 最新版本 | 2.0.0（SKILL.md frontmatter 声明） | GitHub |
| 安装方式 | npx skills add nvidia/skills --skill cupynumeric-hdf5 --agent claude-code |
GitHub README |
2. 功能介绍与亮点
这个技能教 agent 正确使用 legate.io.hdf5（cuPyNumeric 底层的 Legate 并行 I/O 模块）把大型分布式数组读写为 HDF5 文件，覆盖从基础读写到 GPUDirect Storage 加速的完整场景。
主要亮点：
- 三个核心 API 讲清楚边界：
to_file整体写入、from_file整体读取、from_file_batched分块读取，每个都给出何时用、何时不用（如 Parquet/Zarr/S3/纯 h5py 场景一律划出去，转介到对应技能或工具）。 - 踩坑点前置：异步写入需要
issue_execution_fence才能保证外部读取时数据已落盘、SPMD 多进程需保证每个 rank 传入相同路径、在源码树内运行会被本地目录遮蔽已安装包——这些是并行 I/O 场景里容易踩的隐蔽错误，SKILL.md 逐条列出并给出修复代码。 - GPUDirect Storage 指导明确：给出何时该开启
LEGATE_IO_USE_VFD_GDS=1（GPU 读取超过 128MB 默认缓冲区会中止）、何时该关闭（CPU 读取时开启反而增加开销），并说明这是 NVIDIA cuFile 驱动的 GDS VFD 而非 KvikIO，避免混淆。 - 配可运行的验证脚本：
assets/hdf5_roundtrip.py与assets/hdf5_batched_read.py可直接跑通读写往返与分块读取，用于确认环境配置正确。 - 官方发布前量化评测：NVIDIA 内部 NVSkills-Eval 用 17 个评测任务（11 正例、6 负例）分别在 Claude Code 与 Codex 上测了安全性、正确率、可发现性、有效性、效率五个维度。
3. 适用场景
所属分类：工程效率与代码质量
适合把 cuPyNumeric 分布式数组接入 HPC 数据管线的开发者与科研工程师——典型场景是把大规模科学计算的中间结果或最终结果落盘为单一 HDF5 文件供下游工具消费、从已有 HDF5 数据集分块加载超出单机内存的数组、或在具备 GPUDirect Storage 硬件的集群上加速磁盘到 GPU 显存的数据搬运。
4. 跨 Agent 兼容性
- Claude Code：原生支持，官方 README 给出
--agent claude-code安装命令，安装后需运行/reload-skills加载；官方发布前评测在 Claude Code 上实测五维度均有正向提升（如可发现性 +20%、效率 +27%）。 - Codex：原生支持，README 提供对应的
--agent codex安装命令，评测同样覆盖 Codex（正确率 +12%、有效性 +20%）。 - OpenClaw / Hermes Agent：未验证。官方
skillsCLI 目前列出的受支持客户端为 Claude Code、Codex 等，抓取到的材料未提及这两个 agent。
5. 推荐理由
分布式并行 I/O 有若干反直觉的隐蔽坑——异步写入未加 fence 会读到空文件、GPU 读取超过 128MB 不开 GDS 会直接中止、SPMD 场景下每个进程路径不一致会破坏集体 I/O——这些通常要靠踩坑积累经验。这个技能把这些坑逐条写清楚并配对应修复方案，还配了两份可直接跑通验证环境是否正确的脚本，能省下 HPC 团队在数据落盘环节反复试错的时间。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 官方 NVIDIA Corporation 出品（cuPyNumeric/Legate 均为 NVIDIA 自有产品）；未见针对该技能本身的独立第三方讨论或采用数据，NVIDIA 官方技术博客有对 HDF5+GPUDirect Storage 底层技术（165 倍 I/O 吞吐提升）的报道，但未专门评价这个技能 |
| 可用性 | 8 | 需 conda install h5py 及匹配版本的 Legate（26.01+），并理解 SPMD 多进程执行模型，非一条命令直接可用；但文档完整、含可运行验证脚本与故障排查表，技能目录最近一次提交为 2026-06-02，所属仓库整体最近一次提交为 2026-08-07，维护活跃，无付费依赖 |
| 安全性 | 9 | 见下方检查清单 |
安全检查清单：①仅涉及本地文件读写与 conda install h5py 安装命令，无远程执行、无破坏性操作 ②运行时不联网外发数据，GPUDirect Storage 全程走本地硬件路径 ③不需要任何 API Key 或外部凭据 ④通读 SKILL.md 全文未发现可疑指令、混淆代码或隐藏外发行为 ⑤NVIDIA 官方团队出品，发布前评测安全维度 Claude Code 与 Codex 均为 100%，无造假迹象 ⑥License 为 CC-BY-4.0 OR Apache-2.0，明确 ⑦技能目录最近一次提交 2026-06-02（约两个月前），所属仓库整体持续每日同步维护
7. 跟同类 Skills 相比的优势
| 对比对象 | 定位 | 与本技能的差异 |
|---|---|---|
cupynumeric-parallel-data-load（同仓库姊妹技能） |
负责 Parquet/cuDF/原始二进制等分片或自定义布局的并行加载 | 覆盖的是本技能明确排除在外的数据格式；两者合起来才覆盖 cuPyNumeric 的完整数据加载版图，选哪个看目标文件格式是 HDF5 单文件还是分片/其他格式 |
cupynumeric-migration-readiness（同仓库姊妹技能） |
评估现有 NumPy 代码是否值得迁移到 cuPyNumeric GPU，属迁移决策阶段 | 是迁移前的静态评估工具，不涉及具体 I/O 实现；本技能面向的是已经决定使用 cuPyNumeric、需要处理 HDF5 文件读写的实施阶段 |
| 直接使用 h5py（无技能辅助） | Python 生态最常用的通用 HDF5 库 | h5py 面向单进程场景，不了解 Legate 的异步执行模型与 SPMD 集体 I/O 语义；在分布式 cuPyNumeric 场景下直接套用 h5py 写法容易漏掉 fence、路径一致性等要求，本技能专门针对这层差异给出指导 |
目前能找到的同类技能均是同一产品线内按数据格式或流程阶段切分的姊妹技能，专门针对“cuPyNumeric + HDF5 + 分布式/GPU 加速”这个组合给指导的技能暂无其他直接对标。
8. 用户评价
该技能目前在第三方平台尚无经核实的具名用户评价；NVIDIA 官方技术博客对 HDF5 与 GPUDirect Storage 结合的底层技术有报道（含实测的 165 倍 I/O 吞吐提升数据），但该报道针对的是底层技术而非这个技能本身。
9. 其他补充
SKILL.md 明确要求 agent “内联作答”——把文档内的代码片段与规则当作已验证事实直接回答，不必额外读取 assets/ 目录下的脚本源码，只有在需要实际运行验证时才调用它们。
10. 安装使用方式
- 通用安装（交互式选择安装目标）：
npx skills add nvidia/skills，然后从目录中选择cupynumeric-hdf5 - 指定技能与 agent 一次装好：
npx skills add nvidia/skills --skill cupynumeric-hdf5 --agent claude-code（Codex 用户把--agent值换成codex） - 安装后注意事项：在 Claude Code 中需运行
/reload-skills让本次会话识别新装技能；使用前需conda install -c conda-forge h5py；向 agent 描述“把 cuPyNumeric 数组存成 HDF5”或“用 GPUDirect Storage 加速 HDF5 读取”等需求即可触发
11. 注意事项
- 依赖特定版本的 Legate（26.01 及以上，
legate.io.hdf5模块路径在更早的 25.03 版本里位置不同），版本不匹配会导致导入失败 - GPUDirect Storage 是可选能力，需要额外的
vfd-gds插件与 NVIDIA cuFile 驱动；没有 GPUDirect 硬件时会自动降级到兼容模式，但仍需显式设置环境变量才能避开 GPU 读取的内存缓冲区限制 - 仅覆盖单文件 HDF5 格式，Parquet/Arrow/cuDF、分片或自定义布局、Zarr/对象存储等场景需转介到姊妹技能或其他工具
- 面向已具备 cuPyNumeric/Legate 分布式计算环境的开发者，不适合尚未搭建相关运行环境、只是想用 Python 处理普通 HDF5 文件的用户