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