MiaAI-Lab/Qwen3.8-27B-SGLang-DGX-Spark

이 리포지토리의 기능

MiaAI‑Lab은 NVIDIA DGX Spark (aarch64, 128 GB 통합 메모리)에서 SGLang을 사용하여 Qwen 3.8 27B 대규모 언어 모델을 실행할 수 있도록 즉시 실행 가능한 Docker 스크립트를 제공합니다. 이 리포지토리는 다음을 포함합니다:

세 가지 예측 디코딩 엔진(EAGLE/MTP, DSpark, DFlash2)용 Docker 기반 실행 스크립트. 각각 DGX Spark 하드웨어에 최적화되어 있습니다.
README에 기재된 성능 수치를 재현할 수 있는 소규모 벤치마크 유틸리티(bench/).
컨텍스트 길이(최대 1 M 토큰), 동시성(최대 10개의 동시 요청), 양자화 모드, CPU 핀닝을 조정할 수 있는 설정 헬퍼(.env.sample, 시작 스크립트).
저자가 자신의 시스템에서 측정한 최적의 지연/처리량을 얻기 위해 사용한 하드웨어 전용 플래그 문서화.

요약하면, 이 리포지토리는 전용 NVIDIA 서버에서 270억 파라미터 LLM을 고속으로 실행하기 위한 배포 키트입니다.

누구에게 유용한가

대상	중요성
ML 엔지니어 / 연구 운영 팀 – NVIDIA DGX Spark 하드웨어에서 Qwen 3.8 27B를 벤치마크하거나 배포해야 하는 경우.
AI 제품 팀 – 단일 강력한 노드에서 저지연 추론이 필요한 챗 에이전트, 코드 어시스턴트, 도구 호출 서비스를 개발하는 경우.
성능 최적화 마니아 – SGLang의 예측 디코더(EAGLE/MTP, DSpark, DFlash2)를 하드웨어 전용 설정(CPU 세트 핀닝, FP8 KV 캐시, 메모리 분수 조정)과 결합하는 구체적인 예를 원하는 경우.
하위 애플리케이션 개발자 (예: RAG 파이프라인, 자율 에이전트) – 표준 OpenAI 호환 `/v1/models` 엔드포인트를 통해 배포된 모델을 호출할 수 있는 경우.

시작하기 (빠른 시작)

리포지토리 복제하고 샘플 환경 파일을 복사합니다:

git clone https://github.com/MiaAI-Lab/Qwen3.8-27B-SGLang-DGX-Spark.git
cd Qwen3.8-27B-SGLang-DGX-Spark
cp .env.sample .env   # 기본 설정을 가진 .env 생성

Docker가 GPU를 인식할 수 있는지 확인 (NVIDIA Container Toolkit 설치 필요)하고, Hugging Face 액세스 토큰을 HF_TOKEN 환경 변수로 내보내세요.
엔진을 선택하고 실행합니다:
```
# 기본: DSpark (코드 유형 워크로드에서 가장 빠름)
./start-dspark.sh

# 대안: 전통적인 EAGLE/MTP 예측 디코딩
./start.sh

# 대안: DFlash2 (짧은 채팅 및 긴 글쓰기 유형에 적합)
./start-dflash.sh
```
스크립트는 적절한 SGLang 이미지를 다운로드하고, Qwen 체크포인트를 ./.cache/huggingface에 다운로드(약 24GB), 포트 8888에서 리스닝하는 컨테이너를 시작합니다.
서버 테스트:
```
curl http://127.0.0.1:8888/v1/models
```
모델 이름 qwen3.8-27b-sglang가 준비되었음을 확인하는 JSON 응답이 반환되어야 합니다.
사용 후 서비스 중지:
```
./stop.sh
```

변경 가능한 설정 (구성)

변수 (.env 또는 쉘 환경 변수)	기본값	제어 항목
`YARN`	`0`	컨텍스트 길이가 262K 토큰을 초과할 경우 YaRN rope 스케일링 활성화. 네이티브 윈도우를 초과하는 길이에서는 반드시 `1`로 설정해야 함.
`CONTEXT_LENGTH`	`262144`	토큰 윈도우 크기 (262K – 1M). 큰 윈도우는 `YARN=1` 필요.
`MAX_CONCURRENT_REQUESTS`	`10`	동시 API 호출 수. GDN 상태 풀 크기도 결정.
`QUANT`	`nvfp4`	체크포인트 변형 선택: `nvfp4` (밀도 BF16 헤드), `nvfp4-fp4` (패킹 FP4 헤드), `fp8` (FP8 가중치), `bf16` (전체 BF16). 모두 128GB 메모리 예산 내.
`CPUSET`	`5-9,15-19`	컨테이너를 DGX Spark의 10개 고성능 Cortex-X5 코어에 핀딩하여 느린 A725 코어는 여유롭게 유지.
`SPEC_STEPS` / `SPEC_TOPK` / `SPEC_DRAFT`	`3` / `1` / `4`	EAGLE/MTP 예측 디코더용 튜닝 노브. DSpark 및 DFlash2 엔진은 무시.
`CHUNKED_PREFILL`	`8192`	프리필 청크 크기. 이 하드웨어에서는 큰 값이 첫 번째 토큰 지연을 개선.
`DF_TARGET` (DFlash2 전용)	`nvfp4`	DFlash2 엔진이 로드할 체크포인트 선택 (`nvfp4`, `nvfp4-fp4`, `bf16`).
`IMAGE`	엔진별 (스크립트 참조)	로컬에서 빌드한 변형을 사용할 경우 사용자 정의 SGLang 이미지 지정 가능.

모든 변수는 명령줄에서 오버라이드 가능. 예:

MAX_CONCURRENT_REQUESTS=5 CONTEXT_LENGTH=524288 YARN=1 ./start.sh

새 값은 ./stop.sh && ./start… 사이클 후에 적용됩니다.

측정 결과 (저자의 DGX Spark에서 측정한 수치)

엔진	일반적인 지연 (초) – 코드 스니펫	일반적인 지연 – 긴 에세이	일반적인 지연 – 짧은 채팅
DSpark (block-7)	~51.5초 (코드에 최적)	~18초 (MTP보다 느림)	~23초 (좋음)
EAGLE/MTP	~34.5초	~24초 (긴 글쓰기 최적)	~21초
DFlash2 (NVFP4)	~50.9초	~25.4초	29–67초 (토큰 카운팅 수정 후 스트리밍 짧은 채팅에서 승리)

모든 수치는 bench/의 벤치마크 스크립트의 월타임이며, 프리필, 디코딩, 예측 드래프트 오버헤드 포함. 메모리 사용량은 밀도 BF16 헤드 약 24GB + 드래프트 모델 약 2.5GB. 패킹 FP4 변형은 몇 GB 절약 가능.

어떤 엔진을 선택해야 할까

목표	추천 스크립트	이유
도구 호출 또는 코드 생성이 필요한 에이전트	`./start-dspark.sh`	DSpark의 block-7 드래프트가 코드 중심 프롬프트에서 최고의 디코딩 속도 제공.
긴 글쓰기 (에세이, 보고서)	`./start.sh` (EAGLE/MTP)	MTP의 예측 디코딩이 대규모 연속 출력에서 뛰어난 성능 발휘.
일반 채팅 또는 혼합 워크로드	`./start-dflash.sh`	DFlash2는 코드와 채팅 성능을 균형 있게 유지하며, 적절한 토큰 카운팅 후 짧은 채팅 지연에서 다른 것들을 능가.

더 자세한 정보 찾기

이 시스템에서 측정됨 – README의 한 테이블에 저자가 관찰한 모든 지연, 메모리 분수, 토큰 카운팅 제약이 기록됨.
bench/ 스크립트 – ndec.py, bench.sh, ab-image.sh로 자사 하드웨어에서 A/B 비교 재현 가능.
docs/ – 브레인스토밍 노트(brainstorms/*.md)와 장기 계획(plans/*.md) 포함.

TL;DR

NVIDIA DGX Spark에 접근 가능하고 27B Qwen 모델을 낮은 지연으로 실행해야 한다면, 이 리포지토리는 다음을 제공합니다:

세 가지 주요 SGLang 예측 디코더용 미리 구성된 Docker 이미지.
모델을 자동으로 다운로드하고 최적의 하드웨어 플래그를 적용하며 OpenAI 호환 API를 노출하는 스크립트.
컨텍스트 길이를 최대 1M 토큰까지 늘리고 최대 10개의 동시 요청을 실행할 수 있는 간단한 조절 장치.

.env.sample을 복사하고 관심 있는 엔진을 선택한 후 해당 start-*.sh를 실행하면, 몇 분 안에 Qwen 3.8 27B를 배포할 수 있습니다.