eugr/spark-vllm-docker

무엇인가요

spark‑vllm‑docker는 NVIDIA DGX Spark 클러스터(또는 단일 DGX Spark 노드)에서 vLLM 추론 엔진을 실행할 수 있게 해주는 Dockerfile, 도우미 스크립트 및 즉시 사용 가능한 recipes 세트입니다. vLLM(및 선택적 실험적 B12X 커널)이 포함된 Docker 이미지 빌드를 자동화하고, Hugging Face에서 모델 가중치를 가져오며, Ray 또는 vLLM 네이티브 PyTorch‑distributed 백엔드를 사용하여 하나 이상의 Spark 노드에서 vLLM 서버를 실행합니다.

대상 사용자

• DGX Spark 하드웨어에 액세스할 수 있고 대규모 LLM(예: Qwen‑3.8, DeepSeek‑V4, GLM‑5.x, Nemotron 3.5)을 높은 처리량으로 서비스하려는 엔지니어.
• InfiniBand/RDMA, KV‑cache FP8, 추측 디코딩 및 InstantTensor 또는 실험적 B12X 로더를 통한 빠른 모델 로딩을 사용하여 다중 노드 추론이 필요한 팀.
• 각 노드에서 수동으로 vLLM을 빌드하는 대신 재현 가능한 Docker 기반 워크플로우를 선호하는 사용자.

핵심 기능(README에 설명된 대로)

기능	세부 정보
Docker 이미지	eugr/spark-vllm:latest(일반) 또는 eugr/spark-vllm-b12x:latest(실험적 B12X 커널). 이미지는 nightly vLLM wheels 또는 소스에서 빌드되며, 선택적으로 --use-wheels, --rebuild-vllm, --rebuild-flashinfer 플래그를 사용할 수 있습니다.
다중 노드 지원	실행 스크립트(launch‑cluster.sh, run‑recipe.sh)가 Spark 노드를 검색하고, 암호 없는 SSH를 설정하며, InfiniBand/RoCE에서 NCCL을 사용하여 vLLM 워커를 시작합니다.
모델 로딩	표준 safetensors, InstantTensor 제로 카피, 더 빠르고 낮은 메모리 로딩을 위한 B12X 로더를 지원합니다.
추측 디코딩	DFlash, MTP, DSpark 등의 내장 구성을 통해 단계당 최대 8개의 추측 토큰을 허용합니다.
메모리 최적화	FP8 KV‑cache, VLLM_WSL2_ENABLE_PIN_MEMORY, 조기 OOM 모니터, CPU 힙 트리밍 및 선택적 PLE‑table 디스크 오프로드.
편리한 recipes	인기 모델(Qwen‑3.8‑27B, DeepSeek‑V4‑Flash‑Vision, GLM‑5.3, Nemotron‑3.5 등)을 위한 YAML 파일로, 모델 ID, 병렬 처리, 토크나이저 및 성능 플래그가 미리 구성되어 있습니다.
확장성	--apply‑vllm‑pr을 사용하여 시작 시 업스트림 vLLM 풀 리퀘스트 diff를 가져올 수 있으며, mods/ 디렉토리에 사용자 지정 로더 패치를 보관합니다.
상태 확인	간단한 curl http://localhost:8000/health 및 OpenAI 호환 /v1/models 엔드포인트.

시작하기(빠른 시작 요약)

1. Clone: Spark 헤드 노드에서 리포지토리를 복제합니다.
2. 빌드 및 복사: Docker 이미지를 빌드합니다: ./build-and-copy.sh (실험적 이미지는 --exp-b12x 추가).
3. 다운로드: 모델 가중치를 다운로드합니다: ./hf-download.sh <model‑repo>.
4. 실행: 서버를 시작합니다:

   ./launch-cluster.sh --solo -t vllm-node \
     exec vllm serve <model> \
       --host 0.0.0.0 --port 8000 \
       --kv-cache-dtype fp8 ...
   

   (vllm-node를 vllm-node-b12x로 바꾸고 README에 표시된 B12X 기반 레시피를 위한 추가 플래그를 추가하세요.)
5. 테스트: curl을 사용하여 엔드포인트를 테스트하고 클라이언트를 http://<head‑node-ip>:8000/v1으로 지정합니다.

왜 중요한가

단일 GPU에서 vLLM을 실행하는 것은 간단하지만, 낮은 지연 시간을 유지하면서 여러 DGX Spark 노드로 추론을 확장하려면 세심한 네트워킹, 메모리 관리 및 커널 선택이 필요합니다. 이 리포지토리는 이러한 모든 조정 사항을 재현 가능한 Docker 이미지와 스크립트로 패키징하여, 실무자가 저수준 클러스터 구성이 아닌 모델 자체에 집중할 수 있도록 합니다.

---

위의 모든 정보는 리포지토리의 README에서 직접 가져온 것이며, 추가 기능은 추론되지 않았습니다.