개요
DwarfStar는 DeepSeek V4 Flash/PRO 및 GLM 5.2에 최적화된 자체 완결형 네이티브 추론 엔진으로, Metal, CUDA, ROCm 백엔드를 지원하고 SSD 스트리밍 로딩과 멀티 GPU 병렬 처리 기능을 갖추고 있으며, GGUF 생성, imatrix, 품질 테스트 및 코딩 에이전트 등의 도구를 제공합니다.
README 미리보기
\n \n\n\n**DwarfStar** is a small native inference engine optimized first for\n**DeepSeek V4 Flash**. It also supports **GLM 5.2** and, on very high-memory\nmachines, **DeepSeek V4 PRO**. It is self-contained and deliberately narrow,\nnot a general GGUF runner. Model loading, prompt rendering, tool calls, KV\nstate, the HTTP server, and the coding agent are built and tested together.\nThe repository also includes tools and data for GGUF, imatrix, quality, and speed.\n\nSupported backends:\n\n* **Metal**, the primary target, on Macs with 96 GB or more. Smaller machines\n can use SSD streaming.\n* **NVIDIA CUDA**, including multi-GPU systems and DGX Spark.\n* **ROCm** on Strix Halo systems such as the Framework Desktop.\n\nThis project would not exist without **llama.cpp and GGML**, make sure to read\nthe acknowledgements section, a big thank you to Georgi Gerganov and all the\nother contributors.\n\nModel support is intentionally opportunistic. The project follows the best open\nweights for useful local machine sizes, especially 128 GB laptops and 512 GB\nworkstations. A model may be removed when a better replacement arrives.\n\n# So, what can I do with this software?\n\n* You can run a very capable models in your consumer hardware, a MacBook, a DGX Spark, or a Strix Halo for example. Even if you have not enough RAM, with SSD streaming, you can run it at a decent speed.\n* Using the CUDA multi-GPU support and with ds4-server micro batching of decoding and generation, you can turn a server with old-ish CUDA cards (Ada Lovelace architecture), no longer supported for new models by vLLM, into a multi-user LLM server for your company. We tested this setup with 8xL40S NVIDIA cards and multiple sessions with very good results. 120 t/s aggreated generation, 2000 t/s prefill.\n* Using two MacBook M5 Max / M3 Ultra RDMA, you can run 4 bit DeepSeek Flash or GLM 5.2 with tensor parallelism.\n* You can also use pipeline paralellism to glue together multiple systems to sum their
FAQ (5)
문제 해결M1 Ultra에서 오차가 3e-6을 초과하는 test_deepseek41_metal 라우터 수치 검사 실패를 어떻게 해결하나요?
이것은 추론 크래시가 아니라 Metal FP32 수치 테스트 실패입니다: sqrt(softplus(x))가 log(1.0f + exp(x))로 계산되는데, 이는 M5 이전 GPU에서 -12 근처의 로짓에 대해 정밀도 손실을 일으킵니다. PR #1044가 포함된 최신 main으로 업데이트한 다음, 다시 빌드하고 모델 없이 실행하는 테스트를 재실행하세요:
git checkout main
git pull origin main
make clean
make tests/test_deepseek41_metal && ./tests/test_deepseek41_metal병합된 수정 사항은 네 곳의 DeepSeek 라우터 변환 지점 모두에서 부정확한 1.0f + exp(x) 형태를 exp(x) < 1/32일 때 정확한 4항 log1p 급수로 대체하고, 다항식 입력을 클램프하며, 허용 오차를 넓히지 않은 채 Metal 출력을 공유된 정확한 참조와 비교합니다. 이전 커밋에서는 임시 해결책으로 호스트 참조에서 log1pf(expf(v))를 사용하고 테스트 허용 오차를 넓히거나, Metal 커널을 log1p(exp(x))로 변경할 수 있습니다.
문제 해결llama-swap 또는 다른 외부 프로그램에서 실행한 ds4-server의 "cannot open model 'ds4flash.gguf'" 또는 "Metal source not found" 오류를 어떻게 해결하나요?
이 오류는 외부 런처가 ds4-server를 다른 작업 디렉터리에서 실행하기 때문에 발생하며, 상대 GGUF/Metal 경로가 해당 디렉터리를 기준으로 해석됩니다. 먼저 ds4 설치 디렉터리로 이동하는 래퍼 스크립트를 사용하세요:
#!/bin/sh
set -e
cd /path/to/ds4
exec ./ds4-server "$@"실행 권한을 부여하세요:
chmod +x /path/to/ds4/start-ds4.sh그런 다음 llama-swap이 래퍼를 가리키도록 설정하세요. 사용 중인 ds4-server 빌드가 /health를 제공하지 않는 경우 /v1/models를 상태 확인 엔드포인트로 사용하세요:
models:
"deepseek-v4-flash":
cmd: /path/to/ds4/start-ds4.sh
proxy: http://127.0.0.1:5555
checkEndpoint: /v1/models또는 경로 해석 수정이 포함된 릴리스로 업그레이드하세요. 그러면 상대 모델 및 Metal 에셋 경로가 현재 작업 디렉터리에서 찾을 수 없는 경우 실행 파일을 기준으로 해석되며, GET /health를 라이브니스 확인에 사용할 수 있습니다.
문제 해결M5 Metal TensorOps의 logit 드리프트 및 reference kernel과의 greedy decoding 불일치를 해결하는 방법은?
M5급 GPU에서는 자동 Metal 4 TensorOps 경로가 부정확한 matmul2d prefill 누적을 생성할 수 있으며, 이로 인해 logits이 simdgroup/레퍼런스 커널과 달라지고 greedy argmax 결과가 뒤집힐 수 있습니다. 다음 예와 같이 DS4_METAL_DISABLE_METAL4=1을 설정하여 실행하면 자동 TensorOps 경로를 비활성화할 수 있습니다:
DS4_METAL_DISABLE_METAL4=1 ./ds4 -m gguf/GLM-5.3-Flash-Q2.gguf --metal --temp 0 -n 2 --ctx 32768 --prompt-file prompt.txt또는 M5 디바이스에서 자동 TensorOps 활성화를 보류하는 수정 사항이 포함된 빌드로 업데이트하십시오. DS4_METAL_ENABLE_TENSOR=1은 성능 테스트 전용의 명시적 옵트인으로만 유지되며, 출력 동일성이 필요한 경우에는 사용해서는 안 됩니다. 오퍼랜드 스테이징 정밀도나 matmul2d_descriptor::relaxed_precision을 변경해도 이 문제는 해결되지 않습니다.
다음 명령으로 이 우회 방법을 검증하십시오:
DS4_TEST_MODEL=gguf/GLM-5.3-Flash-Q2.gguf \
DS4_TEST_VECTOR_FILE=tests/test-vectors/glm-openrouter/official.vec \
./ds4_test --metal-tensor-equivalenceMetal 4 TensorOps가 비활성화된 상태에서 M5 출력은 logprob 덤프, 디코드 일관성 검사, eval 트레이스 전반에 걸쳐 M5 이전 레퍼런스 머신과 비트 단위로 동일해야 합니다.
방법Metal, CUDA, 또는 ROCm에서 DeepSeek V4 Flash Vision-Exp AProjQ4 GGUF를 테스트하려면 어떻게 해야 하나요?
ds4의 PR #621을 빌드하고, Hugging Face PR #22에서 실험용 GGUF를 다운로드한 후, 그에 맞는 Vision 인코더 사이드카를 제공하세요.
1. 모델과 인코더 다운로드:
mkdir -p gguf
hf download antirez/deepseek-v4-gguf \
DeepSeek-V4-Flash-Vision-Exp-IQ2XXS-w2Q2K-AProjQ4-SExpQ8-OutQ8-imatrix.gguf \
--revision refs/pr/22 \
--local-dir gguf
hf download antirez/deepseek-v4-gguf \
DeepSeek-V4-Flash-Vision-Encoder.gguf \
--revision main \
--local-dir gguf2. 언어 모델 체크섬을 확인하세요. macOS에서는 shasum -a 256을, Linux에서는 sha256sum을 사용하세요. 예상 SHA-256:
a1d0fde967c910e37e4bea00c4db1b2e8a88978770828a95772bc66837386cb83. PR head를 가져와 빌드하세요:
git clone https://github.com/antirez/ds4.git ds4-vision-q4
cd ds4-vision-q4
git fetch origin pull/621/head:pr-621
git checkout pr-621
git rev-parse HEAD
# Apple Silicon / Metal
make clean && make
# 기타 NVIDIA CUDA 시스템
make clean && make cuda-generic
# DGX Spark / GB10
make clean && make cuda-spark
# AMD Strix Halo / ROCm
make clean && make strix-halo -j"$(nproc)"4. 먼저 모델을 검사하세요:
MODEL=gguf/DeepSeek-V4-Flash-Vision-Exp-IQ2XXS-w2Q2K-AProjQ4-SExpQ8-OutQ8-imatrix.gguf
VISION=gguf/DeepSeek-V4-Flash-Vision-Encoder.gguf
./ds4 --cpu --inspect -m "$MODEL"예상 메타데이터에는 GGUF v3, 1328개의 텐서, 43개의 레이어, 215개의
q4_k 텐서, 130개의 q8_0 텐서, 그리고 78.62 GiB 파일 크기가 포함됩니다.
5. SSD 스트리밍으로 실행하세요:
# Metal
./ds4 --metal --ssd-streaming --ctx 4096 --temp 0 \
-m "$MODEL" --vision "$VISION"
# CUDA
./ds4 --cuda --ssd-streaming --ctx 4096 --temp 0 \
-m "$MODEL" --vision "$VISION"
# ROCm
./ds4 --rocm --ssd-streaming --ctx 4096 --temp 0 \
-m "$MODEL" --vision "$VISION"완전 상주 테스트를 하려면
--ssd-streaming을 제거하세요. 78.62 GiB 모델, 비전 인코더, KV 캐시, 런타임 버퍼가 모두 사용 가능한 메모리에 들어가야 합니다.
대화형 CLI에서 다음 명령으로 PNG 또는 JPEG를 로드하세요:
/read /path/to/test-image.png일반 사진 최소 1장, 텍스트가 포함된 스크린샷 1장, 다이어그램 또는 차트 1장, 그리고 후속 질문을 테스트하세요. 정확한 커밋, 백엔드, 스트리밍/상주 모드, 크래시, 이미지 이해 오류, 품질 저하, 성능을 보고하세요.
문제 해결Kimi에 ds4 provider를 추가할 때 발생하는 "Skipping invalid entry object/data"와 "no usable providers" 오류는 어떻게 해결하나요?
이 오류는 Kimi가 OpenAI 스타일의 /v1/models 엔드포인트를 바라보고 있기 때문에 발생합니다. 이 엔드포인트의 응답은 object와 data 필드를 사용합니다. Kimi의 커스텀 프로바이더 레지스트리는 id, name, api, type, models 필드를 포함하는 프로바이더 객체를 요구합니다.
ds4를 Kimi 호환 레지스트리 PR이 포함된 릴리스/빌드로 업그레이드한 다음, 대신 전용 /api.json 엔드포인트를 추가하세요:
kimi provider add http://spark:8000/api.json다음은 사용하지 마세요:
kimi provider add http://spark:8000/v1/models새 엔드포인트는 Kimi가 전송하는 쿼리 스트링 매개변수도 파싱합니다. 사용 중인 빌드에서 /api.json을 사용할 수 없는 경우, ds4를 업데이트하거나 필수 프로바이더 필드가 포함된 Kimi 호환 레지스트리 JSON을 서빙한 후 해당 URL을 추가하세요.