NVIDIA GPUDirect Storage(GDS)는 온프레미스와 클라우드 환경에서 GPU의 스토리지 접근 속도를 높입니다. NVIDIA GPU와 스토리지 사이에 안정적이고 효율적이며 다양한 환경에서 활용할 수 있는 데이터 경로를 제공합니다. 이를 통해 폭넓은 플랫폼, 애플리케이션 프레임워크, 워크로드에서 대역폭을 높이고 지연 시간과 CPU·메모리 사용량을 줄입니다.
NVIDIA GPUDirect Storage를 설정하려면 먼저 사용 환경을 파악해야 합니다. 플랫폼과 워크로드에 어떤 설정과 스토리지 경로가 적합할까요? 지원 아키텍처와 스토리지 솔루션의 설정 및 문제 해결 방법은 문서에 상세히 나와 있습니다. 다만 이 정보를 찾아 실제 환경에 맞게 적용하고 최적화하는 일은 사용자의 몫입니다.
GPUDirect Storage 팀은 설정과 최적화를 간소화하기 위해 gds-diag를 개발했습니다. gds-diag는 사용 환경을 점검하고 문제를 찾아 개선 방법을 제안하는 간단한 오픈소스 명령줄 도구입니다. GDS를 최대한 효율적으로 활용할 수 있도록 돕습니다.
자연어 인터페이스를 제공하고 여러 진단 단계를 조율하는 에이전트 스킬도 함께 제공되며, 필요에 따라 사용할 수 있습니다. 이 스킬은 사용자의 의도를 파악해 적절한 하위 명령을 선택하고 실행하며, 여러 단계로 이루어진 진단 작업을 진행합니다. 명령을 선택하고 연결하는 데서 그치지 않고 AI 모델의 추론 능력도 활용합니다. 진단 결과를 해석하고 시스템 환경을 고려해 적절한 해결 방법을 제안하거나 직접 적용할 수 있습니다.
이 글에서는 명령줄 인터페이스와 에이전트 스킬을 각각 활용해 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 에이전트: 자연어로 대화하면서 GDS 환경을 직관적이고 유연하게 진단할 수 있습니다. 실제 검사는 기반 명령줄 도구가 수행하므로 일관된 진단 방식도 유지됩니다. 선호하는 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는 사용 가능한 하위 명령을 네 가지 범주로 나눠 보여 줍니다.
현재 배포 단계나 확인하려는 문제에 맞춰 진단 범주를 선택하세요.
- 전체 점검:
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처럼 점검 결과를 섹션별로 묶어 보여 줍니다.
각 점검 항목과 섹션에는 다음과 같은 상태 배지가 표시됩니다.
- FAIL: GDS 사용을 가로막는 문제가 있습니다.
- WARN: GDS 사용에 문제가 될 수 있는 사항이 있습니다.
- INFO: 알아둘 만한 정보를 안내합니다.
- PASS: 점검 결과가 정상입니다.
--verbose옵션을 사용할 때만 표시됩니다.
각 점검 결과에는 설명과 해결 방법이 함께 나옵니다. gds-diag가 자체적으로 해결 방법을 적용하거나 시스템을 변경하지는 않습니다. 이 도구는 문제와 최적화할 부분을 찾아 사용자나 관리자가 환경을 개선하도록 돕습니다. 결과에는 여러 섹션이 표시될 수 있으며, 각 섹션에 여러 점검 항목이 포함될 수 있습니다.
팁: --json 명령줄 옵션을 사용하면 모든 진단 보고서를 구조화된 JSON 데이터로 출력할 수 있습니다. 결과를 다른 도구로 가져가거나 나중에 참고할 수 있도록 보관할 때 유용합니다.
대부분의 하위 명령은 같은 출력 구조를 따릅니다. 예외적으로 gds-diag.py support-matrix는 각주가 달린 표로 결과를 보여 줍니다. 이 명령으로 GDS가 지원하는 플랫폼 조합을 확인할 수 있습니다.
--static 옵션은 그림 4와 같은 일반적인 지원 정보를 보여 주며, --live 옵션은 현재 시스템 설정을 반영합니다.
이미지 설명: gds-diag 지원 매트릭스의 스크린샷입니다. 스토리지 경로를 로컬 파일 시스템, 원격 파일 시스템, 스토리지 경로, 호환 모드 전용(compat-only)으로 구분합니다. 각 열에는 GPUDirect Storage 접근 방식별 파일 시스템 지원 상태가 표시됩니다.
초록색은 완전 지원, 노란색은 아키텍처나 설정 조건에 따른 지원, 빨간색은 미지원을 뜻합니다.
팁: 대부분의 분산 스토리지 공급업체는 Linux 운영체제에서 파일 시스템을 nfs 또는 nfs4로 표시합니다. 따라서 지원 매트릭스의 해당 행은 다양한 제품의 지원 여부를 포괄합니다.
명령줄 사용 예시
새로 만들거나 수정한 GDS 설정 파일을 프로덕션 환경에 배포하기 전에 점검하는 상황을 살펴보겠습니다. 이때는 config-audit 하위 명령이 적합합니다. 인수 없이 실행하면 현재 적용되는 설정을 점검합니다. 여기에는 정적 설정 파일뿐 아니라 설정을 동적으로 변경하는 환경 변수도 포함됩니다. 다음 예시에서는 --config 옵션으로 검토할 설정 파일을 지정합니다.
설정 점검 과정에서 파일 내 항목의 오타를 발견합니다. 오류를 수정한 뒤 다시 실행하면 config-audit가 설정이 유효하다는 것을 확인하고, 참고할 만한 추가 정보도 제공합니다.
에이전트 스킬 사용하기
Claude나 Codex 같은 코딩 도우미에서 gds-diag 저장소를 열면 gds-diag 에이전트 스킬이 자동으로 활성화됩니다.
팁: 코딩 도우미에서 /gds-diag를 입력해 스킬을 직접 활성화할 수도 있지만, 반드시 그럴 필요는 없습니다. GDS에 관한 질문을 자연어로 입력하면 코딩 도우미가 적절한 스킬로 판단해 자동으로 선택합니다.
이 스킬은 gds-diag 명령줄 도구가 이미 제공하는 검사를 다시 구현하지 않습니다. 주로 적절한 gds-diag 하위 명령을 선택하고 실행 결과를 해석하는 역할을 합니다. 예를 들어 다음과 같이 질문할 수 있습니다.
- 이 시스템에서 GDS를 사용할 수 있나요?
/mnt/data에서 GDS를 사용할 수 있나요?/mnt/data에 접근할 때 최적의 성능을 내도록 GDS를 설정하려면 어떻게 해야 하나요?- GDS가 현재 어떤 설정 파일을 사용하고 있나요?
- 업데이트해야 할 설정 매개변수가 있나요?
- GPU3와 토폴로지상 가장 가까운 NVMe 장치는 무엇인가요?
에이전트를 활용하면 gds-diag로 할 수 있는 일이 더 많아집니다. 진단 결과에 관해 추가로 질문하거나, 해결 방법을 대신 적용해 달라고 요청할 수도 있습니다.
에이전트 스킬 사용 예시
그림 6은 gds-diag 에이전트 스킬과 AI 모델의 추론 능력을 함께 활용해 컨테이너 설정 문제를 진단하는 과정입니다. 이 예시에서는 Anthropic Claude Code CLI를 사용합니다.
이 사례에서 에이전트는 컨테이너를 시작하는 셸 스크립트를 살펴보고, 문제를 조사하는 데 적합한 gds-diag 도구를 선택합니다. 이어 진단 결과에 따라 스크립트를 수정하는 방안을 제안하고, 수정 후 문제가 해결됐는지 확인합니다. 코딩 도우미는 사용자의 로컬 설정과 조직 정책에 따라 어떤 작업에 확인이 필요한지 판단합니다.
시작하기
GPUDirect Storage의 설정과 최적화를 점검할 때 gds-diag를 첫 진단 도구로 활용해 보세요. 모듈식으로 설계돼 있어 네트워크 전송 방식, 오브젝트 스토리지 시스템, 애플리케이션 프레임워크 등을 점검하는 기능도 추가할 수 있습니다.
추가하고 싶은 진단 항목이나 파일 시스템이 있나요? 커뮤니티의 기여를 환영합니다. 소스 코드와 에이전트 스킬은 오픈소스 라이선스인 Apache 2.0과 Creative Commons Attribution 4.0 International로 공개돼 있습니다. 참여 방법은 기여 가이드를 참고하세요.
