AI 튜토리얼

TensorFold로 단일 DGX Spark에서 Qwen3.8 Flash Next 실행하기

단일 NVIDIA DGX Spark에 Qwen3.8 Flash Next를 설치하고 실행, 테스트 및 튜닝하는 방법을 알아보세요. 이 튜토리얼에서는 TensorFold 배포 스크립트, OpenAI 호환 채팅 요청, 이미지 및 동영상 입력, 추론 제어, 메모리 구성, 모니터링, 성능 점검을 다룹니다.

2026년 9월 29일약 18분 소요

TensorFold로 단일 DGX Spark에서 Qwen3.8 Flash Next 실행

개요

이 프로젝트는 NVIDIA DGX Spark 한 대에서 Qwen3.8 Flash Next를 OpenAI 호환 API로 제공합니다. TensorFold v0.3.6.3, MTP 초안 헤드가 포함된 MLX 4비트 체크포인트, 생성된 텍스트를 변경하지 않고 프롬프트 처리를 가속하도록 설계된 여러 패치를 사용합니다.

기본 구성은 5개의 동시 요청을 지원하며, 각 요청은 모델의 전체 262,144토큰 컨텍스트 윈도우를 사용합니다. 또한 CUDA에서 모델 자체의 비전 타워를 로드하므로 채팅 메시지에 이미지와 동영상을 포함할 수 있습니다.

API 모델 ID: Qwen3.8-Flash-Next
기본 엔드포인트: http://<spark-address>:8888/v1
병렬 스트림: 5
스트림당 컨텍스트: 262,144토큰
전체 KV 풀: 1,310,720토큰
KV 캐시: 기본값은 int8
입력 모드: 텍스트, 이미지, 동영상

주요 기능

긴 컨텍스트 동시 추론

TensorFold는 각 스트림에 전체 컨텍스트 캐시를 할당합니다. 기본 설정에서는 5개의 스트림이 각각 262,144토큰의 프롬프트 및 응답 윈도우를 사용합니다. 그 결과 int8 KV 풀은 약 23.4GiB를 사용합니다.

OpenAI 호환 서비스

서버는 /v1/models 및 /v1/chat/completions와 같은 엔드포인트를 제공합니다. OpenAI 호환 클라이언트는 기본 URL을 변경하고 모델 ID Qwen3.8-Flash-Next를 선택해 연결할 수 있습니다.

멀티모달 프롬프트

사용자 메시지에는 OpenAI 스타일의 image_url 및 video_url 콘텐츠 파트를 포함할 수 있습니다. 지원되는 이미지 형식은 JPEG, PNG, WebP입니다. 동영상은 MP4, WebM, MOV, MKV 또는 FFmpeg가 디코딩할 수 있는 다른 형식을 사용할 수 있습니다.

패치된 프롬프트 처리

포함된 TensorFold 패치는 SSD 프리페치, 네이티브 스레드 읽기, 개선된 희소 어텐션 블록 선택, 구성 가능한 프롬프트 청크, 초안 복사, 실시간 토큰 카운터, Flash Next 비전 지원을 추가합니다. 저장소의 측정 결과에 따르면 프롬프트 처리는 패치하지 않은 비교 버전보다 약 1.7배 빠르며, 테스트한 텍스트 응답은 바이트 단위로 동일합니다.

시스템 요구 사항

저장소를 복제하기 전에 호스트를 준비하세요.

NVIDIA DGX Spark 또는 128GB 통합 메모리를 갖춘 다른 GB10 시스템.
기본 구성을 시작할 때 약 115GiB의 여유 메모리.
NVIDIA 컨테이너 런타임이 설치된 Docker.
docker 그룹에 속한 사용자 계정.
새 시스템 기준 약 160GB의 여유 디스크 공간.
선택 사항: 더 빠른 재개 가능 다운로드를 위한 Hugging Face hf CLI.
선택 사항: ~/.cache/huggingface/token의 Hugging Face 토큰 또는 HF_TOKEN 환경 변수.

기본 배포는 다른 작업이 실행되지 않는 DGX Spark를 대상으로 합니다. 통합 메모리 시스템에서는 메모리를 모두 소진하면 일반적인 할당 오류가 발생하는 대신 시스템이 멈출 수 있습니다.

설치 및 최초 실행

1. 저장소 복제

git clone https://github.com/MiaAI-Lab/Qwen3.8-Flash-Next-Single-DGX-Spark-TensorFold.git
cd Qwen3.8-Flash-Next-Single-DGX-Spark-TensorFold

2. 서버 시작

./start.sh

최초 실행에서는 전체 설정이 진행됩니다. 사용 가능한 경우 미리 빌드된 컨테이너 이미지를 가져오고, 약 106GiB의 체크포인트를 다운로드 및 검증한 뒤 GB10용 CUDA 커널을 컴파일합니다. 미리 빌드된 이미지는 약 11GB이며 체크포인트는 Hugging Face 캐시에서 약 114GB를 차지합니다.

시작 중 스크립트는 설정 진행 상황, 서버 로그, 가중치 로딩 진행 상황 및 메모리 추정치를 표시합니다. 그런 다음 스모크 테스트를 실행합니다. 실행에 성공하면 Qwen3.8-Flash-Next가 8888 포트에서 실행 중이라는 메시지가 표시됩니다.

README에 따르면 이후 실행에서는 완료된 설정 작업을 건너뛰며 가중치 로드에 약 2.5분이 걸립니다.

3. 실행하지 않고 준비

모든 항목을 미리 다운로드하고 빌드하려면 다음을 실행하세요.

scripts/prepare.sh

컨테이너 이미지를 처음부터 다시 빌드하려면 다음을 실행하세요.

scripts/prepare.sh --rebuild

준비 스크립트는 Docker, NVIDIA 런타임 및 디스크 공간을 확인합니다. 그런 다음 TensorFold 이미지를 가져오거나 빌드하고, 체크포인트를 Hugging Face 캐시에 다운로드한 뒤 tensorfold info로 모델을 검증합니다.

기본 API 사용법

사용 가능한 모델 확인

curl -s http://<spark-address>:8888/v1/models

<spark-address>를 DGX Spark의 호스트 이름 또는 IP 주소로 바꾸세요. Spark 자체에서 호출할 때는 127.0.0.1을 사용할 수 있습니다.

채팅 완성 요청 전송

curl -s http://<spark-address>:8888/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "Qwen3.8-Flash-Next",
    "messages": [
      {
        "role": "user",
        "content": "Write a Python fibonacci function."
      }
    ],
    "max_tokens": 1000
  }'

모델은 기본적으로 답변 전에 사고하며, 추론에도 응답 토큰 할당량이 사용됩니다. 추론과 최종 답변을 모두 포함할 수 있도록 max_tokens를 충분히 높게 설정하세요. 추론은 reasoning_content에 반환되며 최종 응답은 content에 표시됩니다.

OpenAI 호환 클라이언트 연결

다음 값으로 클라이언트를 구성하세요.

기본 URL: http://<spark-address>:8888/v1
모델: Qwen3.8-Flash-Next

API는 스트리밍, 타입이 지정된 도구 호출, 추론 콘텐츠, 이미지 입력 및 동영상 입력을 지원합니다. 배열과 같은 도구 매개변수는 해당 JSON 타입으로 반환됩니다.

이미지 전송

기본적으로 미디어는 데이터 URL로 제공해야 합니다. 다음 셸 예제는 JPEG를 인코딩하고 모델에 이미지 설명을 요청합니다.

IMG=$(base64 -w0 photo.jpg)
curl -s http://<spark-address>:8888/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "Qwen3.8-Flash-Next",
    "messages": [{
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,'"$IMG"'"
          }
        },
        {
          "type": "text",
          "text": "What is in this picture?"
        }
      ]
    }],
    "max_tokens": 2000
  }'

요청 하나에는 최대 4개의 이미지를 포함할 수 있습니다. 각 이미지의 크기는 최대 10 MB이며, 전체 크기 제한은 20 MB입니다. 모든 이미지에 사용할 수 있는 토큰은 최대 4,096개입니다. "detail": "low"를 설정하면 이미지가 256토큰으로 제한됩니다.

동영상 전송

동영상은 video_url 콘텐츠 부분을 사용합니다.

{
  "type": "video_url",
  "video_url": {
    "url": "data:video/mp4;base64,..."
  }
}

요청 하나에는 최대 2개의 동영상을 포함할 수 있습니다. 동영상 하나의 크기는 최대 64 MB이며, 요청 전체 크기 제한은 96 MB이고 영상 길이는 최대 1시간입니다. 기본적으로 서버는 초당 2프레임을 샘플링하며, 동영상 전체에 걸쳐 최대 256프레임을 추출하고, 요청당 최대 16,384개의 동영상 토큰을 허용합니다.

이미지 및 동영상 프롬프트는 접두사 재사용을 위해 보존되지 않습니다. 일반 텍스트 요청은 비전 기능을 활성화해도 영향을 받지 않습니다.

공개 HTTPS 미디어 URL 허용

기본값은 데이터 URL입니다. 서버가 공개 HTTPS 이미지 및 동영상 URL을 가져오도록 하려면 다음 명령으로 서버를 다시 시작합니다.

VISION_URLS=1 ./start.sh restart

원격 가져오기는 배포 환경의 보안 및 네트워크 정책에 적합한 경우에만 활성화하세요.

텍스트 전용 모드 실행

비전 타워를 비활성화하여 텍스트 전용으로 제공하려면 다음을 실행합니다.

VISION=0 ./start.sh restart

텍스트 전용 모드에서는 0.84 GiB 비전 타워를 로드하지 않으며, 비전 활성화 시 기본값인 2,048행 대신 4,096행 프롬프트 청크를 사용합니다.

서버 관리

일상적인 작업에는 저장소의 래퍼 스크립트를 사용하세요.

./start.sh restart
./stop.sh
docker logs -f qwen38-flash-next-tf
curl -s http://<spark-address>:8888/health

./start.sh restart는 실행 중인 서버를 교체하기 전에 설정과 인수를 검증합니다.
./stop.sh는 컨테이너를 중지하고 GPU 메모리를 해제합니다. 진행 중인 요청은 중단됩니다.
docker logs -f는 TensorFold 서버 로그를 계속 표시합니다.
/health는 사용 중 상태와 현재 토큰 합계를 보고합니다.

서버가 이미 실행 중이면 일반 ./start.sh는 서버를 그대로 둡니다. systemd와 같은 프로세스 관리자를 사용하려면 포그라운드 모드를 사용하세요.

FOREGROUND=1 ./start.sh

컨텍스트, 동시성 및 KV 정밀도 구성

기본값은 scripts/config.sh에 저장됩니다. 환경 변수로 재정의하거나 start.sh 뒤에 TensorFold 플래그를 전달할 수 있습니다.

여유 메모리를 늘리기 위해 동시성 줄이기

PARALLEL=4 ./start.sh restart

int8 스트림 4개는 1,048,576토큰의 KV 풀을 제공하며, 보고된 시작 시 예상 메모리 사용량은 약 97.7 GiB입니다.

더 짧은 컨텍스트 창 사용

./start.sh restart --context 131072

추가 명령줄 인수는 기본값 뒤에 tensorfold serve로 전달되므로 기본값보다 우선합니다. 사용 가능한 옵션을 확인하려면 ./start.sh --help를 실행하세요.

다른 KV 캐시 타입 선택

KV_DTYPE은 bf16, int8 또는 int4를 허용합니다.

PARALLEL=6 KV_DTYPE=int4 ./start.sh restart

README에 따르면 int4는 출력을 약간 변경하며 품질 측정값은 제공하지 않습니다. 프로젝트의 기본 균형을 원한다면 int8을 사용하세요. 스트림 수보다 최고 정밀도의 KV 저장이 중요하다면 bf16을 사용하세요.

시작 보호 기능 이해

TensorFold는 사용 가능한 메모리에서 RAM의 10분의 1에 해당하는 호스트 예약 메모리를 뺀 값으로 예산을 계산합니다. 요청한 구성이 이 예산에 맞지 않으면 가중치를 로드하기 전에 시작이 거부되며, 오류 메시지에는 사용할 수 있는 컨텍스트 창이 표시됩니다.

사고 및 샘플링 제어

사고 모드 샘플링의 기본값은 temperature 1.0, top-p 0.95, top-k 20입니다. 요청에서 temperature, top_p, top_k 및 seed를 재정의할 수 있습니다. temperature를 0으로 설정하면 탐욕적 디코딩이 활성화됩니다.

한 번의 요청에서 사고 비활성화

{
  "model": "Qwen3.8-Flash-Next",
  "messages": [
    {"role": "user", "content": "Answer in one sentence."}
  ],
  "chat_template_kwargs": {
    "enable_thinking": false
  },
  "max_tokens": 200
}

추론 노력 수준 설정

{
  "chat_template_kwargs": {
    "reasoning_effort": "low"
  }
}

템플릿은 "xhigh"도 허용합니다. 추론 노력 수준을 생략하면 템플릿은 중간 수준의 기본값을 사용합니다. 최상위 OpenAI 스타일의 reasoning_effort 필드는 무시되므로 chat_template_kwargs 안에 지정해야 합니다.

고급 성능 팁

SSD에 n-gram 테이블 유지

기본값인 PLE_ON_SSD=1은 29.8 GiB의 n-gram 테이블을 통합 메모리에 배치하지 않고 SSD에 유지합니다. 이를 통해 KV 캐시를 위한 메모리를 확보합니다. 따라서 기본 구성에서는 빠른 로컬 저장소가 중요합니다.

프롬프트 청크 크기를 신중하게 조정

비전이 활성화되면 TENSORFOLD_PREFILL_ROWS의 기본값은 비전 타워를 위한 공간을 확보하도록 2048로 설정됩니다. 텍스트 전용 모드의 기본값은 4096입니다. README에 따르면 4,096개 행을 사용하면 약 3,000개 토큰으로 구성된 프롬프트의 프롬프트 처리 성능이 약 2–5% 향상될 수 있지만, 약 0.94 GiB의 메모리가 추가로 필요합니다.

TENSORFOLD_PREFILL_ROWS=4096 ./start.sh restart

충분한 메모리 여유가 있을 때만 이 값을 높이세요.

MTP 및 복사 초안 제어

기본 MTP 구성은 라운드당 최대 6개의 초안을 생성하며, 초안의 확신도가 60% 아래로 떨어지면 체인을 중지합니다. 복사 초안 최적화는 TENSORFOLD_MTP_COPY=1로 활성화되며, 최소 2개의 병렬 스트림이 필요합니다. 이는 이전 프롬프트 텍스트를 인용하거나 편집하는 응답을 개선하기 위한 기능입니다.

직렬 참조 디코딩 요청

개별 요청에서 초안 생성을 우회하고 TensorFold의 한 번에 한 토큰씩 처리하는 참조 경로를 사용하려면 다음을 추가하세요.

{
  "draft": false
}

이는 추측 디코딩과 직렬 참조 디코딩을 비교할 때 유용합니다.

준비 단계 강제 또는 건너뛰기

PREPARE=1 ./start.sh restart
PREPARE=0 ./start.sh restart
PULL=0 scripts/prepare.sh

PREPARE=1은 재시작 전에 준비 상태 확인을 강제로 수행합니다.
PREPARE=0은 준비 단계를 건너뜁니다.
PULL=0은 미리 빌드된 레지스트리 이미지를 시도하는 대신 이미지를 로컬에서 빌드합니다.

patches/의 파일을 변경한 후에는 해당 패치가 TensorFold에 적용되도록 이미지를 다시 빌드하세요.

검증 및 벤치마킹

이 저장소에는 실행 중인 서버를 호출하는 유틸리티가 포함되어 있습니다. API URL의 기본값은 http://127.0.0.1:8888입니다.

tools/bench.py local-test
tools/needle.py
tools/toolcheck.py
tools/visioncheck.py

tools/bench.py는 여러 프롬프트 크기를 측정하고 짧은 디코딩 확인을 수행합니다.
tools/needle.py는 약 195,000개 토큰으로 구성된 프롬프트에 암호를 숨긴 후 검색을 검증합니다.
tools/toolcheck.py는 배열 값을 갖는 도구 매개변수가 JSON 배열로 반환되는지 확인합니다.
tools/visioncheck.py는 빨간색 원과 파란색 사각형이 포함된 생성 이미지를 전송한 다음 두 도형이 모두 인식되는지 확인합니다.

다른 시스템에서 테스트하려면 API_URL을 설정하세요.

API_URL=http://<spark-address>:8888 tools/bench.py remote-test

예상 성능

저장소에는 int8 KV 캐싱, SSD 기반 n-gram 테이블, MTP 초안 생성을 사용하는 DGX Spark 한 대에서 다음과 같은 디코딩 결과가 보고되어 있습니다.

단일 요청: 초당 62.4토큰, 첫 토큰까지 152ms.
두 요청: 초당 총 90.5토큰.
네 요청: 초당 총 106.7토큰.
다섯 요청: 초당 총 119.3토큰, 요청당 초당 27.0토큰.

보고된 프리필 속도는 8,229개 토큰 프롬프트에서 초당 약 2,503토큰부터 131,110개 토큰 프롬프트에서 초당 2,200토큰까지입니다. 이 수치는 프로젝트 측정값이며 보장되는 성능이 아닙니다. 구성, 프롬프트 구조, 미디어 입력, 스토리지 및 사용 가능한 메모리에 따라 달라질 수 있습니다.

결론

이 저장소는 단일 DGX Spark에서 Qwen3.8 Flash Next를 서비스하는 데 필요한 모델, TensorFold 런타임, CUDA 전용 설정, 성능 패치 및 운영 스크립트를 제공합니다. 기본 int8 5스트림 구성으로 시작하고, OpenAI 호환 API를 통해 서비스를 확인한 다음 워크로드와 메모리 여유에 맞춰 동시성, 컨텍스트 크기, 비전 및 KV 정밀도를 조정하세요.