NVIDIA GPUDirect Storage（GDS）可加速本地和云环境中的 GPU 存储访问。它在 NVIDIA GPU 与存储目标之间提供稳健、可移植且高效的数据路径，从而在广泛的平台、应用框架和工作负载模式中提升带宽、最小化延迟，并降低 CPU 和内存利用率。
配置 NVIDIA GPUDirect Storage 首先要了解你的环境。哪些设置和存储路径适合你的平台和工作负载？详尽的文档介绍了如何配置和排查受支持的架构和存储解决方案，但你需要自行梳理这些信息并优化你的部署。
gds-diag 工具由 GPUDirect Storage 团队开发，旨在简化 GPUDirect Storage 的优化和配置。gds-diag 是一个简单的开源命令行实用程序，可评估环境、识别问题并建议改进措施，帮助你充分利用 GDS 部署。
它还附带一个可选的 agent skill，增加了自然语言接口和编排层。该 skill 会解读你的意图，选择并调用相应的子命令，并协调多步骤诊断工作流。除命令选择和路由外，该 skill 还通过模型引导的推理扩展了 gds-diag。它可以解读诊断结果、应用相关系统上下文，并提出或执行适当的修复措施。
本文介绍如何通过命令行界面或 agent skill 开始使用 gds-diag。
下载与安装
要使用 gds-diag，你需要一个装有 Python 3.8 或更新版本的 Linux 系统。GPUDirect Storage 需要 NVIDIA 数据中心级 GPU 和 NVIDIA CUDA Toolkit 12.2 或更新版本，但这些并非 gds-diag 本身的依赖项。
gds-diag 作为 NVIDIA Magnum IO GitHub 仓库的一部分分发，无需安装其他依赖项。在计划运行它的机器上克隆该仓库，并使用 git clone https://github.com/NVIDIA/MagnumIO.git 选择以下使用模式之一：
命令行工具：这提供了一条确定性、依赖极少的路径来诊断 GDS 部署。进入
gds-diag目录，运行gds-diag.py --help，并遵循命令行用法指南。AI agent：这提供了最直观、灵活、交互式的自然语言机制来诊断 GDS 部署，同时仍保留底层命令行工具可靠的确定性。在你偏好的 AI 编码助手中打开
gds-diag目录，并遵循 Agent skill 用法指南。
快速提示：如果你的环境中提供此选项，建议使用 AI agent 模式。gds-diag 已通过 Claude 和 Codex 验证，不过它也可能适用于其他工具。
命令行用法
gds-diag 命令行工具是一个单一的 Python 脚本，包含多个子命令，分别聚焦于不同的诊断任务。你可以运行 ./gds-diag.py --help 浏览可用的子命令。
要了解某个特定子命令的更多信息，请运行 ./gds-diag.py <subcommand> --help。
快速提示：不确定从哪里开始？只需运行 ./gds-diag.py all /path/to/check，gds-diag 将自动为该路径运行一整套诊断流程。这适用于裸机、虚拟机和容器环境。
图 2 将可用子命令分为四类。
根据你的部署阶段或需要调查的问题选择诊断类别。
- 端到端检查：使用
all自动为你的环境选择合适的诊断并按顺序运行。 - 安装准备：使用
pre-install检查 GPU 支持和 CUDA Toolkit 安装情况。使用support-matrix查看受支持的存储目标并规划你的部署。 - 验证安装：使用
post-install检查 GDS 是否安装正确并识别阻碍因素。使用config-audit查看影响 GDS 行为的配置文件和環境变量。 - 深度诊断：使用
container-check评估容器环境中的 GDS 支持情况，包括 containerd、Docker、Enroot 和 Kubernetes。使用mount-check诊断特定的挂载点或目录。
gds-diag 诊断结果的结构
大多数 gds-diag 子命令的输出以一组按章节分组的诊断结果呈现，如图 3 所示。
每个诊断结果和每个章节都有一个状态徽章。
- “FAIL”表示硬性阻碍。
- “WARN”表示潜在阻碍。
- “INFO”传达值得注意的信息。
- “PASS”表示正常结果，仅在你使用
--verbose选项时显示。
每个诊断结果都包含说明，随后是缓解计划。gds-diag 不会自行实施缓解计划或以其他方式修改系统。它的作用是识别问题和优化机会，并帮助你或你的管理员进行改进。可能会显示多个章节（以及这些章节内的诊断结果）。
快速提示：你还可以使用 --json 命令行选项将所有诊断报告输出为结构化 JSON 数据。如果你计划将诊断结果导入其他工具或存档以备将来参考，这会很有用。
大多数子命令遵循相同的结构。gds-diag.py support-matrix 命令是一个显著的例外：它以带脚注的表格形式输出。该子命令显示 GDS 支持哪些平台组合。
使用 --static 选项呈现通用数据（如图 4 所示），或使用 --live 选项纳入系统当前配置的信息。
绿色标记的项目表示完全支持，黄色标记的项目表示在架构或配置方面存在限制条件的情况下支持，红色标记的项目表示不支持。
快速提示：大多数分布式存储厂商选择在 Linux 操作系统层面将其文件系统呈现为 nfs 或 nfs4，因此支持矩阵中的这一行对应着广泛的产品支持。
命令行演示
为进行演示，假设要为生产部署准备一个新的或修改过的 GDS 配置文件。config-audit 子命令是此场景的理想选择。如果在不带参数的情况下调用，它将审计当前生效的配置，包括静态配置文件和动态环境变量修饰符。以下示例使用 --config 选项指定一个候选配置进行审查。
配置审计发现配置文件中有一处拼写错误的条目。在你更正错误后，config-audit 确认配置有效，并提供额外的信息性提示。
Agent 技能用法
当你使用 Claude 或 Codex 等编码助手打开 gds-diag 仓库时，gds-diag agent 技能会自动激活。
快速提示：你可以在编码助手中使用 /gds-diag 关键字显式激活 gds-diag，但这并非严格必要。如果你用自然语言提出关于 GDS 的问题，它会自动选择该技能作为合适的技能来使用。
该技能不会尝试重复 gds-diag 命令行工具已提供的确定性检查。相反，它的主要作用是在 gds-diag 各子命令之间进行路由，并解释它们的输出。以下是你使用该技能可以提出的一些查询示例：
- 此系统是否有资格使用 GDS？
- 它是否可用于
/mnt/data？ - 如何以最佳方式配置 GDS 以访问
/mnt/data？ - GDS 正在使用哪些配置文件？
- 是否有任何配置参数需要更新？
- 哪个 NVMe 设备与 GPU3 的局部性最佳？
Agent 是 gds-diag 的能力倍增器；你可以提出后续问题，甚至可以让 agent 代表你实施缓解措施。
Agent 技能演示
图 6 展示了如何将 gds-diag agent 技能与模型固有的推理能力相结合，以诊断容器配置问题。此示例使用 Anthropic Claude Code CLI。
在此例中，agent 检查用于启动容器的 shell 脚本，并确定使用哪个 gds-diag 工具来调查问题最佳。然后它提供选项，根据其发现修改脚本，并确认解决方案。请注意，编码助手将遵循你的本地设置和站点策略，以确定哪些操作需要确认。
开始使用
在调查 GPUDirect Storage 配置和优化时，请将 gds-diag 作为你的首选诊断工具。其模块化设计为更多诊断功能提供了基础，例如对网络传输、对象存储系统和应用框架的检查。
你有想要贡献的诊断检查或文件系统吗？欢迎并强烈鼓励社区贡献。源代码和 agent 技能均以开源许可证（Apache 2.0 和 Creative Commons Attribution 4.0 International）发布。请参阅贡献者指南以开始。