概要
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マージされた修正では、4か所すべての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のロジットドリフトとリファレンスカーネルとの貪欲デコーディングの不一致を修正する方法
M5クラスのGPUでは、自動のMetal 4 TensorOpsパスが不正確なmatmul2dプリフィル累積を生成し、logitsがsimdgroup/リファレンスカーネルと異なったり、グリーディ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以前のリファレンスマシンとビット単位で一致するはずです。
ハウツーDeepSeek V4 Flash Vision-Exp AProjQ4 GGUFをMetal、CUDA、またはROCmでテストするにはどうすればよいですか？
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 のヘッドを取得してビルドする:
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 のモデル、Vision エンコーダー、KV キャッシュ、およびランタイムバッファは、すべて利用可能なメモリに収まる必要がある。
対話型 CLI では、次のようにして PNG または JPEG を読み込む:
/read /path/to/test-image.png少なくとも通常の写真 1 枚、テキストを含むスクリーンショット 1 枚、図またはチャート 1 枚、およびフォローアップの質問をテストする。正確なコミット、バックエンド、ストリーミング/常駐モード、クラッシュ、画像理解のエラー、品質ドリフト、およびパフォーマンスを報告する。
トラブル対応Kimiにds4プロバイダーを追加する際に発生する「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 を追加してください。