刚刚调通，跑了下，炸裂。我再完善下，一会儿把代码push到github吧。

Lucebox DFlash + PFlash 编译与部署指南

1. 克隆与子模块初始化

git clone https://github.com/Luce-Org/lucebox-hub.git
cd lucebox-hub
git submodule update --init --recursive

2. 编译

2.1 系统依赖

# CUDA (NVIDIA)
sudo apt install build-essential cmake git

# ROCm (AMD)
sudo bash dflash/scripts/setup_system.sh

2.2 编译 dflash (GPU Kernel + test_dflash)

cd dflash

# CUDA (NVIDIA, e.g. RTX 4090 sm_89)
cmake -B build -S . \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CUDA_ARCHITECTURES=89
cmake --build build --target test_dflash -j$(nproc)

# ROCm (AMD, e.g. 7900 XTX gfx1100)
# 可选：安装 rocWMMA 头文件以开启 Phase 2 FlashPrefill
git clone --depth 1 https://github.com/ROCm/rocWMMA.git /tmp/rocwmma
mkdir -p /tmp/rocm_include/include
cp -r /tmp/rocwmma/library/include/rocwmma /tmp/rocm_include/include/rocwmma

cmake -B build -S . \
  -DCMAKE_BUILD_TYPE=Release \
  -DDFLASH27B_GPU_BACKEND=hip \
  -DDFLASH27B_HIP_ARCHITECTURES=gfx1100 \
  -DDFLASH27B_HIP_SM80_EQUIV=ON
cmake --build build --target test_dflash -j$(nproc)

DFLASH27B_HIP_SM80_EQUIV=ON 开启 rocWMMA Phase 2 预填充。若不用 rocWMMA，设为 OFF 使用 q8 fallback。

2.3 编译 llama.cpp 基线 (可选)

BUILD_DIR=/tmp/llama-bench-build
cmake -B $BUILD_DIR -S dflash/deps/llama.cpp \
  -DCMAKE_BUILD_TYPE=Release \
  -DGGML_CUDA=ON                    # NVIDIA
  # -DGGML_HIP=ON                   # AMD
cmake --build $BUILD_DIR --target llama-bench llama-server -j$(nproc)

2.4 安装 Python 依赖 (server.py)

pip install fastapi uvicorn transformers pydantic starlette

3. 下载模型文件

3.1 目录结构

lucebox-hub/
├── dflash/
│   ├── models/
│   │   ├── Qwen3.6-27B-Q4_K_M.gguf     # 目标模型 (~16 GB)
│   │   ├── Qwen3-0.6B-BF16.gguf         # PFlash drafter (~1.2 GB)
│   │   └── draft/
│   │       └── dflash-draft-3.6-q8_0.gguf  # 推测解码草稿模型 (~1.84 GB)
│   └── build/
│       └── test_dflash                   # GPU daemon 二进制
└── ...

3.2 下载命令

cd dflash
mkdir -p models/draft

# 方式 A: huggingface-cli
huggingface-cli download unsloth/Qwen3.6-27B-GGUF \
  Qwen3.6-27B-Q4_K_M.gguf --local-dir models/

huggingface-cli download Lucebox/Qwen3.6-27B-DFlash-GGUF \
  dflash-draft-3.6-q8_0.gguf --local-dir models/draft/

huggingface-cli download unsloth/Qwen3-0.6B-GGUF \
  Qwen3-0.6B-BF16.gguf --local-dir models/

# 方式 B: wget
wget -c -O models/Qwen3.6-27B-Q4_K_M.gguf \
  "https://huggingface.co/unsloth/Qwen3.6-27B-GGUF/resolve/main/Qwen3.6-27B-Q4_K_M.gguf"

wget -c -O models/draft/dflash-draft-3.6-q8_0.gguf \
  "https://huggingface.co/Lucebox/Qwen3.6-27B-DFlash-GGUF/resolve/main/dflash-draft-3.6-q8_0.gguf"

wget -c -O models/Qwen3-0.6B-BF16.gguf \
  "https://huggingface.co/unsloth/Qwen3-0.6B-GGUF/resolve/main/Qwen3-0.6B-BF16.gguf"

4. 启动命令（按上下文长度）

所有命令从 lucebox-hub/dflash/ 目录执行。

️ 重要：DFlash / PFlash 不能直接用 llama-server 启动。
llama-speculative-dflash.cpp + llama-server 的集成是待办事项（见 README Contributing），尚未实现。
目前必须使用 dflash/scripts/server.py——它在内部将 test_dflash 作为子进程 daemon 运行，
对外暴露 OpenAI 兼容 API（/v1/chat/completions），功能与用法和 llama-server 一致。
对接 Open WebUI / LM Studio / Cline 时只需设 OPENAI_API_BASE=http://localhost:8080/v1 即可。

模型路径变量说明：以下命令假设模型文件位于 dflash/models/ 下，draft 位于 dflash/models/draft/。如果你的路径不同，修改 --target / --draft / --prefill-drafter 参数。

4.1 短上下文 (4K) — q8_0 KV + Q8 draft，最快解码

python scripts/server.py \
  --target models/Qwen3.6-27B-Q4_K_M.gguf \
  --draft models/draft/dflash-draft-3.6-q8_0.gguf \
  --cache-type-k q8_0 --cache-type-v q8_0 \
  --max-ctx 8704 \
  --fa-window 2048 \
  --budget 8 \
  --host 0.0.0.0 --port 8080

• 显存充裕，无需 PFlash 压缩
• budget=8 对 7900 XTX 最优（GDDR6 高带宽）

4.2 中等上下文 (16K–64K) — 推荐 tq3_0 KV + Q4 draft

python scripts/server.py \
  --target models/Qwen3.6-27B-Q4_K_M.gguf \
  --draft models/draft/dflash-draft-3.6-q4_k_m.gguf \
  --cache-type-k tq3_0 --cache-type-v tq3_0 \
  --max-ctx 131072 \
  --fa-window 2048 \
  --budget 8 \
  --prefill-compression auto \
  --prefill-threshold 32000 \
  --prefill-drafter models/Qwen3-0.6B-BF16.gguf \
  --host 0.0.0.0 --port 8080

• tq3_0 + Q4 draft 在 16K–64K 区间达 75–79 tok/s，速度与显存的最佳平衡
• PFlash 压缩长 prompt 至 5%，64K 预填充 ~733 tok/s

4.3 长上下文 (128K–192K) — 速度优先用 q4_0 + Q4 draft

python scripts/server.py \
  --target models/Qwen3.6-27B-Q4_K_M.gguf \
  --draft models/draft/dflash-draft-3.6-q4_k_m.gguf \
  --cache-type-k q4_0 --cache-type-v q4_0 \
  --max-ctx 200000 \
  --fa-window 2048 \
  --budget 8 \
  --prefill-compression auto \
  --prefill-threshold 32000 \
  --prefill-drafter models/Qwen3-0.6B-BF16.gguf \
  --host 0.0.0.0 --port 8080

• 解码 ~81 tok/s（最快），使用 Q4 draft 节省 ~1 GiB 显存
• 192K 仅 q4_0 KV + Q4 draft 可装入 24 GiB

4.4 长上下文 (128K–192K) — 草稿质量优先用 tq3_0 + Q8 draft

python scripts/server.py \
  --target models/Qwen3.6-27B-Q4_K_M.gguf \
  --draft models/draft/dflash-draft-3.6-q8_0.gguf \
  --cache-type-k tq3_0 --cache-type-v tq3_0 \
  --max-ctx 200000 \
  --fa-window 2048 \
  --budget 8 \
  --prefill-compression auto \
  --prefill-threshold 32000 \
  --prefill-drafter models/Qwen3-0.6B-BF16.gguf \
  --host 0.0.0.0 --port 8080

• 解码 ~72 tok/s，保留 Q8 草稿质量（比 Q4 draft 更准确）
• tq3_0 3.5 bpv 压缩释放 ~1 GiB 显存给 Q8 draft

4.5 超长上下文 (256K) — 推荐 tq3_0 + Q8 draft（唯一方案）

python scripts/server.py \
  --target models/Qwen3.6-27B-Q4_K_M.gguf \
  --draft models/draft/dflash-draft-3.6-q8_0.gguf \
  --cache-type-k tq3_0 --cache-type-v tq3_0 \
  --max-ctx 270000 \
  --fa-window 2048 \
  --budget 8 \
  --prefill-compression auto \
  --prefill-threshold 32000 \
  --prefill-drafter models/Qwen3-0.6B-BF16.gguf \
  --host 0.0.0.0 --port 8080

• 唯一能在 256K 保留 Q8 草稿质量的方案
• tq3_0 (3.5 bpv) 省 ~1 GiB 显存，刚好容纳 Q8 draft
• 解码 ~72 tok/s，预填充 ~730 tok/s

4.6 超长上下文 (256K) — 极致速度 q4_0 + Q4 draft

python scripts/server.py \
  --target models/Qwen3.6-27B-Q4_K_M.gguf \
  --draft models/draft/dflash-draft-3.6-q4_k_m.gguf \
  --cache-type-k q4_0 --cache-type-v q4_0 \
  --max-ctx 270000 \
  --fa-window 2048 \
  --budget 8 \
  --prefill-compression auto \
  --prefill-threshold 32000 \
  --prefill-drafter models/Qwen3-0.6B-BF16.gguf \
  --host 0.0.0.0 --port 8080

• 解码 ~81 tok/s（最快），但草稿质量最低
• 显存勉强装入 24 GiB

5. 快速选择指南

场景	KV 类型	Draft	tok/s	特点
聊天 (≤4K)	q8_0	Q8	86	最快，无损质量
文档分析 (16K–64K)	tq3_0	Q4	75–79	速度/显存最佳平衡
代码理解 (128K–192K)	q4_0	Q4	81	极致速度
代码理解 (128K–192K)	tq3_0	Q8	72	草稿质量优先
超长上下文 (256K)	tq3_0	Q8	72	推荐，唯一 Q8 方案
超长上下文 (256K)	q4_0	Q4	81	最快但有 OOM 风险

6. 对接客户端

服务器启动后，兼容 OpenAI API，可对接任意客户端：

# 测试
curl http://localhost:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"luce-dflash","messages":[{"role":"user","content":"你好"}],"stream":true}'

Open WebUI / LM Studio / Cline 配置：

• API Base: http://localhost:8080/v1
• API Key: sk-any（任意值）
• Model: luce-dflash

7. 常用环境变量